Introduction to PmagPy

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

What is PmagPy?

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.

What are paleomagnetism and rock magnetism?

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

Using Jupyter notebooks for Earth Science

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:

https://nbviewer.jupyter.org/github/ltauxe/Python-for-Earth-Science-Students/blob/master/Lecture_01.ipynb

Guide to PmagPy

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 demonstrated within PmagPy_calculations.ipynb:

  • 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 demonstrated within PmagPy_plots_analysis.ipynb:

  • 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 demonstrated within PmagPy_MagIC.ipynb:

  • 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

Get started

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!')

All modules imported!
  • Now you have everything you need to run PmagPy!