leafwaxtools User API

leafwaxtools is a Python package.

The following describes the Chain and Isotope classes that support the functionality of leafwaxtools

Chain (leafwaxtools.Chain)

class leafwaxtools.api.chain.Chain(input_data)[source]

Represents leaf wax carbon chain-length concentration/abundance data imported as a 2-D, array-like object (i.e., list, array) with rows representing unique samples and columns representing unique data types (carbon chain-length number).

Parameters:: input_data (2-D array-like) – User leaf wax chain-length concentration/abundance data.

input_data

User leaf wax chain-length concentration/abundance data.

Type:: 2-D array-like

Examples

from leafwaxtools import Chain

Methods

`acl`(chain_lengths)	Calculates the Average Chain-Length (ACL; Bray & Evans, 1961; Bush & McInerney, 2013) of each sample (rows).
`corr_pvals`([minimum_obs])	Calculates the Pearson correlation p-values between each leaf wax chain-length (columns).
`corr_rvals`([minimum_obs])	Calculates the Pearson correlation r-values between each leaf wax chain-length (columns).
`cpi`(chain_lengths[, even_over_odd])	Calculates the Carbon Preference Index (CPI; Marzi et al., 1993) of each sample (rows).
`pca`(chain_lengths[, use_clr])	Performs a Principal Component Analysis (PCA) on the leaf wax chain-length data with the centered log-ratio transform (clr; Aitchison, 1982) applied to the input compositional data (Gloor et al. 2017).
`relative_abd`([calculate_percent])	Calculates the relative abundance (fraction out of 1 or percentage) of each leaf wax carbon chain-length (columns) for each sample (rows).
`total_conc`([zero_total, calculate_log])	Calculates the total concentration of each sample (rows).

acl(chain_lengths)[source]

Calculates the Average Chain-Length (ACL; Bray & Evans, 1961; Bush & McInerney, 2013) of each sample (rows).

References:

Bray, E. E., & Evans, E. D. (1961). Distribution of n-paraffins as a clue to recognition of source beds. Geochimica et Cosmochimica Acta, 22(1), 2-15. https://doi.org/10.1016/0016-7037(61)90069-2

Bush, R. T., & McInerney, F. A. (2013). Leaf wax n-alkane distributions in and across modern plants: Implications for paleoecology and chemotaxonomy. Geochimica et Cosmochimica Acta, 117, 161-179. https://doi.org/10.1016/j.gca.2013.04.016

Parameters:

chain_lengths (list) – List of integers or floats representing the carbon chain-length number of each column.

Raises:

TypeError – Raises an error if ‘chain_lengths’ is not a list.
ValueError – Raises an error if ‘chain_lengths’ is an empty list.

Returns:

acl – 1-D Numpy array of ACL values for each sample (row).

Return type:

numpy.ndarray

corr_pvals(minimum_obs=2)[source]

Calculates the Pearson correlation p-values between each leaf wax chain-length (columns). To be extended with other correlation methods (Spearman, Kendall Tau) in a future version.

Parameters:: minimum_obs (int, optional) – Minimum number of observations (samples/rows) required to return a Pearson r-value. The default is 2.
Returns:: p_vals – 2-D Numpy array of Pearson correlation p-values between each leaf wax chain-length (column).
Return type:: numpy.ndarray

corr_rvals(minimum_obs=2)[source]

Calculates the Pearson correlation r-values between each leaf wax chain-length (columns). To be extended with other correlation methods (Spearman, Kendall Tau) in a future version.

Parameters:: minimum_obs (int, optional) – Minimum number of observations (samples/rows) required to return a Pearson r-value. The default is 2.
Returns:: r_vals – 2-D Numpy array of Pearson correlation r-values between each leaf wax chain-length (column) with all values in the major diagonal equal to 1.
Return type:: numpy.ndarray

cpi(chain_lengths, even_over_odd=True)[source]

Calculates the Carbon Preference Index (CPI; Marzi et al., 1993) of each sample (rows).

References:

Marzi, R., Torkelson, B. E., & Olson, R. K. (1993). A revised carbon preference index. Organic Geochemistry, 20(8), 1303-1306. https://doi.org/10.1016/0146-6380(93)90016-5

Parameters:

chain_lengths (list) – List of integers or floats representing the carbon chain-length number of each column.
even_over_odd (bool, optional) – Calculates the CPI of even-chain over odd-chain leaf waxes (use case for n-alkanoic acids). Change to False to calculate the CPI of odd-chain over even-chain waxes (use case for n-alkanes). The default is True.

Raises:

TypeError – Raises an error if ‘chain_lengths’ is not a list.
ValueError – Raises an error if ‘chain_lengths’ is an empty list or if ‘even_over_odd’ is neither True nor False.

Returns:

cpi – 1-D Numpy array of CPI values for each sample (row).

Return type:

numpy.ndarray

pca(chain_lengths, use_clr=True)[source]

Performs a Principal Component Analysis (PCA) on the leaf wax chain-length data with the centered log-ratio transform (clr; Aitchison, 1982) applied to the input compositional data (Gloor et al. 2017).

References:

Aitchison, J. (1982). The statistical analysis of compositional data. Journal of the Royal Statistical Society: Series B (Methodological), 44(2), 139-160. https://doi.org/10.1111/j.2517-6161.1982.tb01195.x

Gloor, G. B., Macklaim, J. M., Pawlowsky-Glahn, V., & Egozcue, J. J. (2017). Microbiome datasets are compositional: and this is not optional. Frontiers in microbiology, 8, 2224. https://doi.org/10.3389/fmicb.2017.02224

Parameters:

chain_lengths (list) – List of integers or floats representing the carbon chain-length number of each column..
use_clr (bool, optional) – Calculates the clr of the leaf wax chain-length abundance data, replacing 0 values with 1/N where N is the number of chain-lengths (columns). The default is True.

Raises:

TypeError – Raises an error if ‘chain_lengths’ is not a list.
ValueError – Raises an error if ‘chain_lengths’ is an empty list or if ‘use_clr’ is neither True nor False.

Returns:

pca_dict – Dictionary of PCA results including the PC scores for each factor loading (chain-lengths/columns) and sample (rows). For more details on all of the returns in pca_dict[‘pca’], please see the documentation for the scikit-learn PCA function (sklearn.PCA()) https://scikit-learn.org/stable/modules/generated/sklearn.decomposition.PCA.html

Return type:

dict

relative_abd(calculate_percent=False)[source]

Calculates the relative abundance (fraction out of 1 or percentage) of each leaf wax carbon chain-length (columns) for each sample (rows).

Parameters:: calculate_percent (bool, optional) – Calculate each chain-length relative abundance as a percentage instead of a fraction of 1. The default is False.
Raises:: ValueError – Raises an error when ‘calculate_percent’ is neither True nor False.
Returns:: rel_abd – 2-D Numpy array of leaf wax chain-length relative abundances (columns) for each sample (row).
Return type:: numpy.ndarray

total_conc(zero_total=0, calculate_log=False)[source]

Calculates the total concentration of each sample (rows).

Parameters:

zero_total (int, optional) – Return value if the sum of all columns in a row = 0. The default is 0.
calculate_log (bool, optional) – Returns log (base e) of the sum of each row instead of just the sum. The default is False.

Raises:

ValueError – Raises an error when ‘calculate_log’ is neither True nor False.

Returns:

total_conc – 1-D Numpy array of total leaf wax concentrations for each sample (row).

Return type:

numpy.ndarray

Isotope (leafwaxtools.Isotope)

class leafwaxtools.api.isotope.Isotope(input_data)[source]

Represents leaf wax compound-specific stable isotope data imported as a 2-D, array-like object (i.e., list, array) with rows representing unique samples and columns representing unique data types (carbon chain-length number).

Parameters:: input_data (2-D array-like) – User leaf wax isotope data.

input_data

User leaf wax isotope data.

Type:: 2-D array-like

Examples

from leafwaxtools import Isotope

Methods

`conc_avg`(chain_data)	Calculates the chain-length concentration-weighted average isotope value of each sample (rows) using .
`corr_pvals`([minimum_obs])	Calculates the Pearson correlation p-values between each leaf wax chain-length (columns).
`corr_rvals`([minimum_obs])	Calculates the Pearson correlation r-values between each leaf wax chain-length (columns).
`epsilon`([epsilon_numerator, epsilon_denominator])	Calculates the isotopic fractionation factor (epsilon) between stable isotope values/arrays (permil units) in the numerator and denominator of the following equation (e.g., Diefendorf & Freimuth, 2017):
`value_range`()	Calculates the maximum isotope value range (max - min) between all chain-lengths (columns) of each sample (rows).
`wax_to_source`(epsilon[, epsilon_numerator])	Calculates the isotopic value of a source material to a leaf wax using an isotopic fractionation factor (epsilon).

conc_avg(chain_data)[source]

Calculates the chain-length concentration-weighted average isotope value of each sample (rows) using .

Parameters:: chain_data (2-D array-like) – User leaf wax chain-length concentration/abundance data. Must be the same shape (same number of rows and columns) as the user isotope input data. Chain-length data with a value of NaN is treated as having a concentration/abundance of 0.
Raises:: ValueError – Raises an error when Isotope.data and ‘chain_data’ are not the same shape (same number of rows and columns).
Returns:: conc_avg – 1-D Numpy array of chain-length concentration-weighted average isotope values for each sample (row).
Return type:: numpy.ndarray

corr_pvals(minimum_obs=2)[source]

Calculates the Pearson correlation p-values between each leaf wax chain-length (columns). To be extended with other correlation methods (Spearman, Kendall Tau) in a future version.

Parameters:: minimum_obs (int, optional) – Minimum number of observations (samples/rows) required to return a Pearson r-value. The default is 2.
Returns:: p_vals – 2-D Numpy array of Pearson correlation p-values between each leaf wax chain-length (column).
Return type:: numpy.ndarray

corr_rvals(minimum_obs=2)[source]

Calculates the Pearson correlation r-values between each leaf wax chain-length (columns). To be extended with other correlation methods (Spearman, Kendall Tau) in a future version.

Parameters:: minimum_obs (int, optional) – Minimum number of observations (samples/rows) required to return a Pearson r-value. The default is 2.
Returns:: r_vals – 2-D Numpy array of Pearson correlation r-values between each leaf wax chain-length (column) with all values in the major diagonal equal to 1.
Return type:: numpy.ndarray

epsilon(epsilon_numerator=None, epsilon_denominator=None)[source]

Calculates the isotopic fractionation factor (epsilon) between stable isotope values/arrays (permil units) in the numerator and denominator of the following equation (e.g., Diefendorf & Freimuth, 2017):

epsilon = (((1000 + numerator) / (1000 + denominator)) - 1) * 1000

This equation is based on epsilon calculations for leaf wax stable hydrogen and carbon isotope vlaues.

References:

Diefendorf, A. F., & Freimuth, E. J. (2017). Extracting the most from terrestrial plant-derived n-alkyl lipids and their carbon isotopes from the sedimentary record: A review. Organic Geochemistry, 103, 1-21. https://doi.org/10.1016/j.orggeochem.2016.10.016

Parameters:

epsilon_numerator (1-D or 2-D array-like, optional) – Numerator stable isotope value/array. Uses Isotope.data by default if no argument is passed. The default is None.
epsilon_denominator (1-D or 2-D array-like, optional) – Denominator stable isotope value/array. Uses Isotope.data by default if no argument is passed. The default is None.

Returns:

epsilon – 1-D or 2-D array-like of epsilon values for each sample (row) and chain-length (column; if applicable).

Return type:

1-D or 2-D array-like

value_range()[source]

Calculates the maximum isotope value range (max - min) between all chain-lengths (columns) of each sample (rows).

Returns:: value_range – 1-D Numpy array of maximum isotope value ranges for each sample (row).
Return type:: numpy.ndarray

wax_to_source(epsilon, epsilon_numerator=None)[source]

Calculates the isotopic value of a source material to a leaf wax using an isotopic fractionation factor (epsilon). A common application is the calculation of source water (e.g., precipitation, lake water) stable hydrogen isotope (d2H) values using leaf wax d2H values and an associated epsilon value between the source water and leaf wax (e.g., Feakins, 2013; Holtzman et al., 2025).

References:

Feakins, S. J. (2013). Pollen-corrected leaf wax D/H reconstructions of northeast African hydrological changes during the late Miocene. Palaeogeography, Palaeoclimatology, Palaeoecology, 374, 62-71. https://doi.org/10.1016/j.palaeo.2013.01.004

Holtzman, H., Thomas, E. K., Erb, M., Marshall, L., Castañeda, I. S., Kaufman, D., … & Melles, M. (2025). Early Holocene atmospheric circulation changes over northern Europe based on isotopic and biomarker evidence from Kola Peninsula. Paleoceanography and Paleoclimatology, 40(3), e2024PA005076. https://doi.org/10.1029/2024PA005076

Parameters:

epsilon (1-D or 2-D array-like) – Isotopic fractionation factor (epsilon) value/array.
epsilon_numerator (1-D or 2-D array-like, optional) – Numerator stable isotope value/array. Uses Isotope.data by default if no argument is passed. The default is None.

Returns:

source_isotope – 1-D or 2-D array-like of source isotope values for each sample (row) and chain-length (column; if applicable).

Return type:

1-D or 2-D array-like