Standardise#
Functions that accept data in specific formats, standardise it to a CF-compliant format and ensure it has the correct metadata attached. The data returned from these functions is then stored in the object store.
Measurement Standardisation#
These functions cover the four types of measurement we currently support.
Surface measurements#
- openghg.standardise.standardise_surface(source_format, network, site, filepath=None, filepaths=None, inlet=None, height=None, instrument=None, sampling_period=None, calibration_scale=None, measurement_type='insitu', verify_site_code=True, site_filepath=None, store=None, update_mismatch='never', if_exists='auto', save_current='auto', overwrite=False, force=False, compression=True, compressor=None, filters=None, chunks=None)[source]#
Standardise surface measurements and store the data in the object store.
- Parameters:
filepath (
Union
[str
,Path
,Tuple
,List
,None
]) – Filepath(s)source_format (
str
) – Data format, for example CRDS, GCWERKSsite (
str
) – Site code/namenetwork (
str
) – Network nameinlet (
Optional
[str
]) – Inlet height. Format ‘NUMUNIT’ e.g. “10m”. If retrieve multiple files pass None, OpenGHG will attempt to extract this from the file.height (
Optional
[str
]) – Alias for inlet.instrument (
Optional
[str
]) – Instrument namesampling_period (
Union
[Timedelta
,str
,None
]) – Sampling period as pandas time code, e.g. 1m for 1 minute, 1h for 1 hourcalibration_scale (
Optional
[str
]) – Calibration scale for datameasurement_type (
str
) – Type of measurement e.g. insitu, flaskverify_site_code (
bool
) – Verify the site codesite_filepath (
Union
[str
,Path
,None
]) – Alternative site info file (see openghg/supplementary_data repository for format). Otherwise will use the data stored within openghg_defs/data/site_info JSON file by default.store (
Optional
[str
]) – Name of object store to write to, required if user has access to more than one writable storeupdate_mismatch (
str
) –This determines how mismatches between the internal data “attributes” and the supplied / derived “metadata” are handled. This includes the options:
”never” - don’t update mismatches and raise an AttrMismatchError
”from_source” / “attributes” - update mismatches based on input attributes
”from_definition” / “metadata” - update mismatches based on input metadata
if_exists (
str
) –What to do if existing data is present. - “auto” - checks new and current data for timeseries overlap
adds data if no overlap
raises DataOverlapError if there is an overlap
”new” - just include new data and ignore previous
”combine” - replace and insert new data into current timeseries
save_current (
str
) – Whether to save data in current form and create a new version. - “auto” - this will depend on if_exists input (“auto” -> False), (other -> True) - “y” / “yes” - Save current data exactly as it exists as a separate (previous) version - “n” / “no” - Allow current data to updated / deletedoverwrite (
bool
) – Deprecated. This will use options for if_exists=”new”.force (
bool
) – Force adding of data even if this is identical to data stored.compression (
bool
) – Enable compression in the storecompressor (
Optional
[Any
]) – A custom compressor to use. If None, this will default to Blosc(cname=”zstd”, clevel=5, shuffle=Blosc.SHUFFLE). See https://zarr.readthedocs.io/en/stable/api/codecs.html for more information on compressors.filters (
Optional
[Any
]) – Filters to apply to the data on storage, this defaults to no filtering. See https://zarr.readthedocs.io/en/stable/tutorial.html#filters for more information on picking filters.chunks (
Optional
[Dict
]) – Chunking schema to use when storing data. It expects a dictionary of dimension name and chunk size, for example {“time”: 100}. If None then a chunking schema will be set automatically by OpenGHG. See documentation for guidance on chunking: https://docs.openghg.org/tutorials/local/Adding_data/Adding_ancillary_data.html#chunking. To disable chunking pass an empty dictionary.
- Returns:
Dictionary of result data
- Return type:
dict
Boundary Conditions#
- openghg.standardise.standardise_bc(filepath, species, bc_input, domain, period=None, continuous=True, store=None, if_exists='auto', save_current='auto', overwrite=False, force=False, compression=True, compressor=None, filters=None, chunks=None)[source]#
Standardise boundary condition data and store it in the object store.
- Parameters:
filepath (
Union
[str
,Path
]) – Path of boundary conditions filespecies (
str
) – Species namebc_input (
str
) – Input used to create boundary conditions. For example: - a model name such as “MOZART” or “CAMS” - a description such as “UniformAGAGE” (uniform values based on AGAGE average)domain (
str
) – Region for boundary conditionsperiod (
Union
[str
,tuple
,None
]) – Period of measurements, if not passed this is inferred from the time coordscontinuous (
bool
) – Whether time stamps have to be continuous.store (
Optional
[str
]) – Name of store to write toif_exists (
str
) –What to do if existing data is present. - “auto” - checks new and current data for timeseries overlap
adds data if no overlap
raises DataOverlapError if there is an overlap
”new” - just include new data and ignore previous
”combine” - replace and insert new data into current timeseries
save_current (
str
) – Whether to save data in current form and create a new version. - “auto” - this will depend on if_exists input (“auto” -> False), (other -> True) - “y” / “yes” - Save current data exactly as it exists as a separate (previous) version - “n” / “no” - Allow current data to updated / deletedoverwrite (
bool
) – Deprecated. This will use options for if_exists=”new”.force (
bool
) – Force adding of data even if this is identical to data stored.compression (
bool
) – Enable compression in the storecompressor (
Optional
[Any
]) – A custom compressor to use. If None, this will default to Blosc(cname=”zstd”, clevel=5, shuffle=Blosc.SHUFFLE). See https://zarr.readthedocs.io/en/stable/api/codecs.html for more information on compressors.filters (
Optional
[Any
]) – Filters to apply to the data on storage, this defaults to no filtering. See https://zarr.readthedocs.io/en/stable/tutorial.html#filters for more information on picking filters.chunks (
Optional
[Dict
]) – Chunking schema to use when storing data. It expects a dictionary of dimension name and chunk size, for example {“time”: 100}. If None then a chunking schema will be set automatically by OpenGHG. See documentation for guidance on chunking: https://docs.openghg.org/tutorials/local/Adding_data/Adding_ancillary_data.html#chunking To disable chunking pass an empty dictionary.
- Returns:
Dictionary containing confirmation of standardisation process.
- Return type:
dict
Emissions / Flux#
- openghg.standardise.standardise_flux(filepath, species, source, domain, database=None, source_format='openghg', database_version=None, model=None, high_time_resolution=False, period=None, chunks=None, continuous=True, store=None, if_exists='auto', save_current='auto', overwrite=False, force=False, compression=True, compressor=None, filters=None)[source]#
Process flux / emissions data
- Parameters:
filepath (
Union
[str
,Path
]) – Path of flux / emissions filespecies (
str
) – Species namesource (
str
) – Flux / Emissions sourcedomain (
str
) – Flux / Emissions domainsource_format (
str
) – Data format, for example openghg, intemdate – Date as a string e.g. “2012” or “201206” associated with emissions as a string. Only needed if this can not be inferred from the time coords
high_time_resolution (
Optional
[bool
]) – If this is a high resolution fileperiod (
Union
[str
,tuple
,None
]) – Period of measurements, if not passed this is inferred from the time coordschunks (
Optional
[Dict
]) – Chunking schema to use when storing data. It expects a dictionary of dimension name and chunk size, for example {“time”: 100}. If None then a chunking schema will be set automatically by OpenGHG. See documentation for guidance on chunking: https://docs.openghg.org/tutorials/local/Adding_data/Adding_ancillary_data.html#chunking. To disable chunking pass an empty dictionary.continuous (
bool
) – Whether time stamps have to be continuous.store (
Optional
[str
]) – Name of store to write toif_exists (
str
) –What to do if existing data is present. - “auto” - checks new and current data for timeseries overlap
adds data if no overlap
raises DataOverlapError if there is an overlap
”new” - just include new data and ignore previous
”combine” - replace and insert new data into current timeseries
save_current (
str
) – Whether to save data in current form and create a new version. - “auto” - this will depend on if_exists input (“auto” -> False), (other -> True) - “y” / “yes” - Save current data exactly as it exists as a separate (previous) version - “n” / “no” - Allow current data to updated / deletedoverwrite (
bool
) – Deprecated. This will use options for if_exists=”new”.force (
bool
) – Force adding of data even if this is identical to data stored.compression (
bool
) – Enable compression in the storecompressor (
Optional
[Any
]) – A custom compressor to use. If None, this will default to Blosc(cname=”zstd”, clevel=5, shuffle=Blosc.SHUFFLE). See https://zarr.readthedocs.io/en/stable/api/codecs.html for more information on compressors.filters (
Optional
[Any
]) – Filters to apply to the data on storage, this defaults to no filtering. See https://zarr.readthedocs.io/en/stable/tutorial.html#filters for more information on picking filters.
- Returns:
Dictionary of Datasource UUIDs data assigned to
- Return type:
dict
Footprints#
- openghg.standardise.standardise_footprint(filepath, site, domain, model, inlet=None, height=None, met_model=None, species=None, network=None, source_format='acrg_org', period=None, chunks=None, continuous=True, retrieve_met=False, store=None, if_exists='auto', save_current='auto', overwrite=False, force=False, high_spatial_resolution=False, high_time_resolution=False, short_lifetime=False, sort=False, drop_duplicates=False, compression=True, compressor=None, filters=None)[source]#
Reads footprint data files and returns the UUIDs of the Datasources the processed data has been assigned to
- Parameters:
filepath (
Union
[str
,Path
,List
]) – Path(s) of file to standardisesite (
str
) – Site namedomain (
str
) – Domain of footprintsmodel (
str
) – Model used to create footprint (e.g. NAME or FLEXPART)inlet (
Optional
[str
]) – Height above ground level in metres. Format ‘NUMUNIT’ e.g. “10m”height (
Optional
[str
]) – Alias for inlet. One of height or inlet must be included.met_model (
Optional
[str
]) – Underlying meteorlogical model used (e.g. UKV)species (
Optional
[str
]) – Species name. Only needed if footprint is for a specific species e.g. co2 (and not inert)network (
Optional
[str
]) – Network namesource_format (
str
) – Format of the input data format, for example acrg_orgperiod (
Union
[str
,tuple
,None
]) – Period of measurements. Only needed if this can not be inferred from the time coordschunks (
Optional
[Dict
]) – Chunk schema to use when storing data. It expects a dictionary of dimension name and chunk size, for example {“time”: 100}. If None then a chunking schema will be set automatically by OpenGHG. See documentation for guidance on chunking: https://docs.openghg.org/tutorials/local/Adding_data/Adding_ancillary_data.html#chunking by OpenGHG as per the TODO RELEASE: add link to documentation. To disable chunking pass an empty dictionary.continuous (
bool
) – Whether time stamps have to be continuous.retrieve_met (
bool
) – Whether to also download meterological data for this footprints areahigh_spatial_resolution (
bool
) – Indicate footprints include both a low and high spatial resolution.high_time_resolution (
bool
) – Indicate footprints are high time resolution (include H_back dimension) Note this will be set to True automatically for Carbon Dioxide data.short_lifetime (
bool
) – Indicate footprint is for a short-lived species. Needs species input. Note this will be set to True if species has an associated lifetime.store (
Optional
[str
]) – Name of store to write toif_exists (
str
) –What to do if existing data is present. - “auto” - checks new and current data for timeseries overlap
adds data if no overlap
raises DataOverlapError if there is an overlap
”new” - just include new data and ignore previous
”combine” - replace and insert new data into current timeseries
save_current (
str
) – Whether to save data in current form and create a new version. - “auto” - this will depend on if_exists input (“auto” -> False), (other -> True) - “y” / “yes” - Save current data exactly as it exists as a separate (previous) version - “n” / “no” - Allow current data to updated / deleted overwrite: Deprecated. This will use options for if_exists=”new”.force (
bool
) – Force adding of data even if this is identical to data stored.sort (
bool
) – Sort data in by timedrop_duplicates (
bool
) – Drop duplicate timestamps, keeping the first valuecompression (
bool
) – Enable compression in the storecompressor (
Optional
[Any
]) – A custom compressor to use. If None, this will default to Blosc(cname=”zstd”, clevel=5, shuffle=Blosc.SHUFFLE). See https://zarr.readthedocs.io/en/stable/api/codecs.html for more information on compressors.filters (
Optional
[Any
]) – Filters to apply to the data on storage, this defaults to no filtering. See https://zarr.readthedocs.io/en/stable/tutorial.html#filters for more information on picking filters.
- Returns:
Dictionary containing confirmation of standardisation process. None if file already processed.
- Return type:
dict / None
Helpers#
Some of the functions above require quite specific arguments as we must ensure all metadata attriuted to data is as correct as possible. These functions help you find the correct arguments in each case.
Behind the scences these functions use parsing functions that are written specifically for each data type. Please see the Developer API for these functions.