Getting Started
Note
This page is under construction. Feel free to send through suggestions or questions.
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 *. 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).
- *
If you’re strapped for space, or are bloat-averse, you could also consider using Anaconda’s miniconda distributions.
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
Writing Some Code
If you’re new to Python †, 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 alternatively 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.
- †
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.
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 ‡. 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)
- ‡
Where each variable is a column, and each observation is a row. If you’re unfamiliar with the ‘Tidy Data’ concept, check out [Wickham2014].
- Wickham2014
Wickham, H., 2014. Tidy Data. Journal of Statistical Software 59, 1–23. doi: doi.org/10.18637/jss.v059.i10
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).
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.
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.
Think it’s a bug or problem with pyrolite specifically?
Some guidelines for reporting issues and bugs are given in the contributing guide.
See also