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. These examples can be adapted into Python scripts.
What are paleomagnetism and rock magnetism?#
For information on the science of paleomagnetism and rock magnetism, see the Essentials of Paleomagnetism textbook at: https://earthref.org/MagIC/books/Tauxe/Essentials/
Using Jupyter notebooks for Earth Science#
Jupyter notebooks allow for executable code, results, text, and graphical output to coherently coexist in a single document. With these combined components, they are excellent tools both for conducting data analysis and presenting results.
You will need to have Python 3 and Jupyter (https://jupyter.org/install) installed on your system to run this and other notebooks.
Having some experience working with Python will help you navigate these notebooks. If you are searching for more experience, you can find materials associated with a full course in Python for Earth Scientists on Github. Links at the bottom of that page direct to individual notebooks such as that for Lecture 1
Quick start for Jupyter Notebooks#
click on a box (called a “cell”), then click on ‘Run’ in the menu bar. That will execute the cell. A shortcut for running a cell is pressing Shift+Enter
there are two types of cells: Markdown and Code - see the menu bar for the type of cell you just clicked on. One type of cell can be switched to another.
Markdown cells are for text and clicking run for it will typeset the text.
Code cells are for code and clicking run for it will execute the code.
Guide to PmagPy#
The functionality of PmagPy is demonstrated within three notebooks in this repository:
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 tensorsatrm_magic
: calculate ATRM tensorsangle
: calculates the angle between two vectorsapwp
: 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 (seevdm_b
)bootams
: calculates bootstrap statistics for tensor datacart_dir
: converts cartesian coordinates (x,y,z) to declination, inclination, intensity (seedir_cart
)di_eq
: maps declination, inclinatitions to X,Y for plotting in equal area projectionsdi_geo
: rotates declination, inclination in specimen coordinates to geographic coordinatesdi_rot
: rotates directions to a coordinate system with D,I as centerdi_tilt
: rotates directions to stratigraphic coordinatesdi_vgp
: converts direction to Virtual Geomagnetic Pole (seevgp_di
)dia_vgp
: converts direction and \(\alpha_{95}\) to Virtual Geomagnetic Pole and dp,dmdipole_pinc
: calculates inclination given latitude assuming geocentric axial dipoledipole_plat
: calculates latitude given inclination assuming geocentric axial dipoledir_cart
: converts declination, inclination, intensity to cartesian coordinates (seecart_dir
)eigs_s
: converts eigenparameters to equivalent 6 element tensor (sees_eigs
)eq_di
: takes X,Y from equal area projection (e.g., from digitized coordinates) and converts to declination, inclinationfcalc
: returns the value from an F table, given the degrees of freedom.fisher
: generates sets of directions drawn from Fisher distributions with vertical true meanfishrot
: generates sets of directions drawn from Fisher distributions with arbitrary true meanflip
: flips a second mode (reverse directions) to their antipodesgaussian
: generates data drawn from a normal distributiongobing
: calculates Bingham statistics from a set of directionsgofish
: calculates Fisher statistics from a set of directionsgokent
: calculates Kent statistics from a set of directionsgoprinc
: calculates principal directions statisticsigrf
: calculates geomagnetic field vectors for location, age given a field model (e.g., IGRF)incfish
: estimates the true mean inclination from inclination only datapca
: calculates the best-fit line or plane for demagnetization data and associated statisticspt_rot
: rotates point given finite rotation polescalc
: calculates VGP scatters_eigs
: takes a 6 element tensor and calculates eigen parameters (seeeigs_s
)s_geo
: rotates 6 element tensors to geographic coordinatess_hext
: calculates Hext statistics from 6 element tensorss_tilt
: rotates 6 element tensors to stratigraphic coordinatesseparate_directions
: separates a set of directions into two modes (normal and reverse)squish
: flattens inclination data given flattening factor (seeunsquish
)sundec
: calulates direction to sun for location, date, time and sun azimuthtk03
: generates sets of directions consistent with the TK03 field modeluniform
: generates sets of uniformly distributed directionsunsquish
: unsquishes flattened inclinations, given flattening factor (seesquish
)vector_mean
: calculates vector mean for sets of vectors (declination, inclination, intensity)vdm_b
: calculates intensity at given location from specified virtual dipole moment (seeb_vdm
)vgp_di
: calculates direction at given location from virtual geomagnetic pole (seedi_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 confidencesbiplot_magic
: plots different columns against each other in MagIC formatted data fileschi_magic
: plots magnetic susceptibility data in MagIC format as function of field, frequency or temperaturecommon_mean
: graphical approach to testing two sets of directions for common mean using bootstrapcore_depthplot
: plots MagIC formatted datacurie
: makes plots of Curie Temperature data and provides estimates for Tcdayplot_magic
: makes Day et al. (1977) and other plots with hysteresis statisticsdmag_magic
: plots remanence against demagnetization step for MagIC formatted fileseqarea
andeqarea_magic
: makes equal area projections for directionseqarea_ell
: makes equal area projections for directions with specified confidence ellipsesfind_ei
: finds the inclination unflattening factor that unsquishes directions to match TK03 distributionfishqq
: makes a Quantile-Quantile plot for directions against uniform and exponential distributionsfoldtest
&foldtest_magic
: finds tilt correction that maximizes concentration of directions, with bootstrap confidence bounds.forc_diagram
: plots FORC diagrams for both conventional and irregular FORCshysteresis_magic
: makes plots of hysteresis data (not FORCs).irm_unmix
: analyzes IRM acquisition data in terms of coercivity distributionsirmaq_magic
: plots IRM acquistion datalnp_magic
: plots lines and planes for site level data and calculates best fit mean and alpha_95lowes
: makes a plot of the Lowe’s spectrum for a geomagnetic field modellowrie
andlowrie_magic
: makes plots of Lowrie’s (1990) 3D-IRM demagnetization experimentsplot_cdf
andplot_2cdfs
: makes a cumulative distribution plot of dataplotdi_a
: makes equal are plots of directions and their \(\alpha_{95}\)splot_geomagia
: makes plots from files downloaded from the geomagia websiteplot_magic_keys
: plots data from MagIC formatted data filesplot_ts
: makes a plot of the desired Geomagnetic Reversal time scaleqqplot
: makes a Quantile-Quantile plot for data against a normal distributionqqunf
: makes a Quantile-Quantile plot for data against a uniform distributionquick_hyst
: makes hysteresis plotsrevtest
&revtest_magic
: performs a bootstrap reversals testthellier_magic
: makes plots of thellier-thellier data.watsons_v
: makes a graph for Watson’s V test for common meanzeq
andzeq_magic
: makes quicky zijderveld plots for measurement data
Maps:
cont_rot
: makes plots of continents after rotation to specified coordinate systemplot_mag_map
: makes a color contour plot of geomagnetic field modelsplot_map_pts
: plots points on mapspolemap_magic
: reads in MagIC formatted file with paleomagnetic poles and plots themvgpmap_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 fileswriting MagIC files
: outputing MagIC formatted filescombine_magic
: combines two MagIC formatted files of same typeconvert_ages
: convert ages in downloaded MagIC file to Magrab_magic_key
: prints out a single column from a MagIC format filemagic_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 publicationscriteria_extract
: makes excel or latex files from criteria.txt for publicationsspecimens_extract
: makes excel or latex files from specimens.txt for publicationscontributions
work with data model 3.0 MagIC contributionsdownload_magic
: unpacks a contribution text file downloaded from the MagIC websiteupload_magic
: prepares a directory with a MagIC contribution for uploading to MagICcb.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 MagICagm_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 MagICjr6_txt_magic
: converts the AGICO JR6 .txt files to MagICk15_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 MagICsio_magic
: converts Scripps Institution of Oceanography data files to MagICsufar4_magic
: converts AGICO SUFAR program (ver.1.2.) ascii files to MagICtdt_magic
: converts Thellier Tool files to MagICutrecht_magic
: converts Fort Hoofddijk, Utrecht University Robot files to MagICorientation_magic
: converts an “orient.txt” formatted file with field notebook information into MagIC formatted filesazdip_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
Customizing this notebook#
If you are running this notebook on JupyterHub and want to make changes, you should make a copy (see File menu). Otherwise, each time you update PmagPy, your changes will be overwritten.
Get started#
To use the functions in this notebook, we have to import the PmagPy modules pmagplotlib, pmag and ipmag and some other handy functions for use in the notebook. This is done in the following code block which must be executed before running any other code block. To execute, click on the code block and then click on the “Run” button in the menu.
In order to access the example data, this notebook is meant to be run in the PmagPy-data directory (PmagPy directory for developers).
Try it! Run the code block below (click on the cell and then click ‘Run’):
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!