Array manipulation routines

Operations that affect the shape or other attributes of the Var, while leaving the data intact.

Var.__call__(ignore_mismatch=False, **kwargs)[source]

Keyword-based data subsetting.

Parameters
ignore_mismatchboolean (optional)

If True, any keywords that don’t match an axis are ignored. Default is False

**kwargsone or more keyword parameters

The keys are the Axis names (or Axis class names), and the values are either a tuple of the desired (lower,upper) range, or a single Axis value. E.g., lat = (-45,45) or lat = 10.5

Returns
subset_varVar

A new Var, restricted to the specified domain.

Notes

There are a couple of special prefixes which can be prepended to each keyword to alter the subsetting behaviour. They can be used together.

  • i_ indicates that the values are indices into the axis, and not the axis values themselves. Indices start at 0. E.g. myvar(i_time = 0) selects the first time step of the variable, and myvar(i_lon=(10,20)) selects the 11th through 21st longitudes.

  • l_ indicates that you are providing an explicit list of coordinates, instead of a range. E.g. myvar(l_lon = (105.,106.,107.,108))

  • n_ returns the complement of the set you request; that is, everything except the specified selection. E.g. myvar(n_lat = (60, 90)) returns all latitudes except those between 60 and 90N.

  • m_ triggers an arithmetic mean over the specified range. E.g., myvar(m_lon = (10, 80)) is a shortcut for doing myvar(lon = (10,80)).mean('lon').

  • s_ triggers a call to squeeze on the specified axis, so that if only one value is selected the degenerate axis is removed. E.g., myvar(s_lon = 5) is a shortcut for doing myvar(lon = 5).squeeze() or myvar.squeeze(lon=5).

Examples

>>> from pygeode.tutorial import t1
>>> print(t1.vars)
[<Var 'Temp'>]
>>> T = t1.Temp
>>> print(T)
<Var 'Temp'>:
  Units: K  Shape:  (lat,lon)  (31,60)
  Axes:
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  Add_Var (dtype="float64")
>>> print(T(lat=30,lon=(100,200)))
<Var 'Temp'>:
  Units: K  Shape:  (lat,lon)  (1,17)
  Axes:
    lat <Lat>      :  30 N
    lon <Lon>      :  102 E to 198 E (17 values)
  Attributes:
    {}
  Type:  SlicedVar (dtype="float64")
Var.slice

A helper to select subsets of this variable using slice notation. See Var._getitem_asvar().

Var._getitem_asvar(slices)[source]

Slice-based data subsetting.

Parameters
sliceslist of slices
Returns
subset_varVar

A new Var, restricted to the specified domain.

See also

Var.slice, Var.__call__, Var.__getitem__

Notes

A helper function so that standard python slicing notation can be used to subset a Var without loading the underlying data. A new Var object is returned.

Examples

>>> from pygeode.tutorial import t1
>>> print(t1.Temp)
<Var 'Temp'>:
  Units: K  Shape:  (lat,lon)  (31,60)
  Axes:
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  Add_Var (dtype="float64")
>>> print(t1.Temp.slice[10:-10, ::10])
<Var 'Temp'>:
  Units: K  Shape:  (lat,lon)  (11,6)
  Axes:
    lat <Lat>      :  30 S to 30 N (11 values)
    lon <Lon>      :  0 E to 300 E (6 values)
  Attributes:
    {}
  Type:  SlicedVar (dtype="float64")
>>> print(t1.Temp.slice[17, :])
<Var 'Temp'>:
  Units: K  Shape:  (lat,lon)  (1,60)
  Axes:
    lat <Lat>      :  12 N
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  SlicedVar (dtype="float64")
Var.squeeze(*iaxes, **kwargs)

Removes degenerate axes from a variable, reducing its dimensionality.

Parameters
*iaxesone or more axes (optional)

The axes to remove (they must already be degenerate). If no explicit axes are provided, then all degenerate axes are removed.

**kwargskeyword arguments

Keyword-based axis slicing. Selects a particular value along the axis and then removes the axis from the output. See Var.__call__() for a similar method which uses this keyword syntax.

Returns
squeezedVar

The squeezed variable

Var.extend(pos, *newaxes)

Adds more axes to a variable. Data will be duplicated along these new axes.

Parameters
posint

The position (within the variable’s current axes) to start inserting the new axes.

*newaxesone or more axes

The new axes to insert

Returns
extended_varVar

The variable, extended to include the new axes.

Examples

>>> from pygeode.tutorial import t1
>>> print(t1.Temp)
<Var 'Temp'>:
  Units: K  Shape:  (lat,lon)  (31,60)
  Axes:
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  Add_Var (dtype="float64")
>>> from pygeode import Pres
>>> paxis = Pres([1000,850,700])  # Create a pressure axis
>>> print(paxis)
pres <Pres>    :  1000 hPa to 700 hPa (3 values)
>>> extended_var = t1.Temp.extend(0, paxis)  # Extend the data with this axis
>>> print(extended_var)
<Var 'Temp'>:
  Units: K  Shape:  (pres,lat,lon)  (3,31,60)
  Axes:
    pres <Pres>    :  1000 hPa to 700 hPa (3 values)
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  ExtendedVar (dtype="float64")
Var.transpose(*axes)

Transposes the axes of a variable.

Parameters
*axesone or more axis identifiers (strings, Axis classes, integer indices)

The new order of the axes. Any unspecified axes will be appended after these.

Returns
transposed_varVar

The transposed variable.

Examples

>>> from pygeode.tutorial import t1
>>> print(t1.Temp)
<Var 'Temp'>:
  Units: K  Shape:  (lat,lon)  (31,60)
  Axes:
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  Add_Var (dtype="float64")
>>> transposed_var = t1.Temp.transpose('lon','lat')
>>> print(transposed_var)
<Var 'Temp'>:
  Units: K  Shape:  (lon,lat)  (60,31)
  Axes:
    lon <Lon>      :  0 E to 354 E (60 values)
    lat <Lat>      :  90 S to 90 N (31 values)
  Attributes:
    {}
  Type:  TransposedVar (dtype="float64")
Var.sorted(*iaxes, **kwargs)

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

Parameters
*iaxes(optional)

Which axes to sort. If not specified, then all axes are sorted. Axes can also be passed as keyword arguments, with a value of 1/0/-1 to specifiy a sort order of increasing/default/decreasing. If positional arguments are passed, or if an order of ‘0’ is specified, then the natural (default) order will be used for that type of axis.

Returns
sorted_varVar

The sorted version of the data.

Examples

>>> from pygeode.tutorial import t2
>>> print(t2.Temp)
<Var 'Temp'>:
  Shape:  (time,pres,lat,lon)  (3650,20,31,60)
  Axes:
    time <ModelTime365>:  Jan 1, 2011 00:00:00 to Dec 31, 2020 00:00:00 (3650 values)
    pres <Pres>    :  1000 hPa to 50 hPa (20 values)
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  TransposedVar (dtype="float64")
>>> print(t2.Temp.sorted('pres'))  # Sort by default/natural order
<Var 'Temp'>:
  Shape:  (time,pres,lat,lon)  (3650,20,31,60)
  Axes:
    time <ModelTime365>:  Jan 1, 2011 00:00:00 to Dec 31, 2020 00:00:00 (3650 values)
    pres <Pres>    :  1000 hPa to 50 hPa (20 values)
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  SortedVar (dtype="float64")
>>> # ^^ no change, since pressure was already in its natrual order (decreasing)
>>> print(t2.Temp.sorted(pres=1))  # Sort pressure explicitly as increasing order
<Var 'Temp'>:
  Shape:  (time,pres,lat,lon)  (3650,20,31,60)
  Axes:
    time <ModelTime365>:  Jan 1, 2011 00:00:00 to Dec 31, 2020 00:00:00 (3650 values)
    pres <Pres>    :  50 hPa to 1000 hPa (20 values)
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  SortedVar (dtype="float64")
Var.replace_axes(axisdict={}, ignore_mismatch=False, newaxes=None, keep_old_name=True, **kwargs)

Replaces one or more axes of a variable with new axes. The axis length must remain the same.

Parameters
axisdictdict (optional)

The keys are identifiers for the current axes, and the values are the replacement axes.

ignore_mismatchboolean (optional)

If True, will ignore axis identifiers that don’t match any axes of this variable. If False, will raise an exception on a mismatch. Default is False.

newaxeslist of axes (optional)

An explicit list of axes to use as replacements. Useful if you want to replace all the axes at the same time.

keep_old_nameboolean (optional)

If True, will keep the old axis name (with the new values). If False, the name ofthe new axis will be used. Default is True.

**kwargskeyword arguments

Similar to ‘axisdict’, but using keyword parameters instead of a dictionary.

Returns
new_varVar

The same variable, but with different axes. The variable data will remain unchanged.

Examples

>>> from pygeode.tutorial import t1
>>> print(t1.Temp)
<Var 'Temp'>:
  Units: K  Shape:  (lat,lon)  (31,60)
  Axes:
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  Add_Var (dtype="float64")
>>> from pygeode import XAxis, YAxis
>>> new_var = t1.Temp.replace_axes(lon=XAxis, lat=YAxis)
>>> print(new_var)
<Var 'Temp'>:
  Units: K  Shape:  (lat,lon)  (31,60)
  Axes:
    lat <YAxis>    :  -90  to 90  (31 values)
    lon <XAxis>    :  0  to 354  (60 values)
  Attributes:
    {}
  Type:  Replace_axes (dtype="float64")
>>> new_var = t1.Temp.replace_axes(lon=XAxis, lat=YAxis, keep_old_name=False)
>>> print(new_var)
<Var 'Temp'>:
  Units: K  Shape:  (yaxis,xaxis)  (31,60)
  Axes:
    yaxis <YAxis>  :  -90  to 90  (31 values)
    xaxis <XAxis>  :  0  to 354  (60 values)
  Attributes:
    {}
  Type:  Replace_axes (dtype="float64")
Var.rename(newname)

Assigns a new name to a variable

Parameters
newnamestring

The new name of the variable.

Returns
renamed_varVar

The same variable, but with a different name.

Notes

In most cases, you could probably change the name attribute of the variable directly instead of calling this method. However, if the variable is being used in other places, this method guarantees that the name change will only affect a local version of the variable, and won’t have any side-effects on other existing references.

Examples

>>> from pygeode.tutorial import t1
>>> print(t1.Temp.rename('i_prefer_really_long_variable_names'))
<Var 'i_prefer_really_long_variable_names'>:
  Units: K  Shape:  (lat,lon)  (31,60)
  Axes:
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  RenamedVar (dtype="float64")
Var.rename_axes(ignore_mismatch=False, axisdict={}, **namemap)

Renames the axes of a variable.

Parameters
ignore_mismatchboolean (optional)

If True, will ignore axis identifiers that don’t match any axes of this variable. If False, will raise an exception on a mismatch. Default is False.

axisdictdictionary

An explicit dictionary mapping old names to new names.

**namemapkeyword arguments

One or more keyword-based arguments. The parameters are the existing axis names, and the values are the new names to substitute.

Returns
new_varVar

The same variable, but with new names for the axes.

Examples

>>> from pygeode.tutorial import t1
>>> print(t1.Temp)
<Var 'Temp'>:
  Units: K  Shape:  (lat,lon)  (31,60)
  Axes:
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  Add_Var (dtype="float64")
>>> new_var = t1.Temp.rename_axes(lat="latitude",lon="longitude")
>>> print(new_var)
<Var 'Temp'>:
  Units: K  Shape:  (latitude,longitude)  (31,60)
  Axes:
    latitude <Lat> :  90 S to 90 N (31 values)
    longitude <Lon>:  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  Replace_axes (dtype="float64")
Var.fill(fill)

Replaces NaN (missing values) with some fill value.

Parameters
fillfloat or int

The fill value

Returns
filled_varVar

A new representation of the variable with missing values filled in.

See also

unfill
Var.unfill(fill)

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

Parameters
fill - float or int

The value to treat as missing

Returns
unfilled_varVar

A new represntation of the variable with the ‘fill’ values removed (replaced with NaN).

See also

fill
Var.as_type(dtype)

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

Parameters
dtypenumpy.dtype or string

The new data type to use.

Returns
casted_varVar

The same var, but with its values cast into a new type.

Examples

>>> from pygeode.tutorial import t1
>>> # Treat the values as single-precision
>>> print(t1.Temp.as_type('float32'))
<Var 'Temp' float32>:
  Units: K  Shape:  (lat,lon)  (31,60)
  Axes:
    lat <Lat>      :  90 S to 90 N (31 values)
    lon <Lon>      :  0 E to 354 E (60 values)
  Attributes:
    {}
  Type:  Cast (dtype="float32")

See Also: Var class overview