Developer Interface

This part of the documentation covers all the interfaces of ODM2PythonAPI.

Database Connection

class odm2api.ODMconnection.SessionFactory(connection_string, echo=True, version=2.0)

Bases: object

getSession()

class odm2api.ODMconnection.dbconnection(debug=False)

Bases: object

classmethod buildConnectionString(engine, address, db, user, password)

classmethod closeConnection(session)

constringBuilder(engine=None, address=None, db=None, user=None, password=None, driver=None)

classmethod createConnection(engine, address, db=None, user=None, password=None, dbtype=2.0, echo=False)

classmethod createConnectionFromString(conn_string, dbtype=2.0, echo=False)

classmethod isValidConnection(connection_string=None, dbtype=2.0)

classmethod testEngine(connection_string, echo=False)

classmethod testEngine1_1(connection_string, echo=False)

class odm2api.base.Base(*args, **kwargs)

Bases: object

class declared_attr(fget, cascading=False)

Bases: sqlalchemy.orm.base._MappedAttribute, property

Mark a class-level method as representing the definition of a mapped property or special declarative member name.

@declared_attr turns the attribute into a scalar-like property that can be invoked from the uninstantiated class. Declarative treats attributes specifically marked with @declared_attr as returning a construct that is specific to mapping or declarative table configuration. The name of the attribute is that of what the non-dynamic version of the attribute would be.

@declared_attr is more often than not applicable to mixins, to define relationships that are to be applied to different implementors of the class:

class ProvidesUser(object):
    "A mixin that adds a 'user' relationship to classes."

    @declared_attr
    def user(self):
        return relationship("User")

It also can be applied to mapped classes, such as to provide a “polymorphic” scheme for inheritance:

class Employee(Base):
    id = Column(Integer, primary_key=True)
    type = Column(String(50), nullable=False)

    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()

    @declared_attr
    def __mapper_args__(cls):
        if cls.__name__ == 'Employee':
            return {
                    "polymorphic_on":cls.type,
                    "polymorphic_identity":"Employee"
            }
        else:
            return {"polymorphic_identity":cls.__name__}

cascading

Mark a declared_attr as cascading.

This is a special-use modifier which indicates that a column or MapperProperty-based declared attribute should be configured distinctly per mapped subclass, within a mapped-inheritance scenario.

Warning

The declared_attr.cascading modifier has several limitations:

• The flag only applies to the use of declared_attr on declarative mixin classes and __abstract__ classes; it currently has no effect when used on a mapped class directly.

• The flag only applies to normally-named attributes, e.g. not any special underscore attributes such as __tablename__. On these attributes it has no effect.

• The flag currently does not allow further overrides down the class hierarchy; if a subclass tries to override the attribute, a warning is emitted and the overridden attribute is skipped. This is a limitation that it is hoped will be resolved at some point.

Below, both MyClass as well as MySubClass will have a distinct id Column object established:

class HasIdMixin(object):
    @declared_attr.cascading
    def id(cls):
        if has_inherited_table(cls):
            return Column(
                ForeignKey('myclass.id'), primary_key=True)
        else:
            return Column(Integer, primary_key=True)

class MyClass(HasIdMixin, Base):
    __tablename__ = 'myclass'
    # ...

class MySubClass(MyClass):
    ""
    # ...

The behavior of the above configuration is that MySubClass will refer to both its own id column as well as that of MyClass underneath the attribute named some_id.

See also

declarative_inheritance

mixin_inheritance_columns

class odm2api.base.modelBase

Bases: object

class Base(**kwargs)

Bases: odm2api.base.Base

metadata = MetaData(bind=None)

declarative_base(metadata=None, mapper=None, cls=<class 'object'>, name='Base', constructor=<function _declarative_constructor>, class_registry=None, metaclass=<class 'sqlalchemy.ext.declarative.api.DeclarativeMeta'>)

Construct a base class for declarative class definitions.

The new base class will be given a metaclass that produces appropriate Table objects and makes the appropriate mapper() calls based on the information provided declaratively in the class and any subclasses of the class.

Parameters

• bind – An optional Connectable, will be assigned the bind attribute on the MetaData instance.

• metadata – An optional MetaData instance. All Table objects implicitly declared by subclasses of the base will share this MetaData. A MetaData instance will be created if none is provided. The MetaData instance will be available via the metadata attribute of the generated declarative base class.

• mapper – An optional callable, defaults to mapper(). Will be used to map subclasses to their Tables.

• cls – Defaults to object. A type to use as the base for the generated declarative base class. May be a class or tuple of classes.

• name – Defaults to Base. The display name for the generated class. Customizing this is not required, but can improve clarity in tracebacks and debugging.

• constructor – Defaults to _declarative_constructor(), an __init__ implementation that assigns **kwargs for declared fields and relationships to an instance. If None is supplied, no __init__ will be provided and construction will fall back to cls.__init__ by way of the normal Python semantics.

• class_registry – optional dictionary that will serve as the registry of class names-> mapped classes when string names are used to identify classes inside of relationship() and others. Allows two or more declarative base classes to share the same registry of class names for simplified inter-base relationships.

• metaclass – Defaults to DeclarativeMeta. A metaclass or __metaclass__ compatible callable to use as the meta type of the generated declarative base class.

Changed in version 1.1: if :paramref:`.declarative_base.cls` is a single class (rather than a tuple), the constructed base class will inherit its docstring.

See also

as_declarative()

class odm2api.base.serviceBase(session_factory, debug=False)

Bases: object

getSession()

reset_session()

Read Services

class odm2api.services.readService.DetailedAffiliation(affiliation, person, org)

Bases: object

class odm2api.services.readService.DetailedResult(action, result, sc, sn, method, variable, processingLevel, unit)

Bases: object

class odm2api.services.readService.ReadODM2(session_factory, debug=False)

Bases: odm2api.base.serviceBase

CalibrationReferenceEquipment()

• Pass nothing - return a list of all objects

CalibrationStandards()

• Pass nothing - return a list of all objects

DataLoggerFiles()

• Pass nothing - return a list of all objects

DataloggerFileColumns()

• Pass nothing - return a list of all objects

DataloggerProgramFiles()

• Pass Nothing - return a list of all objects

EquipmentModels()

• Pass Nothing - return a list of all objects

EquipmentUsed()

• Pass Nothing - return a list of all objects

InstrumentOutputVariables(modelid=None, variableid=None)

• Pass Nothing - return a list of all objects

• Pass ModelID

• Pass VariableID

RelatedEquipment(code=None)

• Pass nothing - return a list of all objects

• Pass code- return a single object with the given code

getActionDirectives(self)

• Pass nothing - return a list of all objects

getActions(ids=None, acttype=None, sfid=None, **kwargs)

• Pass nothing - returns a list of all Actions

• Pass a list of Action ids - returns a list of Action objects

• Pass a ActionTypeCV - returns a list of Action objects of that type

• Pass a SamplingFeature ID - returns a list of Action objects associated with that Sampling feature ID, Found through featureAction table

getAffiliations(ids=None, personfirst=None, personlast=None, orgcode=None)

Retrieve a list of Affiliation objects.

If no arguments are passed to the function, or their values are None, all Affiliation objects in the database will be returned.

Parameters

• ids (list, optional) – List of AffiliationIDs.

• personfirst (str, optional) – Person First Name.

• personlast (str, optional) – Person Last Name.

• orgcode (str, optional) – Organization Code.

Returns

List of Affiliation objects

Return type

list

Examples

>>> ReadODM2.getAffiliations(ids=[39,40])
>>> ReadODM2.getAffiliations(personfirst='John',
...                      personlast='Smith')
>>> ReadODM2.getAffiliations(orgcode='Acme')

getAnnotations(annottype=None, codes=None, ids=None, **kwargs)

• Pass Nothing - return a list of all objects

• Pass AnnotationTypeCV - return a list of all objects of the fiven type

• Pass a list of codes - return a list of objects, one for each of the given codes

• Pass a list of ids -return a list of objects, one for each of the given ids

getAuthorLists(self)

• Pass nothing - return a list of all objects

getCVs(cvtype, **kwargs)

getCVs(self, type): * Pass CVType - return a list of all objects of the given type

getDataQuality()

• Pass nothing - return a list of all objects

getDataSets(ids=None, codes=None, uuids=None, dstype=None)

Retrieve a list of Datasets

Parameters

• ids (list, optional) – List of DataSetsIDs.

• codes (list, optional) – List of DataSet Codes.

• uuids (list, optional) – List of Dataset UUIDs string.

• dstype (str, optional) – Type of Dataset from controlled vocabulary name.

Returns

List of DataSets Objects

Return type

list

Examples

>>> READ = ReadODM2(SESSION_FACTORY)
>>> READ.getDataSets(ids=[39, 40])
>>> READ.getDataSets(codes=['HOME', 'FIELD'])
>>> READ.getDataSets(uuids=['a6f114f1-5416-4606-ae10-23be32dbc202',
...                                 '5396fdf3-ceb3-46b6-aaf9-454a37278bb4'])
>>> READ.getDataSets(dstype='singleTimeSeries')

getDataSetsResults(ids=None, codes=None, uuids=None, dstype=None)

Retrieve a detailed list of Datasets along with detailed metadata about the datasets

and the results contained within them

Must specify either DataSetID OR DataSetUUID OR DataSetCode) :param ids: List of DataSetsIDs. :type ids: list, optional :param codes: List of DataSet Codes. :type codes: list, optional :param uuids: List of Dataset UUIDs string. :type uuids: list, optional :param dstype: Type of Dataset from

controlled vocabulary name.

Returns

List of DataSetsResults Objects

Return type

list

Examples

>>> READ = ReadODM2(SESSION_FACTORY)
>>> READ.getDataSetsResults(ids=[39, 40])
>>> READ.getDataSetsResults(codes=['HOME', 'FIELD'])
>>> READ.getDataSetsResults(uuids=['a6f114f1-5416-4606-ae10-23be32dbc202',
...                                 '5396fdf3-ceb3-46b6-aaf9-454a37278bb4'])
>>> READ.getDataSetsResults(dstype='singleTimeSeries')

getDataSetsValues(ids=None, codes=None, uuids=None, dstype=None, lowercols=True)

Retrieve a list of datavalues associated with the given dataset info

Must specify either DataSetID OR DataSetUUID OR DataSetCode) :param ids: List of DataSetsIDs. :type ids: list, optional :param codes: List of DataSet Codes. :type codes: list, optional :param uuids: List of Dataset UUIDs string. :type uuids: list, optional :param dstype: Type of Dataset from

controlled vocabulary name.

Parameters

lowercols (bool, optional) – Make column names to be lowercase. Default to True. Please start upgrading your code to rely on CamelCase column names, In a near-future release, the default will be changed to False, and later the parameter may be removed.

Returns

List of Result Values Objects

Return type

list

Examples

>>> READ = ReadODM2(SESSION_FACTORY)
>>> READ.getDataSetsValues(ids=[39, 40])
>>> READ.getDataSetsValues(codes=['HOME', 'FIELD'])
>>> READ.getDataSetsValues(uuids=['a6f114f1-5416-4606-ae10-23be32dbc202',
...                                 '5396fdf3-ceb3-46b6-aaf9-454a37278bb4'])
>>> READ.getDataSetsValues(dstype='singleTimeSeries', lowercols=False)

getDatasetCitations(self)

• Pass nothing - return a list of all objects

getDerivationEquations(self)

• Pass nothing - return a list of all objects

getDetailedAffiliationInfo()

• Pass Nothing - Return a list of all Affiliations with detailed information,

including Affiliation, People and Organization

getDetailedResultInfo(resultTypeCV=None, resultID=None, sfID=None)

Get detailed information for all selected Results including , unit info, site info, method info , ProcessingLevel info. * Pass nothing - return a list of all objects * Pass resultTypeCV - All objects of given type * Pass a result ID - single object with the given result ID * Pass a SamplingFeatureID - All objects associated with the given sampling feature.

getDirectives(self)

• Pass nothing - return a list of all objects

getEquipment(codes=None, equiptype=None, sfid=None, actionid=None, **kwargs)

• Pass nothing - returns a list of all Equipment objects

• Pass a list of EquipmentCodes- return a list of all Equipment objects that match each of the codes

• Pass a EquipmentType - returns a single Equipment object

• Pass a SamplingFeatureID - returns a single Equipment object

• Pass an ActionID - returns a single Equipment object

getExtensionProperties(exptype=None, **kwargs)

• Pass nothing - return a list of all objects

• Pass type- return a list of all objects of the given type

getExternalIdentifiers(eitype=None, **kwargs)

• Pass nothing - return a list of all objects

• Pass type- return a list of all objects of the given type

getMethodCitations(self)

• Pass nothing - return a list of all objects

getMethods(ids=None, codes=None, methodtype=None, **kwargs)

• Pass nothing - returns full list of method objects

• Pass a list of MethodIDs - returns a single method object for each given id

• Pass a list of MethodCode - returns a single method object for each given code

• Pass a MethodType - returns a list of method objects of the given MethodType

getModels(self, codes=None)

• Pass nothing - return a list of all Model Objects

• Pass a list of ModelCodes - get a list of converter objects related to the converter having ModeCode

getOrganizations(ids=None, codes=None)

• Pass nothing - returns a list of all organization objects

• Pass a list of OrganizationID - returns a single organization object

• Pass a list of OrganizationCode - returns a single organization object

getPeople(ids=None, firstname=None, lastname=None)

• Pass nothing - returns a list of all People objects

• Pass a list of PeopleID - returns a single People object

• Pass a First Name - returns a single People object

• Pass a Last Name - returns a single People object

getProcessingLevels(ids=None, codes=None)

Retrieve a list of Processing Levels

If no arguments are passed to the function, or their values are None, all Processing Levels objects in the database will be returned.

Parameters

• ids (list, optional) – List of Processing Levels IDs.

• codes (list, optional) – List of Processing Levels Codes.

Returns

List of ProcessingLevels Objects

Return type

list

Examples

>>> READ = ReadODM2(SESSION_FACTORY)
>>> READ.getProcessingLevels(ids=[1, 3])
>>> READ.getProcessingLevels(codes=['L1', 'L3'])

getReferenceMaterialValues()

• Pass nothing - return a list of all objects

getReferenceMaterials()

• Pass nothing - return a list of all objects

getRelatedActions(actionid=None)

• Pass an ActionID - get a list of Action objects related to the input action along with the relationship type

getRelatedAnnotations(self)

• Pass nothing - return a list of all objects

getRelatedCitations(self)

• Pass nothing - return a list of all objects

getRelatedDatasets(self)

• Pass nothing - return a list of all objects

getRelatedModels(self, id=None, code=None)

• Pass a ModelID - get a list of converter objects related to the converter having ModelID

• Pass a ModelCode - get a list of converter objects related to the converter having ModeCode

getRelatedResults(self)

• Pass nothing - return a list of all objects

getRelatedSamplingFeatures(sfid=None, rfid=None, relationshiptype=None)

• Pass a SamplingFeatureID - get a list of sampling feature objects related to the input sampling feature

• Pass a RelatedFeatureID - get a list of Sampling features objects through the related feature

• Pass a RelationshipTypeCV - get a list of sampling feature objects with the given type

getResultDerivationEquations(self)

• Pass nothing - return a list of all objects

getResultNormalizationValues()

• Pass nothing - return a list of all objects

getResultValues(resultids, starttime=None, endtime=None, lowercols=True)

Retrieve result values associated with the given result.

The resultids must be associated with the same result type

Parameters

• resultids (list) – List of SamplingFeatureIDs.

• starttime (object, optional) – Start time to filter by as datetime object.

• endtime (object, optional) – End time to filter by as datetime object.

• lowercols (bool, optional) – Make column names to be lowercase. Default to True. Please start upgrading your code to rely on CamelCase column names, In a near-future release, the default will be changed to False, and later the parameter may be removed.

Returns

Pandas dataframe of result values.

Return type

DataFrame

Examples

>>> READ = ReadODM2(SESSION_FACTORY)
>>> READ.getResultValues(resultids=[10, 11])
>>> READ.getResultValues(resultids=[100, 20, 34], starttime=datetime.today())
>>> READ.getResultValues(resultids=[1, 2, 3, 4],
>>>     starttime=datetime(2000, 01, 01),
>>>     endtime=datetime(2003, 02, 01), lowercols=False)

getResults(ids=None, restype=None, uuids=None, actionid=None, simulationid=None, variableid=None, siteid=None, sfids=None, sfuuids=None, sfcodes=None, **kwargs)

Retrieve a list of Result objects.

If no arguments are passed to the function, or their values are None, all Result objects in the database will be returned.

Parameters

• ids (list, optional) – List of ResultIDs.

• restype (str, optional) –

  Type of Result from controlled vocabulary name.

• uuids (list, optional) – List of UUIDs string.

• actionid (int, optional) – ActionID.

• simulationid (int, optional) – SimulationID.

• variableid (int, optional) – VariableID.

• siteid (int, optional) – SiteID. - goes through related features table and finds all of results recorded at the given site

• sfids (list, optional) – List of Sampling Feature IDs integer.

• sfuuids (list, optional) – List of Sampling Feature UUIDs string.

• sfcodes= (list, optional) – List of Sampling Feature codes string.

Returns

List of Result objects

Return type

list

Examples

>>> ReadODM2.getResults(ids=[39,40])
>>> ReadODM2.getResults(restype='Time series coverage')
>>> ReadODM2.getResults(sfids=[65])
>>> ReadODM2.getResults(uuids=['a6f114f1-5416-4606-ae10-23be32dbc202',
...                            '5396fdf3-ceb3-46b6-aaf9-454a37278bb4'])
>>> ReadODM2.getResults(simulationid=50)
>>> ReadODM2.getResults(siteid=6)
>>> ReadODM2.getResults(variableid=7)
>>> ReadODM2.getResults(actionid=20)

getResultsDataQuality()

• Pass nothing - return a list of all objects

getSamplingFeatureDatasets(ids=None, codes=None, uuids=None, dstype=None, sftype=None)

Retrieve a list of Datasets associated with the given sampling feature data.

Must specify either samplingFeatureID OR samplingFeatureUUID OR samplingFeatureCode)

Parameters

• ids (list, optional) – List of SamplingFeatureIDs.

• codes (list, optional) – List of SamplingFeature Codes.

• uuids (list, optional) – List of UUIDs string.

• dstype (str, optional) –

  Type of Dataset from controlled vocabulary name.

• sftype (str, optional) –

  Type of SamplingFeature from controlled vocabulary name.

Returns

List of DataSetsResults Objects associated with the given sampling feature

Return type

list

Examples

>>> READ = ReadODM2(SESSION_FACTORY)
>>> READ.getSamplingFeatureDatasets(ids=[39, 40])
>>> READ.getSamplingFeatureDatasets(codes=['HOME', 'FIELD'])
>>> READ.getSamplingFeatureDatasets(uuids=['a6f114f1-5416-4606-ae10-23be32dbc202',
...                                 '5396fdf3-ceb3-46b6-aaf9-454a37278bb4'])
>>> READ.getSamplingFeatureDatasets(dstype='singleTimeSeries')
>>> READ.getSamplingFeatureDatasets(sftype='Specimen')

getSamplingFeatures(ids=None, codes=None, uuids=None, sftype=None, wkt=None, results=False, **kwargs)

Retrieve a list of Sampling Feature objects.

If no arguments are passed to the function, or their values are None, all Sampling Feature objects in the database will be returned.

Parameters

• ids (list, optional) – List of SamplingFeatureIDs.

• codes (list, optional) – List of SamplingFeature Codes.

• uuids (list, optional) – List of UUIDs string.

• sftype (str, optional) –

  Type of Sampling Feature from controlled vocabulary name.

• wkt (str, optional) – SamplingFeature Well Known Text.

• results (bool, optional) – Whether or not you want to return only the sampling features that have results associated with them.

Returns

List of Sampling Feature objects

Return type

list

Examples

>>> READ = ReadODM2(SESSION_FACTORY)
>>> READ.getSamplingFeatures(ids=[39, 40])
>>> READ.getSamplingFeatures(codes=['HOME', 'FIELD'])
>>> READ.getSamplingFeatures(uuids=['a6f114f1-5416-4606-ae10-23be32dbc202',
...                                 '5396fdf3-ceb3-46b6-aaf9-454a37278bb4'])
>>> READ.getSamplingFeatures(type='Site')
>>> READ.getSamplingFeatures(wkt='POINT (30 10)')
>>> READ.getSamplingFeatures(results=True)
>>> READ.getSamplingFeatures(type='Site', results=True)

getSimulations(self, name=None, actionid=None)

• Pass nothing - get a list of all converter simuation objects

• Pass a SimulationName - get a single simulation object

• Pass an ActionID - get a single simulation object

getSpatialReferences(self, srsCodes=None)

• Pass nothing - return a list of all Spatial References

• Pass in a list of SRS Codes-

getSpecimenBatchPositions(self)

• Pass nothing - return a list of all objects

getTaxonomicClassifiers()

getTaxonomicClassifiers(self): * Pass nothing - return a list of all objects

getUnits(ids=None, name=None, unittype=None, **kwargs)

• Pass nothing - returns a list of all units objects

• Pass a list of UnitsID - returns a single units object for the given id

• Pass UnitsName - returns a single units object

• Pass a type- returns a list of all objects of the given type

getVariables(ids=None, codes=None, sitecode=None, results=False)

• Pass nothing - returns full list of variable objects

• Pass a list of VariableID - returns a single variable object

• Pass a list of VariableCode - returns a single variable object

• Pass a SiteCode - returns a list of Variable objects that are collected at the given site.

• Pass whether or not you want to return the sampling features that have results associated with them

resultExists(result)

Check to see if a Result Object exists * Pass Result Object - return a boolean value of wether the given object exists

class odm2api.services.readService.SamplingFeatureDataSet(samplingfeature, datasetresults, relatedfeatures)

Bases: object

assignDatasets(datasetresults)

assignRelatedFeatures(relatedfeatures)

datasets = {}

related_features = {}

Create Services

class odm2api.services.createService.CreateODM2(session_factory, debug=False)

Bases: odm2api.base.serviceBase

create(value)

createAction(action)

createActionby(actionby)

createAffiliation(affiliation)

createAll(values)

createAnnotations(anno)

createDataset(dataset)

createDatasetResults(datasetresult)

createFeatureAction(action)

createMethod(method)

createModel(model)

createOrganization(org)

createPerson(person)

createProcessingLevel(proclevel)

createRelatedAction(relatedaction)

createRelatedModel(relatedmodel)

createResult(result)

createResultValue(value)

createSamplingFeature(samplingfeature)

createSimulation(simulation)

createSpatialReference(spatialref)

createTimeSeriesResultValues(datavalues)

createUnit(unit)

createVariable(var)

Delete Services

class odm2api.services.deleteService.DeleteODM2(session_factory, debug=False)

Bases: odm2api.base.serviceBase

deleteTSRValues(ids=None, startdate=None, dates=None)

remove(obj)

Update Services

class odm2api.services.updateService.UpdateODM2(session_factory, debug=False)

Bases: odm2api.base.serviceBase

update(value)

updateAction(actionID=None, begin=None, end=None, action=None)

updateResult(resultID=None, valuecount=None, result=None)

updateResultValidDateTime(resultId, dateTime)