starlingrt documentation#
STARLINGrt is a tool for analyzing retention times from gas chromatogaphy mass spectrometry (GCMS). It can be used to determine a consensus value for compounds by visualizing a collection of results. Compound identification(s) made at a given retention time are assumed to be provided by a separate code which analyzes the mass spectrometry data collected at that time. Currently, STARLINGrt is configured to work with the outputs from MassHunter(TM) but is extensible by subclassing “data._SampleBase” (see samples.py for an example). The code produces an interactive HTML file using Bokeh which can be modified interactively, saved, exported and shared easily between different users. The name “starling” was selected as a reverse acronym of the tool’s purpose.
Use Cases#
Imagine you have multiple GCMS output files which have been used to identify chemicals at different retention times, e.g., using some sort of library. In principle, these could correspond to analyses of a range of different mixtures; regardless, an individual component should elute at the same time regardless of what it is combined with. However, natural variations in:
the retention times can cause confusion when other compounds coelute or elute at very similar times,
the mass spectrometry peak location(s) at a given retention time can cause the identification routine to identify the same compound differently.
Given these uncertainties we would like to learn things like:
What is a consensus value, or at least a natural range, of retention times for each compound identified?
What compounds elute at similar points and are commonly confused with each other?
Are there any analyses that identify a compound at a retention time far away from its consensus value (data cleaning)?
What is a natural “gap” in retention times that can be used to “ideally” divide all compounds from their “neighbors”?
This visualization tool helps users answer these questions by exploring their data with interactive graphs. The output of this tool is an HTML file that acts as a self-contained summary of your data, how you cleaned / modified it, and can be easily shared between users.
Example#
Here is a simple example (see docs/_static/example.py):
import os
import starlingrt
from starlingrt import sample, data, functions, visualize
def load_mass_hunter(input_directory):
"""
Parameters
---------
input_directory : str
Directory to seach for raw folders are in.
Returns
-------
samples : list(sample.MassHunterSample)
List of Samples collected from all directories in `input_directory`.
"""
...
return samples
top_entries = starlingrt.data.Utilities.select_top_entries(
starlingrt.data.Utilities.create_entries(
load_mass_hunter(
"path/to/data/"
)
)
)
starlingrt.visualize.make(
top_entries=top_entries,
width=1200,
threshold=starlingrt.functions.estimate_threshold(starlingrt.functions.get_dataframe(top_entries)[0]),
output_filename='summary.html',
)
Contributors#
This code was developed during a collaboration with:
License Information#
See LICENSE.md for more information.
Any mention of commercial products is for information only; it does not imply recommendation or endorsement by NIST.