ToF-AMS Analysis Software

From Jimenez Group Wiki
Revision as of 15:16, 1 December 2009 by DonnaS (talk | contribs) (→‎Working with MS data)
Jump to: navigation, search

ToF_AMS Analysis Software Resources

Useful Links

caption Squirrel (ToF-AMS Unit Resolution Analysis Software)

Squirrel General FAQ

  • What do I need to run Squirrel?

You need:

  1. Version 6.11 (or the latest update) of Igor.
  2. The HDF5 xop to be placed in your Igor Extensions folder. Igor Extensions are modular bits of code for extending functionality to Igor. The Igor Extensions folder resides in your Igor Pro Folder, and everything in this folder gets loaded automatically everytime you open Igor. The Igor extension you need is called HDF5.xop and in fresh installations of Igor resides in the "Igor Pro Folder/More Extensions/File Loaders" folder. Simply move or copy this file, and along with it's matching help file, HDF5 Help.ihf, into the Igor Extensions folder.
  3. The latest Squirrel software, a packed Igor template, downloadable from the link above.

Squirrel is tested mainly on pcs using Windows XP, but should work on Macintosh OSX systems.

  • When I open a SQUIRREL template I am getting a compilation error at HDF5OpenFile (or HDF5CloseFile or HDF5xxxx). Why?

This compilation errors appears when the HDF5.xop was not loaded. See 'What do I need to run Squirrel?' Typically this happens when users get a new computer, installs Igor, but then forgets to move the HDF.xop or fix a shortcut to this file.

  • How do I upgrade an experiment?

It is always a good idea to upgrade your existing squirrel experiments. Upgrading consists of loading 5 new ipfs (Igor Procedure Files), killing the old ones, and recreating the main AMS panel. Ipfs can be shared or adopted in any experiment; consult the Igor documentation to understand which method you would like to use.

  • Why Squirrel?

The ToF-AMS can generate large data sets (> 10s Gigabytes) very quickly. The need for a somewhat standard user interface for analyses of these often large data sets was identified, and Squirrel was born. Squirrel is a software tool using Igor on HDF files for analyzing ToF-AMS data. Squirrel is an ongoing, collaborative effort between researchers using the ToF-AMS instrument. Its development to date has been lead by the University of Manchester, University of Colorado, Boulder, Max-Plank Institute, Mainz, and Aerodyne Research, Inc. It is free and is covered by the GNU's General Public License, which means we want to keep it free and give all users the freedom to improve and redistribute the software. An older version of software that has some of the same functionality is called TADA. TADA will eventually not be supported. Squirrel's foundation using HDF files will allow for analysis and manipulation of data sets larger than TADA can handle.

  • What is Squirrel?

SQUIRREL (SeQUential Igor data RetRiEvaL ) is a data management utility for Igor designed around the random access of AMS data in HDF (version 5) files and within memory. It is a task-based system that exists as a layer between the function calls and the data processing functions; the idea is that all data processing is done through SQUIRREL. The SQUIRREL name may or may not really come from a White Stripes song.

  • What are the advantages of Squirrel over the existing methods?

First and foremost, it eliminates the limits imposed by having to load all the data into memory. Previously, with the Q-AMS data, we were limited to experiment files of less than a gigabyte in size, which is going to hamstring us even further with the advent of the ToF-AMS instruments. But using this system, the binary data is kept on a hard drive as much as possible. Also, as the data is accessed selectively, you only grab as little or as much is needed, greatly speeding up the processing times for simple tasks while still able to perform the big ones. Finally, because it adopts a pseudo-object orientated approach, it should make the development of new analysis methods that can access the data much easier.

  • How does Squirrel work?

Instead of simply performing a data analysis task on a wave in memory, a call to SQUIRREL is made. The call consists of a ‘to-do’ list, the operation that you wish to perform on the data, some operation-specific parameters and a list of the data types that the functions operate on. SQUIRREL takes a look at the to-do list, retrieves the data and passes it to the function. In the case that there is too much data to analyse in one go (e.g. when analysing PTOF data), the task is broken into chunks (known internally as acorns) which results in multiple function calls. In order to access the data in the HDF files, an index needs to be built, which is handled by a separate function, assumed to have been run before the function call.

  • What are the very basic steps in analyzing a data set with Squirrel?

Analysis steps are generally placed top to bottom, left to right in the ams panel. Briefly:

  1. Gather all the hdf files you wish to analyze in one folder.
  2. Press the Get Index button. A prompt ask you to identify the folder of your hdf files. This function identifies runs and gathers basic information about the data set. The program will search in folder you chose and all subfolders (and subfolders...).
  3. Press the Pre-Process button. This may takes some time to complete. This function generates more handy, organized versions of the data, called intermediate hdf files. A prompt will ask you for a location to put these intermediate hdf files and will save the experiment (will prompt you for a name and location of this experiment).
  4. Go to the MS and PToF tabs and generate graphs of your choosing, such as time series and size distributions.
  • What is an HDF file?

HDF5 is a general purpose library and file format for storing scientific data. In Igor, one can browse the contents of an hdf file via the Data - Load Waves - New HDF Browser feature. Non-Igor tools for browsing hdf files can be found at this link.

  • Are there problems with Squirrel?

There are fewer problems as time goes by. The essential tasks of generating times series and average mass spectra for species and the conversion to ug/m3 units is considered to be robust.

  • What does Squirrel have to do with HieDI?

HieDI is a software tool for converting ToF-AMS .itx and .bin files into .hdf files. The .itx and .bin files are generated using older acquisition software (mostly pre-2007). Analysis of the .itx and .bin files can be done through an Igor software package called TADA. Eventually TADA will not be supported and everything will be done through Squirrel and .hdf files.

Squirrel Technical FAQ

Todo Waves

  • What is a to-do (or todo or 'To Do') wave?

A todo wave is simply a column of integers containing run numbers. A user selects a todo waves to identify the runs that are to be operated on. For example, if you wanted to average all the runs between 102 and 105, you would make a todo wave that would contain four runs: 102, 103, 104 and 105, and select this todo wave from the todo wave drop down menu. Some todo waves are automatically generated, such as all, allV, allPTof, allsEI, new, etc. Todo waves can also be generated based on mask waves, so you can selectively process data based on an inlet condition, wire position, meteorological conditions or anything else.

  • What's some good advice regarding todo waves?

Don't use Igor 'liberal' names. Specifically,don't use spaces in the names, don't begin it with an alphabetic character, etc. Don't use the reserved todo wave names: all, new, and blacklist, allsEI, etc. You should be aware that several graphs automatically color traces that have an AMS species (such as Org or Chl)in their name. For example, squirrel will often automatically designate the color green for those waves with "Org" in the name. If you make a todo wave using these default AMS species names, the colors for graphs will have the color of that species. In general you are advised to name a todo wave "HighNitrate" instead of "HighNO3" or "HydrocarbPlume" instead of "OrgPlume".

  • How can I convert a 'regular' wave to a todo wave?

Often users have found it handy to create their own wave of run numbers, and they want to know how to make this wave appear in the todo wave drop-down menu in the panel. In general, I recommend that a user duplicate an existing todo wave, such as the all todo wave. One can then delete all points in this duplicate wave, and then fill it in with run numbers of their choosing. Then simply select the 'Get List' option and the new todo wave should appear. The other way is to straight-forward but technical. A todo wave needs to be a 32 bit unsigned integer type; the wave type can be changed in the redimension window. Also, the todo wave must have this text in it's wave note: "TYPE:todo" (without the quotes). One can add a wave note via the info area in the Data Browser window or by using the Igor Note command (Note mywave,"TYPE:todo").

  • Can I un-blacklist a run?

Kind of. First, save your experiment before you try this. Then make a table of the blacklist wave. Delete rows containing the run numbers you want to un-blacklist. Do not attempt to insert run numbers here, just remove them. When you are finished, press Get-Index again. This will go through some todo wave and indexing functions; the 'all' todo wave will now have the un-blacklisted runs. Unfortunately user-defined todo waves will NOT have the newly-unblacklisted runs inserted. Depending on where you are in your analysis, you may have to re-preprocess for downstream values to appear.

  • Is the blacklist wave a todo wave?

No, in squirrel the blacklist wave isn't a 'real' todo wave. Every real todo wave has the wave note "TYPE:todo;" attached to it, and the appearance of this note and the fact that a todo wave is of integer type (not single precision, etc) is what makes a wave a todo wave. The blacklist wave is not in the todo wave table on purpose.The idea is that this wave would always be set apart - the name is always blacklist and it always contains the cumulative list of all runs that were deemed junk, never to be looked at again. The runs in blacklist are cumulative.

  • How can I remove a todo wave that's no longer needed from the todo wave list?

If you don't need the wave again, you can simply kill the wave and select 'Get List' from the todo wave drop-down menu. If you want to prevent it from appearing in the todo drop down menu, you can change the wave type to something other than a 32-bit integer or you can remove the todo wave note (See 'How can I convert a 'regular' wave to a ToDo wave'? above).

  • How can I make todo waves based on the DAQ menu numbers?

The menu numbers themselves are not saved in any parVal or infoVal setting as menu numbers them selves are meaningless. A user could switch menu 1 and 3 for example, and the menu numbers themselves would not be helpful in determining what kind of data a particular run has. Instead, there are 3 waves that can/should be able to sort out the needed settings for any particular run: tofType ( 1 = v or 2 = w, c = 0), ionizationType (EI, sEI, etc, given by numbers) DAQSamplingType(parVal #162). This is a new wave created and used in version 1.45. The idea is that any unique combination of these 3 waves should be able to uniquely identify all original menus.

File and Experiment Organization

  • What are intermediate files?

The intermediate files are essential components of your Igor experiment. If you were to move the intermediate files to another location and reopen the igor experiment, you will get a prompt asking for their location. Intermediate files can grow large. One good strategy is to create a separate, dedicated folder to house them, and locate this intermediate data folder in the same folder as your experiment. If you are in doubt as to what intermediate files are attached to an experiment, display, in a table, the wave root:index:file_index. But don't try to edit or monkey with this wave, or any other waves in the index folder. That would be a big no-no.

  • On a Mac OSX system how do I change the font size so that the text fits the buttons in the panel?

In the command line enter DefaultGuiFont button={"Geneva",9,0}. Thanks to Pete DeCarlo for the tip.

  • What can I do when a pxp file goes missing/bad?

From a user: An HR-Squirrel pxp of mine recently disappeared. I think my computer crashed while it was unsaved, which is very sad. But the intermediate files are still there - is there any useful information that can be easily mined from them, or is best if I just start over? The response: Without the root:index:squirrel_index wave, which 'lives' in the pxp file, the intermediate files are pretty much worthless.

Default Settings

  • Why is the default RIE value for the nitrate species 1.1 instead of 1?

The RIE is defined compared to the sum of nitrate ions in the m/z (30+46). RIE_x = (Ions_x/Molecule_x) / (Ions_30+46/Molecule_30+46) * MWno3 / MWxThus, if one were to sum ALL nitrate ions (including m/z 63 for nitric acid, 14 for nitrogen, isotope ions due to 15N and 18O, etc.), one gets ~1.1 * (sum of 30+46). Another way of saying this is that (14+30+46+63+...)/(30+46) ~ 1.1.

  • What are the basic component of a squirrel template experiment file?

One can create a squirrel template file 'from scratch' by simply importing all the 5 ips:

  1. SQ_AMSPanel_version#.ipf - contains all the global variables, strings, code to make things on the main AMS panel work.
  2. SQ_Backbone_version#.ipf - contains code for the squirrel infrastructure (extracting and saving only parts of data sets one is working on at any one time).
  3. SQ_FragDiag_version#.ipf - contains code for 'Alice's diagnostics', which is used to help with checking frag table entries.
  4. SQ_MSConc_version#.ipf - contains code for generating AMS data products such as Org time series, average mass spectra, etc.
  5. SQ_MzCalBkgd_version#.ipf - contains code for the m/z calibration and baseline panels.
  6. and importing the 'frag' data folder. Waves in the frag data folder contain text waves with default settings for generating organic, nitrate, etc, AMS species.
  • Is there something special that should be done when analyzing non-ambient data?

The default frag waves are optimized for ambient conditions. These frag waves need to be changed when doing lab studies using N2 only (and not a clean air gas mixture) as a carrier gas, or when only known components should be present. There is no simple button to press within squirrel that would convert default frag entries to accurately reflect non-ambient conditions.

The 'Get Index' Step

  • What's the difference between *_series and *_index waves?

The waves run_index, rn_series, time_index and t_series will always have the same number of points. The _index waves track each other and indicate a simple listing of when a run was identified as being under consideration, being in an hdf file. The _series waves also track each other, and they have the same information in them as the _index waves, but the series waves are in chronological and run-number increasing order. Data is processed in squirrel in increasing order, that is, using the _series waves. You should always use the _series waves for plotting and such. I can't think of a reason why a user would need to look at the run_index wave. It may be confusing because often the rn _series and the run_index waves are identical, and one may get used to looking at the *_index wave. But you should always use the *_series waves.

  • How does squirrel handle 'fast mode' data?

Here are some things to consider when dealing with fast mode data: In the Get Index step, squirrel should automatically create allFastOpen and allFastClosed todo waves. For fast mode runs, it is good to blacklist the first and/or last closed spectra for each fast mode cycle. Squirrel finds these edge runs. You can then blacklist the closed Edge runs. You then want to recalculate your sticks to get Squirrel to get newly interpolated closed sticks across your fast open runs. The first and/or last open runs in your fast mode cycle may also need to be trimmed. You won't want to report these smeared runs as ambient data. The default m/z calibration settings use MSClosed, not MSOpen (and not MSOpen_p and MSClosed_p), so for fast mode open runs, you will need to be prepared for this and handle as you wish. Lastly, often aircraft measurements require different m/z calibration results for open and closed. I am not clear on why this trend seems to be true, but anecdotally this is the case. This has nothing to do with Fast mode data, but it is something to be aware of.

  • In the diagnostics plot, there are several step functions in 'm/z cal peak position'. What is this 'm/z cal peak position'? What may cause such changes?

This is almost always nothing to worry about. On the contrary, it would be very odd to have these traces be constant for > 6 hours, say. The DAQ can only resolve the center peak position to integer values in ns space. But we know that it should typically drift continuously, so step changes or 'stuttering' between two values is fine. It is only when you see big step changes (>3 ns, or point values) or other serious fluctuations is when you should start to become suspicious. In general the DAQ does a very good job of tracking the individual peaks chosen by the user (typically N2, a Tungsten, and a 3rd peak). If things go really wrong, typically you will see other, more glaring symptoms (step changes in all stick values including 28, etc)

Working with MS data

  • When generating an average mass spectra what does the 'Truncate sticks to 0' checkbox do?

Traditionally one plots average mass spectra of different species on the same graph as stacked sticks. That is, the value of one species is shown above the value of the previously plotted species. But this type of graph only works when all entries are greater than zero. When the 'Truncate sticks to 0' checkbox is checked the negative values in individual species waves (such as mssd_todowave_org) are set to 0, immediately before this wave is plotted but after the sum is calculated. If one find the sum of this wave, you do not get the same value as indicated in the legend because you are only adding all the values > 0, because all the values < 0 have been replaced with zeros.

  • When generating an average mass spectra, why doesn't the sum of the Org sticks in the graph equal to the Org value in the legend?

The difference is that the stick waves in the graph are *nitrate equivalent* so that they are using an RIE and CE of 1 for all species. The values in the legend reflect values where the *species RIE and CE have been applied* (is not nitrate equivalent). The legend indicates the total average species concentration, such as Org, for that todo wave. So if you compare this number with the number you would get by averaging the time series wave of Org for this todo wave, you should get the same result. Note that squirrel provides a time-weighted result, so that if you had one run of 10 second duration and another run of 60 second duration the second run would be weighted by 6.

  • Is there an easy way to compare values found in V and W modes?

There are a few options. If one was alternating between V and W one could simply offset one time series Org wave, for example, by one point. Alternatively, one could use the 'Set interval' time base selection instead of the 'As saved'. For example, if you were taking 1 minute V mode, then 1 minute W mode, you could create an Org time series wave of V only using the AllV todo wave and a 2 minute time interval, and then another Org time series wave using the allW todo wave with the 2 minute time interval. You could then do correlations on these two org waves.

  • How does the airbeam correction work if I run the AMS with v/w mode switching?

You need to choose only one airbeam region, one set of airbeam reference runs. If the AMS was operating in both modes during this region Squirrel will automatically calculate the airbeam average for the v mode only and the w mode only for these reference runs and then combine these to generate the aribeam correction factor. If you select a value from the ToF Type drop down box (in the corrections - airbeam tab) you can view the airbeam average for each of the modes.

  • What happens if I want to change the Ion Efficiency value? If I trust the original air beam value, do I need to do the Airbeam correction?

Ion efficiency values are stored in waves called root:diagnostics:ionEff_logged and possibly root:diagnostics:ionEff.

Values in root:diagnostics:ionEff_logged are read from the parameter values stored in the DAQ; these values should have been entered into the system by the user after an ionization calibration.

As is true for any wave in the diagnostic folder, these values can be overwritten when one presses the button "Update Diagnostics" in the HDF index tab. Also, as is true for a few diagnostic waves, there can be a 'logged' = DAQ version, and a copy of this wave that may be modified by the user (without the '_logged' suffix).

For an airbeam correction and/or ionization calibration, there are 3 values that are interdependent: AB signal in Hz, flow rate, and the single ion value. Each of these values are run-number dependent (we have one value per run; they are waves, not constants for any Squirrel experiment).

We use the single ion value to convert from bits-ns to Hz to get our sticks, including the m/z 28 (=airbeam) stick. When we do an airbeam correction, our goal is to 'normalize' or 'calibrate' data that have been collected during a non-calibration period. Everyone should do an airbeam correction to their data before it is final. Often the airbeam correction factor is on the order of a few percent, but this correction can be reliable applied when it is a factor of 2, 3.

This correction is necessary because we know that the MCP degrades over time. We attempt to quantify this degradation by the assumption that the amount of N2 present in all samples is constant. The idea is to select a period (AB refernce period) of ambient measurement close to a calibration where all values are known. The idea is then to use the ratio of the /z 28 signal of the reference period to all other periods as our correction factor. After the ratio has been calculated, we presume all fluctuations in N2, regardless of their origin, have been quantified. So to correctly apply this factor, one should hold the ionization efficiency value to be constant. Thus the AB correction code creates the wave root:diagnostics:ioneff and inserts a constant value (the ion eff during the reference period) for ALL runs. This ioneff wave (not ioneff_,logged) is subsequently used in all conversions to ug/m3, regardless of whether the 'Use MS AB correction' checkbox is checked. So to be consistent, one should always use the AB correction once it has been found.

  • When generating an average raw mass spectra, why are both 'As Saved' and 'Regrid' checked by default for the m/z base? And what does regrid mean if it doesn't mean using a defined grid as specified in the checkbox below that?

In general, averaging raw (non-stick) spectra is confusing because each run has it's own unique mapping from iToF space to the m/z space. When one wants to generate an average raw spectra, one has to be careful to handle these different mappings. When "As Saved" and "Regrid" is checked and one is generating a raw average mass spec, the m/z base of the first run in the todo wave is used as the x-axis and all other runs are regridded (using a fancy non-linear interpolation) to this one base. If regrid is not checked, it assumes that all other runs in the todo wave have the identical x-axis mapping and a point by point averaging is done. If one doesn't want to use the x-axis mapping of the first run (the first run of the todo wave is arbitrary - we could have also used the last run in a todo wave, i.e.) one can decide what x-axis values to map all raw spectra onto. This is the regrid option checked with the second radio button checked. This option would be useful for one to compare two completely different raw spectra, but don't want to have to fix either to some artibrary x-mapping. One could get a raw open spectra obtained at noon and 6pm, and be able to compare two raw spectra with completely different x-mapping.

Working with PToF data

  • What is the PToF normalization factor?

The PToF normalization factor is a scalar used to multiply PToF size distributions (typically) so that the total mass (for Org, say) as seen by the PToF, by integrating over the size bins, is equivalent to the Org mass as seen by the MS runs for the same todo wave. Suppose you take an average mass spectra and get 10 ugm3 for Org for todo wave MyTodoWave. Suppose we get a PToF size distribution for Org, and it's total Org signal is 8 (to get to total signal you have to be careful to get the x-axis binning correct). Then the normalization factor would simply multiply the entire PToF size distribution spectra for Org by 10/8, so that the sum of PToF data over all size bins is now 10.

The Frag and Batch Table

  • How do I make a time-dependent entry in a frag wave?

All you need to do is enter in the name of the wave in the frag wave. Be sure that the wave is in the root folder and any mapping to get the data onto the ams time base has already been done. If there is a nan in the wave, the resulting frag value will be nan. It is always a good idea to first test this feature and syntax using a dummy wave that has has a constant value in it. For example at m/z 44 in the frag_CO2 wave the default entry is this 0.00037*1.36*1.28*1.14*frag_air[28] And if you have a wave called myCO2 with the gas phase CO2 amounts in it (being careful of units) you could change the entry to a time-dependent frag entry to look like myCO2*1.36*1.28*1.14*frag_air[28]

caption Pika (ToF_AMS High Resolution Analysis software)

Pika General FAQ

  • Why Pika?

The high resolution aerosol mass spectrometer (HR-ToF-AMS) allows for measurement of chemical componenets within aerosols. A software tool was needed for the speciation and quantification of HR-ToF-AMS data and Pika was born. Its development has been lead by the Jimenez Group at the University of Colorado, Boulder. Like Squirrel, it is free and is covered by the GNU's General Public License, which means we want to keep it free and give all users the freedom to improve and redistribute the software.

  • What is Pika?

PIKA (Peak Integration by Key Analysis) is a software tool for Igor built upon SQUIRREL. It is based upon the algorithm by Peter DeCarlo and others detailed in DeCarlo P.F., J.R. Kimmel, A. Trimborn, M.J. Northway, J.T. Jayne, A.C. Aiken, M. Gonin, K. Fuhrer, T. Horvath, K. Docherty, D.R. Worsnop, and J.L. Jimenez, Field-Deployable, High-Resolution, Time-of-Flight Aerosol Mass Spectrometer, Analytical Chemistry, 78: 8281-8289, 2006.

Pika Technical FAQ

  • How do I turn a Squirrel experiment into a Pika experiment?
  1. One needs to upgrade to Igor 6.11.

One needs to load in these additional items:

  1. All the latestes Pika ipfs. As of version 1.07, there are 7 Pika ipfs (each pika ipf has a PK_ prefix).
  2. A group of waves containing information about all the known HR ions. This group of waves needs to be loaded into an Igor data folder named HR. A generous group of folks have volunteered to maintain these waves, headed by Puneet Chhabra at Cal Tech. This group contains waves identifying the chemical formula of the ions, their mass values and isotopic abundances, and default HR ions to fit. It is from this big 'master' list that users choose which ions to fit.
  3. A group of waves containing batch and frag information, similar to the waves found in the Squirrel frag data folder. These waves need to be loaded into a data folder called HR_frag.

Once everything is loaded, things should compile and a user should be able to generate the HR panel via the top AMS menu item.

  • How do I update a 1.06x Pika experiment?

The instructions are similar to those for upgrading a squirrel experiment to a pika experiment.

  1. Upgrade to Igor 6.11.
  2. Load in all 5 squirrel 1.48 ipfs into the experiment. Kill the old squirrel ipfs.
  3. Load in all 7 pika 1.07A ipfs into the experiment (each pika ipf has a PK_ prefix). Note that in versions previous to 1.06, there were only 5 pika ipfs. The new ipfs are PK_frag_xxx.ipf and PK_elemAnal_xxx.ipf. Kill all the old Pika ipfs.
  4. Load in a group of waves containing information about all the known HR ions. This group of waves needs to be loaded into an Igor data folder named HR. A generous group of folks have volunteered to maintain these waves, headed by Puneet Chhabra at Cal Tech. This group contains waves identifying the chemical formula of the ions, their mass values and isotopic abundances, and default HR ions to fit. It is from this big 'master' list that users choose which ions to fit. This HR data folder should already exist;users should simply overwrite the old waves when loading in the new waves.
  5. Load in a group of waves containing batch and frag information, similar to the waves found in the Squirrel frag data folder. These waves need to be loaded into a data folder called HR_frag. Users should create a new folder named HR_frag and load the frag waves into it.
  6. Kill and recreate the main squirrel panel.
  7. Kill and recreate the main pika panel.
  8. It is recommended that you save the experiment after you have done all the previous steps.
  • The HR_PeakHeights graph (or other graph) is too small on my Macintosh system and it won't let me resize it - what do I do?

Many graphs and panels are a fixed sized because sometimes resizing them can cause them to update incorrectly. However, the HR_PeakHeights graph can safely be resized. To enable resizing, select the graph, then go to the top Igor Graph menu, select Modify graph, and select "Auto" instead of "Absolute" in the drop down menus for both the Width mode and the Height mode.

  • I am using the HR species and generated a HRMxD_HROrg matrix, but the number of columns in this matrix (which corresponds to the number of HR ions considered) is larger than expected. What is going on?

When we include other HR ions that were not fit we will have a larger matrix. For example, if 430 HR ions were chosen to fit, and one got an HRMxD_HROrg matrix with 433 columns, then 3 ions were not fit but were included in HROrg (i.e. j13CO). To line up the columns with their appropriate HR ion, you need to use the species waves that live in the HR_frag data folder. Specifically, go to root:HR_frag:SpeciesMassText and root:HR_frag:SpeciesMassWave. The wave root:HR_frag:SpeciesFamilyText copies which family an HR ion that was fit was grouped into, and is created only as a convenience.

caption Apes (ToF-AMS High Resolution Elemental Analysis software)

Apes General FAQ

  • Why Apes?

Apes (Analytic Procedure for Elemental Separation) is a software tool used to separate High resolution AMS ions to their elemental components. It uses the chemical formula of an HR ion and the HR ion mass value to sum, average, or ratio the amount of elements C, O, H, N, and S that are present in an AMS sample.

  • What is Apes?

Apes is the name for the code that performs the elemental analysis calculations. In Pika version 1.07, this code is incorporated into the HR analysis section. This code is also a stand-alone ipf for use in situations where the squirrel and pika infrastructure is not needed (i.e. PMF HR spectra factor results).

An essential primer on the analysis method was given by Jose Jimenez at the 2008 AMS User's meeting in Manchester, UK. The pdf can be found at: http://cires.colorado.edu/jimenez-group/UsrMtgs/UsersMtg9/2008-09_AUM_Jose_Elemental.pdf The defaults for the elemental analysis code described below are appropriate for ambient data. Users should modify the settings as needed for laboratory or unusual ambient conditions.

This code is named APES (Analytic Procedure for Elemental Separation) and is based on the work done in A.C. Aiken, P.F. DeCarlo, and J.L. Jimenez, Analytical Chemistry, 79, 8350-8358, doi:10.1021/ac071150w, 2007 and Aiken, A.C., et al. Environmental Science and Technology, 42, 4478–4485, doi: 10.1021/es703009q, 2008


Apes Light Code (A stand-alone APES for use in PMF results or for individual HR spectra)

This ipf is for use with stand-alone spectra, such as one may obtain via a HR PMF analysis. This ipf is self-contained and will compile by itself; it does not need the squirrel and pika infrastructure. It presumes the input spectra contains only HR ions under consideration (typically all Organic Mass, OM). Such a spectra can be generated with Pika version 1.07 or greater, because these versions have the ability to precisely define HROrg, the High resolution version of the typical AMS organic species. The ability to define HROrg greatly simplifies the elemental analysis. Much of the original APES code dealt with the cumbersome, limited assumptions about organic mass HR ions that did not have a C atom within an ion.


Apes-in-Pika Code (APES code that has now been merged into Pika versions 1.07+, versions with HR species)

The ipf PK_elemAnal_1_07.ipf and higher contain the essential components of the original APES and merged it into Pika. This ipf is now automatically included with all Pika template experiments. It contains the same essential code as the original APES, and in the stand-alone, APES Light code.

Apes Code (The original APES, or APES classic, for use in Pika without HR species)

This ipf must be used within a Pika experiment even if the HR spectra to be analyzed is not Pika generated, because it relies on function within Squirrel and Pika ipfs. Users need at least Igor 6.0; this code was primarily tested using Igor 6.1.

Version Information and Download Site

You do not need to use this version of Apes if you are using Pika 1.07 or higher. The latest 'classic' version of the Apes code is 1.04 and was released on 28 Oct 2009. Version 1.04 is the same as version 1.03, it is simply formatted to fit smaller screens and Macs. This version and all previous versions are available at the ToF AMS software download site at

http://cires.colorado.edu/jimenez-group/ToFAMSResources/ToFSoftware/index.html#APES

Before You Begin

The elemental analysis code (APES) assumes that the high resolution (HR) sticks used for input are both quantitative and inclusive of all measured HR fragments. Generating a complete and quantitative set of HR AMS sticks is non-trivial, especially for ambient data with low concentrations or with higher m/z mass fragments.

Step 0: HR Data to be Analyzed

The user can select either Pika calculated sticks or user-defined sticks. When APES is used with Pika sticks the data set HRDiffSticks, the wave containing the chemical formulas for those HR sticks, and the todo wave and all the associated Squirrel/Pika infrastructure is used. When the 'User chosen' option is selected the user identifies the names of the waves needed for the calculations: the HR sticks, the wave with the chemical formulas of the fragments and the chemical mass of the fragments, and if needed the names of the family mask waves (step 1E). The code assumes that all waves reside in the root folder.

Step 1A, 1B: Mathematical Treatments

HR results from Pika can include nans (Not a Number) and small negative (~ -1e-6ish) values. The APES code needs to know how to handle these values. Default options are to set the nans and negatives to zeros. Users should be aware that nan HR stick results from Pika should be investigated before this option is employed to ensure the validity of APES results. The APES code will return nans for instances where there are nans in the HR stick matrix and the user chooses not to change nans to zeros.

AMS chemical fragments do not ionize at equal proportions; calibration factors are needed. Default calibration factors are as given in the Aiken et. al. Anal. Chem. paper with the exception of the S/C factor which has not been found. It is given a default value of 1.

Step 1C - 1G The Definition of Organic Mass (OM)

OM is defined as the sum of the masses of all HR species which have at least one carbon atom. While this definition seems intuitive and straight-forward, the application of this definition for AMS data requires user input.

In the case of CO2, the Pika generated HR stick may reflect gas-phase and aerosol loadings. CO2 is often one of the larges components of OM, so it is critical to correctly partition this fragment. The frag checks in squirrel will inform this accurate partitioning. User choices are entered in section 1C of the panel. If the HR stick for CO2 is already correctly partitioned and reflects only the aerosol loading, then the user may enter 0 (ppm)for the estimate of the gas phase CO2 and the entire stick value will be used in the analysis.

In the case of CO, it may be difficult in Pika to accurately resolve this HR peak with its neighbor N2. User choices are entered in section 1D of the panel.

A portion of the non-carbon containing water fragments of H2O, OH and O should often be included in the definition of OM. For example organic acids often fragment into H2O, OH and O. Users are able to specify the amount of these three fragments which contribute to OM in step 1E of the panel. The default for this option is given as indicated in Aikin et al Anal Chem paper, Table S-3.

Users can include entire inorganic families of HR fragments to the total OM by using the checkboxes in step 1E. This option is intended for laboratory studies, when the organic aerosol is composed of a known compound. For example if laboratory generated aerosol contains only organic nitrates, the user may want to include all variations of NO fragments, which is the NO family.

The concept of families of HR fragments was introduced into Pika as a way of grouping similar fragments. In Pika, once the user selects the fragments to fit mask waves (waves with 1s and nans or 1s and 0s) are automatically created which indicate the truth/false of whether an ion belongs to a family. Every ion belongs to one and only one family. The Pika code tries to decipher the chemical formula to determine a fragment's family status. If the chemical formula is strange or not formatted properly the fragment may default to belong to the 'other' family.

Users can include additional individual HR fragments by entering the names of the HR fragments in step 1G. This list of HR fragments should be separated by commas; spaces will be ignored. This option is especially useful for the analysis of laboratory standards where all fragments should be more easily identified as originating from an organic molecule. When the OH family is checked, the partitioning of the water fragments H2O, OH and O will proceed as indicated in step 1D. The remaining HR fragments in the OH family (H3O, etc) will be included in OM as an other non-carbon containing fragment.

Users can exclude HR fragments which may be due to air or other interferring species that would otherwise be included in the OM grouping by entering the name of the HR fragment(s) in 1G. This list of HR fragments should be separated by commas, spaces will be ignored.

Step 2 Elemental Analysis

Users can opt to calculate and display the elemental ratios (Step 2A) or the elemental mass spectrum (Step 2B). The order in which either calculation is performed is irrelevant. Once the analysis has been performed, one can view the table of elemental mass fractions to troubleshoot and verify the correct parsing of the chemical formulas and the grouping of fragments to the organic mass entity.

Step 2A

When this button is pressed the code will sum the the elemental loadings and apply the calibration factors. If the Pika HR sticks are used, the results will be displayed as a time series (runs not in the chosen todo wave will have values of Nans). If user defined HR sticks were used, a simple table of all the ratios will be displayed.

Step 2B

When this button is pressed the code will find the elemental loadings and display the results as a mass spectrum. The elemental calibration factors are not applied in this analysis.

Light Scattering Module Analysis

Is under development.

Help

Are tutorials available?

Before using Squirrel, one should be familiar with the basic concepts of Igor. Several good Igor tutorials are available in the Wavemetrics/Igor Pro Folder/Learning Aids folder. You should know how to create, edit and find waves, and create, modify and find graphs.

Currently, there are 3 Squirrel presentations which can be downloaded:

  1. Squirrel overview power point presentation. The original form of this ppt was presented at the 2006 User's Meeting, and has been updated a few times since then.
  2. Squirrel pre-preprocessing power point presentation. This covers the m/z calibration and baseline fitting options.
  3. Squirrel post-preprocessing power point presentation. This covers the airbeam correction factor, DVa and DC marker calculations. It is available as a ppt.

How do I report a problem with the ToF-AMS Analysis software? (Squirrel, Pika, Apes, etc)

There are a few places you should look before reporting any problems.

  • The Technical FAQ
  • The release notes of the version of Squirrel you are using and previous version release notes, if appropriate.
  • The coding to do list, because the feature you are dealing with may not be implemented yet or will be updated.

There are a few things you should try before reporting any problems:

  • Make sure the problem is replicable.
  • Isolate the problem to simplest, smallest case where the problem still occurs.
  • Gather the following (as appropriate):
    • the operating system of the computer, version of Igor, error message and symptoms
    • a screen shot of the problem or "Save Graph" if appropriate (e.g. if a graph looks odd)
    • the Igor experiment if it is small, or an example DAQ hdf if the problem is in regard to a specific file
  • Then put files info a folder you create on the Aerodyne FTP site. This ftp site is ftp.aerodyne.com/ToF-AMS/SquirrelProblems/ and uses the same username and password as for downloading the ToF AMS software. Then fire off an email to Donna Sueper (sueper 'at' colorado.edu).

Please be aware that the latest versions of Squirrel will often have bugs fixed. Users should try upgrading to the latest Igor and ToF-AMS analysis software version to see if the problem persists.

How do I analyze AMS data with Squirrel?

The best resource is the wiki at http://cires.colorado.edu/jimenez-group/wiki/index.php/Field_Data_Analysis_Guide

How do I analyze AMS data with Pika?

The best resource is the wiki at http://cires.colorado.edu/jimenez-group/wiki/index.php/High_Resolution_ToF-AMS_Analysis_Guide



Retrieved from "http://cires1.colorado.edu/jimenez-group/wiki/index.php?title=ToF-AMS_Analysis_Software&oldid=5425"