climate-ref 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

climate_ref/executor/result_handling.py

@@ -0,0 +1,231 @@
+"""
+Execute diagnostics in different environments
+
+We support running diagnostics in different environments, such as locally,
+in a separate process, or in a container.
+These environments are represented by `climate_ref.executor.Executor` classes.
+
+The simplest executor is the `LocalExecutor`, which runs the diagnostic in the same process.
+This is useful for local testing and debugging.
+"""
+
+import pathlib
+import shutil
+from typing import TYPE_CHECKING
+
+from loguru import logger
+from sqlalchemy import insert
+
+from climate_ref.database import Database
+from climate_ref.models import ScalarMetricValue
+from climate_ref.models.execution import Execution, ExecutionOutput, ResultOutputType
+from climate_ref_core.diagnostics import ExecutionResult, ensure_relative_path
+from climate_ref_core.exceptions import ResultValidationError
+from climate_ref_core.logging import EXECUTION_LOG_FILENAME
+from climate_ref_core.pycmec.controlled_vocabulary import CV
+from climate_ref_core.pycmec.metric import CMECMetric
+from climate_ref_core.pycmec.output import CMECOutput, OutputDict
+
+if TYPE_CHECKING:
+    from climate_ref.config import Config
+
+
+def _copy_file_to_results(
+    scratch_directory: pathlib.Path,
+    results_directory: pathlib.Path,
+    fragment: pathlib.Path | str,
+    filename: pathlib.Path | str,
+) -> None:
+    """
+    Copy a file from the scratch directory to the executions directory
+
+    Parameters
+    ----------
+    scratch_directory
+        The directory where the file is currently located
+    results_directory
+        The directory where the file should be copied to
+    fragment
+        The fragment of the executions directory where the file should be copied
+    filename
+        The name of the file to be copied
+    """
+    assert results_directory != scratch_directory
+    input_directory = scratch_directory / fragment
+    output_directory = results_directory / fragment
+
+    filename = ensure_relative_path(filename, input_directory)
+
+    if not (input_directory / filename).exists():
+        raise FileNotFoundError(f"Could not find {filename} in {input_directory}")
+
+    output_filename = output_directory / filename
+    output_filename.parent.mkdir(parents=True, exist_ok=True)
+
+    shutil.copy(input_directory / filename, output_filename)
+
+
+def handle_execution_result(
+    config: "Config",
+    database: Database,
+    execution: Execution,
+    result: "ExecutionResult",
+) -> None:
+    """
+    Handle the result of a diagnostic execution
+
+    This will update the diagnostic execution result with the output of the diagnostic execution.
+    The output will be copied from the scratch directory to the executions directory.
+
+    Parameters
+    ----------
+    config
+        The configuration to use
+    database
+        The active database session to use
+    execution
+        The diagnostic execution result DB object to update
+    result
+        The result of the diagnostic execution, either successful or failed
+    """
+    # Always copy log data
+    _copy_file_to_results(
+        config.paths.scratch,
+        config.paths.results,
+        execution.output_fragment,
+        EXECUTION_LOG_FILENAME,
+    )
+
+    if result.successful and result.metric_bundle_filename is not None:
+        logger.info(f"{execution} successful")
+
+        _copy_file_to_results(
+            config.paths.scratch,
+            config.paths.results,
+            execution.output_fragment,
+            result.metric_bundle_filename,
+        )
+        execution.mark_successful(result.as_relative_path(result.metric_bundle_filename))
+
+        if result.output_bundle_filename:
+            _copy_file_to_results(
+                config.paths.scratch,
+                config.paths.results,
+                execution.output_fragment,
+                result.output_bundle_filename,
+            )
+            _handle_output_bundle(
+                config,
+                database,
+                execution,
+                result.to_output_path(result.output_bundle_filename),
+            )
+
+        cmec_metric_bundle = CMECMetric.load_from_json(result.to_output_path(result.metric_bundle_filename))
+
+        # Check that the diagnostic values conform with the controlled vocabulary
+        try:
+            cv = CV.load_from_file(config.paths.dimensions_cv)
+            cv.validate_metrics(cmec_metric_bundle)
+        except (ResultValidationError, AssertionError):
+            logger.exception("Diagnostic values do not conform with the controlled vocabulary")
+            # TODO: Mark the diagnostic execution result as failed once the CV has stabilised
+            # execution.mark_failed()
+
+        # Perform a bulk insert of scalar values
+        # TODO: The section below will likely fail until we have agreed on a controlled vocabulary
+        # The current implementation will swallow the exception, but display a log message
+        try:
+            # Perform this in a nested transaction to (hopefully) gracefully rollback if something
+            # goes wrong
+            with database.session.begin_nested():
+                database.session.execute(
+                    insert(ScalarMetricValue),
+                    [
+                        {
+                            "execution_id": execution.id,
+                            "value": result.value,
+                            "attributes": result.attributes,
+                            **result.dimensions,
+                        }
+                        for result in cmec_metric_bundle.iter_results()
+                    ],
+                )
+        except Exception:
+            # TODO: Remove once we have settled on a controlled vocabulary
+            logger.exception("Something went wrong when ingesting diagnostic values")
+
+        # TODO Ingest the series values
+
+        # TODO: This should check if the result is the most recent for the execution,
+        # if so then update the dirty fields
+        # i.e. if there are outstanding executions don't make as clean
+        execution.execution_group.dirty = False
+    else:
+        logger.error(f"{execution} failed")
+        execution.mark_failed()
+
+
+def _handle_output_bundle(
+    config: "Config",
+    database: Database,
+    execution: Execution,
+    cmec_output_bundle_filename: pathlib.Path,
+) -> None:
+    # Extract the registered outputs
+    # Copy the content to the output directory
+    # Track in the db
+    cmec_output_bundle = CMECOutput.load_from_json(cmec_output_bundle_filename)
+    _handle_outputs(
+        cmec_output_bundle.plots,
+        output_type=ResultOutputType.Plot,
+        config=config,
+        database=database,
+        execution=execution,
+    )
+    _handle_outputs(
+        cmec_output_bundle.data,
+        output_type=ResultOutputType.Data,
+        config=config,
+        database=database,
+        execution=execution,
+    )
+    _handle_outputs(
+        cmec_output_bundle.html,
+        output_type=ResultOutputType.HTML,
+        config=config,
+        database=database,
+        execution=execution,
+    )
+
+
+def _handle_outputs(
+    outputs: dict[str, OutputDict] | None,
+    output_type: ResultOutputType,
+    config: "Config",
+    database: Database,
+    execution: Execution,
+) -> None:
+    outputs = outputs or {}
+
+    for key, output_info in outputs.items():
+        filename = ensure_relative_path(
+            output_info.filename, config.paths.scratch / execution.output_fragment
+        )
+
+        _copy_file_to_results(
+            config.paths.scratch,
+            config.paths.results,
+            execution.output_fragment,
+            filename,
+        )
+        database.session.add(
+            ExecutionOutput(
+                execution_id=execution.id,
+                output_type=output_type,
+                filename=str(filename),
+                description=output_info.description,
+                short_name=key,
+                long_name=output_info.long_name,
+            )
+        )

climate_ref/executor/synchronous.py

@@ -0,0 +1,62 @@
+from typing import Any
+
+from climate_ref.config import Config
+from climate_ref.database import Database
+from climate_ref.executor.local import process_result
+from climate_ref.models import Execution
+from climate_ref_core.diagnostics import ExecutionDefinition
+from climate_ref_core.executor import execute_locally
+
+
+class SynchronousExecutor:
+    """
+    Run a diagnostic synchronously, in-process.
+
+    This is mainly useful for debugging and testing.
+    [climate_ref.executor.LocalExecutor][] is a more general purpose executor.
+    """
+
+    name = "synchronous"
+
+    def __init__(
+        self, *, database: Database | None = None, config: Config | None = None, **kwargs: Any
+    ) -> None:
+        if config is None:
+            config = Config.default()
+        if database is None:
+            database = Database.from_config(config, run_migrations=False)
+
+        self.database = database
+        self.config = config
+
+    def run(
+        self,
+        definition: ExecutionDefinition,
+        execution: Execution | None = None,
+    ) -> None:
+        """
+        Run a diagnostic in process
+
+        Parameters
+        ----------
+        definition
+            A description of the information needed for this execution of the diagnostic
+        execution
+            A database model representing the execution of the diagnostic.
+            If provided, the result will be updated in the database when completed.
+        """
+        result = execute_locally(definition, log_level=self.config.log_level)
+        process_result(self.config, self.database, result, execution)
+
+    def join(self, timeout: float) -> None:
+        """
+        Wait for all diagnostics to finish
+
+        This returns immediately because the executor runs diagnostics synchronously.
+
+        Parameters
+        ----------
+        timeout
+            Timeout in seconds (Not used)
+        """
+        pass

climate_ref/migrations/env.py

@@ -8,6 +8,11 @@ from climate_ref.models import Base, MetricValue
 from climate_ref_core.logging import capture_logging
 from climate_ref_core.pycmec.controlled_vocabulary import CV
 
+try:
+    import alembic_postgresql_enum  # noqa
+except ImportError:
+    logger.warning("alembic_postgresql_enum not installed, skipping enum migration support")
+
 # Setup logging
 capture_logging()
 logger.debug("Running alembic env")

climate_ref/migrations/versions/2025-05-02T1418_341a4aa2551e_regenerate.py

@@ -235,38 +235,17 @@ def upgrade() -> None:
         sa.Column("attributes", sa.JSON(), nullable=False),
         sa.Column("created_at", sa.DateTime(), server_default=sa.text("(CURRENT_TIMESTAMP)"), nullable=False),
         sa.Column("updated_at", sa.DateTime(), server_default=sa.text("(CURRENT_TIMESTAMP)"), nullable=False),
-        sa.Column("model", sa.Text(), nullable=True),
-        sa.Column("source_id", sa.Text(), nullable=True),
-        sa.Column("variant_label", sa.Text(), nullable=True),
-        sa.Column("metric", sa.Text(), nullable=True),
-        sa.Column("region", sa.Text(), nullable=True),
-        sa.Column("statistic", sa.Text(), nullable=True),
         sa.ForeignKeyConstraint(
             ["execution_id"], ["execution.id"], name=op.f("fk_metric_value_execution_id_execution")
         ),
         sa.PrimaryKeyConstraint("id", name=op.f("pk_metric_value")),
     )
-    with op.batch_alter_table("metric_value", schema=None) as batch_op:
-        batch_op.create_index(batch_op.f("ix_metric_value_metric"), ["metric"], unique=False)
-        batch_op.create_index(batch_op.f("ix_metric_value_model"), ["model"], unique=False)
-        batch_op.create_index(batch_op.f("ix_metric_value_region"), ["region"], unique=False)
-        batch_op.create_index(batch_op.f("ix_metric_value_source_id"), ["source_id"], unique=False)
-        batch_op.create_index(batch_op.f("ix_metric_value_statistic"), ["statistic"], unique=False)
-        batch_op.create_index(batch_op.f("ix_metric_value_variant_label"), ["variant_label"], unique=False)
 
     # ### end Alembic commands ###
 
 
 def downgrade() -> None:
     # ### commands auto generated by Alembic - please adjust! ###
-    with op.batch_alter_table("metric_value", schema=None) as batch_op:
-        batch_op.drop_index(batch_op.f("ix_metric_value_variant_label"))
-        batch_op.drop_index(batch_op.f("ix_metric_value_statistic"))
-        batch_op.drop_index(batch_op.f("ix_metric_value_source_id"))
-        batch_op.drop_index(batch_op.f("ix_metric_value_region"))
-        batch_op.drop_index(batch_op.f("ix_metric_value_model"))
-        batch_op.drop_index(batch_op.f("ix_metric_value_metric"))
-
     op.drop_table("metric_value")
     with op.batch_alter_table("execution_output", schema=None) as batch_op:
         batch_op.drop_index(batch_op.f("ix_execution_output_output_type"))

climate_ref/migrations/versions/2025-05-09T2032_03dbb4998e49_series_metric_value.py

@@ -0,0 +1,57 @@
+"""series-metric-value
+
+Revision ID: 03dbb4998e49
+Revises: 341a4aa2551e
+Create Date: 2025-05-09 20:32:08.664426
+
+"""
+
+from collections.abc import Sequence
+from typing import Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "03dbb4998e49"
+down_revision: Union[str, None] = "341a4aa2551e"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table("metric_value", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("values", sa.JSON(), nullable=True))
+        batch_op.add_column(sa.Column("index", sa.JSON(), nullable=True))
+        batch_op.add_column(sa.Column("index_name", sa.String(), nullable=True))
+        batch_op.alter_column("value", existing_type=sa.FLOAT(), nullable=True)
+
+    if sa.inspect(op.get_bind()).dialect.name == "postgresql":
+        sa.Enum("SCALAR", "SERIES", name="metricvaluetype").create(op.get_bind())
+        op.add_column(
+            "metric_value",
+            sa.Column(
+                "type",
+                postgresql.ENUM("SCALAR", "SERIES", name="metricvaluetype", create_type=False),
+                nullable=False,
+            ),
+        )
+    else:
+        with op.batch_alter_table("metric_value", schema=None) as batch_op:
+            batch_op.add_column(
+                sa.Column("type", sa.Enum("SCALAR", "SERIES", name="metricvaluetype"), nullable=False)
+            )
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table("metric_value", schema=None) as batch_op:
+        batch_op.alter_column("value", existing_type=sa.FLOAT(), nullable=False)
+        batch_op.drop_column("index_name")
+        batch_op.drop_column("index")
+        batch_op.drop_column("values")
+        batch_op.drop_column("type")
+
+    # ### end Alembic commands ###

climate_ref/models/__init__.py

@@ -14,7 +14,7 @@ from climate_ref.models.execution import (
     ExecutionGroup,
     ExecutionOutput,
 )
-from climate_ref.models.metric_value import MetricValue
+from climate_ref.models.metric_value import MetricValue, ScalarMetricValue, SeriesMetricValue
 from climate_ref.models.provider import Provider
 
 Table = TypeVar("Table", bound=Base)
@@ -29,5 +29,7 @@ __all__ = [
     "ExecutionOutput",
     "MetricValue",
     "Provider",
+    "ScalarMetricValue",
+    "SeriesMetricValue",
     "Table",
 ]

climate_ref/models/base.py

@@ -12,6 +12,8 @@ class Base(DeclarativeBase):
 
     type_annotation_map = {  # noqa: RUF012
         dict[str, Any]: JSON,
+        list[float | int]: JSON,
+        list[float | int | str]: JSON,
     }
     metadata = MetaData(
         # Enforce a common naming convention for constraints

climate_ref/models/metric_value.py

@@ -1,7 +1,9 @@
+import enum
+from collections.abc import Mapping
 from typing import TYPE_CHECKING, Any, ClassVar
 
 from loguru import logger
-from sqlalchemy import Column, ForeignKey, Text
+from sqlalchemy import Column, ForeignKey, Text, event
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from climate_ref.models.base import Base, CreatedUpdatedMixin
@@ -11,9 +13,23 @@ if TYPE_CHECKING:
     from climate_ref.models.execution import Execution
 
 
+class MetricValueType(enum.Enum):
+    """
+    Type of metric value
+
+    This is used to determine how the metric value should be interpreted.
+    """
+
+    # The value is a single number
+    SCALAR = "scalar"
+
+    # The value is a list of numbers
+    SERIES = "series"
+
+
 class MetricValue(CreatedUpdatedMixin, Base):
     """
-    Represents a single diagnostic value
+    Represents a single metric 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,
@@ -26,14 +42,24 @@ class MetricValue(CreatedUpdatedMixin, Base):
 
     __tablename__ = "metric_value"
 
+    __mapper_args__: ClassVar[Mapping[str, str]] = {  # type: ignore
+        "polymorphic_on": "type",
+    }
+
     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")
 
+    type: Mapped[MetricValueType] = mapped_column()
+    """
+    Type of metric value
+
+    This value is used to determine how the metric value should be interpreted.
+    """
+
     _cv_dimensions: ClassVar[list[str]] = []
 
     @property
@@ -55,13 +81,7 @@ class MetricValue(CreatedUpdatedMixin, Base):
         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}>"
-        )
+        return f"<MetricValue id={self.id} execution={self.execution} dimensions={self.dimensions}>"
 
     @staticmethod
     def build_dimension_column(dimension: Dimension) -> Column[str]:
@@ -143,7 +163,22 @@ class MetricValue(CreatedUpdatedMixin, Base):
         for key in keys:
             cls._cv_dimensions.remove(key)
 
-        assert not len(cls._cv_dimensions)  # noqa
+        assert not len(cls._cv_dimensions)
+
+
+class ScalarMetricValue(MetricValue):
+    """
+    A scalar value with an associated dimensions
+
+    This is a subclass of MetricValue that is used to represent a scalar value.
+    """
+
+    __mapper_args__: ClassVar[Mapping[str, Any]] = {  # type: ignore
+        "polymorphic_identity": MetricValueType.SCALAR,
+    }
+
+    # This is a scalar value
+    value: Mapped[float] = mapped_column(nullable=True)
 
     @classmethod
     def build(
@@ -158,7 +193,7 @@ class MetricValue(CreatedUpdatedMixin, Base):
         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][].
+        similar to [climate_ref_core.metric_values.ScalarMetricValue][].
 
         Parameters
         ----------
@@ -187,9 +222,99 @@ class MetricValue(CreatedUpdatedMixin, Base):
             if k not in cls._cv_dimensions:
                 raise KeyError(f"Unknown dimension column '{k}'")
 
-        return MetricValue(
+        return ScalarMetricValue(
             execution_id=execution_id,
             value=value,
             attributes=attributes,
             **dimensions,
         )
+
+
+class SeriesMetricValue(MetricValue):
+    """
+    A scalar value with an associated dimensions
+
+    This is a subclass of MetricValue that is used to represent a scalar value.
+    """
+
+    __mapper_args__: ClassVar[Mapping[str, Any]] = {  # type: ignore
+        "polymorphic_identity": MetricValueType.SERIES,
+    }
+
+    # This is a scalar value
+    values: Mapped[list[float | int]] = mapped_column(nullable=True)
+    index: Mapped[list[float | int | str]] = mapped_column(nullable=True)
+    index_name: Mapped[str] = mapped_column(nullable=True)
+
+    @classmethod
+    def build(  # noqa: PLR0913
+        cls,
+        *,
+        execution_id: int,
+        values: list[float | int],
+        index: list[float | int | str],
+        index_name: str,
+        dimensions: dict[str, str],
+        attributes: dict[str, Any] | None,
+    ) -> "MetricValue":
+        """
+        Build a database object from a series
+
+        Parameters
+        ----------
+        execution_id
+            Execution that created the diagnostic value
+        values
+            1-d array of values
+        index
+            1-d array of index values
+        index_name
+            Name of the index. Used for presentation purposes
+        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.
+        ValueError
+            If the length of values and index do not match.
+
+        Returns
+        -------
+            Newly created MetricValue
+        """
+        for k in dimensions:
+            if k not in cls._cv_dimensions:
+                raise KeyError(f"Unknown dimension column '{k}'")
+
+        if len(values) != len(index):
+            raise ValueError(f"Index length ({len(index)}) must match values length ({len(values)})")
+
+        return SeriesMetricValue(
+            execution_id=execution_id,
+            values=values,
+            index=index,
+            index_name=index_name,
+            attributes=attributes,
+            **dimensions,
+        )
+
+
+@event.listens_for(SeriesMetricValue, "before_insert")
+@event.listens_for(SeriesMetricValue, "before_update")
+def validate_series_lengths(mapper: Any, connection: Any, target: SeriesMetricValue) -> None:
+    """
+    Validate that values and index have matching lengths
+
+    This is done on insert and update to ensure that the database is consistent.
+    """
+    if target.values is not None and target.index is not None and len(target.values) != len(target.index):
+        raise ValueError(
+            f"Index length ({len(target.index)}) must match values length ({len(target.values)})"
+        )

climate_ref/provider_registry.py

@@ -139,7 +139,7 @@ class ProviderRegistry:
             provider.configure(config)
             providers.append(provider)
 
-        with db.session.begin_nested():
+        with db.session.begin():
             for provider in providers:
                 _register_provider(db, provider)