quickstart.html

<!DOCTYPE html>

<html lang="en" data-content_root="./">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />

    <title>SpacePy - A Quick Start Documentation &#8212; SpacePy v0.7.0 Manual</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b76e3c8a" />
    <link rel="stylesheet" type="text/css" href="_static/sphinxdoc.css?v=92e3d466" />
    <link rel="stylesheet" type="text/css" href="_static/graphviz.css?v=fd3f3429" />
    <link rel="stylesheet" type="text/css" href="_static/plot_directive.css" />
    
    <script src="_static/documentation_options.js?v=fe7df9b0"></script>
    <script src="_static/doctools.js?v=9a2dae69"></script>
    <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
        <script type="text/javascript" src="_static/copybutton.js"></script>
    <link rel="icon" href="_static/spacepy_favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="SpacePy Help" href="help.html" />
    <link rel="prev" title="Windows Installation" href="install_windows.html" /> 
  </head><body>

<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="index.html"><img src="_static/spacepy_logo.jpg" border="0" alt="spacepy_logo"/></a>
</div>

    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="help.html" title="SpacePy Help"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="install_windows.html" title="Windows Installation"
             accesskey="P">previous</a> |</li>
        <li><a href="https://spacepy.github.io/"">homepage</a>|&nbsp;</li>
        <li><a href="https://github.com/spacepy/spacepy">development</a>|&nbsp;</li>
        <li><a href="search.html">search</a>|&nbsp;</li>
       <li><a href="index.html">documentation </a> &raquo;</li>

        <li class="nav-item nav-item-this"><a href="">SpacePy - A Quick Start Documentation</a></li> 
      </ul>
    </div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="spacepy-a-quick-start-documentation">
<h1>SpacePy - A Quick Start Documentation<a class="headerlink" href="#spacepy-a-quick-start-documentation" title="Link to this heading">¶</a></h1>
<p>The SpacePy Team
(Steve Morley, Josef Koller, Dan Welling, Brian Larsen, Jon Niehof,
Mike Henderson)</p>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Link to this heading">¶</a></h2>
<p>See <a class="reference internal" href="install.html"><span class="doc">Installing SpacePy</span></a>.</p>
</section>
<section id="toolbox-a-box-full-of-tools">
<h2>Toolbox - A Box Full of Tools<a class="headerlink" href="#toolbox-a-box-full-of-tools" title="Link to this heading">¶</a></h2>
<p>Contains tools that don’t fit anywhere else but are, in general, quite
useful. The following functions are a selection of those implemented:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.windowMean" title="spacepy.toolbox.windowMean"><code class="xref py py-func docutils literal notranslate"><span class="pre">windowMean()</span></code></a>: windowing mean with variable window size and overlap</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.dictree" title="spacepy.toolbox.dictree"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictree()</span></code></a>: pretty prints the contents of dictionaries (recursively)</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.loadpickle" title="spacepy.toolbox.loadpickle"><code class="xref py py-func docutils literal notranslate"><span class="pre">loadpickle()</span></code></a>: single line convenience routine for loading Python pickles</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.savepickle" title="spacepy.toolbox.savepickle"><code class="xref py py-func docutils literal notranslate"><span class="pre">savepickle()</span></code></a>: same as loadpickle, but for saving</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.update" title="spacepy.toolbox.update"><code class="xref py py-func docutils literal notranslate"><span class="pre">update()</span></code></a>: updates the OMNI database and the leap seconds database (internet connection required)</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.tOverlap" title="spacepy.toolbox.tOverlap"><code class="xref py py-func docutils literal notranslate"><span class="pre">tOverlap()</span></code></a>: find interval of overlap between two time series</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.tCommon" title="spacepy.toolbox.tCommon"><code class="xref py py-func docutils literal notranslate"><span class="pre">tCommon()</span></code></a>: find times common to two time series</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.binHisto" title="spacepy.toolbox.binHisto"><code class="xref py py-func docutils literal notranslate"><span class="pre">binHisto()</span></code></a>: calculate number of bins for a histogram</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.medAbsDev" title="spacepy.toolbox.medAbsDev"><code class="xref py py-func docutils literal notranslate"><span class="pre">medAbsDev()</span></code></a>: find the median absolute deviation of a data series</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.normalize" title="spacepy.toolbox.normalize"><code class="xref py py-func docutils literal notranslate"><span class="pre">normalize()</span></code></a>: normalize a data series</p></li>
</ul>
</div></blockquote>
<p>Import this module as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.toolbox</span> <span class="k">as</span> <span class="nn">tb</span>
</pre></div>
</div>
<p>Examples:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.toolbox</span> <span class="k">as</span> <span class="nn">tb</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;entry1&#39;</span><span class="p">:</span><span class="s1">&#39;val1&#39;</span><span class="p">,</span> <span class="s1">&#39;entry2&#39;</span><span class="p">:</span><span class="mi">2</span><span class="p">,</span> <span class="s1">&#39;recurse1&#39;</span><span class="p">:{</span><span class="s1">&#39;one&#39;</span><span class="p">:</span><span class="mi">1</span><span class="p">,</span> <span class="s1">&#39;two&#39;</span><span class="p">:</span><span class="mi">2</span><span class="p">}}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">tb</span><span class="o">.</span><span class="n">dictree</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>
<span class="go">+</span>
<span class="go">|____entry1</span>
<span class="go">|____entry2</span>
<span class="go">|____recurse1</span>
<span class="go">     |____one</span>
<span class="go">     |____two</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">dat</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">random_sample</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">tb</span><span class="o">.</span><span class="n">binHisto</span><span class="p">(</span><span class="n">dat</span><span class="p">)</span>
<span class="go">(0.19151723370512266, 5.0)</span>
</pre></div>
</div>
</section>
<section id="time-and-coordinate-transformations">
<h2>Time and Coordinate Transformations<a class="headerlink" href="#time-and-coordinate-transformations" title="Link to this heading">¶</a></h2>
<p>Import the modules as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.time</span> <span class="k">as</span> <span class="nn">spt</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.coords</span> <span class="k">as</span> <span class="nn">spc</span>
</pre></div>
</div>
<section id="ticktock-class">
<h3>Ticktock Class<a class="headerlink" href="#ticktock-class" title="Link to this heading">¶</a></h3>
<p>The Ticktock class provides a number of time conversion routines and is
implemented as a container class built on the functionality of the Python
datetime module. The following time coordinates are provided</p>
<blockquote>
<div><ul class="simple">
<li><p>UTC: Coordinated Universal Time implemented as a <a class="reference external" href="https://docs.python.org/3/library/datetime.html#datetime.datetime" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.datetime</span></code></a></p></li>
<li><p>ISO: standard ISO 8601 format like <code class="docutils literal notranslate"><span class="pre">2002-10-25T14:33:59</span></code></p></li>
<li><p>TAI: International Atomic Time in units of seconds since Jan 1, 1958 (midnight) and includes leap seconds, i.e. every second has the same length</p></li>
<li><p>JD:  Julian Day</p></li>
<li><p>MJD: Modified Julian Day</p></li>
<li><p>UNX: UNIX time in seconds since Jan 1, 1970</p></li>
<li><p>RDT: Rata Die Time (Gregorian Ordinal Time) in days since Jan 1, 1 AD midnight</p></li>
<li><p>CDF: CDF Epoch time in milliseconds since Jan 1, year 0</p></li>
<li><p>DOY: Day of Year including fractions</p></li>
<li><p>leaps: Leap seconds according to <a class="reference external" href="ftp://maia.usno.navy.mil/ser7/tai-utc.dat">ftp://maia.usno.navy.mil/ser7/tai-utc.dat</a></p></li>
</ul>
</div></blockquote>
<p>To access these time coordinates, you’ll create an instance of a
Ticktock class, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">t</span> <span class="o">=</span> <span class="n">spt</span><span class="o">.</span><span class="n">Ticktock</span><span class="p">(</span><span class="s1">&#39;2002-10-25T12:30:00&#39;</span><span class="p">,</span> <span class="s1">&#39;ISO&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Instead of ISO you may use any of the formats listed above. You can also
use numpy arrays or lists of time points. <code class="docutils literal notranslate"><span class="pre">t</span></code> has now the class
attributes:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="o">.</span><span class="n">dtype</span> <span class="o">=</span> <span class="s1">&#39;ISO&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="o">.</span><span class="n">data</span> <span class="o">=</span> <span class="s1">&#39;2002-10-25T12:30:00&#39;</span>
</pre></div>
</div>
<p>FYI <code class="docutils literal notranslate"><span class="pre">t.UTC</span></code> is added automatically.</p>
<p>If you want to convert/add a class attribute from the list above,
simply type e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="o">.</span><span class="n">RTD</span>
</pre></div>
</div>
<p>You can replace RTD with any from the list above.</p>
<p>You can find out how many leap seconds were used by issuing the command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="o">.</span><span class="n">getleapsecs</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="timedelta-class">
<h3>Timedelta Class<a class="headerlink" href="#timedelta-class" title="Link to this heading">¶</a></h3>
<p>You can add/subtract time from a Ticktock class instance by using an
instance of <a class="reference external" href="https://docs.python.org/3/library/datetime.html#datetime.timedelta" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.timedelta</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mf">2.3</span><span class="p">)</span>
</pre></div>
</div>
<p>Then you can add by e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="o">+</span><span class="n">dt</span>
</pre></div>
</div>
</section>
<section id="coords-class">
<h3>Coords Class<a class="headerlink" href="#coords-class" title="Link to this heading">¶</a></h3>
<p>The spatial coordinate class includes the following coordinate systems in
Cartesian and spherical forms.</p>
<blockquote>
<div><ul class="simple">
<li><p>GZD:  (altitude, latitude, longitude) in km, deg, deg</p></li>
<li><p>GEO: cartesian, Re</p></li>
<li><p>GSM: cartesian, Re</p></li>
<li><p>GSE: cartesian, Re</p></li>
<li><p>SM: cartesian, Re</p></li>
<li><p>GEI: cartesian, Re</p></li>
<li><p>MAG: cartesian, Re</p></li>
<li><p>SPH: same as GEO but in spherical</p></li>
<li><p>RLL: radial distance, latitude, longitude, Re, deg, deg.</p></li>
</ul>
</div></blockquote>
<p>Create a Coords instance with spherical=’sph’ or cartesian=’car’
coordinates:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">spaco</span> <span class="o">=</span> <span class="n">spc</span><span class="o">.</span><span class="n">Coords</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">4</span><span class="p">],[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">2</span><span class="p">]],</span> <span class="s1">&#39;GEO&#39;</span><span class="p">,</span> <span class="s1">&#39;car&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>This will let you request, for example, all y-coordinates by <code class="docutils literal notranslate"><span class="pre">spaco.y</span></code>
or if given in spherical coordinates by <code class="docutils literal notranslate"><span class="pre">spaco.lati</span></code>. One can transform
the coordinates by <code class="docutils literal notranslate"><span class="pre">newcoord</span> <span class="pre">=</span> <span class="pre">spaco.convert('GSM',</span> <span class="pre">'sph')</span></code>.
This will return GSM coordinates in a spherical system. Since GSM
coordinates depend on time, you’ll have to add first a Ticktock
vector with the name <code class="docutils literal notranslate"><span class="pre">ticks</span></code> like <code class="docutils literal notranslate"><span class="pre">spaco.ticks</span> <span class="pre">=</span> <span class="pre">spt.Ticktock(['2002-02-02T12:00:00',</span>
<span class="pre">'2002-02-02T12:00:00'],</span> <span class="pre">'ISO')</span></code></p>
<p>Unit conversion will be implemented in the future.</p>
</section>
</section>
<section id="omni-module">
<h2>OMNI Module<a class="headerlink" href="#omni-module" title="Link to this heading">¶</a></h2>
<p>The OMNI database is an hourly resolution, multi-source data set
with coverage from November 1963; higher temporal resolution versions of
the OMNI database exist, but with coverage from 1995. The primary data are
near-Earth solar wind, magnetic field and plasma parameters. However, a
number of modern magnetic field models require derived input parameters,
and Qin and Denton (2007) have used the publicly-available OMNI database to provide
a modified version of this database containing all parameters necessary
for these magnetic field models. These data are available through ViRBO  - the Virtual
Radiation Belt Observatory.</p>
<p>In SpacePy this data is made available, at 1-hourly resolution, on request
on first import; if not downloaded when SpacePy is first used then any
attempt to import the omni module will
ask the user whether they wish to download the data. Should the user
require the latest data, the toolbox.update function can
be used to fetch the latest files from ViRBO.</p>
<p>The following example fetches the OMNI data for the storms of
October and November, 2003.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.time</span> <span class="k">as</span> <span class="nn">spt</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.omni</span> <span class="k">as</span> <span class="nn">om</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">datetime</span> <span class="k">as</span> <span class="nn">dt</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">st</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2003</span><span class="p">,</span><span class="mi">10</span><span class="p">,</span><span class="mi">20</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">en</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2003</span><span class="p">,</span><span class="mi">12</span><span class="p">,</span><span class="mi">5</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">delta</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ticks</span> <span class="o">=</span> <span class="n">spt</span><span class="o">.</span><span class="n">tickrange</span><span class="p">(</span><span class="n">st</span><span class="p">,</span> <span class="n">en</span><span class="p">,</span> <span class="n">delta</span><span class="p">,</span> <span class="s1">&#39;UTC&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="n">om</span><span class="o">.</span><span class="n">get_omni</span><span class="p">(</span><span class="n">ticks</span><span class="p">)</span>
</pre></div>
</div>
<p><em>data</em> is a dictionary containing all the OMNI data, by variable, for the timestamps
contained within the <code class="docutils literal notranslate"><span class="pre">Ticktock</span></code> object <em>ticks</em>. Now it is simple to plot Dst values
for instance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">pyplot</span> <span class="k">as</span> <span class="nn">p</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">ticks</span><span class="o">.</span><span class="n">eDOY</span><span class="p">,</span> <span class="n">data</span><span class="p">[</span><span class="s1">&#39;Dst&#39;</span><span class="p">])</span>
</pre></div>
</div>
</section>
<section id="the-irbempy-module">
<h2>The irbempy Module<a class="headerlink" href="#the-irbempy-module" title="Link to this heading">¶</a></h2>
<p>ONERA (Office National d’Etudes et Recherches Aerospatiales) initiated a
well-known FORTRAN library that provides routines to compute magnetic
coordinates for any location in the Earth’s magnetic field, to perform
coordinate conversions, to compute magnetic field vectors in geospace for
a number of external field models, and to propagate satellite orbits in
time. Older versions of this library were called ONERA-DESP-LIB. Recently
the library has changed its name to IRBEM-LIB and is maintained by a number
of different institutions.</p>
<p>A number of key routines in IRBEM-LIB have been made available through the
module <a class="reference internal" href="autosummary/spacepy.irbempy.html#module-spacepy.irbempy" title="spacepy.irbempy"><code class="xref py py-mod docutils literal notranslate"><span class="pre">irbempy</span></code></a>. Current functionality includes calls to calculate the local
magnetic field vectors at any point in geospace, calculation of the magnetic
mirror point for a particle of a given pitch angle (the angle between a
particle’s velocity vector and the magnetic field line that it immediately
orbits such that a pitch angle of 90 degrees signifies gyration perpendicular
to the local field) anywhere in geospace, and calculation of electron drift
shells in the inner magnetosphere.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.time</span> <span class="k">as</span> <span class="nn">spt</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.coordinates</span> <span class="k">as</span> <span class="nn">spc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.irbempy</span> <span class="k">as</span> <span class="nn">ib</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span> <span class="o">=</span> <span class="n">spt</span><span class="o">.</span><span class="n">Ticktock</span><span class="p">([</span><span class="s1">&#39;2002-02-02T12:00:00&#39;</span><span class="p">,</span> <span class="s1">&#39;2002-02-02T12:10:00&#39;</span><span class="p">],</span> <span class="s1">&#39;ISO&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">y</span> <span class="o">=</span> <span class="n">spc</span><span class="o">.</span><span class="n">Coords</span><span class="p">([[</span><span class="mi">3</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">],[</span><span class="mi">2</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">]],</span> <span class="s1">&#39;GEO&#39;</span><span class="p">,</span> <span class="s1">&#39;car&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ib</span><span class="o">.</span><span class="n">get_Bfield</span><span class="p">(</span><span class="n">t</span><span class="p">,</span><span class="n">y</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># {&#39;Blocal&#39;: array([  976.42565251,  3396.25991675]),</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1">#    &#39;Bvec&#39;: array([[ -5.01738885e-01,  -1.65104338e+02,   9.62365503e+02], [  3.33497974e+02,  -5.42111173e+02,   3.33608693e+03]])}</span>
</pre></div>
</div>
<p>One can also calculate the drift shell L* for a 90 degree pitch angle value by using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">ib</span><span class="o">.</span><span class="n">get_Lstar</span><span class="p">(</span><span class="n">t</span><span class="p">,</span><span class="n">y</span><span class="p">,</span> <span class="p">[</span><span class="mi">90</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># {&#39;Bmin&#39;: array([  975.59122652,  3388.2476667 ]),</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1">#  &#39;Bmirr&#39;: array([[  976.42565251], [ 3396.25991675]]),</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1">#  &#39;Lm&#39;: array([[ 3.13508015], [ 2.07013638]]),</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1">#  &#39;Lstar&#39;: array([[ 2.86958324], [ 1.95259007]]),</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1">#  &#39;MLT&#39;: array([ 11.97222034,  12.13378624]),</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1">#  &#39;Xj&#39;: array([[ 0.00081949], [ 0.00270321]])}</span>
</pre></div>
</div>
<p>Other function wrapped with the IRBEM library include:</p>
<ul class="simple">
<li><p><a class="reference internal" href="autosummary/spacepy.irbempy.html#spacepy.irbempy.find_Bmirror" title="spacepy.irbempy.find_Bmirror"><code class="xref py py-func docutils literal notranslate"><span class="pre">find_Bmirror()</span></code></a></p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.irbempy.html#spacepy.irbempy.find_magequator" title="spacepy.irbempy.find_magequator"><code class="xref py py-func docutils literal notranslate"><span class="pre">find_magequator()</span></code></a></p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.irbempy.html#spacepy.irbempy.coord_trans" title="spacepy.irbempy.coord_trans"><code class="xref py py-func docutils literal notranslate"><span class="pre">coord_trans()</span></code></a></p></li>
</ul>
</section>
<section id="pycdf-python-access-to-nasa-cdf-library">
<h2>pyCDF - Python Access to NASA CDF Library<a class="headerlink" href="#pycdf-python-access-to-nasa-cdf-library" title="Link to this heading">¶</a></h2>
<p>pycdf provides a “pythonic” interface to the NASA CDF library. It requires
that the NASA CDF C-library is properly installed.
The module can then be imported, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.pycdf</span> <span class="k">as</span> <span class="nn">cdf</span>
</pre></div>
</div>
<p>To open and close a CDF file, we use the <a class="reference internal" href="autosummary/spacepy.pycdf.CDF.html#spacepy.pycdf.CDF" title="spacepy.pycdf.CDF"><code class="xref py py-class docutils literal notranslate"><span class="pre">CDF</span></code></a> class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">cdf_file</span> <span class="o">=</span> <span class="n">cdf</span><span class="o">.</span><span class="n">CDF</span><span class="p">(</span><span class="s1">&#39;filename.cdf&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">cdf_file</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>CDF files, like standard Python files, act as context managers:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">cdf</span><span class="o">.</span><span class="n">CDF</span><span class="p">(</span><span class="s1">&#39;filename.cdf&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">cdf_file</span><span class="p">:</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="c1">#do brilliant things with cdf_file</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1">#cdf_file is automatically closed here</span>
</pre></div>
</div>
<p>CDF files act as Python dictionaries, holding CDF variables keyed
by the variable name:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">var_names</span> <span class="o">=</span> <span class="n">keys</span><span class="p">(</span><span class="n">cdf_file</span><span class="p">)</span> <span class="c1">#list of all variables</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">for</span> <span class="n">var_name</span> <span class="ow">in</span> <span class="n">cdf_file</span><span class="p">:</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="nb">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">cdf_file</span><span class="p">[</span><span class="n">var_name</span><span class="p">]))</span> <span class="c1">#number of records in each variable</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1">#list comprehensions work, too</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">lengths</span> <span class="o">=</span> <span class="p">[</span><span class="nb">len</span><span class="p">(</span><span class="n">cdf_file</span><span class="p">[</span><span class="n">var_name</span><span class="p">])</span> <span class="k">for</span> <span class="n">var_name</span> <span class="ow">in</span> <span class="n">cdf_file</span><span class="p">]</span>
</pre></div>
</div>
<p>Each CDF variable acts like a numpy array, where the first dimension is the
record number. Multidimensional CDF variables can be subscripted using
numpy’s multidimensional slice notation. Many common list operations are also
implemented, where each record acts as one element of the list and can be
independently deleted, inserted, etc. Creating a Python <a class="reference internal" href="autosummary/spacepy.pycdf.Var.html#spacepy.pycdf.Var" title="spacepy.pycdf.Var"><code class="xref py py-class docutils literal notranslate"><span class="pre">Var</span></code></a>
object does not read the data from disc; data are only read as they are
accessed:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">epoch</span> <span class="o">=</span> <span class="n">cdf_file</span><span class="p">[</span><span class="s1">&#39;Epoch&#39;</span><span class="p">]</span> <span class="c1">#Python object created, nothing read from disc</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">epoch</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="c1">#time of first record in CDF (datetime object)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">epoch</span><span class="p">[</span><span class="o">...</span><span class="p">]</span> <span class="c1">#copy all times to list a</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">epoch</span><span class="p">[</span><span class="o">-</span><span class="mi">5</span><span class="p">:]</span> <span class="c1">#copy last five times to list a</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b_gse</span> <span class="o">=</span> <span class="n">cdf_file</span><span class="p">[</span><span class="s1">&#39;B_GSE&#39;</span><span class="p">]</span> <span class="c1">#B_GSE is a 1D, three-element array</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bz</span> <span class="o">=</span> <span class="n">b_gse</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">]</span> <span class="c1">#Z component of first record</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bx</span> <span class="o">=</span> <span class="n">b_gse</span><span class="p">[:,</span><span class="mi">0</span><span class="p">]</span> <span class="c1">#copy X component of all records to bx</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bx</span> <span class="o">=</span> <span class="n">cdf_file</span><span class="p">[</span><span class="s1">&#39;B_GSE&#39;</span><span class="p">][:,</span><span class="mi">0</span><span class="p">]</span> <span class="c1">#same as above</span>
</pre></div>
</div>
</section>
<section id="the-datamodel-module">
<h2>The datamodel Module<a class="headerlink" href="#the-datamodel-module" title="Link to this heading">¶</a></h2>
<p>The SpacePy datamodel module implements classes that are designed to make implementing a standard
data model easy. The concepts are very similar to those used in standards like HDF5, netCDF and
NASA CDF.</p>
<p>The basic container type is analogous to a folder (on a filesystem; HDF5 calls this a
group): Here we implement this as a dictionary-like object, a <a class="reference internal" href="autosummary/spacepy.datamodel.SpaceData.html#spacepy.datamodel.SpaceData" title="spacepy.datamodel.SpaceData"><code class="xref py py-class docutils literal notranslate"><span class="pre">SpaceData</span></code></a> object, which
also carries attributes. These attributes can be considered to be global, i.e. relevant for the
entire folder. The next container type is for storing data and is based on a numpy array, this
class is <a class="reference internal" href="autosummary/spacepy.datamodel.dmarray.html#spacepy.datamodel.dmarray" title="spacepy.datamodel.dmarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">dmarray</span></code></a> and also carries attributes. The dmarray class is analogous to an
HDF5 dataset.</p>
<section id="guide-for-nasa-cdf-users">
<h3>Guide for NASA CDF users<a class="headerlink" href="#guide-for-nasa-cdf-users" title="Link to this heading">¶</a></h3>
<p>By definition, a NASA CDF only has a single ‘layer’. That is, a CDF contains a series of records
(stored variables of various types) and a set of attributes that are either global or local in
scope. Thus to use SpacePy’s datamodel to capture the functionality of CDF the two basic data types
are all that is required, and the main constraint is that datamodel.SpaceData objects cannot be
nested (more on this later, if conversion from a nested datamodel to a flat datamodel is required).</p>
<p>This is best illustrated with an example. Imagine representing some satellite data within a CDF –
the global attributes might be the mission name and the instrument PI, the variables might be the
instrument counts [n-dimensional array], timestamps[1-dimensional array and an orbit number [scalar].
Each variable will have one attribute (for this example).</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.datamodel</span> <span class="k">as</span> <span class="nn">dm</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mydata</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">SpaceData</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;MissionName&#39;</span><span class="p">:</span> <span class="s1">&#39;BigSat1&#39;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mydata</span><span class="p">[</span><span class="s1">&#39;Counts&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">dmarray</span><span class="p">([[</span><span class="mi">42</span><span class="p">,</span> <span class="mi">69</span><span class="p">,</span> <span class="mi">77</span><span class="p">],</span> <span class="p">[</span><span class="mi">100</span><span class="p">,</span> <span class="mi">200</span><span class="p">,</span> <span class="mi">250</span><span class="p">]],</span> <span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;Units&#39;</span><span class="p">:</span> <span class="s1">&#39;cnts/s&#39;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mydata</span><span class="p">[</span><span class="s1">&#39;Epoch&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">dmarray</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;units&#39;</span><span class="p">:</span> <span class="s1">&#39;minutes&#39;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mydata</span><span class="p">[</span><span class="s1">&#39;OrbitNumber&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">dmarray</span><span class="p">(</span><span class="mi">16</span><span class="p">,</span> <span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;StartsFrom&#39;</span><span class="p">:</span> <span class="mi">1</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mydata</span><span class="o">.</span><span class="n">attrs</span><span class="p">[</span><span class="s1">&#39;PI&#39;</span><span class="p">]</span> <span class="s1">&#39;Prof. Big Shot&#39;</span>
</pre></div>
</div>
<p>This has now populated a structure that can map directly to a NASA CDF. To visualize our datamodel,
we can use the <a class="reference internal" href="autosummary/spacepy.datamodel.SpaceData.html#spacepy.datamodel.SpaceData.tree" title="spacepy.datamodel.SpaceData.tree"><code class="xref py py-meth docutils literal notranslate"><span class="pre">tree()</span></code></a> method, which is equivalent to <a class="reference internal" href="autosummary/spacepy.toolbox.html#spacepy.toolbox.dictree" title="spacepy.toolbox.dictree"><code class="xref py py-func docutils literal notranslate"><span class="pre">dictree()</span></code></a>
(which works for any dictionary-like object, including PyCDF file objects).</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mydata</span><span class="o">.</span><span class="n">tree</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">+</span>
<span class="go">:|____MissionName</span>
<span class="go">:|____PI</span>
<span class="go">|____Counts</span>
<span class="go">    :|____Units</span>
<span class="go">|____Epoch</span>
<span class="go">    :|____units</span>
<span class="go">|____OrbitNumber</span>
<span class="go">    :|____StartsFrom</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.toolbox</span> <span class="k">as</span> <span class="nn">tb</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">tb</span><span class="o">.</span><span class="n">dictree</span><span class="p">(</span><span class="n">mydata</span><span class="p">,</span> <span class="n">attrs</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">+</span>
<span class="go">:|____MissionName</span>
<span class="go">:|____PI</span>
<span class="go">|____Counts</span>
<span class="go">    :|____Units</span>
<span class="go">|____Epoch</span>
<span class="go">    :|____units</span>
<span class="go">|____OrbitNumber</span>
<span class="go">    :|____StartsFrom</span>
</pre></div>
</div>
<p>Attributes are denoted by a leading colon. The global attributes are those in the base level,
and the local attributes are attached to each variable.</p>
<p>If we have data that has nested ‘folders’, allowed by HDF5 but not by NASA CDF, then how can this be
represented such that the data structure can be mapped directly to a NASA CDF? The data will need to
be flattened so that it is single layered. Let us now store some ephemerides in our data structure:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mydata</span><span class="p">[</span><span class="s1">&#39;Ephemeris&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">SpaceData</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">mydata</span><span class="p">[</span><span class="s1">&#39;Ephemeris&#39;</span><span class="p">][</span><span class="s1">&#39;GSM&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">dm</span><span class="o">.</span><span class="n">dmarray</span><span class="p">([[</span><span class="mi">1</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> <span class="p">[</span><span class="mf">1.2</span><span class="p">,</span><span class="mi">4</span><span class="p">,</span><span class="mf">2.5</span><span class="p">],</span> <span class="p">[</span><span class="mf">1.4</span><span class="p">,</span><span class="mi">5</span><span class="p">,</span><span class="mf">1.9</span><span class="p">]])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">tb</span><span class="o">.</span><span class="n">dictree</span><span class="p">(</span><span class="n">mydata</span><span class="p">,</span> <span class="n">attrs</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">+</span>
<span class="go">:|____MissionName</span>
<span class="go">:|____PI</span>
<span class="go">|____Counts</span>
<span class="go">    :|____Units</span>
<span class="go">|____Ephemeris</span>
<span class="go">    |____GSM</span>
<span class="go">|____Epoch</span>
<span class="go">    :|____units</span>
<span class="go">|____OrbitNumber</span>
<span class="go">    :|____StartsFrom</span>
</pre></div>
</div>
<p>Nested dictionary-like objects is not uncommon in Python (and can be exceptionally useful for representing
data, so to make this compatible with NASA CDF we call the <a class="reference internal" href="autosummary/spacepy.datamodel.SpaceData.html#spacepy.datamodel.SpaceData.flatten" title="spacepy.datamodel.SpaceData.flatten"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flatten()</span></code></a> method .</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">mydata</span><span class="o">.</span><span class="n">flatten</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">tb</span><span class="o">.</span><span class="n">dictree</span><span class="p">(</span><span class="n">mydata</span><span class="p">,</span> <span class="n">attrs</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="go">+</span>
<span class="go">:|____MissionName</span>
<span class="go">:|____PI</span>
<span class="go">|____Counts</span>
<span class="go">    :|____Units</span>
<span class="go">|____Ephemeris&lt;--GSM</span>
<span class="go">|____Epoch</span>
<span class="go">    :|____units</span>
<span class="go">|____OrbitNumber</span>
<span class="go">    :|____StartsFrom</span>
</pre></div>
</div>
<p>Note that the nested SpaceData has been moved to a variable with a new name reflecting its origin. The
data structure is now flat again and can be mapped directly to NASA CDF.</p>
</section>
<section id="converters-to-from-datamodel">
<h3>Converters to/from datamodel<a class="headerlink" href="#converters-to-from-datamodel" title="Link to this heading">¶</a></h3>
<p>Currently converters exist to read HDF5 and NASA CDF files directly to a SpacePy datamodel. This capability
also exists for JSON-headed ASCII files (RBSP/AutoPlot-compatible). A converter from the datamodel to HDF5
is now available and a converter to NASA CDF is under development. Also under development is the reverse of
the SpaceData.flatten method, so that flattened objects can be restored to their former glory.</p>
</section>
</section>
<section id="empiricals-module">
<h2>Empiricals Module<a class="headerlink" href="#empiricals-module" title="Link to this heading">¶</a></h2>
<p>The empiricals module provides access to some useful empirical models.
As of SpacePy 0.1.2, the models available are:</p>
<blockquote>
<div><ul class="simple">
<li><p><a class="reference internal" href="autosummary/spacepy.empiricals.html#spacepy.empiricals.getLmax" title="spacepy.empiricals.getLmax"><code class="xref py py-func docutils literal notranslate"><span class="pre">getLmax()</span></code></a> An empirical parametrization of the L* of the last closed drift shell
(Lmax)</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.empiricals.html#spacepy.empiricals.getPlasmaPause" title="spacepy.empiricals.getPlasmaPause"><code class="xref py py-func docutils literal notranslate"><span class="pre">getPlasmaPause()</span></code></a> The plasmapause location, following either Carpenter and Anderson
(1992) or Moldwin et al. (2002)</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.empiricals.html#spacepy.empiricals.getMPstandoff" title="spacepy.empiricals.getMPstandoff"><code class="xref py py-func docutils literal notranslate"><span class="pre">getMPstandoff()</span></code></a> The magnetopause standoff location (i.e. the sub-solar point), using
the Shue et al. (1997) model</p></li>
<li><p><a class="reference internal" href="autosummary/spacepy.empiricals.html#spacepy.empiricals.vampolaPA" title="spacepy.empiricals.vampolaPA"><code class="xref py py-func docutils literal notranslate"><span class="pre">vampolaPA()</span></code></a> A conversion of omnidirectional electron flux to pitch-angle dependent
flux, using the sin <sup>n</sup> model of Vampola (1996)</p></li>
</ul>
</div></blockquote>
<p>Each of the first three models is called by passing it a Ticktock object (see above) which then
calculates the model output using the 1-hour Qin-Denton OMNI data (from the
OMNI module; see above). For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.time</span> <span class="k">as</span> <span class="nn">spt</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.empiricals</span> <span class="k">as</span> <span class="nn">emp</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">ticks</span> <span class="o">=</span> <span class="n">spt</span><span class="o">.</span><span class="n">tickrange</span><span class="p">(</span><span class="s1">&#39;2002-01-01T12:00:00&#39;</span><span class="p">,</span><span class="s1">&#39;2002-01-04T00:00:00&#39;</span><span class="p">,</span><span class="mf">.25</span><span class="p">)</span>
</pre></div>
</div>
<p>calls <a class="reference internal" href="autosummary/spacepy.time.html#spacepy.time.tickrange" title="spacepy.time.tickrange"><code class="xref py py-func docutils literal notranslate"><span class="pre">tickrange()</span></code></a> and makes a Ticktock object
with times from midday on January 1st 2002 to midnight January 4th 2002,
incremented 6-hourly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Lpp</span> <span class="o">=</span> <span class="n">emp</span><span class="o">.</span><span class="n">getPlasmaPause</span><span class="p">(</span><span class="n">ticks</span><span class="p">)</span>
</pre></div>
</div>
<p>then returns the model plasmapause location using the default setting of the
Moldwin et al. (2002) model. The Carpenter and Anderson model can be used by
setting the Lpp_model keyword to ‘CA1992’.</p>
<p>The magnetopause standoff location can be called using this syntax, or can be
called for specific solar wind parameters (ram pressure, P, and IMF Bz) passed
through in a Python dictionary:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">data</span> <span class="o">=</span> <span class="p">{</span><span class="s1">&#39;P&#39;</span><span class="p">:</span> <span class="p">[</span><span class="mi">2</span><span class="p">,</span><span class="mi">4</span><span class="p">],</span> <span class="s1">&#39;Bz&#39;</span><span class="p">:</span> <span class="p">[</span><span class="o">-</span><span class="mf">2.4</span><span class="p">,</span> <span class="o">-</span><span class="mf">2.4</span><span class="p">]}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">emp</span><span class="o">.</span><span class="n">getMPstandoff</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span>  <span class="c1"># array([ 10.29156018,   8.96790412])</span>
</pre></div>
</div>
</section>
<section id="seapy-superposed-epoch-analysis-in-python">
<h2>SeaPy - Superposed Epoch Analysis in Python<a class="headerlink" href="#seapy-superposed-epoch-analysis-in-python" title="Link to this heading">¶</a></h2>
<p>Superposed epoch analysis is a technique used to reveal consistent responses,
relative to some repeatable phenomenon, in noisy data . Time series of the variables
under investigation are extracted from a window around the epoch and all data
at a given time relative to epoch forms the sample of events at that lag. The
data at each time lag are then averaged so that fluctuations not
consistent about the epoch cancel. In many superposed epoch analyses the mean of
the data at each time <em>u</em> relative to epoch, is used to
represent the central tendency. In SeaPy we calculate both the mean and the median,
since the median is a more robust measure of central tendency and is less affected
by departures from normality. SeaPy also calculates a measure of spread at each time
relative to epoch when performing the superposed epoch analysis; the interquartile
range is the default, but the median absolute deviation and bootstrapped confidence
intervals of the median (or mean) are also available.</p>
<p>As an example we fetch OMNI data for 4 years and perform a superposed epoch analysis
of the solar wind radial velocity, with a set of epoch times read from a text file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">datetime</span> <span class="k">as</span> <span class="nn">dt</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.seapy</span> <span class="k">as</span> <span class="nn">sea</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.omni</span> <span class="k">as</span> <span class="nn">om</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.toolbox</span> <span class="k">as</span> <span class="nn">tb</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">spacepy.time</span> <span class="k">as</span> <span class="nn">spt</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># now read the epochs for the analysis (the path specified is the default</span>
<span class="gp">&gt;&gt;&gt; </span><span class="c1"># install location on linux, different OS will have this elsewhere)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">epochs</span> <span class="o">=</span> <span class="n">sea</span><span class="o">.</span><span class="n">readepochs</span><span class="p">(</span><span class="s1">&#39;~/.local/lib/python2.7/site-packages/spacepy/data/SEA_epochs_OMNI.txt&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>The readepochs function can handle multiple formats by a user-specified format code.
ISO 8601 format is directly supported though it is not used here. The the readepochs docstring
for more information. As above, we use the get_omni function to retrieve the hourly data
from the OMNI module:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">ticks</span> <span class="o">=</span> <span class="n">spt</span><span class="o">.</span><span class="n">tickrange</span><span class="p">(</span><span class="n">dt</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2005</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">),</span> <span class="n">dt</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2009</span><span class="p">,</span><span class="mi">1</span><span class="p">,</span><span class="mi">1</span><span class="p">),</span> <span class="n">dt</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">1</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">omni1hr</span> <span class="o">=</span> <span class="n">om</span><span class="o">.</span><span class="n">get_omni</span><span class="p">(</span><span class="n">ticks</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">omni1hr</span><span class="o">.</span><span class="n">tree</span><span class="p">(</span><span class="n">levels</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span> <span class="n">verbose</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">+</span>
<span class="o">|</span><span class="n">____ByIMF</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz1</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz2</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz3</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz4</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz5</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Bz6</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____BzIMF</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____DOY</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Dst</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____G</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,</span> <span class="mi">3</span><span class="p">))</span>
<span class="o">|</span><span class="n">____Hr</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Kp</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Pdyn</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____Qbits</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">SpaceData</span> <span class="p">[</span><span class="mi">7</span><span class="p">])</span>
<span class="o">|</span><span class="n">____RDT</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____UTC</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____W</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,</span> <span class="mi">6</span><span class="p">))</span>
<span class="o">|</span><span class="n">____Year</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____akp3</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
<span class="o">|</span><span class="n">____dens</span> <span class="p">(</span><span class="n">spacepy</span><span class="o">.</span><span class="n">datamodel</span><span class="o">.</span><span class="n">dmarray</span> <span class="p">(</span><span class="mi">35065</span><span class="p">,))</span>
</pre></div>
</div>
<p>and these data are used for the superposed epoch analysis.
the temporal resolution is 1 hr and the window is +/- 3 days</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">delta</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">window</span><span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">sevx</span> <span class="o">=</span> <span class="n">sea</span><span class="o">.</span><span class="n">Sea</span><span class="p">(</span><span class="n">omni1hr</span><span class="p">[</span><span class="s1">&#39;velo&#39;</span><span class="p">],</span> <span class="n">omni1hr</span><span class="p">[</span><span class="s1">&#39;UTC&#39;</span><span class="p">],</span> <span class="n">epochs</span><span class="p">,</span> <span class="n">window</span><span class="p">,</span> <span class="n">delta</span><span class="p">)</span>
<span class="go">    #rather than quartiles, we calculate the 95% confidence interval on the median</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">sevx</span><span class="o">.</span><span class="n">sea</span><span class="p">(</span><span class="n">ci</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">sevx</span><span class="o">.</span><span class="n">plot</span><span class="p">()</span>
</pre></div>
</div>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="index.html">
              <img class="logo" src="_static/logo.png" alt="Logo"/>
            </a></p>
  <div>
    <h3><a href="index.html">Table of Contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">SpacePy - A Quick Start Documentation</a><ul>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#toolbox-a-box-full-of-tools">Toolbox - A Box Full of Tools</a></li>
<li><a class="reference internal" href="#time-and-coordinate-transformations">Time and Coordinate Transformations</a><ul>
<li><a class="reference internal" href="#ticktock-class">Ticktock Class</a></li>
<li><a class="reference internal" href="#timedelta-class">Timedelta Class</a></li>
<li><a class="reference internal" href="#coords-class">Coords Class</a></li>
</ul>
</li>
<li><a class="reference internal" href="#omni-module">OMNI Module</a></li>
<li><a class="reference internal" href="#the-irbempy-module">The irbempy Module</a></li>
<li><a class="reference internal" href="#pycdf-python-access-to-nasa-cdf-library">pyCDF - Python Access to NASA CDF Library</a></li>
<li><a class="reference internal" href="#the-datamodel-module">The datamodel Module</a><ul>
<li><a class="reference internal" href="#guide-for-nasa-cdf-users">Guide for NASA CDF users</a></li>
<li><a class="reference internal" href="#converters-to-from-datamodel">Converters to/from datamodel</a></li>
</ul>
</li>
<li><a class="reference internal" href="#empiricals-module">Empiricals Module</a></li>
<li><a class="reference internal" href="#seapy-superposed-epoch-analysis-in-python">SeaPy - Superposed Epoch Analysis in Python</a></li>
</ul>
</li>
</ul>

  </div>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="install_windows.html"
                          title="previous chapter">Windows Installation</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="help.html"
                          title="next chapter">SpacePy Help</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/quickstart.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<search id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="help.html" title="SpacePy Help"
             >next</a> |</li>
        <li class="right" >
          <a href="install_windows.html" title="Windows Installation"
             >previous</a> |</li>
        <li><a href="https://spacepy.github.io/"">homepage</a>|&nbsp;</li>
        <li><a href="https://github.com/spacepy/spacepy">development</a>|&nbsp;</li>
        <li><a href="search.html">search</a>|&nbsp;</li>
       <li><a href="index.html">documentation </a> &raquo;</li>

        <li class="nav-item nav-item-this"><a href="">SpacePy - A Quick Start Documentation</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
    &#169; Copyright 2011-2024, The SpacePy Team.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.3.7.
    </div>
  </body>
</html>