DOCSEARCHbyAlgolia
Submit Docs

pyrolite: Python for Geochemistry

repository·main·Indexed 41 days ago

https://github.com/morganjwilliams/pyrolite

A Python library for geochemical data analysis, specializing in rock and mineral chemistry. It provides tools for compositional data manipulation, variable transformation, and advanced visualization including ternary diagrams, spiderplots, and density plots. The library features Pandas-based interfaces via pyrocomp, pyrochem, and pyroplot, and includes geochemical modeling for trace element partitioning and REE patterns.

Tokens
3.8K
Snippets
15
Records
25
Agent score
51%

What's inside pyrolite

  1. Overview of pyrolite capabilities

    main

    pyrolite is a Python toolkit designed for geochemical data analysis. It provides specialized functions for:

    • Compositional Data Analysis: Tools to work with and manipulate compositional datasets.
    • Variable Transformation: Functions to transform geochemical variables, such as converting elemental concentrations to oxide concentrations.
    • Geochemical Plotting: Specialized plotting utilities including spiderplots, ternary diagrams, and both bivariate and ternary density diagrams.
    • Auxiliary Utilities: Various helper functions for common geochemical data tasks.

  2. Overview of pyrolite for geochemical data analysis

    main

    pyrolite is a Python package designed for processing, transforming, and visualizing multivariate geochemical data, specifically focusing on rock and mineral chemistry. It provides tools for:

    • Compositional Data Handling: The pyrolite.comp submodule provides methods for transforming compositional data (data that sums to 100%) to facilitate robust statistical practices.
    • Visualization: Includes standard diagrams (ternary, spider, data-density), templated diagrams (e.g., Total-Alkali Silica, Pearce diagrams), and novel methods to reduce 'overplotting' using density-based approaches.
    • Data Normalization: Includes reference datasets for compositional reservoirs (e.g., CI-Chondrite, Bulk Silicate Earth, Mid-Ocean Ridge Basalt) and rock-forming mineral endmembers.
    • Geochemical Modeling: Implements models like the lattice strain model (trace element partitioning), Sulfur Content at Sulfur Saturation (SCSS), and orthogonal polynomial decomposition for REE patterns.
    • Machine Learning Readiness: Provides a foundation for preparing geochemical data for use with scikit-learn.

  3. Explore the pyrolite API modules

    main

    The pyrolite library is organized into several functional modules. Depending on your task, you should import from one of the following top-level packages:

    • pyrolite.plot: Visualization tools including spider diagrams, density plots, ternary plots, parallel coordinate plots, and biplots.
    • pyrolite.geochem: Geochemical analysis tools including normalization, transformations, parsing, magma modeling, alteration modeling, and isotope/ion calculations.
    • pyrolite.comp: Compositional data analysis tools including aggregation, imputation, and handling of compositional data structures.
    • pyrolite.mineral: Tools specifically for mineralogical data.
    • pyrolite.util: A collection of utility functions for general tasks, pandas integration, mathematical operations, spatial analysis, unit conversions, and more.

  4. How pyrolite integrates with pandas via accessor classes

    main

    The pyrolite API is designed to be intuitive for users familiar with pandas. It uses dataframe accessor classes to add new namespaces to existing pandas DataFrames. This allows you to call pyrolite methods directly on your data objects using a familiar syntax.

    For example, instead of passing a DataFrame to a standalone function, you can use the .pyroplot accessor to call plotting methods like .spider() directly on the DataFrame object.

    # Conceptual example of the accessor pattern
df.pyroplot.spider()

  5. Data conventions for pyrolite: Tidy tables and Oxygen handling

    main

    To use pyrolite effectively, your data should follow these two core conventions:

    Tidy Geochemical Tables

    pyrolite operates on pandas DataFrames following 'tidy data' principles:

    • Columns: Each geochemical variable or component (e.g., an element or an oxide) must be a column.
    • Rows: Each row represents a single observation.
    • Naming: Column names must be identifiable as either element-based (e.g., Ca, Mg) or oxide-based (e.g., MgO, Al2O3). Names should contain only one element excluding oxygen. Avoid names like Ti_ppm or complex formulas like Ca3Al3(SiO4)3.

    Open to Oxygen

    pyrolite assumes the system is open to oxygen. All geochemical calculations conserve mass for all elements except oxygen. This simplifies calculations by avoiding the need to account for a 'free oxygen' phase.

  9. Cite pyrolite in research

    main

    If you use pyrolite extensively for research, please cite the software to help quantify its impact and support the project.

    General Citation

    The standard citation for pyrolite is the Journal of Open Source Software (JOSS) paper. Note that the paper refers to pyrolite v0.2.7; if you are using a different version, please specify that in your citation.

    Format: Williams et al., (2020). pyrolite: Python for geochemistry. Journal of Open Source Software, 5(50), 2314, doi: 10.21105/joss.02314

    Citing Lambdas

    If you are specifically using the lambdas implementation within pyrolite, you should cite the following publication instead:

    Format: Anenburg, M., & Williams, M. J. (2021). Quantifying the Tetrad Effect, Shape Components, and Ce–Eu–Gd Anomalies in Rare Earth Element Patterns. Mathematical Geosciences. doi: 10.1007/s11004-021-09959-5

    @article{Williams2020,
  title = {pyrolite: Python for geochemistry},
  author = {Morgan J. Williams and
            Louise Schoneveld and
            Yajing Mao and
            Jens Klump and
            Justin Gosses and
            Hayden Dalton and
            Adam Bath and
            Steve Barnes},
  year = {2020},
  journal = {Journal of Open Source Software}
  doi = {10.21105/joss.02314},
  url = {https://doi.org/10.21105/joss.02314},
  publisher = {The Open Journal},
  volume = {5},
  number = {50},
  pages = {2314},
}

  10. Run pyrolite unit tests

    main

    After installing the package in editable mode with development dependencies (pip install -e .[dev]), you can run the full suite of unit tests using pytest via uv run from the root directory. To run a specific subset of tests, provide the path to the test file or folder.

    # Run all tests
uv run pytest

# Run a specific test or folder
uv run pytest ./test/<path to test or test folder>

  12. Install pyrolite via pip

    main

    You can install pyrolite from PyPI using pip. It is generally recommended to use the --user flag to perform a user-level installation. This helps avoid permission issues and conflicts, particularly on systems with a system-level Python installation (such as Linux, WSL, or macOS).

    Note: pyrolite is not currently packaged for Anaconda; conda install pyrolite is not supported.

    pip install --user pyrolite