spacepy.poppy

PoPPy – Point Processes in Python.

This module contains point process class types and a variety of functions for association analysis. The routines given here grew from work presented by Morley and Freeman (Geophysical Research Letters, 34, L08104, doi:10.1029/ 2006GL028891, 2007), which were originally written in IDL. This module is intended for application to discrete time series of events to assess statistical association between the series and to calculate confidence limits. Any mis-application or mis-interpretation by the user is the user’s own fault.

>>> import datetime as dt
>>> import spacepy.time as spt

Since association analysis is rather computationally expensive, this example shows timing.

>>> t0 = dt.datetime.now()
>>> onsets = spt.Ticktock(onset_epochs, 'CDF')
>>> ticksR1 = spt.Ticktock(tr_list, 'CDF')

Each instance must be initialized

>>> lags = [dt.timedelta(minutes=n) for n in range(-400,401,2)]
>>> halfwindow = dt.timedelta(minutes=10)
>>> pp1 = poppy.PPro(onsets.UTC, ticksR1.UTC, lags, halfwindow)

To perform association analysis

>>> pp1.assoc()
Starting association analysis
calculating association for series of length [3494, 1323] at 401 lags
>>> t1 = dt.datetime.now()
>>> print("Elapsed:  " + str(t1-t0))
Elapsed:  0:35:46.927138

Note that for calculating associations between long series at a large number of lags is SLOW!!

To plot

>>> pp1.plot(dpi=80)
Error: No confidence intervals to plot - skipping

To add 95% confidence limits (using 4000 bootstrap samples)

>>> pp1.aa_ci(95, n_boots=4000)

The plot method will then add the 95% confidence intervals as a semi- transparent patch.

Authors: Steve Morley and Jon Niehof Institution: Los Alamos National Laboratory Contact: smorley@lanl.gov, jniehof@lanl.gov

Copyright 2010 Los Alamos National Security, LLC.

Functions

applyRefractory(process1, period)	Apply a refractory period to an input discrete event time sequence
boots_ci(data, n, inter, func[, seed, ...])	Construct bootstrap confidence interval
plot_two_ppro(pprodata, pproref[, ratio, ...])	Overplots two PPro objects
value_percentile(sequence, target)	Find the percentile of a particular value in a sequence

Classes

PPro(process1, process2[, lags, winhalf, ...])

PoPPy point process object

spacepy.poppy.applyRefractory(process1, period)

Apply a refractory period to an input discrete event time sequence

All events in the refractory period are removed from the point process.

Parameters:

process1iterable

an iterable of datetimes, or a spacepy.time.Ticktock

perioddatetime.timedelta

length of refractory period

Returns:

keepiterable

returns pruned set of datetimes with same type as input NOTE: array subclasses will be lost

spacepy.poppy.boots_ci(data, n, inter, func, seed=None, target=None, sample_size=None, usepy=False, nretvals=1)

Construct bootstrap confidence interval

The bootstrap is a statistical tool that uses multiple samples derived from the original data (called surrogates) to estimate a parameter of the population from which the sample was drawn. This assumes that the sample is randomly drawn and hence is representative of the underlying distribution. The benefit of the bootstrap is that it is non-parametric and can be applied in situations where there is reasonable doubt about the characteristics of the underlying distribution. This routine uses the boot- strap for its most common application - the estimation of confidence intervals.

Parameters:

dataarray like

data to bootstrap

nint

number of surrogate series to select, i.e. number of bootstrap iterations.

internumerical

desired percentage confidence interval

funccallable

Function to apply to each surrogate series

sample_sizeint

number of samples in the surrogate series, default length of L{data}. This will change the statistical properties of the bootstrap and should only be used for good reason!

seedint

Optional seed for the random number generator. If not specified, numpy generator will not be reseeded; C generator will be seeded from the clock.

targetsame as data

a ‘target’ value. If specified, will also calculate percentage confidence of being at or above this value.

nretvalsint

number of return values from input function

Returns:

outsequence of float

inter percent confidence interval on value derived from func applied to the population sampled by data. If target is specified, also the percentage confidence of being above that value.

Examples

>>> data, n = numpy.random.lognormal(mean=5.1, sigma=0.3, size=3000), 4000.
>>> myfunc = lambda x: numpy.median(x)
>>> ci_low, ci_high = poppy.boots_ci(data, n, 95, myfunc)
>>> ci_low, numpy.median(data), ci_high
(163.96354196633686, 165.2393331896551, 166.60491435416566) iter. 1
... repeat
(162.50379144492726, 164.15218265100233, 165.42840588032755) iter. 2

For comparison

>>> data = numpy.random.lognormal(mean=5.1, sigma=0.3, size=90000)
>>> numpy.median(data)
163.83888237895815

Note that the true value of the desired quantity may lie outside the 95% confidence interval one time in 20 realizations. This occurred for the first iteration here.

For the lognormal distribution, the median is found exactly by taking the exponential of the “mean” parameter. Thus here, the theoretical median is 164.022 (6 s.f.) and this is well captured by the above bootstrap confidence interval.

spacepy.poppy.plot_two_ppro(pprodata, pproref, ratio=None, norm=False, title=None, xscale=None, figsize=None, dpi=80, ylim=[None, None], log=False, xticks=None, yticks=None)

Overplots two PPro objects

Parameters:

pprodataPPro

first point process to plot (in blue)

pprorefPPro

second process to plot (in red)

ratiofloat

multiply L{pprodata} by this ratio before plotting, useful for comparing processes of different magnitude

normboolean

normalize everything to L{pproref}, i.e. the association number for L{pproref} will always plot as 1.

titlestring

title to put on the plot

xscalefloat

scale x-axis by this factor (e.g. 60.0 to convert seconds to minutes)

figsize

passed through to matplotlib.pyplot.figure

dpiint

passed through to matplotlib.pyplot.figure

ylimlist

[minimum, maximum] values of y for the axis

logbollean

True for a log plot

xtickssequence or float

if provided, a list of tickmarks for the X axis

ytickssequance or float

if provided, a list of tickmarks for the Y axis

spacepy.poppy.value_percentile(sequence, target)

Find the percentile of a particular value in a sequence

Parameters:

sequencesequence

a sequence of values, sorted in ascending order

targetsame type as sequence

a target value

Returns:

outfloat

the percentile of target in sequence