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
- var
Var
Variable to process
- var
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 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.
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
- output
CDF
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.)
- output
- 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 casestop
andstep
must not be specified. This can be substantially slower than specifyingstop
andstep
.- 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,))]]