pyrolite Documentation Release 0.3.0+88.g052ca43 Morgan Williams Sep 23, 2021 Getting Started 1 Introduction 1 2 Why pyrolite? 3 3 Getting Started 5 4 Development 129 5 Reference 157 Bibliography 297 Python Module Index 299 Index 301 i ii CHAPTER 1 Introduction pyrolite is a set of tools for making the most of your geochemical data. The python package includes functions to work with compositional data, to transform geochemical variables (e.g. elements to oxides), functions for common plotting tasks (e.g. spiderplots, ternary diagrams, bivariate and ternary density diagrams), and numerous auxiliary utilities. • On this site you can browse the API, or look through some of the usage examples. • There’s also a quick installation guide, a list of recent changes and some notes on where the project is heading in the near future. • If you’re interested in contributing to the project, there are many potential avenues, whether you’re experienced with python or not. Note: pyrolite has been published in the Journal of Open Source Software, and a recent publication focusing on using lambdas and tetrads to parameterise Rare Earth Element patterns has been published in Mathematical Geosciences! 1 pyrolite Documentation, Release 0.3.0+88.g052ca43 2 Chapter 1. Introduction CHAPTER 2 Why pyrolite? The name pyrolite is an opportunistic repurposing of a term used to describe an early model mantle composition proposed by Ringwood [Ringwood1962], comprised principally of pyr-oxene & ol-ivine. While the model certainly hasn’t stood the test of time, the approach optimises the aphorism “All models are wrong, but some are useful” [Box1976]. It is with this mindset that pyrolite is built, to better enable you to make use of your geochemical data to build and test geological models. 3 pyrolite Documentation, Release 0.3.0+88.g052ca43 4 Chapter 2. Why pyrolite? CHAPTER 3 Getting Started 3.1 Installation pyrolite is available on PyPi, and can be downloaded with pip: pip install --user pyrolite Note: With pip, a user-level installation is generally recommended (i.e. using the --user flag), especially on systems which have a system-level installation of Python (including *.nix, WSL and MacOS systems); this can avoid some permissions issues and other conflicts. For detailed information on other pip options, see the relevant docs. pyrolite is not yet packaged for Anaconda, and as such conda install pyrolite will not work. 3.1.1 Upgrading pyrolite New versions of pyrolite are released frequently. You can upgrade to the latest edition on PyPi using the --upgrade flag: pip install --upgrade pyrolite See also: Development Installation 3.1.2 Optional Dependencies Optional dependencies (dev, skl, spatial, db, stats, docs) can be specified during pip installation. For example: pip install --user pyrolite[stats] pip install --user pyrolite[dev,docs] 5 pyrolite Documentation, Release 0.3.0+88.g052ca43 3.2 Getting Started Note: This page is under construction. Feel free to send through suggestions or questions. 3.2.1 Getting Set Up Before you can get up and running with pyrolite, you’ll need to have a distribution of Python installed. If you’re joining the scientific Python world, chances are that the Anaconda distributions are a good match for you*0. Check PyPI for the most up to date information regarding pyrolite compatibility, but as of writing this guide, pyrolite is known to work well with Python 3.5, 3.6 and 3.7. When it comes to how you edit files and interact with Python, there are now many different choices (especially for editors), and choosing something which allows you to work the way you wish to work is the key aspect. While you can certainly edit python files (.py) in any text editor, choosing an editor designed for the task makes life easier. Choosing one is subjective - know that many exist, and perhaps try a few. Integrated Development Environments (IDEs) often allow you to quickly edit and run code within the same window (e.g. Spyder, which is typically included in the default Anaconda distribution). Through notebooks and related ideas the Jupyter ecosystem has broadened how people are interacting with code across multiple languages, including Python. For reference, pyrolite has been developed principally in Atom, leveraging the Hydrogen package to provide an interactive coding environment using Jupyter. Finally, consider getting up to speed with simple Git practises for your projects and code such that you can keep versioned histories of your analyses, and have a look at hosted repository services (e.g. GitHub, GitLab). These hosted repositories together with integrated services are often worth taking advantage of (e.g. hosting material and analyses from papers, posters or presentation, and linking this through to Zenodo to get an archived version with a DOI). 3.2.2 Installing pyrolite There’s a separate page dedicated to pyrolite installations, but for most purposes, the best way to install pyrolite is through opening a terminal (an Anaconda terminal, if that’s the distribution you’re using) and type: pip install pyrolite To keep pyrolite up to date (new versions are released often), periodically run the following to update your local version: pip install --upgrade pyrolite 3.2.3 Writing Some Code If you’re new to Python†0, or just new to pyrolite, checking out some of the examples is a good first step. You should be able to copy-paste or download and run each of these examples as written on your own system, or alterna- tively you can run them interatively in your browser thanks to Binder and sphinx-gallery (check for the links towards the bottom of each page). Have a play with these, and adapt them to your own purposes. 0 If you’re strapped for space, or are bloat-averse, you could also consider using Anaconda’s miniconda distributions. 0 If you’re completely new to Python, check out some of the many free online courses to get up to scratch with basic Python concepts, data structures and get in a bit of practice writing code (e.g. the basic Python course on Codecademy). Knowing your way around some of these things before you dive into applying them can help make it a much more surmountable challenge. Remember that the pyrolite community is also around to help out if you get stuck, and we all started from a similar place! There are no ‘stupid questions’, so feel free to ping us on Gitter with any questions or aspects that are proving particularly challenging. 6 Chapter 3. Getting Started pyrolite Documentation, Release 0.3.0+88.g052ca43 3.2.4 Importing Data A large part of the pyrolite API is based around pandas DataFrames. One of the first hurdles for new users is importing their own data tables. To make this as simple as possible, it’s best to organise - or ‘tidy’ - your data tables‡0. Minimise unnecessary whitespace, and where possible make sure your table columns are the first row of your table. In most cases, where these data are in the form of text or Excel files, the typical steps for data import are similar. A few simple examples are given below. To import a table from a .csv file: from pathlib import Path import pandas as pd filepath= Path('./mydata.csv') df= pd.read_csv(filepath) In the case of an excel table: filepath= Path('./mydata.xlsx') df= pd.read_excel(filepath) There is also a pyrolite function which abstracts away these differences by making a few assumptions, and enables you to import the table from either a csv or excel file: from pyrolite.util.pd import read_table df= read_table(filepath) 3.2.5 Gitter Community A Gitter Community has been set up to serve as a landing page for conversations, questions and support regarding the pyrolite python package and related activities. Here we hope to capture questions and bugs from the community such that these can be addressed quickly, and we can ensure pyrolite and its documentation are as useful as possible to the community. Please feel free to use this space to: • Ask questions or seek help about getting started with pyrolite or particular pyrolite features • Get tips for troubleshooting • Discuss the general development of pyrolite • Ask about contributing to pyrolite Items which are related to specific aspects of pyrolite development (requesting a feature, or reporting an identified bug) are best coordinated through GitHub, but feel free to touch base here first. See below and the contribution and development guides for more information. Note that users and contributors in online spaces (including Gitter) are expected to adhere to the Code of Conduct of this project (and any other guidelines of the relevant platform). 3.2.6 Bugs, Debugging & Bug Reporting This section provides some guidance for what to do when things don’t work as expected, and some tips for debugging issues and common errors associated with pyrolite. Note that the scope of these suggestions is necessarily limited, and specific issues which relate more to matplotlib.pyplot, pandas, and numpy are often well documented elsewhere online. 0 Where each variable is a column, and each observation is a row. If you’re unfamiliar with the ‘Tidy Data’ concept, check out [Wickham2014]. 3.2. Getting Started 7 pyrolite Documentation, Release 0.3.0+88.g052ca43 • Checked the documentation, had a look for FAQ and examples here and still stuck? The maintainers are happy to answer questions and help you solve small bugs. It’s useful to know where people get stuck so we can modify things where useful, and this is an easy way to contribute to the project. Consider posting a question on Gitter, and if you think it’s something others may run into or could be a problem related to use of another package, perhaps also consider posting a question on stackoverflow for visibility.