API Reference

basin3d.monitor

synopsis:: The BASIN-3D monitoring module
module author:: Val Hendrix <vhendrix@lbl.gov>

This module holds the logging functionality of BASIN-3D. It supports logging the messages and their contexts

Functions 

get_logger() - Get the Basin3DLogger.
configure() - Configure logging in BASIN-3D

basin3d.monitor.configure(log_config_path=None, **kwargs)[source]

Load YAML python logging configuraiton file

Parameters:: log_config_path (Optional[str]) – Path to the YAML file for configuring Python logging
Return type:: Dict
Returns:: Logging configuration as dictionary

Keyword Args Overwrite default logging config.

filters (dict)
formatters (dict)
handlers (dict)
loggers (dict)

basin3d.monitor.get_logger(name=None)[source]

Get the basin3d logger for the specified name. Using this logger provides additional context for BASIN-3D synthesis.

See logging.getLogger()

Param:: Name of the logger
Return type:: Logger
Returns:: The BASIN-3D Logger object

basin3d.synthesis

synopsis:: BASIN-3D Synthesis API
module author:: Val Hendrix <vhendrix@lbl.gov>, Danielle Svehla Christianson <dschristianson@lbl.gov>. Catherine Wong <catwong@lbl.gov>

Functions

register() - Register the specified plugins or implicitly register loaded plugins

Classes

DataSynthesizer - Synthesis API

synthesis.DataSynthesizer Functions

DataSynthesizer.attribute_mappings()- Search for attribute_mappings which describe how the datasource vocabularies are mapped to BASIN-3D vocabularies, including observed properties, statistics, result_quality, etc.
DataSynthesizer.measurement_timeseries_tvp_observations()- Search for Measurement Timeseries TVP Observations from specified Monitoring features and observed property variables
DataSynthesizer.monitoring_features()- Search for all monitoring features, features by parent monitoring features, features by monitoring feature identifiers, or look for a single monitoring feature by id.
DataSynthesizer.observed_properties()- Search for observed properties

class basin3d.synthesis.DataSynthesizer(plugins, catalog)[source]

Synthesis API

attribute_mappings(datasource_id=None, attr_type=None, attr_vocab=None, from_basin3d=False)[source]

>>> from basin3d.plugins import usgs
>>> from basin3d import synthesis
>>> synthesizer = synthesis.register()
>>> response = synthesizer.attribute_mappings()  # list all attribute mappings registered
>>> for attr_mapping in response:
...     print(f'{attr_mapping.attr_type} | {attr_mapping.basin3d_vocab} -- {attr_mapping.datasource_vocab}')
OBSERVED_PROPERTY:SAMPLING_MEDIUM | PH:WATER -- 00400
OBSERVED_PROPERTY:SAMPLING_MEDIUM | RDC:WATER -- 00060
OBSERVED_PROPERTY:SAMPLING_MEDIUM | WLE:WATER -- 63161
OBSERVED_PROPERTY:SAMPLING_MEDIUM | WT:WATER -- 00010
OBSERVED_PROPERTY:SAMPLING_MEDIUM | DO:WATER -- 00300
...

>>> response = synthesizer.attribute_mappings(datasource_id='USGS', attr_type='STATISTIC')
>>> for attr_mapping in response:
...     print(f'{attr_mapping.attr_type} | {attr_mapping.basin3d_vocab} -- {attr_mapping.datasource_vocab}')
STATISTIC | MEAN -- 00003
STATISTIC | MIN -- 00002
STATISTIC | MAX -- 00001
STATISTIC | TOTAL -- 00006

>>> response = synthesizer.attribute_mappings(datasource_id='USGS', attr_type='RESULT_QUALITY', attr_vocab=['VALIDATED', 'ESTIMATED'], from_basin3d=True)
>>> for attr_mapping in response:
...     print(f'{attr_mapping.attr_type} | {attr_mapping.basin3d_vocab} -- {attr_mapping.datasource_vocab}, {attr_mapping.datasource_desc}')
RESULT_QUALITY | ESTIMATED -- e, Value has been edited or estimated by USGS personnel and is write protected
RESULT_QUALITY | ESTIMATED -- E, Value was computed from estimated unit values.
RESULT_QUALITY | VALIDATED -- A, Approved for publication -- Processing and review completed.

Return all the basin3d.core.models.AttributMapping registered or those that match the specified fields.

Parameters:

datasource_id – str, The datasource identifier
attr_type – str, The attribute type (e.g., OBSERVED_PROPERTY, STATISTIC, etc)
attr_vocab – str, The attribute vocabulary, either the BASIN-3D vocabulary or the datasource vocabulary
from_basin3d – bool, True = the specified attr_vocab is a BASIN-3D vocabulary, False: the specified attr_vocab is from the datasource

Returns:

iterator of basin3d.core.models.AttributeMapping objects

property datasources: List[DataSource]: The Datasources loaded in this synthesizer :return:

measurement_timeseries_tvp_observations(query=None, **kwargs)[source]

Search for Measurement Timeseries TVP Observations for the specified query arguments.

Aggregation Duration for DAY (default) and NONE are both supported.

Search with aggregation duration DAY:

>>> from basin3d.plugins import usgs
>>> from basin3d import synthesis
>>> synthesizer = synthesis.register()
>>> timeseries = synthesizer.measurement_timeseries_tvp_observations(monitoring_feature=['USGS-09110990'],observed_property=['RDC','WT'],start_date='2019-10-01',end_date='2019-10-30',aggregation_duration='DAY')
>>> for timeseries in timeseries:
...    print(f"{timeseries.feature_of_interest.id} - {timeseries.observed_property.get_basin3d_vocab()}")
USGS-09110990 - RDC

Search with aggregation duration NONE:

>>> from basin3d.plugins import usgs
>>> from basin3d import synthesis
>>> synthesizer = synthesis.register()
>>> timeseries = synthesizer.measurement_timeseries_tvp_observations(monitoring_feature=["USGS-09110990", "USGS-09111250"],observed_property=['RDC','WT'],start_date='2020-04-01',end_date='2020-04-30',aggregation_duration='NONE')
>>> for timeseries in timeseries:
...    print(f"{timeseries.feature_of_interest.id} - {timeseries.observed_property.get_basin3d_vocab()}")
USGS-09110990 - RDC
USGS-09111250 - RDC

Parameters:

query (Optional[QueryMeasurementTimeseriesTVP]) – (optional) basin3d.core.schema.query.QueryMeasurementTimeseriesTVP object
kwargs – (required) Measurement Timeseries TVP Query parameters. See Query info below.

Return type:

DataSourceModelIterator

Returns:

a DataSourceModelIterator that yields basin3d.core.models.MeasurementTimeseriesTVPObservation objects

Note

Measurement Timeseries TVP Query parameters basin3d.core.schema.query.QueryMeasurementTimeseriesTVP

Required arguments:

* monitoring_feature List of monitoring features id(s)
* observed_property List of observed property(ies), i.e., BASIN-3D observed property vocabulary. See basin3d.synthesis.DataSynthesizer.observed_properties()
* start_date Start date YYYY-MM-DD

Optional arguments:

* end_date End date YYYY-MM-DD
* aggregation_duration A single aggregation duration basin3d.core.schema.enum.AggregationDurationEnum (YEAR|MONTH|DAY|HOUR|MINUTE|SECOND|NONE)
* statistic List of statistic(s) basin3d.core.schema.enum.StatisticEnum (MEAN|MIN|MAX|INSTANTANEOUS)
* result_quality List of result quality(ies) basin3d.core.schema.enum.ResultQualityEnum (VALIDATED|UNVALIDATED|SUSPECTED|REJECTED|ESTIMATED)
* sampling_medium List of sampling medium(s) basin3d.core.schema.enum.SamplingMediumEnum (SOLID_PHASE|WATER|GAS|OTHER)
* datasource A single data source id prefix

Note

Measurement Timeseries TVP Observation attributes basin3d.core.models.MeasurementTimeseriesTVPObservation

Attributes values are dependent on data source features.

basin3d.core.models.MappedAttribute are returned for several attributes so that the data source values are also available.

* id Observation identifier
* type Type of observation: MEASUREMENT_TVP_TIMESERIES
* observed_property The observation’s observed property basin3d.core.models.MappedAttribute
* datasource The data source basin3d.core.models.DataSource
* sampling_medium Observed property sampling medium basin3d.core.models.MappedAttribute (SOLID_PHASE, WATER, GAS, OTHER)
* phenomenon_time Datetime of the observation, for a timeseries the start and end times can be provided
* utc_offset Coordinate Universal Time offset in hours (offset in hours), e.g., +9
* feature_of_interest Monitoring Feature object basin3d.core.models.MonitoringFeature, feature on which the observation is being made
* feature_of_interest_type Feature type of the feature of interest, basin3d.core.schema.enum.FeatureTypeEnum
* result Observed values of the observed property being assessed, and (opt) their result quality, basin3d.core.models.ResultListTVP
* time_reference_position Position of timestamp in aggregated_duration (START, MIDDLE, END)
* aggregation_duration Time period represented by observation basin3d.core.models.MappedAttribute (YEAR, MONTH, DAY, HOUR, MINUTE, SECOND)
* unit_of_measurement Units in which the observation is reported
* statistic Statistical property of the observation result basin3d.core.models.MappedAttribute (MEAN, MIN, MAX, TOTAL)
* result_quality List quality assessment found in the results basin3d.core.models.MappedAttribute (VALIDATED, UNVALIDATED, SUSPECTED, REJECTED, ESTIMATED)

monitoring_features(query=None, **kwargs)[source]

Search for all Monitoring Features, Monitoring Features by parent monitoring features, or Monitoring Feature by id(s).

To see feature types for a given plugin: <plugin_module>.<plugin_class>.feature_types

Search for a single monitoring feature by id:

>>> from basin3d.plugins import usgs, epa
>>> from basin3d import synthesis
>>> synthesizer = synthesis.register()
>>> response = synthesizer.monitoring_features(id='USGS-0101')
>>> mf = response.data
>>> print(f"{mf.id} - {mf.description}")
USGS-0101 - SUBREGION: St. John

Search for all USGS monitoring features:

>>> for mf in synthesizer.monitoring_features(datasource='USGS', feature_type='region'): 
...     print(f"{mf.id} - {mf.description}")
USGS-01 - REGION: New England
USGS-02 - REGION: Mid Atlantic
USGS-03 - REGION: South Atlantic-Gulf
...

Search for USGS points by parent (subbasin) monitoring features:

>>> for mf in synthesizer.monitoring_features(feature_type='point',parent_feature=['USGS-17040101']): 
...    print(f"{mf.id} {mf.coordinates and [(p.x, p.y) for p in mf.coordinates.absolute.horizontal_position]}")
USGS-13010000 [(-110.6647222, 44.1336111)]
USGS-13010065 [(-110.6675, 44.09888889)]
USGS-13010450 [(-110.5874305, 43.9038296)]
...

Search for USGS points by monitoring features identifiers:

>>> for mf in synthesizer.monitoring_features(feature_type='point', monitoring_feature=['USGS-13010000', 'USGS-13010450']): 
...    print(f"{mf.id} {mf.coordinates and [(p.x, p.y) for p in mf.coordinates.absolute.horizontal_position]}")
USGS-13010000 [(-110.6647222, 44.1336111)]
USGS-13010450 [(-110.5874305, 43.9038296)]

Unsupported feature types warning:

The code below is an example of what you will see if a registered plugin does not support the requested feature type.

>>> response_itr = synthesizer.monitoring_features(feature_type='horizontal_path')
>>> for mf in response_itr:
...   print(mf)
...

Output warning messages from the returned iterator

This is an example of checking the synthesis response messages in the basin3d.core.synthesis.DataSourceModelIterator.

>>> response_itr.synthesis_response.messages
[SynthesisMessage(msg='Feature type HORIZONTAL_PATH not supported by USGS.', level='WARN', where=['USGS', 'MonitoringFeature']), SynthesisMessage(msg='Feature type HORIZONTAL_PATH not supported by EPA Water Quality eXchange.', level='WARN', where=['EPA', 'MonitoringFeature'])]

Parameters:

query (Optional[QueryMonitoringFeature]) – (optional) A Monitoring Feature Query basin3d.core.schema.query.QueryMonitoringFeature object
kwargs – (optional) Monitoring Feature Query parameters. See Query info below.

Return type:

Union[DataSourceModelIterator, SynthesisResponse]

Returns:

a single SynthesisResponse for a query by id or a DataSourceModelIterator for multple basin3d.core.models.MonitoringFeature objects.

Note

Monitoring Feature Query parameters basin3d.core.schema.query.QueryMonitoringFeature

All parameters are optional.

* datasource A single data source id prefix.
* feature_type The basin3d.core.schema.enum.FeatureTypeEnum of the desired Monitoring Feature(s). Data Sources may not support all Feature Types.

Only one of the following can be specified in a query:

* id A single Monitoring Feature ID for the Monitoring Feature desired. Returns a single Synthesis Response object.
* monitoring_feature List of Monitoring Feature IDs for the Monitoring Features desired. Returns iterator of MonitoringFeature objects.
* parent_feature List of Monitoring Feature IDs for the parent features of the desired Monitoring Features. Returns iterator of MonitoringFeature objects.

Note

Monitoring Feature attributes basin3d.core.models.MonitoringFeature

Attributes values are dependent on data source features.

* id Unique feature identifier, prefixed by data source id
* name Feature name
* description Description of the Monitoring Feature
* feature_type basin3d.core.schema.enum.FeatureTypeEnum REGION, SUBREGION, BASIN, SUBBASIN, WATERSHED, SUBWATERSHED, SITE, PLOT, HORIZONTAL PATH, VERTICAL PATH, POINT
* observed_properties List of observed properties basin3d.core.models.ObservedProperty collected at the feature.
* related_sampling_feature_complex List of basin3d.core.models.RelatedSamplingFeature. PARENT features are currently supported.
* shape Shape of the feature: POINT, CURVE, SURFACE, SOLID
* coordinates Location of feature in absolute and/or representative datum: basin3d.core.models.Coordinate
* description_reference Additional information about the feature
* related_party List of people or organizations responsible for the feature
* utc_offset Coordinate Universal Time offset in hours (offset in hours), e.g., +9
* datasource The feature’s data source basin3d.core.models.DataSource

observed_properties()[source]

>>> from basin3d.plugins import usgs
>>> from basin3d import synthesis
>>> synthesizer = synthesis.register()
>>> response = synthesizer.observed_properties()
>>> for opv in response:
...     print(f'{opv.basin3d_vocab} -- {opv.full_name} -- {opv.units}')
ACT -- Acetate (CH3COO) -- mM
Br -- Bromide (Br) -- mM
Cl -- Chloride (Cl) -- mM
DIN -- Dissolved Inorganic Nitrogen (Nitrate + Nitrite) -- mg/L
DTN -- Dissolved Total Nitrogen (DTN) -- mg/L
F -- Fluoride (F) -- mM
...

BASIN-3D observed properties. An observed property defines what is being measured. Data source observed property vocabularies are mapped and thus synthesized to the BASIN-3D observed property vocabulary.

Returns:: an iterator of basin3d.core.models.ObservedProperty objects

exception basin3d.synthesis.SynthesisException[source]: Special Exception for Synthesis module

basin3d.synthesis.register(plugins=None)[source]

Register the specified plugins or implicitly register loaded plugins

>>> from basin3d import synthesis
>>> synthesizer = synthesis.register(['basin3d.plugins.usgs.USGSDataSourcePlugin'])
>>> synthesizer.datasources
[DataSource(id='USGS', name='USGS', id_prefix='USGS', location='https://waterservices.usgs.gov/nwis/', credentials={})]

Parameters:: plugins (Optional[List[str]]) – [Optional] plugins to registered
Returns:: DataSynthesizer(plugin_dict, catalog)

basin3d.plugins.usgs

platform:: Unix, Mac
synopsis:: USGS Daily Values and Instantaneous Values Plugin Definition and supporting views.
module author:: Val Hendrix <vhendrix@lbl.gov>
module author:: Danielle S Christianson <dschristianson@lbl.gov>

USGSDataSourcePlugin - This Data Source plugin maps the USGS Daily Values and Instantaneous Values Service to BASIN-3D Models

USGS to BASIN-3D Mapping

The table below describes how BASIN-3D synthesis models are mapped to the USGS Daily Values and Instantaneous Service models.

USGS NWIS		BASIN-3D
`nwis/dv`	>>	`basin3d.core.models.MeasurementTimeseriesTVPObservation` with aggregation_duration == DAY
`nwis/iv`	>>	`basin3d.core.models.MeasurementTimeseriesTVPObservation` with aggregation_duration == NONE
`nwis/sites`	>>	`basin3d.synthesis.models.field.MonitoringFeature`
`nwis/huc`	>>	`basin3d.core.models.MonitoringFeature`
`new_huc_rdb.txt`	>>	`basin3d.synthesis.models.field.MonitoringFeature` Region (2-digit HUC code) to Region Subregion (4-digit HUC code) to Subregion Accounting (6-digit HUC code) Unit to Basin Watershed (8-digit HUC code) to Subbasin

Access Classes

The following are the access classes that map USGS Water Data to the BASIN-3D Models.

USGSMeasurementTimeseriesTVPObservationAccess - Access for accessing a group of data points grouped by time, space, model, sample etc.
USGSMonitoringFeatureAccess - Access for accessing monitoring features

class basin3d.plugins.usgs.USGSDataSourcePlugin(catalog)[source]

class DataSourceMeta[source]

This is an internal metadata class for defining additional basin3d.core.models.DataSource attributes.

Attributes:

id - unique id short name
name - human friendly name (more descriptive)
location - resource location
id_prefix - id prefix to make model object ids unique across plugins
credentials_format - if the data source requires authentication, this is where the
format of the stored credentials is defined.

id = 'USGS'

id_prefix = 'USGS'

location = 'https://waterservices.usgs.gov/nwis/'

name = 'USGS'

feature_types = ['POINT', 'REGION', 'BASIN', 'SUBREGION', 'SUBBASIN']

plugin_access_classes = (<class 'basin3d.plugins.usgs.USGSMonitoringFeatureAccess'>, <class 'basin3d.plugins.usgs.USGSMeasurementTimeseriesTVPObservationAccess'>)

title = 'USGS Data Source Plugin'

class basin3d.plugins.usgs.USGSMeasurementTimeseriesTVPObservationAccess(datasource, catalog)[source]

USGS Daily Values Service: https://waterservices.usgs.gov/docs/dv-service/

USGS Instantaneous Values Service: https://waterservices.usgs.gov/docs/instantaneous-values/

Access for mapping USGS water services daily or instantaneous value data to basin3d.core.models.MeasurementTimeseriesTVPObservation objects.

Daily Value and Instantaneous Value Qualification Code (dv_rmk_cd)

BASIN-3D Code	USGS Code	Description
ESTIMATED	e	Value has been edited or estimated by USGS personnel and is write protected
NOT_SUPPORTED	&	Value was computed from affected unit values
ESTIMATED	E	Value was computed from estimated unit values.
VALIDATED	A	Approved for publication – Processing and review completed.
UNVALIDATED	P	Provisional data subject to revision.
NOT_SUPPORTED	<	The value is known to be less than reported value and is write protected.
NOT_SUPPORTED	>	The value is known to be greater than reported value and is write protected.
NOT_SUPPORTED	1	Value is write protected without any remark code to be printed
NOT_SUPPORTED	2	Remark is write protected without any remark code to be printed
NOT_SUPPORTED	_	No remark (blank)

list(query)[source]

List of Measurement Timeseries TVP Observation objects for USGS Daily Values or Instantaneous Values

Parameters:: query (QueryMeasurementTimeseriesTVP) – basin3d.core.schema.query.QueryMeasurementTimeseriesTVP
Returns:: a generator object that yields MeasurementTimeseriesTVPObservation objects

synthesis_model_class: alias of MeasurementTimeseriesTVPObservation

class basin3d.plugins.usgs.USGSMonitoringFeatureAccess(datasource, catalog)[source]

Access for mapping USGS HUC Units to MonitoringFeature objects.

USGS HUC code		BASIN-3D
2-digit	>>	`basin3d.core.schema.enum.FeatureType` REGION
4-digit	>>	`basin3d.core.schema.enum.FeatureType` SUBREGION
6-digit	>>	`basin3d.core.schema.enum.FeatureType` BASIN
8-digit	>>	`basin3d.core.schema.enum.FeatureType` SUBBASIN

get(query)[source]

Get a single Monitoring Feature object

Parameters:: query (QueryMonitoringFeature) – The query info object with id specified
Returns:: a basin3d.core.models.MonitoringFeature object

get_hydrological_unit_codes(synthesis_messages)[source]: Get the hydrological unit codes for USGS

list(query)[source]

List Monitoring Feature

Parameters:: query (QueryMonitoringFeature) – The query information object
Returns:: a generator object that yields MonitoringFeature objects

synthesis_model_class: alias of MonitoringFeature

basin3d.plugins.usgs.convert_discharge(data, data_str, parameter, units)[source]: Convert the River Discharge to m^3 :type data: :param data: :type data_str: :param data_str: :type parameter: :param parameter: :type units: :param units: :return:

basin3d.plugins.usgs.generator_usgs_measurement_timeseries_tvp_observation(view, query, synthesis_messages)[source]

Get the data for USGS Daily Values or Instantaneous Values

Parameters:

view – Access class
query (QueryMeasurementTimeseriesTVP) – Query information for this request

Returns:

a generator object that yields data from the request in json form

basin3d.plugins.usgs.iter_rdb_to_json(rdb_text)[source]

Generator that iterates over an rdb file

Parameters:: rdb_text – USGS rdb data
Returns:

basin3d.plugins.epa

platform:: Unix, Mac
synopsis:: EPA Water Quality eXchange Plugin Definition
module author:: Danielle Christianson <dschristianson@lbl.gov>

EPADataSourcePlugin - This Data Source plugin maps the EPA Water Quality Exchange Data Source to the BASIN-3D Models

class basin3d.plugins.epa.EPADataSourcePlugin(catalog)[source]

class DataSourceMeta[source]

This is an internal metadata class for defining additional DataSource attributes.

Attributes:

id - unique id short name
name - human friendly name (more descriptive)
location - resource location
id_prefix - id prefix to make model object ids unique across plugins
credentials_format - if the data source requires authentication, this is where the
format of the stored credentials is defined.

id = 'EPA'

id_prefix = 'EPA'

location = 'https://www.waterqualitydata.us'

name = 'EPA Water Quality eXchange'

feature_types = ['POINT']

plugin_access_classes = (<class 'basin3d.plugins.epa.EPAMonitoringFeatureAccess'>, <class 'basin3d.plugins.epa.EPAMeasurementTimeseriesTVPObservationAccess'>)

title = 'EPA Water Quality eXchange Data Source Plugin'

class basin3d.plugins.epa.EPAMeasurementTimeseriesTVPObservationAccess(datasource, catalog)[source]

Water Quality Portal Service: https://www.waterqualitydata.us/

Access for mapping EPA water quality data to MeasurementTimeseriesTVPObservation objects.

list(query)[source]

Generate EPA Measurement Timeseries TVP object. The data are not really time series. But we are treating them as such.

Parameters:: query (QueryMeasurementTimeseriesTVP) –
Returns:

synthesis_model_class: alias of MeasurementTimeseriesTVPObservation

class basin3d.plugins.epa.EPAMonitoringFeatureAccess(datasource, catalog)[source]

Access for mapping EPA Water Quality Exchange sampling locations to MonitoringFeature objects.

Using WFS OGC Mapping service: ‘~/ogcservices/wfs/?request=GetFeature&service=wfs&version=2.0.0&typeNames=wqp_sites&SEARCHPARAMS=providers%3ASTORET&outputFormat=application%2Fjson’

EPA WQX		BASIN-3D
siteid	>>	`basin3d.core.models.MonitoringFeature`

get(query)[source]: Get a EPA measurement location based on the id :type query: QueryMonitoringFeature :param query: MonitoringFeature query, id must be specified :return:

list(query)[source]

Return measurement locations based on the query parameters Either a parent_feature list or monitoring_feature list should be specified. USGS hucs can be specified for parent_feature parameters (e.g., EPA-14020001)

Parameters:: query (QueryMonitoringFeature) – MonitoringFeature query
Return type:: Iterator[Optional[MonitoringFeature]]
Returns:

synthesis_model_class: alias of MonitoringFeature

basin3d.plugins.essdive

class basin3d.plugins.essdive.ESSDIVEDataSourcePlugin(catalog)[source]

class DataSourceMeta[source]

This is an internal metadata class for defining additional DataSource attributes.

Attributes:

id - unique id short name
name - human friendly name (more descriptive)
location - resource location
id_prefix - id prefix to make model object ids unique across plugins
credentials_format - if the data source requires authentication, this is where the
format of the stored credentials is defined.

id = 'ESSDIVE'

id_prefix = 'ESSDIVE'

location = 'https://ess-dive.data.lbl.gov'

name = 'ESSDIVE'

feature_types = ['POINT']

plugin_access_classes = (<class 'basin3d.plugins.essdive.ESSDIVEMonitoringFeatureAccess'>, <class 'basin3d.plugins.essdive.ESSDIVEMeasurementTimeseriesTVPObservationAccess'>)

title = 'ESS-DIVE Hydrological Monitoring Reporting Format Data Source Plugin'

class basin3d.plugins.essdive.ESSDIVEMeasurementTimeseriesTVPObservationAccess(datasource, catalog)[source]

Access for ESS-DIVE data in the Hydrological Monitoring Reporting Format to MeasurementTimeseriesTVPObservation objects.

list(query)[source]

Get the data that matches the specified query

Parameters:: query (QueryMeasurementTimeseriesTVP) – a QueryMeasurementTimeseriesTVP object
Returns:: a generator object that yields MeasurementTimeseriesTVPObservation objects

synthesis_model_class: alias of MeasurementTimeseriesTVPObservation

class basin3d.plugins.essdive.ESSDIVEMonitoringFeatureAccess(datasource, catalog)[source]

Access for mapping locations for ESS-DIVE datasets following the Hydrological Monitoring Reporting Format to MonitoringFeature objects.

A location is considered unique on location id

get(query)[source]

Get a single monitoring feature object based on an identifier, i.e. the query must have id specified.

Parameters:: query – a QueryMonitoringFeature object
Returns:: a MonitoringFeature object

list(query)[source]

List the monitoring features that match the specified query.

Parameters:: query (QueryMonitoringFeature) – a QueryMonitoringFeature object
Return type:: Iterator
Returns:: a generator object that yields MonitoringFeature objects

synthesis_model_class: alias of MonitoringFeature

class basin3d.plugins.essdive.HydroRFTerms(value)[source]

An enumeration.

column_header = 'Column_Header'

date_time = 'DateTime'

date_time_end = 'DateTime_End'

date_time_start = 'DateTime_Start'

date_time_vars = ['DateTime', 'DateTime_Start', 'DateTime_End']

depth = 'Depth'

depth_reference = 'Depth_Reference'

elevation = 'Elevation'

elevation_reference = 'Elevation_Reference'

format_row_text = '# HeaderRows_Format:'

classmethod get_attr_name(target_value)[source]

Return type:: Optional[str]

header_delimiter = ';'

header_row_char = '#'

install_method_desc = 'InstallationMethod_Description'

install_method_id = 'InstallationMethod_ID'

lat = 'Latitude'

loc_id = 'Site_ID'

loc_names = ['Site_Name', 'Water_Name']

loc_numeric_type = ['Latitude', 'Longitude', 'Depth', 'Elevation']

loc_type = 'Site_Type'

location_terms = ['Latitude', 'Longitude', 'Depth', 'Depth_Reference', 'Elevation', 'Elevation_Reference', 'Site_ID', 'Site_Name', 'Water_Name', 'Sensor_ID', 'Site_Type', 'UTC_Offset', 'InstallationMethod_ID']

long = 'Longitude'

missing_value_numeric = -9999

missing_value_str = 'N/A'

sensor_depth = 'Sensor_Depth'

sensor_elevation = 'Sensor_Elevation'

sensor_id = 'Sensor_ID'

site_name = 'Site_Name'

unique_loc_terms = ['Site_ID']

units = 'Unit'

utc_offset = 'UTC_Offset'

variables = {'Depth_To_Water': {'convert': 'to_m', 'rf_options': ['meters', 'centimeters']}, 'Dissolved_Oxygen': {'convert': None, 'rf_options': ['milligrams_per_liter']}, 'Electrical_Conductivity': {'convert': 'to_micro', 'rf_options': ['microsiemens_per_centimeter', 'millisiemens_per_centimeter']}, 'Gage_Height': {'convert': 'to_m', 'rf_options': ['meters', 'centimeters']}, 'Specific_Conductance': {'convert': 'to_micro', 'rf_options': ['microsiemens_per_centimeter', 'millisiemens_per_centimeter']}, 'Water_Depth': {'convert': 'to_m', 'rf_options': ['meters', 'centimeters']}, 'Water_Surface_Elevation': {'convert': None, 'rf_options': ['meters_above_mean_sea_level_NAVD88']}, 'Water_Temperature': {'convert': None, 'rf_options': ['degree_celsius']}, 'pH': {'convert': None, 'rf_options': ['pH']}}

water_name = 'Water_Name'

class basin3d.plugins.essdive.UnitHandler[source]

Class to handle specific unit conversions for the Hydrological Monitoring RF

static cm_to_m(unit)[source]

Return type:: float

convert_value(rf_unit, convert_type)[source]

Return type:: Union[float, int]

match_unit(rf_units, unit)[source]: Try to match unit :type rf_units: List[str] :param rf_units: :type unit: str :param unit: :rtype: Optional[str] :return:

static milli_to_micro(unit)[source]

Return type:: int

class basin3d.plugins.essdive.locInfo(ds_id, ds_pid, loc_id, lat=None, long=None, depth=None, sensor_depth=None, depth_reference=None, elevation=None, sensor_elevation=None, elevation_reference=None, site_name=None, water_name=None, sensor_id=None, utc_offset=None, install_method_id=None, install_method_desc=None, loc_type='POINT')[source]

depth: Optional[List[float]] = None

depth_reference: Optional[str] = None

ds_id: str

ds_pid: str

elevation: Optional[List[float]] = None

elevation_reference: Optional[str] = None

install_method_desc: Optional[str] = None

install_method_id: Optional[str] = None

lat: Optional[float] = None

loc_id: str

loc_type: str = 'POINT'

long: Optional[float] = None

sensor_depth: Optional[float] = None

sensor_elevation: Optional[float] = None

sensor_id: Optional[str] = None

site_name: Optional[str] = None

utc_offset: Optional[int] = None

water_name: Optional[str] = None

basin3d.core.schema.enum

platform:: Unix, Mac
synopsis:: BASIN-3D Enumeration Schema
module author:: Val Hendrix <vhendrix@lbl.gov>
module author:: Danielle Svehla Christianson <dschristianson@lbl.gov>

class basin3d.core.schema.enum.AggregationDurationEnum(value)[source]

Aggregation Duration enums

DAY = 'DAY': Observations aggregated by day

HOUR = 'HOUR': Observations aggregated by hour

MINUTE = 'MINUTE': Observations aggregated by minute

MONTH = 'MONTH': Observations aggregated by month

NONE = 'NONE': Observations aggregated by no standard frequency, used for instantaneous values

SECOND = 'SECOND': Observations aggregated by second

YEAR = 'YEAR': Observations aggregated by year

class basin3d.core.schema.enum.BaseEnum(value)[source]

Base Enumeration Class that adds some helper methods

classmethod names()[source]

classmethod values()[source]

class basin3d.core.schema.enum.FeatureTypeEnum(value)[source]

Enumeration for Feature Types

BASIN = 'BASIN'

HORIZONTAL_PATH = 'HORIZONTAL_PATH'

PLOT = 'PLOT'

POINT = 'POINT'

REGION = 'REGION'

SITE = 'SITE'

SUBBASIN = 'SUBBASIN'

SUBREGION = 'SUBREGION'

SUBWATERSHED = 'SUBWATERSHED'

VERTICAL_PATH = 'VERTICAL_PATH'

WATERSHED = 'WATERSHED'

class basin3d.core.schema.enum.MappedAttributeEnum(value)[source]

Enumeration for mapped attributes

AGGREGATION_DURATION = 'AGGREGATION_DURATION'

OBSERVED_PROPERTY = 'OBSERVED_PROPERTY'

RESULT_QUALITY = 'RESULT_QUALITY'

SAMPLING_MEDIUM = 'SAMPLING_MEDIUM'

STATISTIC = 'STATISTIC'

class basin3d.core.schema.enum.MessageLevelEnum(value)[source]

Enumeration of Message Levels

CRITICAL = 'CRITICAL'

ERROR = 'ERROR'

WARN = 'WARN'

class basin3d.core.schema.enum.ResultQualityEnum(value)[source]

Enumeration for Result Quality

ESTIMATED = 'ESTIMATED': The result is estimated. Synonyms: Interpolated, Modeled.

NOT_SUPPORTED = 'NOT_SUPPORTED': The quality type is not supported

REJECTED = 'REJECTED': The result is identified as poor quality. Synonyms: Poor, Bad, Unaccepted

SUSPECTED = 'SUSPECTED': The result’s quality is suspect. Synonyms: Questionable, Doubtful, Spike/Noise, Flagged

UNVALIDATED = 'UNVALIDATED': The result is raw or unchecked for quality. Synonyms: Unchecked, Preliminary, No QC

VALIDATED = 'VALIDATED': The result has been checked for quality and no issues identified. Synonyms: Checked, Accepted, Pass, OK, Good

class basin3d.core.schema.enum.SamplingMediumEnum(value)[source]

Types of sampling mediums for Observed Properties

GAS = 'GAS'

NOT_APPLICABLE = 'NOT_APPLICABLE'

NOT_SUPPORTED = 'NOT_SUPPORTED'

OTHER = 'OTHER'

SOLID_PHASE = 'SOLID_PHASE'

WATER = 'WATER'

class basin3d.core.schema.enum.StatisticEnum(value)[source]

Enumeration for Statistics

INSTANT = 'INSTANT'

MAX = 'MAX'

MEAN = 'MEAN'

MIN = 'MIN'

NOT_SUPPORTED = 'NOT_SUPPORTED'

TOTAL = 'TOTAL'

class basin3d.core.schema.enum.TimeFrequencyEnum(value)[source]

Enumeration for time frequencies

DAY = 'DAY'

HOUR = 'HOUR'

MINUTE = 'MINUTE'

MONTH = 'MONTH'

NONE = 'NONE'

NOT_SUPPORTED = 'NOT_SUPPORTED'

SECOND = 'SECOND'

YEAR = 'YEAR'

basin3d.core.schema.enum.set_mapped_attribute_enum_type(attr_type)[source]: Return the enum type for the specified MappedAttributeEnum. :type attr_type: str :param attr_type: MappedAttributeEnum :return: the type’s Enum

basin3d.core.schema.query

platform:: Unix, Mac
synopsis:: BASIN-3D Query Schema
module author:: Val Hendrix <vhendrix@lbl.gov>
module author:: Danielle Svehla Christianson <dschristianson@lbl.gov>

class basin3d.core.schema.query.QueryBase(*, datasource: List[str] | None = None, id: str | None = None, isValidTranslatedQuery: None | bool = None)[source]

Query Base Class. This sets QueryBase.Config defaults and processes incoming datasource ids

class Config[source]

alias_generator(): Change provided string with underscores to Javascript camelcase (e.g. to_camelcase -> toCamelcase) :type string: :param string: The string to transform :rtype: str :return:

allow_population_by_field_name = True

use_enum_values = True

validate_all = True

datasource: Optional[List[str]]

id: Optional[str]

is_valid_translated_query: Optional[bool]

mapped_fields: ClassVar[List[str]] = []

prefixed_fields: ClassVar[List[str]] = []

class basin3d.core.schema.query.QueryMeasurementTimeseriesTVP(*, datasource: List[str] | None = None, id: str | None = None, isValidTranslatedQuery: None | bool = None, monitoringFeature: ConstrainedListValue[str], observedProperty: ConstrainedListValue[str], startDate: date, aggregationDuration: AggregationDurationEnum = 'DAY', endDate: date | None = None, statistic: List[StatisticEnum] | None = None, resultQuality: List[ResultQualityEnum] | None = None, samplingMedium: List[SamplingMediumEnum] | None = None)[source]

Query basin3d.core.models.MeasurementTimeseriesTVP

aggregation_duration: AggregationDurationEnum

end_date: Optional[date]

mapped_fields: ClassVar[List[str]] = ['observed_property', 'aggregation_duration', 'statistic', 'result_quality', 'sampling_medium']

monitoring_feature: List[str]

observed_property: List[str]

prefixed_fields: ClassVar[List[str]] = ['monitoring_feature']

result_quality: Optional[List[ResultQualityEnum]]

sampling_medium: Optional[List[SamplingMediumEnum]]

start_date: date

statistic: Optional[List[StatisticEnum]]

class basin3d.core.schema.query.QueryMonitoringFeature(*, datasource: List[str] | None = None, id: str | None = None, isValidTranslatedQuery: None | bool = None, featureType: FeatureTypeEnum | None = None, monitoringFeature: List[str] | None = None, parentFeature: List[str] | None = None)[source]

Query basin3d.core.models.MonitoringFeature

feature_type: Optional[FeatureTypeEnum]

monitoring_feature: Optional[List[str]]

parent_feature: Optional[List[str]]

prefixed_fields: ClassVar[List[str]] = ['id', 'monitoring_feature', 'parent_feature']

class basin3d.core.schema.query.SynthesisMessage(**data)[source]

BASIN-3D Synthesis Message

class Config[source]

alias_generator(): Change provided string with underscores to Javascript camelcase (e.g. to_camelcase -> toCamelcase) :type string: :param string: The string to transform :rtype: str :return:

allow_population_by_field_name = True

use_enum_values = True

validate_all = True

level: MessageLevelEnum

msg: str

where: Optional[List[str]]

class basin3d.core.schema.query.SynthesisResponse(**data)[source]

BASIN-3D Synthesis Response

class Config[source]

alias_generator(): Change provided string with underscores to Javascript camelcase (e.g. to_camelcase -> toCamelcase) :type string: :param string: The string to transform :rtype: str :return:

allow_population_by_field_name = True

arbitrary_types_allowed = True

use_enum_values = True

validate_all = True

data: Union[object, List[object], None]

messages: List[Optional[SynthesisMessage]]

query: QueryBase

basin3d.core.access

platform:: Unix, Mac
synopsis:: BASIN-3D DataSource access classes
module author:: Val Hendrix <vhendrix@lbl.gov>
module author:: Danielle Svehla Christianson <dschristianson@lbl.gov>

basin3d.core.access.get_url(url, params=None, headers=None, verify=True, **kwargs)[source]: Send a GET request to the specified URL. Note look up extra kwargs in requests.get :type url: :param url: :type params: :param params: request parameters :type headers: :param headers: request headers :type verify: :param verify: verify SSL connection :return: Response

basin3d.core.access.post_url(url, params=None, headers=None, verify=True)[source]: Send a POST request to the specified URL :type url: :param url: :type params: :param params: request parameters :type headers: :param headers: request headers :type verify: :param verify: verify SSL connection :return: Response

basin3d.core.catalog

platform:: Unix, Mac
synopsis:: BASIN-3D DataSource catalog classes
module author:: Val Hendrix <vhendrix@lbl.gov>
module author:: Danielle Svehla Christianson <dschristianson@lbl.gov>

class basin3d.core.catalog.CatalogBase(variable_filename='basin3d_observed_property_vocabulary.csv')[source]

find_attribute_mappings(datasource, attr_type, attr_vocab, from_basin3d)[source]

Find the list of attribute mappings given the specified fields. Exact matches are returned (see attr_vocab formats below for BASIN-3D vocab nuances). If no fields are specified, all registered attribute mappings will be returned.

Parameters:

datasource_id – the datasource identifier
attr_type – the attribute type
attr_vocab – the attribute vocabulary, the formats are one of the following: 1) datasource vocab that is a complete vocab 2) BASIN-3D vocab that is a complete vocab for a given attr_type regardless if it is compound or not. 3) BASIN-3D vocab that is compound and fully specified for each attr_type either with the complete vocab or with wildcards.
from_basin3d – boolean that says whether the attr_vocab is a BASIN-3D vocabulary. If not, then this a datasource vocabulary.

Return type:

Iterator[AttributeMapping]

Returns:

generator that yields basin3d.models.AttributeMapping objects

find_datasource_attribute_mapping(datasource_id, attr_type, attr_vocab)[source]

Find the datasource attribute vocabulary to BASIN-3D mapping given a specific datasource_id, attr_type, and datasource attr_vocab.

Param:: datasource_id: the datasource identifier
Param:: attr_type: attribute type
Param:: datasource_vocab: the datasource attribute vocabulary
Return type:: Optional[AttributeMapping]
Returns:: a basin3d.models.AttributeMapping object

find_observed_properties(basin3d_vocab=None)[source]

Report the observed_properties available based on the BASIN-3D vocabularies specified. If no BASIN-3D vocabularies are specified, then return all observed properties available.

Parameters:: basin3d_vocab – list of the BASIN-3D observed properties
Return type:: Iterator[Optional[ObservedProperty]]
Returns:: generator that yields basin3d.models.ObservedProperty objects

find_observed_property(basin3d_vocab)[source]

Return the basin3d.models.ObservedProperty object for the BASIN-3D vocabulary specified.

Parameters:: basin3d_vocab – BASIN-3D vocabulary
Return type:: Optional[ObservedProperty]
Returns:: a basin3d.models.ObservedProperty object

initialize(plugin_list)[source]

Parameters:: plugin_list (list) – list of plugins
Returns:: tinyDB object

is_initialized()[source]

Has the catalog been initialized?

Return type:: bool

exception basin3d.core.catalog.CatalogException[source]

class basin3d.core.catalog.CatalogTinyDb(variable_filename='basin3d_observed_property_vocabulary.csv')[source]

find_attribute_mappings(datasource_id=None, attr_type=None, attr_vocab=None, from_basin3d=False)[source]

Find the list of attribute mappings given the specified fields. Exact matches are returned (see attr_vocab formats below for BASIN-3D vocab nuances). If no fields are specified, all registered attribute mappings will be returned.

Parameters:

datasource_id (Optional[str]) – the datasource identifier
attr_type (Optional[str]) – the attribute type
attr_vocab (Union[str, List, None]) – the attribute vocabulary, the formats are one of the following: 1) datasource vocab that is a complete vocab 2) BASIN-3D vocab that is a complete vocab for a given attr_type regardless if it is compound or not. 3) BASIN-3D vocab that is compound and fully specified for each attr_type either with the complete vocab or with wildcards.
from_basin3d (bool) – boolean that says whether the attr_vocab is a BASIN-3D vocabulary. If not, then this a datasource vocabulary.

Return type:

Iterator[AttributeMapping]

Returns:

generator that yields basin3d.models.AttributeMapping objects

find_datasource_attribute_mapping(datasource_id, attr_type, datasource_vocab)[source]

Find the datasource attribute vocabulary to BASIN-3D mapping given a specific datasource_id, attr_type, and datasource attr_vocab.

Param:: datasource_id: the datasource identifier
Param:: attr_type: attribute type
Param:: datasource_vocab: the datasource attribute vocabulary
Return type:: Optional[AttributeMapping]
Returns:: a basin3d.models.AttributeMapping object

find_observed_properties(basin3d_vocab=None)[source]

Report the observed_properties available based on the BASIN-3D vocabularies specified. If no BASIN-3D vocabularies are specified, then return all observed properties available.

Parameters:: basin3d_vocab (Optional[List[str]]) – list of the BASIN-3D observed properties
Return type:: Iterator[Optional[ObservedProperty]]
Returns:: generator that yields basin3d.models.ObservedProperty objects

find_observed_property(basin3d_vocab)[source]

Return the basin3d.models.ObservedProperty object for the BASIN-3D vocabulary specified.

Parameters:: basin3d_vocab (str) – BASIN-3D vocabulary
Return type:: Optional[ObservedProperty]
Returns:: a basin3d.models.ObservedProperty object

is_initialized()[source]

Has the catalog been initialized?

Return type:: bool

basin3d.core.connection

platform:: Unix, Mac
synopsis:: BASIN-3D DataSource connection classes
module author:: Val Hendrix <vhendrix@lbl.gov>
module author:: Danielle Svehla Christianson <dschristianson@lbl.gov>

class basin3d.core.connection.HTTPConnectionDataSource(datasource, *args, credentials=None, verify_ssl=False, **kwargs)[source]

Class for handling Authentication and authorization of basin3d.models.DataSource over HTTP

Parameters:: datasource (basin3d.models.DataSource instance) – the datasource to authenticate and authorize via HTTP

get(url_part, params=None, headers=None)[source]

The resources at the spedicfied url

Parameters:

url_part –
params –
headers –

Returns:

classmethod get_credentials_format()[source]: This returnes the format that the credentials are stored in the DB :return: The format for the credentials

login()[source]

Login to the basin3d.models.DataSource

Returns:: JSON response
Return type:: dict

logout()[source]

Login out of the basin3d.models.DataSource

Returns:: None

post(url_part, params=None, headers=None)[source]

The resources at the spedicfied url

Parameters:

url_part –
params –
headers –

Returns:

class basin3d.core.connection.HTTPConnectionOAuth2(datasource, *args, auth_token_path='o/token/', revoke_token_path='o/revoke_token/', auth_scope='read', grant_type='client_credentials', **kwargs)[source]

Class for handling Authentication and authorization of basin3d.models.DataSource over HTTP with OAuth2

Parameters:

datasource (basin3d.models.DataSource instance) – the datasource to authenticate and authorize via HTTP
auth_token_path – The url part for requesting a token
revoke_token_path – The url part for revoking a valid token
auth_scope – The scope of the token being requested (e.g read, write, group)
grant_type – The type of oauth2 grant (e.g client_credentials, password, refresh_token, authorization_code)

CREDENTIALS_FORMAT = 'client_id:\nclient_secret:\n'

get(url_part, params=None, headers=None)[source]

Login Data Source if not already logged in. Access url with the Authorization header and the access token

Authorization Header:

Authorization”: “{token_type} {access_token}

Parameters:

url_part – The url part to request
params (dict) – additional parameters for the request
headers – request headers

Returns:

None

Raises:

PermissionDenied

login()[source]

Get a token

OAuth Client credentials (client_id, client_secret) stored in the DataSource.

Url: https://<datasource location>/<auth_token_path>
Scope: <token_scope>
Grant Type: <grant_type>
Client Id: stored in encrypted basin3d.models.DataSource field
Client Secret: stored in encrypted basin3d.models.DataSource field

Example JSON Response:

{
    "access_token": "<your_access_token>",
    "token_type": "Bearer",
    "expires_in": 36000,
    "refresh_token": "<your_refresh_token>",
    "scope": "read"
}

logout()[source]

Revokes atoken

Parameters:: token – The current Token
Returns:: None

post(url_part, params=None, headers=None)[source]

Login Data Source if not already logged in. Access url with the Authorization header and the access token

Authorization Header:

Authorization”: “{token_type} {access_token}

Parameters:

url_part – The url part to request
params (dict) – additional parameters for the request
headers – request headers

Returns:

None

Raises:

PermissionDenied

class basin3d.core.connection.HTTPConnectionTokenAuth(datasource, login_path='api/login')[source]

Class for handling Authentication and authorization of basin3d.models.DataSource over HTTP with Tokens :type datasource: :param datasource: the datasource to authenticate and authorize via HTTP :type datasource: basin3d.models.DataSource instance :type login_path: :param login_path: The url part for requesting a token

CREDENTIALS_FORMAT = 'username: \npassword: \n'

get(url_part, params=None, headers=None)[source]: Get the url :type url_part: :param url_part: relative location of the requeste URL :type params: :param params: The query parameters :type params: dict or list of 2-tuples :type headers: :param headers: :return:

login()[source]: Get a Token :return: JSON response :rtype: dict

logout()[source]

Login out of the basin3d.models.DataSource

Returns:: None

post(url_part, params=None, headers=None)[source]: Post to the url :type url_part: :param url_part: relative location of the requeste URL :type params: :param params: The query parameters :type params: dict or list of 2-tuples :type headers: :param headers: :return:

exception basin3d.core.connection.InvalidOrMissingCredentials[source]: The credentials are invalid or missing

basin3d.core.models

synopsis:: The BASIN-3D Models
module author:: Val Hendrix <vhendrix@lbl.gov>
module author:: Danielle Svehla Christianson <dschristianson@lbl.gov>

class basin3d.core.models.AbsoluteCoordinate(**kwargs)[source]

Absolute coordinate describes the geo-referenced location of a feature. Coordinates match the feature’s shape. For example, a curve is a list of points. Currently collections of discrete points describing a feature are supported.

property horizontal_position: List[GeographicCoordinate]: list of obj GeographicCoordinate

property vertical_extent: List[AltitudeCoordinate]: list of obj AltitudeCoordinate

class basin3d.core.models.AltitudeCoordinate(**kwargs)[source]

An altitudinal vertical position (i.e., distance from sea level). The reference frame or system is specified. The term “altitude” is used instead of the common term “elevation” to conform to the terminology in Federal Information Processing Standards 70-1 and 173.

DATUM_NAVD88 = 'NAVD88': North American Vertical Datum of 1988

DATUM_NGVD29 = 'NGVD29': National Geodetic Vertical Datum of 1929

property datum: str: The reference coordinate system. Use constants prefixed with DATUM_

class basin3d.core.models.AttributeMapping(attr_type, basin3d_vocab, basin3d_desc, datasource_vocab, datasource_desc, datasource=DataSource(id='', name='', id_prefix='', location='', credentials={}))[source]

A data class for attribute mappings between datasource vocabularies and BASIN-3D vocabularies. These are the associations defined in the datasource (i.e., plugin) mapping file.

Fields:

attr_type: Attribute Type; e.g., STATISTIC, RESULT_QUALITY, OBSERVED_PROPERTY; separate compound mappings with ‘:’
basin3d_vocab: The BASIN-3D vocabulary; separate compound mappings with ‘:’
basin3d_desc: The BASIN-3D vocabulary descriptions; objects or enum
datasource_vocab: The datasource vocabulary
datasource_desc: The datasource vocabulary description
datasource: The datasource of the mapping

attr_type: str

basin3d_desc: list

basin3d_vocab: str

datasource: DataSource = DataSource(id='', name='', id_prefix='', location='', credentials={})

datasource_desc: str

datasource_vocab: str

class basin3d.core.models.Base(plugin_access, **kwargs)[source]

Base synthesis model class. All classes that extend this are immutable.

property datasource

property datasource_ids

property id

property original_id

class basin3d.core.models.Coordinate(**kwargs)[source]

Top level coordinate class that holds AbsoluteCoordinate or RepresentativeCoordinate

property absolute: AbsoluteCoordinate: Absolute coordinate

property representative: RepresentativeCoordinate: Representative coordinate

class basin3d.core.models.DataSource(id='', name='', id_prefix='', location='', credentials=<factory>)[source]

Data Source definition

Fields:

id: string (inherited)
name: string
id_prefix: string, prefix that is added to all data source ids
location:
credentials:

credentials: dict

id: str = ''

id_prefix: str = ''

location: str = ''

name: str = ''

class basin3d.core.models.DepthCoordinate(**kwargs)[source]

A depth vertical position (i.e., the height or depth from the specified reference position) The reference frame or system is specified.

DATUM_LOCAL_SURFACE = 'LS': Local surface

DATUM_MEAN_SEA_LEVEL = 'MSL': Mean sea level

property datum: str: The reference coordinate system. Use constants prefixed with DATUM_

class basin3d.core.models.Feature(plugin_access, **kwargs)[source]

A general feature upon which an observation can be made. Loosely after GF_Feature (ISO).

property description: str: The feature description

property feature_type: str: The feature type. For a list of feature types see basin3d.schema.enum.FeatureTypeEnum.

property id: str: Unique identifier for the feature

property name: str: A name for the feature

property observed_properties: List[MappedAttribute] | List[str]: List of observed properties

class basin3d.core.models.GeographicCoordinate(**kwargs)[source]

The latitude and longitude which define the position of a point on the Earth’s surface with respect to a reference spheroid. (https://www.fgdc.gov/csdgmgraphical/spref.htm)

UNITS = {'DD': 'Decimal degrees', 'DDM': 'Degrees and decimal minutes', 'DM': 'Decimal minutes', 'DMDS': 'Degrees, minutes, and decimal seconds', 'DS': 'Decimal seconds', 'Grads': 'Grads', 'Radians': 'Radians'}

UNITS_DATA_TYPES = {'DD': <class 'float'>, 'DDM': (<class 'int'>, <class 'float'>), 'DM': <class 'float'>, 'DMDS': (<class 'int'>, <class 'int'>, <class 'int'>), 'DS': <class 'float'>, 'Grads': <class 'float'>, 'Radians': <class 'float'>}

UNITS_DEC_DEGREES = 'DD': Decimal degrees

UNITS_DEC_MINUTES = 'DM': Decimal minutes

UNITS_DEC_SECONDS = 'DS': Decimal seconds

UNITS_DEGREES_DEC_MINUTES = 'DDM': Degrees and decimal minutes

UNITS_DEGREES_MIN_DEC_SECS = 'DMDS': Degrees, minutes, and decimal second

UNITS_GRADS = 'Grads': Grads

UNITS_RADIANS = 'Radians': Radians

property latitude: float: Alias for Y Coordinate

property longitude: float: Alias for X Coordinate

property units: str: Latitude and longitude units. Use constants prefixed with UNITS_

class basin3d.core.models.HorizontalCoordinate(**kwargs)[source]

Generic XY coordinates for a point on earth (https://www.fgdc.gov/csdgmgraphical/spref.htm)

DATUM_NAD27 = 'NAD27': North American Datum 1927 (NAD27)

DATUM_NAD83 = 'NAD83': North American Datum of 1983 (NAD 83)

DATUM_WGS84 = 'WGS84': World Geodetic System 1984 (WGS84)

TYPE_GEOGRAPHIC = 'GEOGRAPHIC': The quantities of latitude and longitude which define the position of a point on the Earth’s surface with respect to a reference spheroid.

TYPE_LOCAL = 'LOCAL': A description of any coordinate system that is not aligned with the surface of the Earth.

TYPE_PLANAR_GRID = 'PLANAR_GRID': T plane-rectangular coordinate system usually based on, and mathematically adjusted to, a map projection so that geographic positions can be readily transformed to and from plane coordinates.

TYPE_PLANAR_LOCAL = 'PLANAR_LOCAL': Any right-handed planar coordinate system of which the z-axis coincides with a plumb line through the origin that locally is aligned with the surface of the Earth.

TYPE_PLANAR_MAP_PROJECTION = 'PLANAR_MAP_PROJECTION': The systematic representation of all or part of the surface of the Earth on a plane or developable surface.

property datum: str: The reference coordinate system. Use constants prefixed with DATUM_

property type: str: The type of horizontal coordinates. Use constants prefixed with TYPE_ from HorizontalCoordinate

property x: float: X Coordinate

property y: float: Y Coordinate

class basin3d.core.models.JSONSerializable[source]

Make a Data class serializable to json

to_dict()[source]

to_json()[source]

class basin3d.core.models.MappedAttribute(attr_type, attr_mapping)[source]

A data class for an attribute that is translated (i.e., mapped) from a datasource vocabulary to BASIN-3D vocabulary. Note that this model holds an AttributeMapping that maybe compound in nature; however this class specifies only one attribute types. For example, if the AttributeMapping is for a compound mapping of attribute types OBSERVED_PROPERTY:SAMPLING_MEDIUM, then the attr_type field would be either OBSERVED_PROPERTY or SAMPLING_MEDIUM but not both.

Fields:

attr_type: Attribute Type; e.g., STATISTIC, RESULT_QUALITY, OBSERVED_PROPERTY, etc; single type only
attr_mapping: AttributeMapping as described in the datasource’s (i.e., plugin’s mapping file).

attr_mapping: AttributeMapping

attr_type: MappedAttributeEnum

get_basin3d_desc()[source]

get_basin3d_vocab()[source]

Return type:: Optional[str]

get_datasource_desc()[source]

Return type:: str

get_datasource_vocab()[source]

Return type:: str

class basin3d.core.models.MeasurementMetadataMixin(*args, **kwargs)[source]

Metadata attributes for Observations type Measurement

property sampling_medium: MappedAttribute: Sampling medium in which the observed property was measured

property statistic: MappedAttribute: The statistical property of the observation result. Use constants prefixed with STATISTIC_ from MeasurementMetadataMixin

class basin3d.core.models.MeasurementResultMixin(**kwargs)[source]

Result Mixin: Measurement

property result: ResultPointFloat: Result

property unit_of_measurement: str: Unit of measurement

class basin3d.core.models.MeasurementTimeseriesTVPObservation(plugin_access, **kwargs)[source]: Series of measurement (numerical) observations in TVP format grouped by time (i.e., a timeseries). Anything specified at the group level automatically applies to the individual observation.

class basin3d.core.models.MeasurementTimeseriesTVPResultMixin(*args, **kwargs)[source]

Result Mixin: Measurement Timeseries TimeValuePair

property result: ResultListTVP: A list of results

property unit_of_measurement: str: Unit of measurement

class basin3d.core.models.MonitoringFeature(plugin_access, **kwargs)[source]

A feature upon which monitoring is made. OGC Timeseries Profile OM_MonitoringFeature.

property description_reference: str: Extra information about the Monitoring Feature

property related_party: List[Person]: list of Person, people or organizations responsible for Feature. To be extended in future to full OGC Responsible_Party

property utc_offset: int: Coordinated Universal Time (UTC) offset in hours (e.g. +/-9)

class basin3d.core.models.Observation(plugin_access, **kwargs)[source]

OGC OM_Observation feature type. This is a parent class to which Mixins: should be added to create observation types with metadata and result.

TYPE_MEASUREMENT = 'MEASUREMENT': A measurement

TYPE_MEASUREMENT_TVP_TIMESERIES = 'MEASUREMENT_TVP_TIMESERIES': Measurement Time Value Pair Timeseries

property feature_of_interest: MonitoringFeature: The feature on which the observed property was observed

property feature_of_interest_type: FeatureTypeEnum: The type of feature that was observed. See basin3d.models.FeatureTypeEnum

property id: str: Unique observation identifier

property observed_property: MappedAttribute: The property that was observed

property phenomenon_time: str: datetime of the observation (required OGC attribute timePhenomenon). For timeseries, start and end datetimes can be provided.

property result_quality: List[MappedAttribute]: The result quality assessment. See ResultQuality

property type: str: Type of observation. Use constants prefixed with TYPE_

property utc_offset: int: Coordinated Universal Time (UTC) offset in hours (e.g. +/-9)

class basin3d.core.models.ObservedProperty(basin3d_vocab='', full_name='', categories=<factory>, units='')[source]

Defining the properties being observed (measured). See http://vocabulary.odm2.org/variablename/ for controlled vocabulary

Fields:

basin3d_vocab: string,
full_name: string,
categories: List of strings (in order of priority).
units: string

See http://vocabulary.odm2.org/variabletype/ for options, although I think we should have our own list (theirs is a bit funky).

basin3d_vocab: str = ''

categories: list

full_name: str = ''

units: str = ''

class basin3d.core.models.Person(**kwargs)[source]

A person or organization

property email: str: Email address

property first_name: str: First (given) name of person

property institution: str: Institution or organization name

property last_name: str: Last (family) name

property role: str: Role of person in relation to responsibility

class basin3d.core.models.RelatedSamplingFeature(plugin_access, **kwargs)[source]

Class that represents a related sampling feature and its role relative to the sampling feature to which it is related. Spatial hierarchies of features are built by specifying related sampling features.

Data model from OGC Observations and Measurements.

ROLE_PARENT = 'PARENT': Sampling Feature is a parent

ROLE_TYPES = ['PARENT']

property related_sampling_feature: SamplingFeature: A sampling feature relation

property related_sampling_feature_type: str: Feature type of the related sampling feature. See FeatureTypeEnum for a list of types

property role: str: Currently the only Related Sampling Feature role is a RelatedSamplingFeature.PARENT

class basin3d.core.models.RepresentativeCoordinate(**kwargs)[source]

Representative coordinates describe the location of a feature by a representative shape / location. For example, a study area may be represented by the center point. The veritical position from a reference position (e.g., height, depth) is also described in this class. Currently representative points are supported. The class is extendable to other forms of representing (e.g., diameter, area, side_length) Representative point types are also expandable as use cases require.

REPRESENTATIVE_POINT_TYPE_CENTER_LOCAL_SURFACE = 'CENTER LOCAL SURFACE': Placement of the representative point is the center of a local surface

REPRESENTATIVE_POINT_TYPE_LOWER_LEFT_CORNER = 'LOWER LEFT CORNER': Placement of the representative point is the lower left corner (southhwest)

REPRESENTATIVE_POINT_TYPE_LOWER_RIGHT_CORNER = 'LOWER RIGHT CORNER': Placement of the representative point is the lower right corner (northeast)

REPRESENTATIVE_POINT_TYPE_UPPER_LEFT_CORNER = 'UPPER LEFT CORNER': Placement of the representative point is the upper left corner (northwest)

REPRESENTATIVE_POINT_TYPE_UPPER_RIGHT_CORNER = 'UPPER RIGHT CORNER': Placement of the representative point is the upper right corner (northeast)

property representative_point: AbsoluteCoordinate: A point representation of the feature. obj AbsoluteCoordinate for POINT

property representative_point_type: str: The type of representative point relative to the feature’s geometry Currently the point is assumed to be located at the local surface (CV). Use constants prefixed with REPRESENTATIVE_POINT_TYPE_

property vertical_position: DepthCoordinate: The vertical position of the feature from a reference position (e.g., height or depth). obj DepthCoordinate

class basin3d.core.models.ResultListTVP(plugin_access, **kwargs)[source]

Result Point Float

property result_quality: List[MappedAttribute]: Result that was measured

property value: List[TimeValuePair]: Result that was measured

class basin3d.core.models.ResultPointFloat(plugin_access, **kwargs)[source]

Result Point Float

property result_quality: MappedAttribute: Result that was measured

property value: float: Result that was measured

class basin3d.core.models.SamplingFeature(plugin_access, **kwargs)[source]

A feature where sampling is conducted. OGC Observation & Measurements SF_SamplingFeature.

property related_sampling_feature_complex: List[SamplingFeature]: List of related sampling features obj RelatedSamplingFeature

class basin3d.core.models.SpatialSamplingFeature(plugin_access, **kwargs)[source]

A spatially-defined feature where sampling is conducted. OGC Observation & Measurements SF_SpatialSamplingFeature.

property coordinates: Coordinate: Description of feature location. An instance of Coordinate

property shape: str: The shape of the feature. See basin3d.models.SpatialSamplingShapes

class basin3d.core.models.TimeMetadataMixin(*args, **kwargs)[source]

Metadata attributes for Observations with a time

TIME_REFERENCE_END = 'END': Observation taken at the end

TIME_REFERENCE_MIDDLE = 'MIDDLE': Observation taken in the middle

TIME_REFERENCE_START = 'START': Observation taken at the start

property aggregation_duration: MappedAttribute: Time period represented by the observation. Follows OGC TM_PeriodDuration. Use constants prefixed with AGGREGATION_DURATION from TimeseriesMetadataMixin

property time_reference_position: str: Position of timestamp in aggregated_duration. Encompassed as part of OGC interpolationType. Use constants prefixed with TIME_REFERENCE from TimeseriesMetadataMixin

class basin3d.core.models.TimeValuePair(timestamp, value)[source]

Tuple that represents a time value pair. This will handle timestamp conversion

(timestamp, value)

class basin3d.core.models.VerticalCoordinate(**kwargs)[source]

The vertical position of the feature (altitudes or depths). The reference frame or system is specified.

DISTANCE_UNITS_FEET = 'feet': Distance in feet

DISTANCE_UNITS_METERS = 'meters': Distance in meters

ENCODING_ATTRIBUTE = 'ATTRIBUTE': Attribute values

ENCODING_EXPLICIT = 'EXPLICIT': Explicit coordinate included with horizontal coordinates

ENCODING_IMPLICIT = 'IMPLICIT': Implicit coordinate

TYPE_ALTITUDE = 'ALTITUDE': The distance above or below sea level (elevation)

TYPE_DEPTH = 'DEPTH': The distance above (height) or below (depth) of the local surface

property datum: str: The reference coordinate system. Use constants prefixed with DATUM_

property distance_units: str: The unit of distance. It uses constants prefixed with DISTANCE_UNITS_ from VerticalCoordinate

property encoding_method: str: The method for encoding the units of distance. Use constants prefixed with ENCODING_ from VerticalCoordinate

property resolution: float: The minimum distance possible between two adjacent depth values, expressed in Distance Units used for Depth

property type: str: The type of veritical position VerticalCoordinate.TYPE_ALTITUDE or VerticalCoordinate.TYPE_DEPTH

property value: float: The vertical position value

basin3d.core.monitor

synopsis:: The BASIN-3D monitoring module
module author:: Val Hendrix <vhendrix@lbl.gov>

This module holds the logging functionality of BASIN-3D. It supports logging the messages and their contexts

class basin3d.core.monitor.Basin3dLogger(name, level=0)[source]

Custom logger for adding realtime context information (basin3d_where)

critical(msg, *args, **kwargs)[source]

Log ‘msg % args’ with severity ‘CRITICAL’.