climate-ref 0.5.0__py3-none-any.whl

climate_ref/models/metric_value.py

@@ -0,0 +1,195 @@
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from loguru import logger
+from sqlalchemy import Column, ForeignKey, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from climate_ref.models.base import Base, CreatedUpdatedMixin
+from climate_ref_core.pycmec.controlled_vocabulary import CV, Dimension
+
+if TYPE_CHECKING:
+    from climate_ref.models.execution import Execution
+
+
+class MetricValue(CreatedUpdatedMixin, Base):
+    """
+    Represents a single diagnostic value
+
+    This value has a number of dimensions which are used to query the diagnostic value.
+    These dimensions describe aspects such as the type of statistic being measured,
+    the region of interest or the model from which the statistic is being measured.
+
+    The columns in this table are not known statically because the REF can track an arbitrary
+    set of dimensions depending on the controlled vocabulary that will be used.
+    A call to `register_cv_dimensions` must be made before using this class.
+    """
+
+    __tablename__ = "metric_value"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    execution_id: Mapped[int] = mapped_column(ForeignKey("execution.id"))
+
+    value: Mapped[float] = mapped_column()
+    attributes: Mapped[dict[str, Any]] = mapped_column()
+
+    execution: Mapped["Execution"] = relationship(back_populates="values")
+
+    _cv_dimensions: ClassVar[list[str]] = []
+
+    @property
+    def dimensions(self) -> dict[str, str]:
+        """
+        Get the non-null dimensions and their values
+
+        Any changes to the resulting dictionary are not reflected in the object
+
+        Returns
+        -------
+            Collection of dimensions names and their values
+        """
+        dims = {}
+        for key in self._cv_dimensions:
+            value = getattr(self, key)
+            if value is not None:
+                dims[key] = value
+        return dims
+
+    def __repr__(self) -> str:
+        return (
+            f"<MetricValue "
+            f"id={self.id} "
+            f"execution={self.execution} "
+            f"value={self.value} "
+            f"dimensions={self.dimensions}>"
+        )
+
+    @staticmethod
+    def build_dimension_column(dimension: Dimension) -> Column[str]:
+        """
+        Create a column representing a CV dimension
+
+        These columns are not automatically generated with alembic revisions.
+        Any changes to this functionality likely require a manual database migration
+        of the existing columns.
+
+        Parameters
+        ----------
+        dimension
+            Dimension definition to create the column for.
+
+            Currently only the "name" field is being used.
+
+        Returns
+        -------
+            An instance of a sqlalchemy Column
+
+            This doesn't create the column in the database,
+            but enables the ORM to access it.
+
+        """
+        return Column(
+            dimension.name,
+            Text,
+            index=True,
+            nullable=True,
+            info={"skip_autogenerate": True},
+        )
+
+    @classmethod
+    def register_cv_dimensions(cls, cv: CV) -> None:
+        """
+        Register the dimensions supplied in the controlled vocabulary
+
+        This has to be done at run-time to support custom CVs.
+        Any extra columns already in the database, but not in the CV are ignored.
+
+        Parameters
+        ----------
+        cv
+            Controlled vocabulary being used by the application.
+            This controlled vocabulary contains the definitions of the dimensions that can be used.
+        """
+        for dimension in cv.dimensions:
+            target_attribute = dimension.name
+            if target_attribute in cls._cv_dimensions:
+                continue
+
+            cls._cv_dimensions.append(target_attribute)
+            logger.debug(f"Registered MetricValue dimension: {target_attribute}")
+
+            if hasattr(cls, target_attribute):
+                # This should only occur in test suite as we don't support removing dimensions at runtime
+                logger.warning("Column attribute already exists on MetricValue. Ignoring")
+            else:
+                setattr(cls, target_attribute, cls.build_dimension_column(dimension))
+
+            # TODO: Check if the underlying table already contains columns
+
+    @classmethod
+    def _reset_cv_dimensions(cls) -> None:
+        """
+        Remove any previously registered dimensions
+
+        Used by the test suite and should not be called at runtime.
+
+        This doesn't remove any previous column definitions due to a limitation that columns in
+        declarative classes cannot be removed.
+        This means that `hasattr(MetricValue, "old_attribute")`
+        will still return True after resetting, but the values will not be included in any executions.
+        """
+        logger.warning(f"Removing MetricValue dimensions: {cls._cv_dimensions}")
+
+        keys = list(cls._cv_dimensions)
+        for key in keys:
+            cls._cv_dimensions.remove(key)
+
+        assert not len(cls._cv_dimensions)  # noqa
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        execution_id: int,
+        value: float,
+        dimensions: dict[str, str],
+        attributes: dict[str, Any] | None,
+    ) -> "MetricValue":
+        """
+        Build a MetricValue from a collection of dimensions and a value
+
+        This is a helper method that validates the dimensions supplied and provides an interface
+        similar to [climate_ref_core.pycmec.metric.MetricValue][].
+
+        Parameters
+        ----------
+        execution_id
+            Execution that created the diagnostic value
+        value
+            The value of the diagnostic
+        dimensions
+            Dimensions that describe the diagnostic execution result
+        attributes
+            Optional additional attributes to describe the value,
+            but are not in the controlled vocabulary.
+
+        Raises
+        ------
+        KeyError
+            If an unknown dimension was supplied.
+
+            Dimensions must exist in the controlled vocabulary.
+
+        Returns
+        -------
+            Newly created MetricValue
+        """
+        for k in dimensions:
+            if k not in cls._cv_dimensions:
+                raise KeyError(f"Unknown dimension column '{k}'")
+
+        return MetricValue(
+            execution_id=execution_id,
+            value=value,
+            attributes=attributes,
+            **dimensions,
+        )

climate_ref/models/provider.py

@@ -0,0 +1,39 @@
+from typing import TYPE_CHECKING
+
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from climate_ref.models.base import Base, CreatedUpdatedMixin
+
+if TYPE_CHECKING:
+    from climate_ref.models.diagnostic import Diagnostic
+
+
+class Provider(CreatedUpdatedMixin, Base):
+    """
+    Represents a provider that can provide diagnostic calculations
+    """
+
+    __tablename__ = "provider"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    slug: Mapped[str] = mapped_column(unique=True)
+    """
+    Globally unique identifier for the provider.
+    """
+
+    name: Mapped[str] = mapped_column()
+    """
+    Long name of the provider
+    """
+
+    version: Mapped[str] = mapped_column(nullable=False)
+    """
+    Version of the provider.
+
+    This should map to the package version.
+    """
+
+    diagnostics: Mapped[list["Diagnostic"]] = relationship(back_populates="provider")
+
+    def __repr__(self) -> str:
+        return f"<Provider slug={self.slug} version={self.version}>"

climate_ref/provider_registry.py

@@ -0,0 +1,146 @@
+"""
+Registry of the currently active providers in the REF
+
+This module provides a registry for the currently active providers.
+Often, we can't directly import a provider and it's diagnostics
+as each provider maintains its own virtual environment to avoid dependency conflicts.
+
+For remote providers, a proxy is used to access the metadata associated with the diagnostics.
+These diagnostics cannot be run locally, but can be executed using other executors.
+"""
+
+from attrs import field, frozen
+from loguru import logger
+
+from climate_ref.config import Config
+from climate_ref.database import Database
+from climate_ref_core.diagnostics import Diagnostic
+from climate_ref_core.providers import DiagnosticProvider, import_provider
+
+
+def _register_provider(db: Database, provider: DiagnosticProvider) -> None:
+    """
+    Register a provider with the database
+
+    This is temporary until we have a proper flow for registering providers
+
+    Parameters
+    ----------
+    provider
+        DiagnosticProvider instance
+    """
+    from climate_ref.models import Diagnostic, Provider
+
+    provider_model, created = db.get_or_create(
+        Provider,
+        slug=provider.slug,
+        version=provider.version,
+        defaults={
+            "name": provider.name,
+        },
+    )
+    if created:
+        logger.info(f"Created provider {provider.slug}")
+        db.session.flush()
+
+    for diagnostic in provider.diagnostics():
+        diagnostic_model, created = db.get_or_create(
+            Diagnostic,
+            slug=diagnostic.slug,
+            provider_id=provider_model.id,
+            defaults={
+                "name": diagnostic.name,
+            },
+        )
+        if created:
+            db.session.flush()
+            logger.info(f"Created diagnostic {diagnostic_model.full_slug()}")
+
+
+@frozen
+class ProviderRegistry:
+    """
+    Registry for the currently active providers
+
+    In some cases we can't directly import a provider and it's diagnostics,
+    in this case we need to proxy the diagnostics.
+    """
+
+    providers: list[DiagnosticProvider] = field(factory=list)
+
+    def get(self, slug: str) -> DiagnosticProvider:
+        """
+        Retrieve a provider by name
+
+        Parameters
+        ----------
+        slug
+            Slug of the provider of interest
+
+        Raises
+        ------
+        KeyError
+            A provider with the matching slug has not been registered
+
+        Returns
+        -------
+            The requested provider
+        """
+        for p in self.providers:
+            if p.slug == slug:
+                return p
+
+        raise KeyError(f"No provider with slug matching: {slug}")
+
+    def get_metric(self, provider_slug: str, diagnostic_slug: str) -> "Diagnostic":
+        """
+        Retrieve a diagnostic by name
+
+        This is a convenience method to retrieve a diagnostic from a provider
+
+        Parameters
+        ----------
+        provider_slug :
+            Slug of the provider of interest
+        diagnostic_slug
+            Slug of the diagnostic of interest
+
+        Raises
+        ------
+        KeyError
+            If the provider/diagnostic with the given slugs is not found.
+
+        Returns
+        -------
+            The requested diagnostic.
+        """
+        return self.get(provider_slug).get(diagnostic_slug)
+
+    @staticmethod
+    def build_from_config(config: Config, db: Database) -> "ProviderRegistry":
+        """
+        Create a ProviderRegistry instance using information from the database
+
+        Parameters
+        ----------
+        config
+            Configuration object
+        db
+            Database instance
+
+        Returns
+        -------
+        :
+            A new ProviderRegistry instance
+        """
+        providers = []
+        for provider_info in config.diagnostic_providers:
+            provider = import_provider(provider_info.provider)
+            provider.configure(config)
+            providers.append(provider)
+
+        with db.session.begin_nested():
+            for provider in providers:
+                _register_provider(db, provider)
+
+        return ProviderRegistry(providers=providers)