OWI-metadatabase Results Extension

Results extension for OWI Metadatabase SDK

Overview

This package extends owi-metadatabase SDK under the owi.metadatabase.* namespace so it behaves like the existing extension packages.

📚 Read the Documentation

Installation

Install as extension package (owi-metadatabase-results)

pip install owi-metadatabase-results

Using uv:

uv pip install owi-metadatabase-results

Install from core package extra (owi-metadatabase[results])

If you prefer installing from the base package extras:

pip install "owi-metadatabase[results]"

Using uv:

uv pip install "owi-metadatabase[results]"

Quick Start

from owi.metadatabase.results import ResultsAPI

api = ResultsAPI(token="your-api-token")
print(api.ping())

Architecture At A Glance

The diagram below shows how the package is structured, which parts are core, and how data moves from domain payloads to backend persistence and plots. Colour legend: green = core orchestration, blue = domain models and analyses, amber = infrastructure / HTTP, yellow = protocol contracts, grey = external packages.

flowchart TD
  User[User Code / Notebooks / Scripts] --> Service[services/core.py\nResultsService\nHigh-level facade]
  User --> API[io.py\nResultsAPI\nLow-level HTTP client]

  Service --> Repo[services/core.py\nApiResultsRepository]
  Repo --> API
  API -. routes .-> Endpoints[endpoints.py\nResultsEndpoints]

  Service --> Serializers[serializers.py\nDjangoAnalysisSerializer\nDjangoResultSerializer]
  Service --> Registry[registry.py\nAnalysisRegistry]
  Service --> PlotRegistry[plotting/registry.py\nRegistered cross-analysis plots]
  Serializers --> Models

  Registry --> BaseAnalysis[analyses/base.py\nBaseAnalysis mixin]
  PlotRegistry --> PlotDefs[plotting/definitions.py\nPlotDefinition · PlotSourceSpec]

  BaseAnalysis --> Freq[analyses/lifetime_design_frequencies.py\nComparison + location + geo frequencies]
  BaseAnalysis --> Verify[analyses/lifetime_design_verification.py\nTime-series verification]
  BaseAnalysis --> Hist[analyses/wind_speed_histogram.py\nHistogram analysis]
  BaseAnalysis --> CEIT[analyses/ceit.py\nCEIT corrosion monitoring]

  Freq --> Models[models.py\nAnalysisDefinition · ResultSeries\nResultVector · ResultQuery\nPlotRequest · PlotResponse]
  Verify --> Models
  Hist --> Models
  CEIT --> Models

  Protocols[protocols.py\nAnalysisProtocol · PlotStrategyProtocol\nPlotDefinitionProtocol · ResultsRepositoryProtocol\nSerializerProtocol] -. structural contracts .-> Service
  Protocols -. structural contracts .-> BaseAnalysis
  Protocols -. structural contracts .-> Repo

  BaseAnalysis --> GenericPlots[plotting/strategies.py\nGeneric single-analysis strategies]
  Freq --> FreqPlots[plotting/frequency.py\nComparison / location / geo plots]
  Verify --> VerifyPlots[plotting/verification.py\nTime-series + water-depth trend charts]
  PlotRegistry --> FreqVerifyPlots[plotting/frequency_verification.py\nCross-analysis fleetwide plot]
  CEIT --> CeitPlots[plotting/ceit.py\nSensor dropdown charts]

  GenericPlots --> PlotWidgets[plotting/response.py + theme.py\nDropdown builders + monospace theme]
  FreqPlots --> PlotWidgets
  VerifyPlots --> PlotWidgets
  FreqVerifyPlots --> PlotWidgets
  CeitPlots --> PlotWidgets

  Repo -. location metadata .-> Locations[owi.metadatabase.locations\nLocationsAPI]
  Geometry[owi.metadatabase.geometry\nOWT / subassembly context] -. joined by site/location .-> User

  classDef core fill:#d9f2e6,stroke:#2c7a4b,color:#143d28;
  classDef domain fill:#e8eefc,stroke:#3559b7,color:#1e2f63;
  classDef infra fill:#f7ead9,stroke:#b7791f,color:#5a3d0c;
  classDef external fill:#f3f4f6,stroke:#6b7280,color:#374151;
  classDef contract fill:#fef3c7,stroke:#d97706,color:#78350f;

  class Service,Repo,Registry,PlotRegistry,BaseAnalysis core;
  class GenericPlots,FreqPlots,VerifyPlots,FreqVerifyPlots,CeitPlots,PlotWidgets core;
  class Freq,Verify,Hist,CEIT,Models,Serializers domain;
  class PlotDefs domain;
  class API,Endpoints infra;
  class User,Locations,Geometry external;
  class Protocols contract;

Data Model At A Glance

The results extension stores analysis metadata separately from persisted result rows. Result rows link back to site and location metadata, while geometry stays adjacent and is usually joined through location-aware identifiers.

erDiagram
  ANALYSIS {
    int id PK
    string name
    string source_type
    string source
    string description
    json additional_data
  }

  RESULT {
    int id PK
    int analysis_id FK
    int site FK
    int location FK
    string short_description
    string description
    json additional_data
    json related_object
    string name_col1
    string units_col1
    float_array value_col1
    string name_col2
    string units_col2
    float_array value_col2
    string name_col3
    string units_col3
    float_array value_col3
  }

  PROJECTSITE {
    int id PK
    string title
  }

  ASSETLOCATION {
    int id PK
    int projectsite_id FK
    string title
    float northing
    float easting
  }

  OWT {
    int id PK
    int assetlocation_id FK
    string title
  }

  SUBASSEMBLY {
    int id PK
    int owt_id FK
    string type
  }

  ANALYSIS ||--o{ RESULT : owns
  PROJECTSITE ||--o{ ASSETLOCATION : contains
  PROJECTSITE ||--o{ RESULT : site_scope
  ASSETLOCATION ||--o{ RESULT : location_scope
  ASSETLOCATION ||--|| OWT : anchors
  OWT ||--o{ SUBASSEMBLY : contains

Interpretation:

• ANALYSIS stores one logical analysis definition, such as LifetimeDesignVerification or WindSpeedHistogram.
• RESULT stores one persisted series row with 2 to 3 aligned numeric vectors plus JSON metadata.
• PROJECTSITE and ASSETLOCATION come from the locations package and provide the site and asset identifiers used by result queries.
• northing and easting on ASSETLOCATION are what make geo-oriented result plots possible.
• Geometry objects like OWT and SUBASSEMBLY are not owned by the results package, but they are the physical context users typically join onto result rows through location/site relationships.

Development

uv sync --dev
uv run invoke test
uv run invoke qa
uv run invoke docs