PmagPy_introduction.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to PmagPy\n",
    "\n",
    "by Lisa Tauxe, Lori Jonestrask, Nick Swanson-Hysell and Nick Jarboe\n",
    "\n",
    "## What is **PmagPy**?  \n",
    "\n",
    "**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**](https://pmagpy.github.io/PmagPy-cli.html).  If you are running this notebook locally, you can click the following link to launch [**PmagPy-cli.ipynb**](PmagPy-cli.ipynb)\n",
    "\n",
    "## What are paleomagnetism and rock magnetism?  \n",
    "\n",
    "For information on the science of paleomagnetism and rock magnetism, see textbook at: https://earthref.org/MagIC/books/Tauxe/Essentials/\n",
    "\n",
    "## Using Jupyter notebooks for Earth Science\n",
    "\n",
    "You will need to have Python 3 and Jupyter (https://jupyter.org/install) installed on your system to run this notebook.\n",
    "\n",
    "If you already have some experience working with Python, you should be able to navigate these notebooks. \n",
    "\n",
    "If not, we have a full course in Python for Earth Scientists available on Github.  To check it out, see: \n",
    "\n",
    "https://nbviewer.jupyter.org/github/ltauxe/Python-for-Earth-Science-Students/blob/master/Lecture_01.ipynb\n",
    "\n",
    "## Quick start for Jupyter Notebooks\n",
    "\n",
    "- click on a box (called a \"cell\"), then click on 'Run' in the menu bar.  That will execute the cell.\n",
    "- there are two types of cells:  Markdown and Code - see the menu bar for the type of cell you just clicked on.  \n",
    "- Markdown cells are for text and clicking on it will typeset the text.\n",
    "- Code cells are for code and clicking on it will execute the code. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Guide to PmagPy\n",
    "\n",
    "The functionality of PmagPy is demonstrated within three notebooks in this repository:\n",
    "\n",
    "- [PmagPy_calculations.ipynb](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. \n",
    "- [PmagPy_plots_analysis.ipynb](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.\n",
    "- [PmagPy_MagIC.ipynb](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.\n",
    "\n",
    "### Functions demonstrated within [PmagPy_calculations.ipynb](PmagPy_calculations.ipynb): \n",
    "- Functions in **PmagPy_calculations.ipynb**:\n",
    "    - [aarm_magic](#aarm_magic) : calculate AARM tensors\n",
    "    - [atrm_magic](#aarm_magic) : calculate ATRM tensors\n",
    "    - [angle](#angle) : calculates the angle between two vectors\n",
    "    - [apwp](#apwp) : returns predicted paleolatitudes, directions and pole latitude/longitude from apparent polar wander paths of Besse and Courtillot (2002).\n",
    "    - [b_vdm](#b_vdm) : converts B (in microT) and (magnetic) latitude to V(A)DM (see [vdm_b](#vdm_b))\n",
    "    - [bootams](#bootams) : calculates bootstrap statistics for tensor data\n",
    "    - [cart_dir](#cart_dir) : converts cartesian coordinates (x,y,z) to declination, inclination, intensity (see [dir_cart](#dir_cart))\n",
    "    - [di_eq](#di_eq) : maps declination, inclinatitions to X,Y for plotting in equal area projections\n",
    "    - [di_geo](#di_geo) : rotates declination, inclination in specimen coordinates to geographic coordinates\n",
    "    - [di_rot](#di_rot) : rotates directions to a  coordinate system with D,I as center\n",
    "    - [di_tilt](#di_tilt) : rotates directions to stratigraphic coordinates\n",
    "    - [di_vgp](#di_vgp) : converts direction to Virtual Geomagnetic Pole (see [vgp_di](#vgp_di))\n",
    "    - [dia_vgp](#dia_vgp) : converts direction and $\\alpha_{95}$ to Virtual Geomagnetic Pole and dp,dm\n",
    "    - [dipole_pinc](#dipole_pinc) : calculates inclination given latitude assuming geocentric axial dipole\n",
    "    - [dipole_plat](#dipole_plat) : calculates latitude given inclination assuming geocentric axial dipole\n",
    "    - [dir_cart](#dir_cart) : converts declination, inclination, intensity to cartesian coordinates (see [cart_dir](#cart_dir))\n",
    "    - [eigs_s](#eigs_s) : converts eigenparameters to equivalent 6 element tensor (see [s_eigs](#s_eigs))\n",
    "    - [eq_di](#eq_di) : takes X,Y from equal area projection (e.g., from digitized coordinates) and  converts to declination, inclination\n",
    "    - [fcalc](#fcalc) : returns the value from an F table, given the degrees of freedom.\n",
    "    - [fisher](#fisher) : generates sets of directions drawn from Fisher distributions with vertical true mean\n",
    "    - [fishrot](#fishrot) : generates sets of directions drawn from Fisher distributions with arbitrary true mean\n",
    "    - [flip](#flip) : flips a second mode (reverse directions) to their antipodes\n",
    "    - [gaussian](#gaussian) : generates data drawn from a normal distribution\n",
    "    - [gobing](#gobing) : calculates Bingham statistics from a set of directions\n",
    "    - [gofish](#gofish) : calculates Fisher statistics from a set of directions\n",
    "    - [gokent](#gokent) : calculates Kent statistics from a set of directions\n",
    "    - [goprinc](#goprinc) : calculates principal directions statistics\n",
    "    - [igrf](#igrf) : calculates geomagnetic field vectors for location, age given a field model (e.g., IGRF)\n",
    "    - [incfish](#incfish) : estimates the true mean inclination from inclination only data\n",
    "    - [pca](#pca) : calculates the best-fit line or plane for demagnetization data and associated statistics\n",
    "    - [pt_rot](#pt_rot) : rotates point given finite rotation pole\n",
    "    - [scalc](#scalc) : calculates  VGP scatter\n",
    "    - [s_eigs](#s_eigs) : takes a 6 element tensor and calculates eigen parameters (see [eigs_s](#eigs_s))\n",
    "    - [s_geo](#s_geo) : rotates 6 element tensors to geographic coordinates\n",
    "    - [s_hext](#s_hext) : calculates Hext statistics from 6 element tensors\n",
    "    - [s_tilt](#s_tilt) : rotates 6 element tensors to stratigraphic coordinates\n",
    "    - [separate_directions](#separate_directions) : separates a set of directions into two modes (normal and reverse)\n",
    "    - [squish](#squish): flattens inclination data given flattening factor (see [unsquish](#unsquish))\n",
    "    - [sundec](#sundec) : calulates direction to sun for location, date, time and sun azimuth\n",
    "    - [tk03](#tk03) : generates sets of directions consistent with the TK03 field model\n",
    "    - [uniform](#uniform) : generates sets of uniformly distributed directions\n",
    "    - [unsquish](#unsquish) : unsquishes flattened inclinations, given flattening factor (see [squish](#squish))\n",
    "    - [vector_mean](#vector_mean) : calculates vector mean for sets of vectors (declination, inclination, intensity)\n",
    "    - [vdm_b](#vdm_b) : calculates intensity at given location from specified virtual dipole moment (see [b_vdm](#b_vdm))\n",
    "    - [vgp_di](#vgp_di) : calculates direction at given location from virtual geomagnetic pole (see [di_vgp](#di_vgp))\n",
    "    - [watsons_f](#watsons_f) : calculates Watson's F statistic for testing for common mean\n",
    "    \n",
    "### Functions demonstrated within [PmagPy_plots_analysis.ipynb](PmagPy_plots_analysis.ipynb):\n",
    "- Functions in **PmagPy_plots_analysis.ipynb**\n",
    "    - [ani_depthplot](#ani_depthplot) : plots anisotropy data against depth in stratigraphic section (Xmas tree plots)\n",
    "    - [aniso_magic](#aniso_magic) : makes plots of anisotropy data and bootstrapped confidences \n",
    "    - [biplot_magic](#biplot_magic) : plots different columns against each other in MagIC formatted data files\n",
    "    - [chi_magic](#chi_magic) : plots magnetic susceptibility data in MagIC format as function of field, frequency or temperature\n",
    "    - [common_mean](#common_mean) : graphical approach to testing two sets of directions for common mean using bootstrap\n",
    "    - [core_depthplot](#core_depthplot) : plots MagIC formatted data \n",
    "    - [curie](#curie) : makes plots of Curie Temperature data and provides estimates for Tc\n",
    "    - [dayplot_magic](#dayplot_magic) : makes Day et al. (1977) and other plots with hysteresis statistics\n",
    "    - [dmag_magic](#dmag_magic) : plots remanence against demagnetization step for MagIC formatted files\n",
    "    - [eqarea](#eqarea) and [eqarea_magic](#eqarea_magic) : makes equal area projections for directions\n",
    "    - [eqarea_ell](#eqarea_ell) : makes equal area projections for directions with specified confidence ellipses\n",
    "    - [find_ei](#find_ei) : finds the inclination unflattening factor that unsquishes directions to match TK03 distribution\n",
    "    - [fishqq](#fishqq): makes a Quantile-Quantile plot for directions against uniform and exponential distributions\n",
    "    - [foldtest](#foldtest) & [foldtest_magic](#foldtest_magic) : finds  tilt correction that maximizes concentration of directions, with bootstrap confidence bounds.          \n",
    "    - [forc_diagram](#forc_diagram): plots FORC diagrams for both conventional and irregular FORCs\n",
    "    - [hysteresis_magic](#hysteresis_magic) : makes plots of hysteresis data (not FORCs). \n",
    "    - [irm_unmix](#irm_unmix) : analyzes IRM acquisition data in terms of coercivity distributions\n",
    "    - [irmaq_magic](#irm_magic) : plots IRM acquistion data\n",
    "    - [lnp_magic](#lnp_magic) : plots lines and planes for site level data and calculates best fit mean and alpha_95\n",
    "    - [lowes](#lowes) : makes a plot of the Lowe's spectrum for a geomagnetic field model\n",
    "    - [lowrie](#lowrie) and [lowrie_magic](#lowrie) : makes plots of Lowrie's (1990) 3D-IRM demagnetization experiments\n",
    "    - [plot_cdf](#plot_cdf) and [plot_2cdfs](#plot_2cdfs) : makes a cumulative distribution plot of data\n",
    "    - [plotdi_a](#plotdi_a) : makes equal are plots of directions and their $\\alpha_{95}$s\n",
    "    - [plot_geomagia](#plot_geomagia) : makes plots from files downloaded from the  geomagia website\n",
    "    - [plot_magic_keys](#plot_magic_keys) : plots data from MagIC formatted data files\n",
    "    - [plot_ts](#plot_ts) : makes a plot of the desired Geomagnetic Reversal time scale\n",
    "    - [qqplot](#qqplot) : makes a Quantile-Quantile plot for data against a normal distribution\n",
    "    - [qqunf](#qqunf) : makes a Quantile-Quantile plot for data against a uniform distribution\n",
    "    - [quick_hyst](#quick_hyst) : makes hysteresis plots\n",
    "    - [revtest](#revtest) & [revtest_magic](#revtest_magic) : performs a bootstrap reversals test\n",
    "    - [thellier_magic](#thellier_magic) : makes plots of thellier-thellier data. \n",
    "    - [watsons_v](#watsons_v) : makes a graph for Watson's V test for common mean\n",
    "    - [zeq](#zeq) and [zeq_magic](#zeq_magic) : makes quicky zijderveld plots for measurement data\n",
    "\n",
    "- Maps: \n",
    "    - [cont_rot](#cont_rot) : makes plots of continents after rotation to specified coordinate system\n",
    "    - [plot_mag_map](#plot_mag_map) : makes a color contour plot of geomagnetic field models\n",
    "    - [plot_map_pts](#plot_map_pts) : plots points on maps\n",
    "    - [polemap_magic](#polemap_magic) : reads in MagIC formatted file with paleomagnetic poles and plots them\n",
    "    - [vgpmap_magic](#vgpmap_magic) : reads in MagIC formatted file with virtual geomagnetic poles and plots them\n",
    "    \n",
    "### Functions demonstrated within [PmagPy_MagIC.ipynb](PmagPy_MagIC.ipynb):\n",
    "- Functions in **PmagPy_MagIC.ipynb**\n",
    "    - [reading MagIC files](#magic_read) : reading in MagIC formatted files\n",
    "    - [writing MagIC files](#magic_write) : outputing MagIC formatted files\n",
    "    - [combine_magic](#combine_magic) : combines two MagIC formatted files of same type\n",
    "    - [convert_ages](#convert_ages) : convert ages in downloaded MagIC file to Ma\n",
    "    - [grab_magic_key](#grab_magic_key) : prints out a single column from a MagIC format file\n",
    "    - [magic_select](#magic_select) : selects data from MagIC format file given conditions (e.g., method_codes contain string)\n",
    "    - [sites_extract](#sites_extract) : makes excel or latex files from sites.txt for publications\n",
    "    - [criteria_extract](#criteria_extract) : makes excel or latex files from criteria.txt for publications\n",
    "    - [specimens_extract](#specimens_extract) : makes excel or latex files from specimens.txt for publications\n",
    "\n",
    "    - [contributions](#Contributions) work with data model 3.0 MagIC contributions\n",
    "        - [download_magic](#download_magic) : unpacks a contribution text file downloaded from the MagIC website\n",
    "        - [upload_magic](#upload_magic) : prepares a directory with a MagIC contribution for uploading to MagIC\n",
    "        - [cb.add_sites_to_meas_table](#cb.add_sites_to_meas_table) : completes a measurements data frame with the information required for plotting by site. \n",
    "        - [cb.get_intensity_col](#cb.get_intensity_col) : finds the first non-zero type of intensity data in a measurements dataframe.\n",
    "\n",
    "    - [conversion scripts](#Conversion-Scripts) : convert many laboratory measurement formats to the MagIC data model 3 format\n",
    "        - [\\_2g\\_asc_magic](#\\_2g\\_asc\\_magic) : converts 2G ascii files to MagIC\n",
    "        - [\\_2g\\_bin_magic](#\\_2g\\_bin\\_magic) : converts 2G binary files to MagIC\n",
    "        - [agm_magic](#agm_magic) : converts Princeton Measurements alternating gradient force magnetization (AGM) files to MagIC.\n",
    "        - [bgc_magic](#bgc_magic) : convert Berkeley Geochronology Center files to MagIC. \n",
    "        - [cit_magic](#cit_magic) : convert Cal Tech format files to MagIC.\n",
    "        - [generic_magic](#generic_magic) : converts generic files to MagIC. \n",
    "        - [huji_magic](#huji_magic) : converts Hebrew University, Jerusalem, Israel files to MagIC.\n",
    "        - [huji_sample_magic](#huji_sample_magic) : converts HUJI files to a MagIC format. \n",
    "        - [jr6_jr6_magic](#jr6_jr6_magic) : converts the AGICO JR6 spinner .jr6 files to MagIC \n",
    "        - [jr6_txt_magic](#jr6_txt_magic) : converts the AGICO JR6 .txt files to MagIC\n",
    "        - [k15_magic](#k15_magic) : converts 15 measurement anisotropy of magnetic susceptibility files to MagIC.\n",
    "        - [kly4s_magic](#kly4s_magic) : converts SIO KLY4S formatted files to MagIC.\n",
    "        - [ldeo_magic](#ldeo_magic) : converts Lamont-Doherty files to MagIC.  \n",
    "        - [livdb_magic](#livdb_magic) : converts Liverpool files to MagIC.  \n",
    "        - [mst_magic](#mst_magic) : converts Curie Temperature experimental data to MagIC\n",
    "        - [sio_magic](#sio_magic) : converts Scripps Institution of Oceanography data files to MagIC \n",
    "        - [sufar4_magic](#sufar4_magic) : converts AGICO SUFAR program (ver.1.2.) ascii files to MagIC\n",
    "        - [tdt_magic](#tdt_magic) : converts Thellier Tool files to MagIC\n",
    "        - [utrecht_magic](#utrecht_magic) : converts Fort Hoofddijk, Utrecht University Robot files to MagIC\n",
    "        - [orientation_magic](#orientation_magic) : converts an \"orient.txt\" formatted file with field notebook information into MagIC formatted files\n",
    "        - [azdip_magic](#azdip_magic) : converts an \"azdip\" formatted file to a samples.txt file format\n",
    "- other handy scripts\n",
    "    - [chartmaker](#chartmaker) : script for making chart to guide IZZI lab experiment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "## Customizing this notebook\n",
    "\n",
    "If you want to make changes to this notebook, you should make a copy (see File menu).  Otherwise each time you update **PmagPy**, your changes will be overwritten.\n",
    "\n",
    "## Get started\n",
    "\n",
    "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.  \n",
    "\n",
    "In order to access the example data, this notebook is meant to be run in the PmagPy-data directory (PmagPy directory for developers).\n",
    "\n",
    "Try it!  Run the code block below (click on the cell and then click 'Run'):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "All modules imported!\n"
     ]
    }
   ],
   "source": [
    "import pmagpy.pmag as pmag\n",
    "import pmagpy.pmagplotlib as pmagplotlib\n",
    "import pmagpy.ipmag as ipmag\n",
    "import pmagpy.contribution_builder as cb\n",
    "from pmagpy import convert_2_magic as convert\n",
    "import matplotlib.pyplot as plt # our plotting buddy\n",
    "import numpy as np # the fabulous NumPy package\n",
    "import pandas as pd # and of course Pandas\n",
    "# test if Basemap and/or cartopy is installed\n",
    "has_basemap, Basemap = pmag.import_basemap()\n",
    "has_cartopy, Cartopy = pmag.import_cartopy()\n",
    "# test if xlwt is installed (allows you to export to excel)\n",
    "try:\n",
    "    import xlwt\n",
    "    has_xlwt = True\n",
    "except ImportError:\n",
    "    has_xlwt = False\n",
    "# This allows you to make matplotlib plots inside the notebook.  \n",
    "%matplotlib inline \n",
    "from IPython.display import Image\n",
    "import os\n",
    "\n",
    "print('All modules imported!')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Now you have everything you need to run PmagPy!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  },
  "toc-showtags": false
 },
 "nbformat": 4,
 "nbformat_minor": 2
}