GC-IRMS Processing

pysotope.iso_process(user_linearity_conditions=False, min_area_threshold=None, include_parabolic=False, force_linearity_model=None)[source]

Main processing pipeline for GC-IRMS isotope data.

This function executes the complete correction workflow for compound-specific isotope measurements, including:

  • Instrument drift correction

  • Linearity (area-dependent) correction

  • Reference standard normalization (e.g., VSMOW or VPDB)

  • Optional methanol/PAME correction

  • Outlier removal

  • Replicate averaging with propagated uncertainty

  • Figure generation and export

  • Final results export to disk

The function is file-based and does not return data objects. All intermediate and final results are written to structured output folders along with diagnostic figures and a processing log.

Parameters:

  • user_linearity_conditions (dict or bool, default=False) – Optional user-defined configuration for linearity correction. If provided, overrides automatically determined regression conditions (e.g., selected standards or model form).

  • min_area_threshold (float or None, default=None) – Minimum peak area required for inclusion in processing. Peaks below this threshold are removed prior to correction. If None, no area-based filtering is applied.

  • include_parabolic (bool, default=False) – If True, includes a second-order (parabolic) term in the linearity correction model. If False, a linear model is used.

  • force_linearity_model (str, default = None,) – Used to force the type of model used for linearity correction. Can be “linear”, “decay”, “growth”, or “parabolic”.

  • Outputs

  • -------

  • disk (This function writes the following to)

  • (drift (• Diagnostic plots)

  • linearity

  • standard (reference)

  • results (• Mean of corrected sample)

  • results

  • uncertainties (• Final processed dataset with propagated)

  • (drift

  • linearity

  • standards

  • outliers)

  • steps (• Processing log file documenting all correction)

  • Figures (• Correction)

  • returned. (No objects are)

Notes

Processing sequence:

  1. Isotope system selection

  2. Output directory creation

  3. Standards loading

  4. Data import and classification

  5. Area-based filtering (optional)

  6. Drift correction (time-based regression)

  7. Linearity correction (area-based regression)

  8. Reference standard normalization

  9. Optional methanol/PAME correction

  10. Optional hydrogen or carbon isotope calculation of methanol from PAME

  11. Outlier removal

  12. Replicate averaging with uncertainty propagation

  13. Final export and figure generation

Uncertainty Propagation

Analytical uncertainty is propagated analytically through:

  • Drift regression parameter covariance

  • Linearity regression parameter covariance

  • Reference standard scaling uncertainty

  • Methanol correction uncertainty (if applicable)

  • Replicate variability

All variance components are combined using first-order Taylor series propagation and reported in the final dataset.

pysotope.assign_chain_length(output_location=None, rt_min=0, rt_max=2500, chain_lengths=['C16', 'C18', 'C20', 'C22', 'C24', 'C26', 'C28', 'C30', 'C32'])[source]

Interactively assign chain-length labels to compounds based on retention time.

This function allows the user to define retention-time (RT) windows corresponding to specific chain-length compounds (e.g., C16–C32). The assigned chain labels are written to a configuration file and used downstream in the iso_process correction workflow.

The function is typically used during initial setup or when chromatographic conditions change and retention times must be re-mapped.

Parameters:

  • output_location (str or pathlib.Path, optional) – Path to the processed output file containing retention time information. If provided, the file is loaded and used to visualize compound RT positions for interactive selection. If None, the function may prompt the user to select a file.

  • rt_min (float, default=0) – Minimum retention time (in seconds) considered when assigning chain-length windows.

  • rt_max (float, default=2500) – Maximum retention time (in seconds) considered when assigning chain-length windows.

  • chain_lengths (list of str, default=['C16', 'C18', ..., 'C32']) – List of chain identifiers to be assigned. Each entry represents a compound whose RT window will be defined interactively. Custom chain sets may be provided if needed.

Returns:

  • None – This function does not return a value. Instead, it updates the chain configuration file (e.g., chains.json) stored within the package directory.

  • Functionality

  • ————-

  • - Loads peak retention time data.

  • - Displays chromatographic information for user inspection.

  • - Allows interactive selection of RT windows for each chain length.

  • - Saves updated chain definitions to configuration.

    • These definitions are used by iso_process for compound matching.

Notes

  • Accurate retention-time assignment is critical for correct standard identification and downstream corrections.

  • If chromatographic conditions shift (e.g., column change, temperature program modification), chain windows should be redefined.

  • The saved configuration affects all subsequent processing runs.

pysotope.standard_editor()[source]
Return type:

None

Elemental Analyzer (EA)

pysotope.ea_process()[source]

Process Elemental Analyzer (EA-IRMS) isotope data through drift correction, VPDB calibration, and uncertainty propagation.

This function executes the full EA isotope processing workflow. It imports raw EA-IRMS data, applies instrumental drift correction, performs VPDB normalization using reference standards, calculates analytical uncertainties, and writes intermediate and final results to disk.

Processing Steps

  1. Create project output directory structure.

  2. Load EA reference standards.

  3. Import raw EA data file.

  4. Apply time-based drift correction.

  5. Apply VPDB scale calibration.

  6. Compute propagated analytical uncertainties.

  7. Export intermediate and final processed datasets.

Workflow Details

Drift Correction

Corrects for temporal instrument drift using standard measurements throughout the analytical run. The correction parameters are saved for use in subsequent calibration steps.

VPDB Calibration

Converts drift-corrected isotope values to the VPDB scale using regression-based normalization against certified reference standards.

Uncertainty Propagation

Calculates final analytical uncertainty by combining: - Measurement precision - Drift model uncertainty - Calibration regression uncertainty

Outputs

Drift_Results.csv

Dataset after drift correction.

VPDB_Results.csv

Dataset after VPDB normalization.

EA_processed_<project_name>.csv

Final dataset including calibrated isotope values and propagated analytical uncertainties.

returns:

Results are written directly to the output directory. The function does not return a DataFrame.

rtype:

None

Notes

  • This function assumes EA reference standards are properly defined in the EA standards configuration file.

  • All processing steps append metadata and results to a log file for traceability and reproducibility.

  • The processing pipeline is deterministic and does not include interactive user input.

  • Errors are propagated analytically using first-order variance propagation methods.