API

Bin Averaging

Instrument independent seasonal averaging routine.

Supports bin averaging N-dimensional data over 1D and 2D bin distributions.

pysatSeasons.avg.mean_by_day(inst, data_label)

Calculate mean of data_label by day over Instrument.bounds.

Parameters:

inst (pysat.Instrument) – Instrument object to perform mean upon.
data_label (str) – Data product label to be averaged.

Returns:

mean – Mean of data_label indexed by day.

Return type:

pandas.Series

Note

The range of dates to be loaded, and the cadence used to load data over that range, is controlled by the inst.bounds attribute.

pysatSeasons.avg.mean_by_file(inst, data_label)

Calculate mean of data_label by orbit over Instrument.bounds.

Parameters:

inst (pysat.Instrument) – Instrument object to perform mean upon.
data_label (str) – Data product label to be averaged.

Returns:

mean – Mean of data_label indexed by start of each file.

Return type:

pandas.Series

Note

The range of dates to be loaded, and the cadence used to load data over that range, is controlled by the inst.bounds attribute.

pysatSeasons.avg.mean_by_orbit(inst, data_label)

Calculate mean of data_label by orbit over Instrument.bounds.

Parameters:

inst (pysat.Instrument) – Instrument object to perform mean upon.
data_label (str) – Data product label to be averaged.

Returns:

mean – Mean of data_label indexed by start of each orbit.

Return type:

pandas.Series

Note

The range of dates to be loaded, and the cadence used to load data over that range, is controlled by the inst.bounds attribute.

pysatSeasons.avg.median1D(const, bin1, label1, data_label, auto_bin=True, returnData=None, return_data=False)

Calculate a 1D median of nD data_label over time binned by label1.

Parameters:

const (Constellation or Instrument) – Constellation or Instrument object.
bin1 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
label1 (str) – Identifies data product for bin1.
data_label (list-like) – Strings identifying data product(s) to be averaged.
auto_bin (bool) – If True, function will create bins from the min, max and number of bins. If false, bin edges must be manually entered in bin1. (default=True)
returnData (bool or NoneType) – If True, also return binned data used to calculate the average in the output dictionary as ‘data’, in addition to the statistical outputs. Deprecated in favor of return_data. (default=None)
return_data (bool) – If True, also return binned data used to calculate the average in the output dictionary as ‘data’, in addition to the statistical outputs. (default=False)

Returns:

median – 1D median accessed by data_label as a function of label1 over the season delineated by bounds of passed instrument objects. Also includes ‘count’ and ‘avg_abs_dev’ as well as the values of the bin edges in ‘bin_x’. If returnData True, then binned data stored under ‘data’ under data_label.

Return type:

dict

Note

The range of dates to be loaded, and the cadence used to load data over that range, is controlled by the const.bounds attribute.

pysatSeasons.avg.median2D(const, bin1, label1, bin2, label2, data_label, returnData=None, auto_bin=True, return_data=False)

Calculate 2D median of nD data_label over time and label1 label2.

Parameters:

const (pysat.Constellation or Instrument) –
bin1 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
bin2 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
label1 (str) – Identifies data product for binning.
label2 (str) – Identifies data product for binning.
data_label (list-like) – Strings identifying data product(s) to be averaged.
returnData (bool or NoneType) – If True, also return binned data used to calculate the average in the output dictionary as ‘data’, in addition to the statistical outputs. Deprecated in favor of return_data. (default=None)
auto_bin (bool) – If True, function will create bins from the min, max and number of bins. If false, bin edges must be manually entered in bin*. (default=True)
return_data (bool) – If True, also return binned data used to calculate the average in the output dictionary as ‘data’, in addition to the statistical outputs. (default=False)

Returns:

median – 2D median accessed by data_label as a function of label1 and label2 over the season delineated by bounds of passed instrument objects. Also includes ‘count’ and ‘avg_abs_dev’ as well as the values of the bin edges in ‘bin_x’ and ‘bin_y’.

Return type:

dict

Note

The range of dates to be loaded, and the cadence used to load data over that range, is controlled by the const.bounds attribute.

Occurrence Probability

Occurrence probability routines, daily or by orbit.

Routines calculate the occurrence of an event greater than a supplied gate occurring at least once per day, or once per orbit. The probability is calculated as the (number of times with at least one hit in bin) / (number of times in the bin). The data used to determine the occurrence must be 1D. If a property of a 2D or higher dataset is needed attach a custom function that performs the check and returns a 1D Series.

Note

The included routines use the bounds attached to the supplied instrument object as the season of interest.

pysatSeasons.occur_prob.by_orbit2D(const, bin1, label1, bin2, label2, data_label, gate, returnBins=None, return_bins=False)

2D Occurrence Probability of data_label orbit-by-orbit over a season.

Deprecated since version 0.2.0: returnBins will be removed in v0.3.0, it is replaced by return_bins because it has standards compliant case.

If data_label is greater than gate at least once per orbit, then a 100% occurrence probability results. Season delineated by the bounds attached to Instrument object. Probability = (# of times with at least one hit) / (# of times in bin)

Parameters:

const (pysat.Instrument or pysat.Constellation) – Instrument/Constellation to use for calculating occurrence probability.
bin1 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
bin2 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
label1 (str) – Identifies data product for binX.
label2 (str) – Identifies data product for binX.
data_label (list of str) – Data product label(s) to calculate occurrence probability.
gate (list of values) – Values that data_label must achieve to be counted as an occurrence.
returnBins (bool or NoneType) – If True, also return arrays with values of bin edges, useful for pcolor. Deprecated in favor of return_bins. (default=None)
return_bins (bool) – If True, also return arrays with values of bin edges, useful for pcolor. (default=False)

Returns:

occur_prob – A dict of dicts indexed by data_label. Each entry is dict with entries ‘prob’ for the probability and ‘count’ for the number of orbits with any data; ‘bin_x’ and ‘bin_y’ are also returned if requested. Note that arrays are organized for direct plotting, y values along rows, x along columns.

Return type:

dict

Note

Season delineated by the bounds attached to Instrument object.

pysatSeasons.occur_prob.by_orbit3D(const, bin1, label1, bin2, label2, bin3, label3, data_label, gate, returnBins=None, return_bins=False)

3D Occurrence Probability of data_label orbit-by-orbit over a season.

Deprecated since version 0.2.0: returnBins will be removed in v0.3.0, it is replaced by return_bins because it has standards compliant case.

If data_label is greater than gate at least once per orbit, then a 100% occurrence probability results. Season delineated by the bounds attached to Instrument object. Prob = (# of times with at least one hit) / (# of times in bin)

Parameters:

const (pysat.Instrument or pysat.Constellation) – Instrument/Constellation to use for calculating occurrence probability.
bin1 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
bin2 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
bin3 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
label1 (str) – Identifies data product for binX.
label2 (str) – Identifies data product for binX.
label3 (str) – Identifies data product for binX.
data_label (list of str) – Identifies data product(s) to calculate occurrence probability e.g. inst[data_label].
gate (list of values) – Values that data_label must achieve to be counted as an occurrence.
returnBins (bool or NoneType) – If True, also return arrays with values of bin edges, useful for pcolor. Deprecated in favor of return_bins. (default=None)
return_bins (bool) – If True, also return arrays with values of bin edges, useful for pcolor. (default=False)

Returns:

occur_prob – A dict of dicts indexed by data_label. Each entry is dict with entries ‘prob’ for the probability and ‘count’ for the number of orbits with any data; ‘bin_x’, ‘bin_y’, and ‘bin_z’ are also returned if requested. Note that arrays are organized for direct plotting, z, y, x.

Return type:

dict

Note

Season delineated by the bounds attached to Instrument object.

pysatSeasons.occur_prob.daily2D(const, bin1, label1, bin2, label2, data_label, gate, returnBins=None, return_bins=False)

2D Daily Occurrence Probability of data_label > gate over a season.

Deprecated since version 0.2.0: returnBins will be removed in v0.3.0, it is replaced by return_bins because it has standards compliant case.

If data_label is greater than gate at least once per day, then a 100% occurrence probability results. Season delineated by the bounds attached to Instrument object. Probability = (# of times with at least one hit) / (# of times in bin)

Parameters:

const (pysat.Instrument or pysat.Constellation) – Instrument/Constellation to use for calculating occurrence probability.
bin1 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
bin2 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
label1 (str) – Identifies data product for binX.
label2 (str) – Identifies data product for binX.
data_label (list of str) – Identifies data product(s) to calculate occurrence probability e.g. inst[data_label].
gate (list of values) – Values that data_label must achieve to be counted as an occurrence.
returnBins (bool or NoneType) – If True, also return arrays with values of bin edges, useful for pcolor. Deprecated in favor of return_bins. (default=None)
return_bins (bool) – If True, also return arrays with values of bin edges, useful for pcolor. (default=False)

Returns:

occur_prob – A dict of dicts indexed by data_label. Each entry is dict with entries ‘prob’ for the probability and ‘count’ for the number of days with any data; ‘bin_x’ and ‘bin_y’ are also returned if requested. Note that arrays are organized for direct plotting, y values along rows, x along columns.

Return type:

dict

Note

Season delineated by the bounds attached to Instrument object.

pysatSeasons.occur_prob.daily3D(const, bin1, label1, bin2, label2, bin3, label3, data_label, gate, returnBins=None, return_bins=False)

3D Daily Occurrence Probability of data_label > gate over a season.

Deprecated since version 0.2.0: returnBins will be removed in v0.3.0, it is replaced by return_bins because it has standards compliant case.

If data_label is greater than gate at least once per day, then a 100% occurrence probability results. Season delineated by the bounds attached to Instrument object. Probability = (# of times with at least one hit) / (# of times in bin)

Parameters:

const (pysat.Instrument or pysat.Constellation) – Instrument/Constellation to use for calculating occurrence probability.
bin1 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
bin2 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
bin3 (array-like) – List holding [min, max, number of bins] or array-like containing bin edges.
label1 (str) – Identifies data product for binX.
label2 (str) – Identifies data product for binX.
label3 (str) – Identifies data product for binX.
data_label (list of str) – Identifies data product(s) to calculate occurrence probability e.g. inst[data_label].
gate (list of values) – Values that data_label must achieve to be counted as an occurrence.
returnBins (bool or NoneType) – If True, also return arrays with values of bin edges, useful for pcolor. Deprecated in favor of return_bins. (default=None)
return_bins (bool) – If True, also return arrays with values of bin edges, useful for pcolor. (default=False)

Returns:

occur_prob – A dict of dicts indexed by data_label. Each entry is dict with entries ‘prob’ for the probability and ‘count’ for the number of days with any data; ‘bin_x’, ‘bin_y’, and ‘bin_z’ are also returned if requested. Note that arrays are organized for direct plotting, z, y, x.

Return type:

dict

Note

Season delineated by the bounds attached to Instrument object.

Scatter Plot

Support scatterplot production over seasons of interest.

pysatSeasons.plot.scatterplot(const, labelx, labely, data_label, datalim, xlim=None, ylim=None)

Return 2D and 3D scatterplot of data_label over label* for a season.

Parameters:

const (pysat.Instrument or pysat.Constellation) – Instrument/Constellation to scatterplot.
labelx (str) – Data product for x-axis.
labely (str) – Data product for y-axis.
data_label (str or array-like of str) – Data product(s) to be scatter plotted.
datalim (numpy.array) – Plot limits for data_label.
xlim (numpy.array or None.) – Array for limits along x or y axes. If None, limits are determined automatically. (default=None)
ylim (numpy.array or None.) – Array for limits along x or y axes. If None, limits are determined automatically. (default=None)

Returns:

figs – Scatter plots of data_label as a function of labelx and labely over the season delineated by inst.bounds.

Return type:

list