by Lisa Tauxe, Lori Jonestrask, Nick Swanson-Hysell and Nick Jarboe

**PmagPy** is a software package for analyzing paleomagnetic and rock magnetic data using Python. These notebooks demonstrate how to use **PmagPy** in a Jupyter notebook or Python script. For examples of how to use PmagPy scripts on the command line, see the static version of **PmagPy_cli.ipynb**.

For information on the science of paleomagnetism and rock magnetism, see textbook at: https://earthref.org/MagIC/books/Tauxe/Essentials/

If you already have some experience working with Python, you should be able to navigate these examples.

If not, we have a full course in Python for Earth Scientists available on Github. To check it out, see:

The functionality of PmagPy is demonstrated within three notebooks:

- PmagPy_calculations.ipynb This notebook demonstrates many of the PmagPy calculation functions such as those that rotate directions, return statistical parameters, and simulate data from specified distributions.
- PmagPy_plots_analysis.ipynb This notebook demonstrates PmagPy functions that can be used to visual data as well as those that conduct statistical tests that have associated visualizations.
- PmagPy_MagIC.ipynb This notebook demonstrates how PmagPy can be used to read and write data to and from the MagIC database format including conversion from many individual lab measurement file formats.

- Functions in
**PmagPy_calculations.ipynb**:- aarm_magic : calculate AARM tensors
- atrm_magic : calculate ATRM tensors
- angle : calculates the angle between two vectors
- apwp : returns predicted paleolatitudes, directions and pole latitude/longitude from apparent polar wander paths of Besse and Courtillot (2002).
- b_vdm : converts B (in microT) and (magnetic) latitude to V(A)DM (see vdm_b)
- bootams : calculates bootstrap statistics for tensor data
- cart_dir : converts cartesian coordinates (x,y,z) to declination, inclination, intensity (see dir_cart)
- di_eq : maps declination, inclinatitions to X,Y for plotting in equal area projections
- di_geo : rotates declination, inclination in specimen coordinates to geographic coordinates
- di_rot : rotates directions to a coordinate system with D,I as center
- di_tilt : rotates directions to stratigraphic coordinates
- di_vgp : converts direction to Virtual Geomagnetic Pole (see vgp_di)
- dia_vgp : converts direction and $\alpha_{95}$ to Virtual Geomagnetic Pole and dp,dm
- dipole_pinc : calculates inclination given latitude assuming geocentric axial dipole
- dipole_plat : calculates latitude given inclination assuming geocentric axial dipole
- dir_cart : converts declination, inclination, intensity to cartesian coordinates (see cart_dir)
- eigs_s : converts eigenparameters to equivalent 6 element tensor (see s_eigs)
- eq_di : takes X,Y from equal area projection (e.g., from digitized coordinates) and converts to declination, inclination
- fcalc : returns the value from an F table, given the degrees of freedom.
- fisher : generates sets of directions drawn from Fisher distributions with vertical true mean
- fishrot : generates sets of directions drawn from Fisher distributions with arbitrary true mean
- flip : flips a second mode (reverse directions) to their antipodes
- gaussian : generates data drawn from a normal distribution
- gobing : calculates Bingham statistics from a set of directions
- gofish : calculates Fisher statistics from a set of directions
- gokent : calculates Kent statistics from a set of directions
- goprinc : calculates principal directions statistics
- igrf : calculates geomagnetic field vectors for location, age given a field model (e.g., IGRF)
- incfish : estimates the true mean inclination from inclination only data
- pca : calculates the best-fit line or plane for demagnetization data and associated statistics
- pt_rot : rotates point given finite rotation pole
- scalc : calculates VGP scatter
- s_eigs : takes a 6 element tensor and calculates eigen parameters (see eigs_s)
- s_geo : rotates 6 element tensors to geographic coordinates
- s_hext : calculates Hext statistics from 6 element tensors
- s_tilt : rotates 6 element tensors to stratigraphic coordinates
- separate_directions : separates a set of directions into two modes (normal and reverse)
- squish: flattens inclination data given flattening factor (see unsquish)
- sundec : calulates direction to sun for location, date, time and sun azimuth
- tk03 : generates sets of directions consistent with the TK03 field model
- uniform : generates sets of uniformly distributed directions
- unsquish : unsquishes flattened inclinations, given flattening factor (see squish)
- vector_mean : calculates vector mean for sets of vectors (declination, inclination, intensity)
- vdm_b : calculates intensity at given location from specified virtual dipole moment (see b_vdm)
- vgp_di : calculates direction at given location from virtual geomagnetic pole (see di_vgp)
- watsons_f : calculates Watson's F statistic for testing for common mean

Functions in

**PmagPy_plots_analysis.ipynb**- ani_depthplot : plots anisotropy data against depth in stratigraphic section (Xmas tree plots)
- aniso_magic : makes plots of anisotropy data and bootstrapped confidences
- biplot_magic : plots different columns against each other in MagIC formatted data files
- chi_magic : plots magnetic susceptibility data in MagIC format as function of field, frequency or temperature
- common_mean : graphical approach to testing two sets of directions for common mean using bootstrap
- core_depthplot : plots MagIC formatted data
- curie : makes plots of Curie Temperature data and provides estimates for Tc
- dayplot_magic : makes Day et al. (1977) and other plots with hysteresis statistics
- dmag_magic : plots remanence against demagnetization step for MagIC formatted files
- eqarea and eqarea_magic : makes equal area projections for directions
- eqarea_ell : makes equal area projections for directions with specified confidence ellipses
- find_ei : finds the inclination unflattening factor that unsquishes directions to match TK03 distribution
- fishqq: makes a Quantile-Quantile plot for directions against uniform and exponential distributions
- foldtest & foldtest_magic : finds tilt correction that maximizes concentration of directions, with bootstrap confidence bounds.
- forc_diagram: plots FORC diagrams for both conventional and irregular FORCs
- hysteresis_magic : makes plots of hysteresis data (not FORCs).
- irm_unmix : analyzes IRM acquisition data in terms of coercivity distributions
- irmaq_magic : plots IRM acquistion data
- lnp_magic : plots lines and planes for site level data and calculates best fit mean and alpha_95
- lowes : makes a plot of the Lowe's spectrum for a geomagnetic field model
- lowrie and lowrie_magic : makes plots of Lowrie's (1990) 3D-IRM demagnetization experiments
- plot_cdf and plot_2cdfs : makes a cumulative distribution plot of data
- plotdi_a : makes equal are plots of directions and their $\alpha_{95}$s
- plot_geomagia : makes plots from files downloaded from the geomagia website
- plot_magic_keys : plots data from MagIC formatted data files
- plot_ts : makes a plot of the desired Geomagnetic Reversal time scale
- qqplot : makes a Quantile-Quantile plot for data against a normal distribution
- qqunf : makes a Quantile-Quantile plot for data against a uniform distribution
- quick_hyst : makes hysteresis plots
- revtest & revtest_magic : performs a bootstrap reversals test
- thellier_magic : makes plots of thellier-thellier data.
- watsons_v : makes a graph for Watson's V test for common mean
- zeq and zeq_magic : makes quicky zijderveld plots for measurement data

Maps:

- cont_rot : makes plots of continents after rotation to specified coordinate system
- plot_mag_map : makes a color contour plot of geomagnetic field models
- plot_map_pts : plots points on maps
- polemap_magic : reads in MagIC formatted file with paleomagnetic poles and plots them
- vgpmap_magic : reads in MagIC formatted file with virtual geomagnetic poles and plots them

Functions in

**PmagPy_MagIC.ipynb**- reading MagIC files : reading in MagIC formatted files
- writing MagIC files : outputing MagIC formatted files
- combine_magic : combines two MagIC formatted files of same type
- convert_ages : convert ages in downloaded MagIC file to Ma
- grab_magic_key : prints out a single column from a MagIC format file
- magic_select : selects data from MagIC format file given conditions (e.g., method_codes contain string)
- sites_extract : makes excel or latex files from sites.txt for publications
- criteria_extract : makes excel or latex files from criteria.txt for publications
specimens_extract : makes excel or latex files from specimens.txt for publications

contributions work with data model 3.0 MagIC contributions

- download_magic : unpacks a contribution text file downloaded from the MagIC website
- upload_magic : prepares a directory with a MagIC contribution for uploading to MagIC
- cb.add_sites_to_meas_table : completes a measurements data frame with the information required for plotting by site.
- cb.get_intensity_col : finds the first non-zero type of intensity data in a measurements dataframe.

conversion scripts : convert many laboratory measurement formats to the MagIC data model 3 format

- _2g_asc_magic : converts 2G ascii files to MagIC
- _2g_bin_magic : converts 2G binary files to MagIC
- agm_magic : converts Princeton Measurements alternating gradient force magnetization (AGM) files to MagIC.
- bgc_magic : convert Berkeley Geochronology Center files to MagIC.
- cit_magic : convert Cal Tech format files to MagIC.
- generic_magic : converts generic files to MagIC.
- huji_magic : converts Hebrew University, Jerusalem, Israel files to MagIC.
- huji_sample_magic : converts HUJI files to a MagIC format.
- jr6_jr6_magic : converts the AGICO JR6 spinner .jr6 files to MagIC
- jr6_txt_magic : converts the AGICO JR6 .txt files to MagIC
- k15_magic : converts 15 measurement anisotropy of magnetic susceptibility files to MagIC.
- kly4s_magic : converts SIO KLY4S formatted files to MagIC.
- ldeo_magic : converts Lamont-Doherty files to MagIC.
- livdb_magic : converts Liverpool files to MagIC.
- mst_magic : converts Curie Temperature experimental data to MagIC
- sio_magic : converts Scripps Institution of Oceanography data files to MagIC
- sufar4_magic : converts AGICO SUFAR program (ver.1.2.) ascii files to MagIC
- tdt_magic : converts Thellier Tool files to MagIC
- utrecht_magic : converts Fort Hoofddijk, Utrecht University Robot files to MagIC
- orientation_magic : converts an "orient.txt" formatted file with field notebook information into MagIC formatted files
- azdip_magic : converts an "azdip" formatted file to a samples.txt file format

- other handy scripts
- chartmaker : script for making chart to guide IZZI lab experiment

To use the functions demonstrated in these notebooks, we have to import the **PmagPy** modules **pmagplotlib**, **pmag** and **ipmag** and some other handy functions. You can run the following commands in a Python environment where PmagPy is installed (i.e., in the Python interpreter, or in a notebook).

In [1]:

```
import pmagpy.pmag as pmag
import pmagpy.pmagplotlib as pmagplotlib
import pmagpy.ipmag as ipmag
import pmagpy.contribution_builder as cb
from pmagpy import convert_2_magic as convert
import matplotlib.pyplot as plt # our plotting buddy
import numpy as np # the fabulous NumPy package
import pandas as pd # and of course Pandas
# test if Basemap and/or cartopy is installed
has_basemap, Basemap = pmag.import_basemap()
has_cartopy, Cartopy = pmag.import_cartopy()
# test if xlwt is installed (allows you to export to excel)
try:
import xlwt
has_xlwt = True
except ImportError:
has_xlwt = False
# This allows you to make matplotlib plots inside the notebook.
%matplotlib inline
from IPython.display import Image
import os
print('All modules imported!')
```

- Now you have everything you need to run PmagPy!