Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Getting set up with Python and RockmagPy

The notebooks in this book can be downloaded and run on your own computer using RockmagPy — a set of Python tools (part of the PmagPy package) with accompanying Jupyter notebooks for visualizing and interpreting rock magnetic measurements. This page walks through setting up everything you need, starting from scratch. No prior experience with Python — or with a “terminal” or “command line” — is assumed.

The whole setup takes about 15–20 minutes with a decent internet connection, and you only have to do it once. After that, getting back to work is three short commands (see Coming back later).

Already comfortable with conda?

The short version: create an environment with conda create -n rockmag -c conda-forge --override-channels python=3.12 jupyterlab ipywidgets ipympl bokeh statsmodels dynesty cartopy, activate it, pip install pmagpy, clone or download RockmagPy-notebooks, and launch jupyter lab. The rest of this page spells these steps out for readers new to Python.

What you are installing

  • Miniforge — a free installer that puts Python on your computer along with conda, a tool for managing Python packages. It installs into your own user folder and doesn’t require administrator access or interfere with anything else on your computer.

  • A conda “environment” — a self-contained workspace named rockmag holding a specific Python version and the packages the notebooks need. If anything ever goes wrong inside it, you can delete it and rebuild it in minutes without touching the rest of your computer.

  • JupyterLab — the program (it runs in your web browser) where you’ll open and run notebooks. A Jupyter notebook is a document that mixes explanatory text, runnable code, and the plots that code produces.

  • PmagPy — the Python package that contains the rockmag module with the functions for analyzing rock magnetic data.

  • The RockmagPy notebooks — a folder of ready-made notebooks from the RockmagPy-notebooks repository for working with hysteresis, thermomagnetic, low-temperature (MPMS), and other data types.

Step 1 — Install Miniforge

Python may already be on your computer from a past class or project — most often under the name Anaconda or Miniconda. Installing a second copy alongside an old one is a common source of confusing problems, so take a moment to check before installing anything:

Mac
Windows (PC)

Open the Terminal: press ⌘ command+space to open Spotlight search, type terminal, and press return. In the window that opens, type this line and press return:

conda --version

  • If it prints a version number (like conda 24.11.0) — or the command line already starts with (base) — your computer already has conda, and you should not install another one. Skip the rest of this step and go straight to Step 2; every command in this guide works the same with your existing installation.

  • If it prints command not found, you don’t have conda. Continue below and install Miniforge.

Miniforge is the recommended way to get Python for scientific work. The steps differ between Mac and Windows, so follow the tab for your computer.

Mac
Windows (PC)

On a Mac, Miniforge is installed by pasting two commands into the Terminal app. The Terminal is a program, included on every Mac, where you type text commands instead of clicking buttons — you’ll use it a few times in this guide, always by copying and pasting commands from this page.

  1. Open the Terminal: press ⌘ command+space to open Spotlight search, type terminal, and press return. A window opens with a blinking cursor — that’s where commands go.

  2. Copy the line below (select it and press ⌘ command+C, or use the copy button in the corner of the box), click in the Terminal window, paste it (⌘ command+V), and press return. This downloads the installer (it automatically picks the right version for your Mac’s chip):

    curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"

  3. When the download finishes and the prompt returns, paste this line and press return to run the installer:

    bash Miniforge3-$(uname)-$(uname -m).sh

  4. The installer asks a few questions in the Terminal:

    • Press return to start, then press space to page through the license, and type yes and press return to accept it.

    • Press return to accept the default install location.

    • When asked “Do you wish to update your shell profile to automatically initialize conda?”, type yes and press return. This one matters — the default is “no”, and answering “no” means later commands won’t be found.

  5. Quit the Terminal completely (⌘ command+Q) and open it again. You should now see (base) at the start of the command line — that’s how you know the install worked.

Step 2 — Create the environment and install the software

These commands are the same on Mac and Windows, and they work the same whether you installed Miniforge in Step 1 or already had Anaconda/Miniconda. Type them in the Terminal (Mac) or the Miniforge Prompt or Anaconda Prompt (Windows), one at a time, pressing return/enter after each and waiting for it to finish before the next. A command is finished when the (base) or (rockmag) prompt reappears and the cursor is waiting for input again.

First, create the rockmag environment with Python, JupyterLab, and the plotting packages the notebooks use. Copy the whole line — the -c conda-forge --override-channels part tells conda where to download packages from, which is what makes the command behave the same on every installation. This downloads a few hundred megabytes and can take several minutes; when asked to confirm, type y and press return:

conda create -n rockmag -c conda-forge --override-channels python=3.12 jupyterlab ipywidgets ipympl bokeh statsmodels dynesty cartopy

Next, switch into the new environment. The (base) at the start of the line changes to (rockmag), which tells you the environment is active:

conda activate rockmag

Finally, install PmagPy (which includes RockmagPy) into the environment using pip, Python’s package installer:

pip install pmagpy

That’s the software done. You can check that it worked by copying this line into the terminal and pressing return — it should print a version number (like pmagpy-4.3.16) rather than an error:

python -c "from pmagpy import pmag; print(pmag.get_version())"

Step 3 — Download the RockmagPy notebooks

The notebooks live in a repository (a shared folder of files) on GitHub. You don’t need a GitHub account — you can download the whole thing as a ZIP file:

  1. Go to github.com/PmagPy/RockmagPy-notebooks.

  2. Click the green <> Code button near the top right, then click Download ZIP.

  3. Unzip the downloaded file:

Mac
Windows (PC)

Find RockmagPy-notebooks-main.zip in your Downloads folder and double-click it. A folder named RockmagPy-notebooks-main appears next to it. Drag that folder into your Documents folder so it’s easy to find later.

Step 4 — Launch JupyterLab and open a notebook

With the environment active (you see (rockmag) at the start of the line — if not, run conda activate rockmag first), start JupyterLab:

jupyter lab

After a few seconds your web browser opens a JupyterLab tab. (Although it runs in the browser, everything is happening locally on your computer — no internet is needed once it’s running.)

In the left sidebar of JupyterLab is a file browser showing the folders on your computer. Double-click Documents (on Windows, if you don’t see Documents, look inside the OneDrive folder), then RockmagPy-notebooks-main, then the folder for the data type you’re working with (for example hysteresis_backfield_notebooks or MPMS_notebooks), and double-click a notebook (a file ending in .ipynb) to open it. If a dialog pops up asking you to select a kernel (some notebooks were last saved on a different system), choose Python 3 (ipykernel) and click Select. Run a notebook’s cells one at a time with shift+return, or run everything via the menu with Run → Run All Cells.

Two things to know while JupyterLab is running:

Coming back later

Everything above is one-time setup. From now on, getting back to work is:

  1. Open the Terminal (Mac) or the Miniforge Prompt or Anaconda Prompt (Windows — whichever you used during setup).

  2. conda activate rockmag

  3. jupyter lab

If something goes wrong

RockmagPy Documentation
RockmagPy Documentation
Nuts & Bolts
Rock magnetic data import