Var class overview

In PyGeode, all gridded data is represented by Var objects. They can be thought of as numpy arrays, which have been further abstracted in the following ways:

  • They can have a name, and other useful metadata associated with them

  • Each array dimension has an associated Axis object (a special type of Var), containing the coordinate values.

  • The array values are not immediately loaded into memory. Instead, the Var object knows where to find its values if it needs them, and will only bother to retrieve the values if something else is explicitly requesting them.

  • Similarly, operations on the data are not performed immediately. Instead, a new Var object is constructed, encapsulating the input Vars and the operation. If any of that data is ever requested, then the corresponding input data is retrieved, and only then is the operation performed.

class pygeode.Var[source]

Var.__init__(axes[, dtype, name, values, ...])

Create a new Var object with the given axes and values.

Useful attributes

Var.name

A description of the variable (may not be set).

Var.axes

The axes of the variable.

Var.naxes

The number of axes of this variable.

Var.shape

The dimensions of this variable, as a tuple.

Var.size

The total number of data points represented by this variable.

Var.atts

Dictionary of metadata associated with the variable.

Var.dtype

The numerical type of the data as a numpy.dtype.

Var.units

A string representation of the units of the variable.

Retrieving values from a variable

Var.get([pbar])

Gets a raw numpy array containing the values of the variable.

Var.__getitem__(slices)

Gets a raw numpy array containing a subset of values of the variable.

Var.load([pbar])

Returns a version of this variable with all data loaded into memory.

Variable Querying Routines

Var.hasaxis(iaxis)

Determines if a particular Axis is associated with this variable.

Var.whichaxis(iaxis)

Locates a particular Axis associated with this variable.

Var.getaxis(iaxis)

Grabs a reference to a particular Axis associated with this variable.

Var.getweights([iaxes])

Returns weights associated with the axes of this variable.

Array manipulation routines

Var.__call__([ignore_mismatch])

Keyword-based data subsetting.

Var.slice

A helper to select subsets of this variable using slice notation.

Var._getitem_asvar(slices)

Slice-based data subsetting.

Var.squeeze(*iaxes, **kwargs)

Removes degenerate axes from a variable, reducing its dimensionality.

Var.extend(pos, *newaxes)

Adds more axes to a variable.

Var.transpose(*axes)

Transposes the axes of a variable.

Var.sorted(*iaxes, **kwargs)

Sorts the data so that the axes have monotonically increasing values.

Var.replace_axes([axisdict, ...])

Replaces one or more axes of a variable with new axes.

Var.rename(newname)

Assigns a new name to a variable

Var.rename_axes([ignore_mismatch, axisdict])

Renames the axes of a variable.

Var.fill(fill)

Replaces NaN (missing values) with some fill value.

Var.unfill(fill)

Replaces all occurrences of the specified value with an NaN (missing value).

Var.as_type(dtype)

Casts a variable to a new data type (I.e., float32, float64, etc.)

Axis Reductions

Var.mean(*axes, **kwargs)

Computes the mean of this variable.

Var.nanmean(*axes, **kwargs)

Computes the mean of this variable, ignoring any NaNs in the domain.

Var.sum(*axes, **kwargs)

Computes the sum of this variable.

Var.nansum(*axes, **kwargs)

Computes the sum of this variable, ignoring any NaNs.

Var.stdev(*axes)

Computes the standard deviation of this variable.

Var.nanstdev(*axes)

Computes the standard deviation of this variable, ignoring any NaNs present.

Var.variance(*axes, **kwargs)

Computes the variance of this variable.

Var.nanvariance(*axes)

Computes the variance of this variable, ignoring any NaNs.

Var.min(*axes)

Computes the minimum value of this variable.

Var.nanmin(*axes)

Computes the minimum value of this variable, ignoring NaNs.

Var.max(*axes)

Computes the maximum value of this variable.

Var.nanmax(*axes)

Computes the maximum value of this variable, ignoring NaNs.

Var.argmin(axis)

Finds the index of the minumum value of this variable along the given axis.

Var.argmax(axis)

Finds the index of the maximum value of this variable along the given axis.

Arithmetic Operations on Variables

Operation

Method

Description

x + y

Var.__add__()

Element-wise addition

x - y

Var.__sub__()

Element-wise subtraction

x * y

Var.__mul__()

Element-wise multiplication

x / y

Var.__div__()

Element-wise division

x ** y

Var.__pow__()

Exponentiation

abs(x)

Var.__abs__()

Absolute value

-x

Var.__neg__()

Negation

+x

Var.__pos__()

Null operation

x % t

Var.__mod__()

Modulo

x < y

Var.__lt__()

True where x < y

x <= y

Var.__le__()

True where x <= y

x > y

Var.__gt__()

True where x > y

x >= y

Var.__ge__()

True where x >= y

x == y

Var.__eq__()

True where x == y

x != y

Var.__ne__()

True where x != y

Element-wise math

Var.sign()

Sign (+1 = positive, -1 = negative).

Var.exp()

Natural exponent.

Var.log()

Natural logarithm.

Var.log10()

Base-10 logarithm.

Var.cos()

Cosine of angle (in radians).

Var.sin()

Sine of angle (in radians).

Var.tan()

Tangent of angle (in radians).

Var.cosd()

Cosine of angle (in degrees) Called on the Var object.

Var.sind()

Sine of angle (in degrees) Called on the Var object.

Var.tand()

Tangent of angle (in degrees) Called on the Var object.

Var.sinh()

Hyperbolic sine.

Var.cosh()

Hyperbolic cosine.

Var.tanh()

Hyperbolic tangent.

Var.arcsin()

Inverse sine (in radians).

Var.arccos()

Inverse cosine (in radians).

Var.arctan()

Inverse tangent (in radians).

Var.arcsind()

Inverse sine (in degrees).

Var.arccosd()

Inverse cosine (in degrees).

Var.arctand()

Inverse tangent (in degrees).

Var.arcsinh()

Inverse hyperbolic sine.

Var.arccosh()

Inverse hyperbolic cosine.

Var.arctanh()

Inverse hyperbolic tangent.

Var.sqrt()

Square root.

Var.absolute()

Absolute value.

Var.nan_to_num()

Replace nan with zero and inf with finite numbers.

Var.real()

Real part of a complex array.

Var.imag()

Imaginary part of a complex array.

Var.angle()

Angles (arguments) of a complex array.

Var.conj()

Complex conjugate of a complex array.

Var.clip()

Clips values to given interval.

Other operations

Var.diff([axis, n])

Computes the forward difference along the given axis.

Var.deriv(daxis[, dx, df])

Computes derivative along the given axis.

Var.integrate(iaxis[, dx, v0, order, type])

Computes an indefinite integral along the given axis.

Var.interpolate(inaxis, outaxis[, inx, ...])

Interpolates a variable along a single dimension.

Var.smooth(saxis[, kernel, fft])

Smooths this variable along saxis by convolving it with an averaging kernel.

Var.fft_smooth(saxis, maxharm)

Smooths this variable along saxis by retaining leading Fourier components.

Var.composite(**kwargs)

Creates a composite based on this variable.

Var.flatten([inner, naxis])

Var.lag(iaxis, lags[, reverse])

Adds a lag axis with offset values.

Formatting and plotting operations

Var.plotatts

Dictionary of attributes for plotting; see plotting documentation.

Var.formatstr

Formatting code to use for printing values.

Var.formatvalue(value[, fmt, units, unitstr])

Returns formatted string representation of value.

Var.formatter()

Returns a matplotlib formatter (pygeode.AxisFormatter) for use in plotting.

Var.locator()

Returns a matplotlib locator object for use in plotting.
Var.__init__(axes, dtype=None, name=None, values=None, atts=None, plotatts=None)[source]

Create a new Var object with the given axes and values.

Parameters
axeslist/tuple

The Axis objects to associate with each of the data dimensions

dtypestring / Python type / numpy.dtype (optional)

The numerical type of the data (can be automatically determined from the array)

namestring (optional)

What to call the variable (i.e. for plot titles & when saving to file)

valuesnumpy.ndarray

The data to be wrapped.

attsdict (optional)

Any additional metadata to associate with the variable. The dictionary keys should be strings.

plotattsdict (optional)

Parameters that control plotting behaviour; default values are available. The dictionary keys should be strings.

Returns
outVar

The array, wrapped as a Var object.

Notes

The Var class can be instantiated directly (see constructing-vars), in which case providing an array for the values argument is necessary. Sub-classes of Var which define their values based on some operation need not provide any data; however all subclasses of Var need to call this __init__ method within their own __init__, to properly initialize all attributes.

Var.name string

A description of the variable (may not be set). Usually determined at the data source (e.g. input file), and may be used to identify the variable when saving to an output file.

Var.axes tuple of Axis classes

The axes of the variable. A tuple of Axis instances.

Var.naxes integer

The number of axes of this variable.

Var.shape tuple

The dimensions of this variable, as a tuple. Similar to numpy.ndarray.shape.

Var.size integer

The total number of data points represented by this variable.

Var.atts dictionary

Dictionary of metadata associated with the variable.

Var.dtype numpy dtype

The numerical type of the data as a numpy.dtype. See also Var.__init__().

Var.units string

A string representation of the units of the variable.

Var.plotatts dictionary

Dictionary of attributes for plotting; see plotting documentation.

Var.formatstr string

Formatting code to use for printing values.

Var.formatvalue(value, fmt=None, units=True, unitstr=None)[source]

Returns formatted string representation of value.

Parameters
valuefloat or int

Value to format.

fmtstring (optional)

Format specification. If the default None is specified, self.formatstr is used.

unitsboolean (optional)

If True, will include the units in the string returned. Default is True.

unitstrstring (optional)

String to use for the units; default is self.units.

Returns
If units is True, fmt % value + ‘ ‘ + unitstr. Otherwise fmt % value.

Notes

This is overridden in a number of Axis classes for more sophisticated formatting.

Var.formatter()[source]

Returns a matplotlib formatter (pygeode.AxisFormatter) for use in plotting.

Var.locator()[source]

Returns a matplotlib locator object for use in plotting.