FAQ

FAQ Page

This is not in-fact frequently asked questions, but things I have come up with myself (throughout I means A.J. London). Please ask some questions using the email contact and I will gladly add them here. This page includes some general comments as well as eplainations and solutions to common errors and warnings.

• FAQ Page
  • FAQ
    • Is there a description of the method for solving single-ion mass peak overlaps?
    • Why does AtomProbeLab exist?
    • Why Matlab?
    • What is the future of AtomProbeLab?
    • How do I get the overlap fit from massOverlapSolver?
    • How can I make averaged composition line profiles?
  • Common errors and warnings
    • Undefined function or variable
    • massOverlapSolver: No element for range
      • Warning
      • Explaination
      • Solution
    • overlapProblemBuilder: peaks not be assigned to ranges
      • Warning
      • Explaination
      • Solution

FAQ

Is there a description of the method for solving single-ion mass peak overlaps?

The idea for the method was first described by Cairney et. al (2015) (in the section on "Spectral decomposition in atom probe") but an improved version of the method with fewer limitations using maximum likelihood estimation was published by London et at. (2017).

AtomProbeLab is licensed under GPL and is not citeware, however, if you use this method in your work and publish it, you may find citing London et at. (2017) - for single-ion overlap solving or London (2019) - for quantification of uncertainty arising from overlaps, helpful.

Why does AtomProbeLab exist?

My PhD involved the analysis of a lot of atom probe microscopy data. Due to the limitations of the tools available at the time, I found helpful to start writing my own analysis tools in Matlab. Many of the earlier functions focused on cluster analysis and were badly written and overly specific. Later, I wrote more general functions that were helpful to other people. I shared my code with colleagues and having an online repository for the code was a natural progression. When London et at. (2017) was published it acted as a catalyst to but the code used in the paper online - and so AtomProbeLab was born.

Why Matlab?

While Matlab is great for somethings, I am aware Matlab is not an ideal choice for this project. It makes prototyping code and importing data very easy, but it makes a barrier for people to use the code (you have to pay for Matlab) and some of the functions would run much faster if written in C++. When I started out, Matlab was an obvious choice but as the project has evolved it has become less ideal. But because all this code exists, it might as well be free for everyone to use - if you have Matlab that is!

What is the future of AtomProbeLab?

This code will remain here for as long as sourceforge allows, but once I have implemented the outstanding features listed in the [TODO list], I am expecting to move on from developing AtomProbeLab. My hope is that I will be working on AtomProbeLab until the end of 2019 and then all the functionality will be migrated over to non-Matlab codes. For example, some "heavy" functions will be rewritten in C++ for libatomprobe and the high-level scripting functionality will most likely be moved over to R.

How do I get the overlap fit from massOverlapSolver?

Basically for each overlap group we need the actual counts and the fit. The following sections of code are taken from demoScript_bulkDecomp.m and the following assumes you have run that script, or at least massOverlapSolver like so:

[comp_ele,eleNames,comp_ionic,ionNames,deconvCounts,asRangedCounts ,...
    rangeTableDecompEle,rangeTableDecompIonic,overlapIonicRangeComp, ...
    ionAmounts] = massOverlapSolver(OP,confidenceAlpha,useWeightPercent);

And that you have the overlap problem stored in a struct called OP (to build an overlap problem see [overlapProblemBuilder]).
The following is taken from a loop over all the different overlap groups, with the loop variable "o".

% Get overlap fit details
s = OP.overlapTable{o};

This is the abundance matrix for this overlap, first column are the peak centres, other columns are each ion.

ionAmounts1 = ionAmounts{o}(1:end-1);

This is the amounts of each ion in this overlap group, last entry is the residual counts.

ionicRangeComp = overlapIonicRangeComp{o}(:,2:end); 

This is a matrix which has what proportion of each ion is in each range...

rangeCounts1 = overlapIonicRangeComp{o}(:,1);  

... and the 1st column is the range counts.
The amount of each ion in each range is given by the following:
- To get the fit for each bar
- Multiply the ideal peak abundance by the number of each ion
Note: bsxfun does a column-wise multiplication, multiplying each column of s by each item in ionAmounts1 - it's a shortcut where a loop would otherwise be used.

barValues = bsxfun(@times,s(:,2:end),ionAmounts1);

Plot a bar graph of the computed peak heights. Matlab plots each column of barValues as separately coloured bars, one column for each ion = one bar at each x-position for one ion (then there are multiple columns). Then over the top, plot the actual measured range counts from rangeCounts1 using a "x" marker.

bar(s(:,1),barValues,1,'stacked')
hold on
% Actual measured range counts as x's - plots the measured data against the fit
plot(s(:,1),rangeCounts1,'kx');
hold off

If you plot the residual as well then the bar height will exactly match the measured peak counts. It gets a bit confusing though, as the residual can make up a short bar to the "x" or a negative residual, then it plots over the top of the bar which goes above the "x" - which looks weird.

How can I make averaged composition line profiles?

You can use the script in src/cluster/ called [averagedCompLineProfiles_script].m
You need a cluster statistics files created by IVAS, pos files and range files. The cluster stats file is used to define the size and location of the clusters, so you don't need to use IVAS, but that is how it is set up at the moment.
Running it with the data supplied is very boring, but if you supply your own lists of files it should work.
It is still rather early in development... but it should be enough to save you many hours of doing line profiles manually.

Common errors and warnings

---

Undefined function or variable

---

I get an error like:

Undefined function or variable 'localDecomp_atom'.

Error in demoScript_localDecomp (line 23)

If the "Undefined function" is one you would expect to be found in AtomProbeLab, then you probably haven't added the AtomProbeLab/src folder to your MATLAB path. You can add it for the current session with:

addpath('src\');

Or you can add it permanently using:

savepath('src\');

If the function is related to something in the curve fitting or statistics tool box, then you will need to install those MATLAB tool boxes first.

massOverlapSolver: No element for range

---

Warning

In massOverlapSolver you may get a warning like so:

Warning: No element for range:
Range:  6 @ 101.4 Da, original range entry: Pd
Range:  1 @  52.7 Da, original range entry: Pd
Range: 21 @ 112.8 Da, original range entry: PdH2

Explaination

This happens when there is a range in the range file (see [RRNG]) which contains an ion and that ion is considered part of an overlap but the range is not considered part of the overlap. In the warning above, the Pd⁺ and PdH₂⁺ ions are overlaped. Range 21 at 113 Da was originally ranged as PdH₂, however, this has a natural abundance of 0.0035%. The overlap problem was made using with a minimum abundance limit of 0.04 % (see [overlapProblemBuilder]), therefore this range was not included in solving the overlap. As a result the counts from this range are not included in the composition result.

Solution

Either:

• Remove the range from the range file: the range no longer exisits and it contributes no counts to the overall composition
• Set a lower minimum abundance limit in [overlapProblemBuilder]: now the range will be correctly identified as belonging to the the Pd⁺ and PdH₂⁺ overlap.

overlapProblemBuilder: peaks not be assigned to ranges

---

Warning

Warning: *** Some peaks could not be assigned to ranges ***
O+             abun.:   0.20%  :  18.0 Da
*** These peaks will not be included in the overlap calculation ***

Explaination

When [overlapProblemBuilder] is used with the 'rangeFile' option (you supply a range file and these ranges define where peaks of different ions overlap), there can be a mis-match between the peaks defined by the ions and the mass-window ranges supplied. Above, the mass peak of O⁺, with a natural abundance of 0.2%, at 18 Da does not fall into any of the ranges supplied. Any ions with unranged intensity will not be included in further calculations. In the example above, O⁺ would effectively change from 99.8% ¹⁶O and 0.2% ¹⁸O to just being 100% ¹⁶O. Note: the minimum abundance limit already excluded ¹⁸O with a natural abundance of 0.04%.

Therefore, if O⁺ overlapped with Ti³⁺, then any counts in the 18 Da peak will not be included in either solving the overlap or the resulting composition.

Solution

• Ignore it. You may not want to include the ions identified in the warning message. If they are small peaks with low intensities, you may introduce additional errors (through background noise and background correction) by ranging these peaks.
• Range the peaks identified. The counts from these ranges will be used in all subsequent calculations.
• Lower the minimum abundance (using the 'minAbundance' option in [overlapProblemBuilder]) so that these mass peaks are excluded. E.g. set the minimum abundance to 0.2%, this will exclude ¹⁸O.