spacepy.pycdf.istp.VarBundle

class spacepy.pycdf.istp.VarBundle(var)[source]

Collective handling of ISTP-compliant variable and its dependencies.

Representation of an ISTP-compliant variable bundled together with its dependencies to enable aggregate operations. Normally used to copy a subset of data from one CDF to another by chaining operations.

Unusual or indecipherable error messages may indicate an ISTP compliance issue; see VariableChecks for some checks.

Parameters
varVar

Variable to process

Examples

>>> import spacepy.pycdf
>>> import spacepy.pycdf.istp
>>> #https://rbsp-ect.newmexicoconsortium.org/data_pub/rbspa/hope/level3/pitchangle/2012/
>>> infile = spacepy.pycdf.CDF('rbspa_rel04_ect-hope-PA-L3_20121201_v7.1.0.cdf')
>>> infile['FPDU']
<Var:
CDF_FLOAT [3228, 11, 72]
>
>>> infile['FPDU'].attrs
<zAttrList:
CATDESC: HOPE differential proton flux [CDF_CHAR]
DEPEND_0: Epoch_Ion [CDF_CHAR]
DEPEND_1: PITCH_ANGLE [CDF_CHAR]
DEPEND_2: HOPE_ENERGY_Ion [CDF_CHAR]
...
>
>>> b = spacepy.pycdf.istp.VarBundle(infile['FPDU'])
>>> outfile = spacepy.pycdf.CDF('output.cdf', create=True)
>>> b.slice(1, 2, single=True).output(outfile)
<VarBundle:
FPDU: CDF_FLOAT [3228, 72]
Epoch_Ion: CDF_EPOCH [3228]
    Epoch_Ion_DELTA: CDF_REAL4 [3228]
PITCH_ANGLE: CDF_FLOAT ---
    Pitch_LABL: CDF_CHAR*5 ---
HOPE_ENERGY_Ion: CDF_FLOAT [3228, 72]
    ENERGY_Ion_DELTA: CDF_FLOAT [3228, 72]
    Energy_LABL: CDF_CHAR*3 [72] NRV
>
>>> outfile['FPDU']
<Var:
CDF_FLOAT [3228, 72]
>
>>> outfile['FPDU'].attrs
<zAttrList:
CATDESC: HOPE differential proton flux [CDF_CHAR]
DEPEND_0: Epoch_Ion [CDF_CHAR]
DEPEND_1: HOPE_ENERGY_Ion [CDF_CHAR]
...
>
>>> outfile.close()
>>> infile.close()

mean(dim)

Take the mean of a dimension.

operations()

Operations of this bundle

output(output[, suffix])

Output the variables as modified

slice(dim[, start, stop, step, single])

Slice on a single dimension

sum(dim)

Sum across a dimension.

variables()

Description of variable output from the bundle

mean(dim)[source]

Take the mean of a dimension.

Take mean of the main variable of the bundle across the given dimension. That dimension disappears from the output and dependencies (including their uncertainties) are assumed to be constant across the summed dimension. The uncertainty of the main variable, if any, is appropriately propagated.

Invalid values are excluded fromthe mean. This does not work well for variables that define multiple VALIDMIN/VALIDMAX based on position within a dimension; the smallest VALIDMIN/largest VALIDMAX rather than the position-specific value.

Averaging occurs after slicing, to allow averaging of a subset of a dimension. A single element slice (which removes the dimension) is incompatible with averaging over that dimension.

There is not currently a way to “undo” a mean; create a new bundle instead.

Parameters
dimint

CDF dimension to average. This is the dimension as specified in the CDF (0-base for RV variables, 1-base for NRV) and does not change with successive slicing or summing. This must be a positive number (no support for e.g. -1 for last dimension.)

Returns
VarBundle

This bundle, for method chaining. This is not a copy: the original object is updated.

Examples

See the VarBundle examples for creating output.

>>> import spacepy.pycdf
>>> import spacepy.pycdf.istp
>>> infile = spacepy.pycdf.CDF('rbspa_rel04_ect-hope-PA-L3_20121201_v7.1.0.cdf')
>>> b = spacepy.pycdf.istp.VarBundle(infile['Counts_P'])
>>> #Average over dimension 1 (pitch angle)
>>> b.mean(1)
>>> #Get a new bundle (without the previous sum)
>>> b = spacepy.pycdf.istp.VarBundle(infile['Counts_P'])
>>> #Average over first 10 elements of dimension 2 (energy bins)
>>> b.slice(2, 0, 10).mean(2)
>>> infile.close()
output(output, suffix=None)[source]

Output the variables as modified

Parameters
outputCDF

Output CDF to receive the new data.

suffixstr

Suffix to append to the name of any variables that are changed for the output. This allows the output to contain multiple variables derived from the same input variable. The main variable and its DELTA variables will always have the suffix applied. Any dependencies will have the suffix applied only if they have changed from the input CDF (e.g. from slicing.)

Returns
VarBundle

This bundle, for method chaining.

Examples

>>> import spacepy.pycdf
>>> import spacepy.pycdf.istp
>>> infile = spacepy.pycdf.CDF('rbspa_rel04_ect-hope-PA-L3_20121201_v7.1.0.cdf')
>>> b = spacepy.pycdf.istp.VarBundle(infile['FPDU'])
>>> outfile = spacepy.pycdf.CDF('output.cdf', create=True)
>>> #Output the low energy half in one variable
>>> b.slice(2, 0, 36).output(outfile, suffix='_LoE')
>>> #And the high energy half in another variable
>>> b.slice(2, 36, 72).output(outfile, suffix='_HiE')
>>> outfile.close()
>>> infile.close()
operations()[source]

Operations of this bundle

Provides information describing the operations this bundle would perform.

Returns
list

Each element is a tuple: first element is a string with the name of the operation (i.e. method of VarBundle), next is also a tuple of positional arguments, and finally a dict of keyword arguments.

Examples

>>> import spacepy.pycdf
>>> import spacepy.pycdf.istp
>>> infile = spacepy.pycdf.CDF('rbspa_rel04_ect-hope-PA-L3_20121201_v7.1.0.cdf')
>>> b = spacepy.pycdf.istp.VarBundle(infile['FPDU'])
>>> b.slice(1, 2, single=True).operations()
  [('slice', (1, 2), {'single': True})]
>>> #Apply same operations to a different variable
>>> b2 = spacepy.pycdf.istp.VarBundle(infile['FEDU'])
>>> for op, args, kwargs in b2.operations():
...     getattr(b2, op)(*args, **kwargs)
slice(dim, start=None, stop=None, step=None, single=False)[source]

Slice on a single dimension

Selects subset of a dimension to include in the output. Slicing is done with reference to the dimensions of the main variable and the corresponding dimensions of all other variables are sliced similarly. The first non-record dimension of the variable is always 1; 0 is the record dimension (and is ignored for NRV variables). Multiple slices can be applied to select subsets of multiple dimensions; however, if one dimension is indexed multiple times, only the last one in the chain takes effect.

Interpretation of the slice parameters is like normal Python slicing, including the ability to use negative values, etc.

Passing in only a dimension “resets” the slice to include the entire dimension.

Parameters
dimint

CDF dimension to slice on. This is the dimension as specified in the CDF (0-base for RV variables, 1-base for NRV) and does not change with successive slicing. Each dimension can only be sliced once.

singlebool

Treat start as a single index and return only that index (reducing dimensionality of the data by one.)

startint

Index of first element of dim to include in the output. This can also be a sequence of indices to include, in which case stop and step must not be specified. This can be substantially slower than specifying stop and step.

stopint

Index of first element of dim to exclude from the output.

stepint

Increment between elements to include in the output.

Returns
VarBundle

This bundle, for method chaining. This is not a copy: the original object is updated.

Examples

See the VarBundle examples for creating output from the slices.

>>> import spacepy.pycdf
>>> import spacepy.pycdf.istp
>>> infile = spacepy.pycdf.CDF('rbspa_rel04_ect-hope-PA-L3_20121201_v7.1.0.cdf')
>>> b = spacepy.pycdf.istp.VarBundle(infile['FPDU'])
>>> #Select index 2 from axis 1
>>> b.slice(1, 2, single=True)
>>> #Select from index 5 to end for axis 2, keeping index 2 from axis 1
>>> b.slice(2, 5)
>>> #Select 10 through 15 on axis 2, but all of axis 1
>>> b.slice(1).slice(2, 10, 15)
>>> #Select just record 5 and 10
>>> b.slice(2).slice(0, [5, 10])
>>> infile.close()
sum(dim)[source]

Sum across a dimension.

Total the main variable of the bundle across the given dimension. That dimension disappears from the output and dependencies (including their uncertainties) are assumed to be constant across the summed dimension. The uncertainty of the main variable, if any, is appropriately propagated (quadrature sum.)

An invalid value for any element summed over will result in a fill value on the output. This does not work well for variables that define multiple VALIDMIN/VALIDMAX based on position within a dimension; the smallest VALIDMIN/largest VALIDMAX rather than the position-specific value.

Summing occurs after slicing, to allow summing of a subset of a dimension. A single element slice (which removes the dimension) is incompatible with summing over that dimension.

There is not currently a way to “undo” a sum; create a new bundle instead.

Parameters
dimint

CDF dimension to total. This is the dimension as specified in the CDF (0-base for RV variables, 1-base for NRV) and does not change with successive slicing or summing. This must be a positive number (no support for e.g. -1 for last dimension.)

Returns
VarBundle

This bundle, for method chaining. This is not a copy: the original object is updated.

Examples

See the VarBundle examples for creating output.

>>> import spacepy.pycdf
>>> import spacepy.pycdf.istp
>>> infile = spacepy.pycdf.CDF('rbspa_rel04_ect-hope-PA-L3_20121201_v7.1.0.cdf')
>>> b = spacepy.pycdf.istp.VarBundle(infile['Counts_P'])
>>> #Total over dimension 1 (pitch angle)
>>> b.sum(1)
>>> #Get a new bundle (without the previous sum)
>>> b = spacepy.pycdf.istp.VarBundle(infile['Counts_P'])
>>> #Total over first 10 elements of dimension 2 (energy bins)
>>> b.slice(2, 0, 10).sum(2)
>>> infile.close()
variables()[source]

Description of variable output from the bundle

Provides information describing the variables output from the bundle

Returns
list

Each element is a list-of-tuples. The list corresponds to a dimension of the master var: first the master var itself, then the uncertainties and labels associated with each dimension. Each element of these sublists is then a tuple of variable name and shape on the output (itself a tuple). If a variable isn’t included in the output (sliced away), its shape will be None.

Examples

>>> import spacepy.pycdf
>>> import spacepy.pycdf.istp
>>> infile = spacepy.pycdf.CDF('rbspa_rel04_ect-hope-PA-L3_20121201_v7.1.0.cdf')
>>> b = spacepy.pycdf.istp.VarBundle(infile['FPDU'])
>>> b.slice(1, 2, single=True).variables()
[[('FPDU', (100, 72))],
 [('Epoch_Ion', (100,)), ('Epoch_Ion_DELTA', (100,))],
 [('PITCH_ANGLE', None), ('Pitch_LABL', None)],
 [('HOPE_ENERGY_Ion', (100, 72)),
  ('ENERGY_Ion_DELTA', (100, 72)),
  ('Energy_LABL', (72,))]]