API

terndata.flux.export_as_excel(filename: str, site: str, version: str | None = None, processing_level: str = 'L6') → None

Export the 30min/default dataset of the specified site, version and processing-level in excel format.

The method exports the dataset in excel format to the file specified

Parameters:

filename (str) – Output excel file (must have ‘xlxs’ as extension).
site (str) – Site name.
version (str | None) – Dataset version. Defaults to None, indicating latest versions.
processing_level (str) – dataset processing-level. Defaults to “L6”.

Returns:

A Excel workbook file path.

Raises:

Exception – An exception for fail to export dataset.

Return type:

None

terndata.flux.export_oneflux_csv(outdir: str, site: str, version: str | None = None, processing_level: str = 'L4') → list[str]

Export the 30min/default dataset of specified site, version and processing-level in oneFlux csv format.

The method exports the dataset in oneFlux csv format to the output folder specified. Note that there is no unit conversion i.e. unit for VPD remains as Kpa.

Parameters:

outdir (str) – Output folder for the generated csv files.
site (str) – Site name.
version (str | None) – Dataset version. Defaults to None, indicating latest versions.
processing_level (str) – dataset processing-level. Defaults to “L4”.

Returns:

A list of output oneflux csv files.

Raises:

Exception – An exception for fail to export dataset.

Return type:

list[str]

terndata.flux.get_attributes(site: str, version: None | str = None, processing_level: str = 'L3', variables: None | list[str] = None) → dict

Get the attributes for the 30min dataset’s variables specified.

Parameters:

site (str) – Site name.
version (None | str) – Dataset version. Defaults to None.
processing_level (str) – Dataset processing-level. Defaults to “L3”.
variables (None | list[str]) – List of variables

Returns:

A dictionary of the dataset’s attributes.

Raises:

ValueError – An exception for invalid variables specified.

Return type:

dict

terndata.flux.get_coordinates(site: str, version: str, processing_level: str = 'L3') → list[str]

Get dataset’s coordinate variables for the site, version, processing-level specified.

Parameters:

site (str) – Site name.
version (str) – Dataset version.
processing_level (str) – Dataset processing-level. Defaults to “L3”.

Returns:

A list of dataset’s coordinate variable names.

Return type:

list[str]

terndata.flux.get_dataset(site: str, version: str, processing_level: str = 'L3', missing_as_nan: bool = False) → Dataset

Get the 30-min (default) dataset for the specified site, version and processing-level.

Parameters:

site (str) – Site name.
version (str) – Dataset version.
processing_level (str) – Dataset processing-level. Defaults to “L3”
missing_as_nan (bool) – Whether to set the missing value as nan in the dataset. Defaults to False.

Returns:

An xarray dataset for the site, version and processing-level specified.

Raises:

Exception – Exception for fail to get dataset.

Return type:

Dataset

terndata.flux.get_datasets(sites: list[str], version: str, processing_level: str = 'L3', missing_as_nan: bool = False) → dict[str, Dataset]

Get the 30min/default datasets for the specified sites, version, processing-level.

Parameters:

sites (list[str]) – A list of site names.
version (str) – Dataset version.
processing_level (str) – Dataset processing-level. Defaults to “L3”.
missing_as_nan (bool) – Whether to set the missing value as nan in the dataset. Defaults to False.

Returns:

A dictionary of datasets for the specified sites, version and processing level, indexed by site name.

Return type:

dict[str, Dataset]

terndata.flux.get_global_attributes(site: str, version: None | str = None, processing_level: str = 'L3') → dict

Get the global attributes of the 30min dataset specified.

Parameters:

site (str) – Site name.
version (None | str) – Dataset version. Defaults to None.
processing_level (str) – Dataset processing-level. Defaults to “L3”.

Returns:

A dictionary of the dataset’s attributes.

Return type:

dict

terndata.flux.get_l6_dataset(site: str, version: str, ds_type: str, missing_as_nan: bool = False) → Dataset

Get the L6-dataset of the specified dataset type for the site specified.

Parameters:

site (str) – Site name.
version (str) – Dataset version.
ds_type (str) – Dataset type: 30min, hourly, daily, monthly, annual, cumulative.
missing_as_nan (bool) – Whether to set the missing value as nan in the dataset. Defaults to False.

Returns:

A xarray dataset.

Raises:

Exception – An exception for fail to get L6 dataset.

Return type:

Dataset

terndata.flux.get_processing_levels(site: str, version: str) → list[str]

Get the processing-levels available for the specified site and version.

Parameters:

site (str) – Site name.
version (str) – Dataset version.

Returns:

A list of processing-levels available for the specified site and version.

Raises:

Exception – Exception for fail to get processing-levels.

Return type:

list[str]

terndata.flux.get_sites() → GeoDataFrame

List all the sites and their locations.

The location is based on the latest version, L6 of 30-min/default dataset.

Returns:: A GeoDataFrame containing a list of site location with site name, longitude and latitude.
Raises:: Exception – An exception for fail to get sites.
Return type:: GeoDataFrame

terndata.flux.get_subset(site: str, version: None | str = None, processing_level: str = 'L3', variables: None | list[str] = None, start: None | str | datetime = None, end: None | str = None, keep_attrs: bool = True, keep_qcflags: bool = True, missing_as_nan: bool = False) → Dataset

Get a subset of dataset containing only the specified variables, and time range.

If variables is not specified, then all variables are included. If start/end time are not specified, then full time series of data is included. By default, corresponding variables’ qc flags are included. The start/end time can be in ISO-formatted string (i.e. yyyy-mm-dd HH:MM).

Parameters:

site (str) – Site name.
version (None | str) – Dataset version. Default to None.
processing_level (str) – Dataset processing-level. Default to “L3”
variables (None | list[str]) – Dataset variable names. Defaults to None.
start (None | str | datetime) – Data start time, an ISO-formatted string or datetime object. Defaults to None.
end (None | str) – Data end time, an ISO-formatted string or datetime object. Defaults to None.
keep_attrs (bool) – Whether to keep variable attributes. Defaults to True.
keep_qcflags (bool) – Whether to keep the corresponding variables’ QC flags. Defaults to True.
missing_as_nan (bool) – Whether to set the missing value as nan in the dataset. Defaults to False.

Returns:

A xarray dataset with the variables specified.

Raises:

Exception – An exception for fail to get subset.
ValueError – An exception for invalid ISO-formatted date parameter.

Return type:

Dataset

terndata.flux.get_subsets(sites: list[str], version: None | str = None, processing_level: str = 'L3', variables: None | list[str] = None, start: None | str = None, end: None | str = None, keep_attrs: bool = True, keep_qcflags: bool = True, missing_as_nan: bool = False) → dict[str, Dataset]

Get subset of 30min datasets for the specified variables and time range from specified sites.

If variables is not specified, then all variables are included. If start/end time are not specified, then full time series of data is included. The start/end time can be in ISO-formatted string (i.e. yyyy-mm-dd HH:MM).

Parameters:

sites (list[str]) – List of site names.
version (None | str) – Dataset version. Default to from datetime import datetimeNone.
processing_level (str) – Dataset processing-level. Default to “L3”
variables (None | list[str]) – Dataset variable names. Defaults to None.
start (None | str) – Data start time, an ISO-formatted string or datetime object. Defaults to None.
end (None | str) – Data end time, an ISO-formatted string or datetime object. Defaults to None.
keep_attrs (bool) – Whether to keep variable attributes. Defaults to True.
keep_qcflags (bool) – Whether to keep the corresponding variables’ QC flags. Defaults to True.
missing_as_nan (bool) – Whether to set the missing value as nan in the dataset. Defaults to False.

Returns:

A dictionary of xarray datasets, indexed by site name.

Return type:

dict[str, Dataset]

terndata.flux.get_temporal_range(site: str, version: str, processing_level: str = 'L3') → tuple[str, str]

Get the temporal range for 30min dataset of the site, version, processing-level specified.

Parameters:

site (str) – Site name.
version (str) – Dataset version.
processing_level (str) – Dataset processing-level. Defaults to “L3”.

Returns:

A tuple of date and time, indicating the start and end timestamps.

Return type:

tuple[str, str]

terndata.flux.get_variables(site: str, version: None | str = None, processing_level: str = 'L3') → list[str]

Get the names of the variables for the 30min dataset specified.

Parameters:

site (str) – Site name.
version (None | str) – Dataset version. Defaults to None.
processing_level (str) – Dataset processing-level. Defaults to “L3”.

Returns:

A list of dataset’s variable names

Return type:

list[str]

terndata.flux.get_versions(site: str) → list[str]

Get the versions available for the specified site.

Parameters:: site (str) – Site name
Returns:: A list of versions available for the specified site.
Raises:: Exception – Exception for fail to get versions.
Return type:: list[str]

terndata.flux.plot.plot_timeseries(xds: Dataset, varnames: str | list[str])

Generate time-series plot for the dataset’s variables specified.

Adapted from PyFluxPro (https://github.com/OzFlux/PyFluxPro).

Parameters:

xds (Dataset) – An xarray dataset.
varnames (str | list[str]) – List of variable names to be plotted.

Raises:

Exception – An exception for invalid parameter varnames.

terndata.flux.plot.plot_fingerprints(xds: Dataset, varnames: str | list[str])

Generate finger-prints plot for the dataset’s variable specified.

Adapted from PyFluxPro (https://github.com/OzFlux/PyFluxPro).

Parameters:

xds (Dataset) – An xarray dataset.
varnames (str | list[str]) – List of variable names to be plotted.

Raises:

Exception – An exception for invalid parameter varnames.