basin3d_schema

EXPERIMENTAL rendering of basin3d as linkml

Website

• https://cmungall.github.io/basin3d_schema

The above website is entirely generated from the source LinkML yaml files.

This generates pages for classes, including:

• Feature

Vocabularies/enums, e.g.

• StatisticEnum

Slots/fields, e.g.

• observed_property

Repository Structure

• examples/ - example data
• project/ - project files (generated: do not edit these)
  • jsonschema - JSON schema, for validating JSON documents
  • sqlschema - SQL DDL (CREATE TABLE statements)
  • jdonld - JSON-LD Contexts
  • shacl - SHACL shape definitions (for RDF validation)
• src/ - source files (edit these)
  • basin3d_schema
    • schema -- LinkML schema (edit this)
    • datamodel -- Generated pydantic datamodel
• tests - python tests

Usage

pip install basin3d_schema

(^^ may not work if this is a new repo)

Creating Objects

Creating objects via generated Pydantic model:

from basin3d_schema.datamodel.core import Observation, MonitoringFeature, Coordinate, AbsoluteCoordinate,
    GeographicCoordinate

geo_coord = GeographicCoordinate(x=-5, y=20)
ft = FeatureTypeEnum.WATERSHED
feat = MonitoringFeature(description="test",
                         coordinates=Coordinate(absolute=AbsoluteCoordinate(horizontal_position=[geo_coord])))
obs = Observation(feature_of_interest=feat,
                  feature_of_interest_type=ft)
print(obs.json(exclude_unset=True, indent=True))

Generates:

{
 "feature_of_interest": {
  "description": "test",
  "coordinates": {
   "absolute": {
    "horizontal_position": [
     {
      "x": -5.0,
      "y": 20.0
     }
    ]
   }
  }
 }, 
  "feature_of_interest_type": "WATERSHED"
}

Validating Objects

Pydantic auto-validates by default

E.g:

ac = AbsoluteCoordinate(horizontal_position=geo_coord)

raises an exception as a list is expected:

pydantic.error_wrappers.ValidationError: 1 validation error for AbsoluteCoordinate
horizontal_position
  value is not a valid list (type=type_error.list)

See test_models in the unit tests for more examples

Serialization/Deserialization

Pydantic objects naturally serialize/deserialize to JSON

Using the LinkML runtime framework it's possible to ser/de from:

• SQL Databases
• RDF
• TSVs (with caveats)

Vocabularies

See the generated enums page

The generated Python looks like:

class TimeFrequencyEnum(str, Enum):
    
    YEAR = "YEAR"
    MONTH = "MONTH"
    DAY = "DAY"
    HOUR = "HOUR"
    MINUTE = "MINUTE"
    SECOND = "SECOND"

The underlying schema is more granular:

enums:
  TimeFrequencyEnum:
    permissible_values:
      YEAR:
        meaning: UO:0000036 ## year
        unit:
          ucum_code: a
      MONTH:
        meaning: UO:0000035 ## month
        unit:
          ucum_code: mo
      DAY:
        meaning: UO:0000033 ## day
        unit:
          ucum_code: d
      HOUR:
        meaning: UO:0000032 ## hour
        unit:
          ucum_code: h
      MINUTE:
        meaning: UO:0000031 ## minute
        unit:
          ucum_code: min
      SECOND:
        meaning: UO:0000010 ## second
        unit:
          ucum_code: s

The additional metadata gives interoperability hooks

But using these is just like any normal Python enum

Time(aggregation_duration=TimeFrequencyEnum.MONTH)

Developer Documentation

Use the `make` command to generate project artefacts:

• make all: make everything
• make deploy: deploys site

About

this project was made with linkml-project-cookiecutter

Most of the content was autogenerated using semi-automated tools from the basin3 python codebase. Any mistakes are my own!

This is intended mainly for conversation starting purposes