ds format

Documentation version: 2.0.1 3.0.0 3.1.0 3.2.0 3.3.3 3.4.0 3.5.1 (latest) master
You are viewing documentation for version 3.0.0. The latest release is 3.5.1.
GitHub

Python API

The ds-format Python package provides API for reading, writing and manipulating data fies. The library can be imported with:

import ds_format as ds

Contents

Function Description
attr Get or set a dataset or variable attribute.
attrs Get variable or dataset attributes.
dim Get a dimension size.
dims Get dataset or variable dimensions or set variable dimensions.
find Find a variable, dimension or attribute matching a glob pattern in a dataset.
findall Find variables, dimensions or attributes matching a glob pattern in a dataset.
group_by Group values along a dimension.
merge Merge datasets along a dimension.
meta Get dataset or variable metadata.
read Read dataset from a file.
readdir Read multiple files in a directory.
rename Rename a variable.
rename_attr Rename a dataset or variable attribute.
rename_dim Rename a dimension.
require Require that a variable, dimension or attribute is defined in a dataset.
rm Remove a variable.
rm_attr Remove a dataset or variable attribute.
select Filter dataset by a selector.
size Get variable size.
type Get or set variable type.
var Get or set variable data.
vars Get all variable names in a dataset.
write Write dataset to a file.

Constants

ds.drivers.netcdf.JD_UNITS

days since -4713-11-24 12:00 UTC

NetCDF units for storing Julian date time variables.

ds.drivers.netcdf.JD_CALENDAR

proleptic_greogorian

NetCDF calendar for storing Julian date time variables.

Variables

mode

Error handling mode. If “strict”, handle missing variables, dimensions and attributes as errors. If “moderate”, report a warning. If “soft”, ignore missing items. Overrides the environment variable DS_MODE.

Examples:

Set error handling mode to strict.

ds.mode = 'strict'

Environment variables

DS_MODE

The same as mode.

Functions

attr

Get or set a dataset or variable attribute.

Usage: attr(d, attr, *value, var=None)

Arguments:

Options:

Return value:

Attribute value if value is not set, otherwise None.

attrs

Get variable or dataset attributes.

Usage: attrs(d, var=None, *value)

Arguments:

Options:

Return value:

Attributes (dict).

dim

Get a dimension size.

Usage: dim(d, dim, full=None)

Arguments:

Options:

Return value:

Dimension size or 0 if the dimension does not exist (int).

dims

Aliases: get_dims

Get dataset or variable dimensions or set variable dimensions.

Usage:

dims(d, var=None, *value, full=False, size=False)
get_dims(d, var=None, full=False, size=False)

The function get_dims (deprecated) is the same as dims, but assumes that size is True if var is None and does not allow setting of dimensions.

Arguments:

Options:

Return value:

If size is False, a list of dataset or variable dimension names (list of str). If size is True, a dictionary of dataset or variable dimension names and sizes (dict), where a key is a dimension name (str) and the value is the dimension size (int). The order of keys in the dictionary is not guaranteed. Dataset dimensions are the dimensions of all variables together.

find

Find a variable, dimension or attribute matching a glob pattern in a dataset.

Usage: find(d, what, name, var=None)

If more than one name matches the pattern, raises ValueError.

Arguments:

Options:

Return value:

A variable, dimension or attribute name matching the pattern, or name if no matching name is found (str).

findall

Find variables, dimensions or attributes matching a glob pattern in a dataset.

Usage: findall(d, what, name, var=None)

Arguments:

Options:

Return value:

A list of variables, dimensions or attributes matching the pattern, or [name] if no matching names are found (list of str).

attrs

Get variable or dataset attributes.

Usage: attrs(d, var=None, *value)

Arguments:

Options:

Return value:

Attributes (dict).

group_by

Group values along a dimension.

Usage: group_by(d, dim, group, func)

Each variable with a given dimension dim is split by group into subsets. Each subset is replaced with a value computed by func.

Arguments:

Return value:

None

merge

Merge datasets along a dimension.

Usage: merge(dd, dim, new=None, variables=None)

Merge datasets along a dimension dim. If the dimension is not defined in the dataset, merge along a new dimension dim. If new is None and dim is not new, variables without the dimension are set with the first occurrence of the variable. If new is not None and dim is not new, variables without the dimension dim are merged along a new dimension new. If variables is not None, only those variables are merged along a new dimension and other variables are set to the first occurrence of the variable.

Arguments:

Options:

Return value:

A dataset (dict).

meta

Aliases: get_meta

Get or set dataset or variable metadata.

Usage: meta(d, var=None, meta=None, create=False)

Arguments:

Options:

Return value:

Metadata (dict).

read

Read dataset from a file.

Usage: read(filename, variables=None, sel=None, full=False, jd=False)

Arguments:

Options:

Return value:

Dataset (dict).

Supported formats:

readdir

Read multiple files in a directory.

Usage: readdir(dirname, variables=None, merge=None, warnings=[], …)

Arguments:

Options:

Return value:

A list of datasets (list of dict) if merge is None or a merged dataset (dict) if merge is a dimension name.

rename

Rename a variable.

Usage: rename(d, old, new)

Any dimension with the same name is also renamed.

Arguments:

Return value:

None

rename_attr

Rename a dataset or variable attribute.

Arguments:

Options:

Return value:

None

rename

Rename a dimension.

Usage: rename_dim(d, old, new)

Arguments:

Return value:

None

require

Require that a variable, dimension or attribute is defined in a dataset.

Usage: require(d, what, name, var=None, full=False)

If the item is not found and the mode is “soft”, returns False. If the mode is “strict”, raises NameError. If the mode is “moderate”, produces a warning and returns False.

Arguments:

Options:

Return value:

true if the required item is defined in the dataset, otherwise false or raises an exception depending on the mode.

rm

Remove a variable.

Usage: rm(d, var)

Arguments:

Return value:

None

rm_attr

Remove a dataset or variable attribute.

Usage: rm_attr(d, attr, var)

Arguments:

Options:

Return value:

None

select

Filter dataset by a selector.

Usage: select(d, sel)

Arguments:

Return value:

None

size

Get variable size.

Usage: size(d, var)

Variable size is determined based on the size of the variable data if defined, or by variable metadata attribute .size.

Arguments:

Return value:

Variable size (list) or None if not defined.

type

Get or set variable type.

Usage: type(d, var, *value)

Variable type is determined based on the type of the variable data if defined, or by variable metadata attribute .type.

Arguments:

Return value:

Variable type (str) or None if not defined.

var

Get or set variable data.

Usage: var(d, var, *value)

Arguments:

Return value:

Variable data (np.ndarray or np.generic) or None if the variable data are not defined or value is supplied. If the variable data are a list or tuple, they are converted to np.ndarray, or to np.ma.MaskedArray if they contain None, which is masked. If the variable data are int, float, bool, str or bytes, they are converted to np.generic. Raises ValueError if the output dtype is not one of float32, float64, int8, int16, int32, int64, uint8, uint16, uint32, uint64, bool, bytes`, `str`, or `object` for which all items are an instance of `str` or `bytes`.

vars

Aliases: get_vars

Get all variable names in a dataset.

Usage: get_vars(d, full=False)

Arguments:

Options:

Return value:

Variable names (list of str).

with_mode

Context manager which temporarily changes ds.mode.

Arguments:

Examples:

A block of code in which ds.mode is set to “soft”.

with ds.with_mode('soft'):
	...

write

Write dataset to a file.

Usage: write(filename, d)

The file type is determined from the file extension.

Arguments:

Return value:

None

Supported formats: