feat: add reference datasets

Author: lewisjared

backend/pyproject.toml

@@ -13,6 +13,7 @@ dependencies = [
     "sentry-sdk[fastapi]>=1.40.6,<2.0.0",
     "climate-ref[aft-providers,postgres]>=0.6.3",
     "loguru",
+    "pyyaml>=6.0",
     # Not exactly sure why we need to pin this
     "lz4==4.4.4",
     "fastapi-sqlalchemy-monitor>=1.1.3",

backend/src/ref_backend/core/config.py

@@ -1,6 +1,7 @@
 import functools
 import secrets
 import warnings
+from pathlib import Path
 from typing import Annotated, Any, Literal, Self
 
 from pydantic import (
@@ -60,6 +61,28 @@ def all_cors_origins(self) -> list[str]:
     This is useful for local development and testing, but should not be used in production.
     """
 
+    DIAGNOSTIC_METADATA_PATH: Path | None = None
+    """
+    Path to the diagnostic metadata YAML file.
+
+    This file provides additional metadata for diagnostics that can override or supplement
+    the default values from diagnostic implementations. If not provided, defaults to
+    'static/diagnostics/metadata.yaml' relative to the backend directory.
+    """
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def diagnostic_metadata_path_resolved(self) -> Path:
+        """
+        Get the resolved path to the diagnostic metadata file.
+
+        Returns the configured path or the default location.
+        """
+        if self.DIAGNOSTIC_METADATA_PATH is not None:
+            return self.DIAGNOSTIC_METADATA_PATH
+        # Default to static/diagnostics/metadata.yaml relative to backend directory
+        return Path(__file__).parent.parent.parent.parent / "static" / "diagnostics" / "metadata.yaml"
+
     def _check_default_secret(self, var_name: str, value: str | None) -> None:
         if value == "changethis":
             message = (

backend/src/ref_backend/core/diagnostic_metadata.py

@@ -0,0 +1,118 @@
+"""
+Diagnostic metadata loading and override system.
+
+This module provides functionality for loading diagnostic metadata from a YAML file
+that can override or supplement the default metadata from diagnostic implementations.
+It's particularly useful for exposing reference dataset information and other metadata
+that may not be directly available from the diagnostic provider code.
+"""
+
+from pathlib import Path
+from typing import Literal
+
+import yaml
+from loguru import logger
+from pydantic import BaseModel, Field
+
+
+class ReferenceDatasetLink(BaseModel):
+    """
+    Link to a reference dataset used by a diagnostic.
+
+    Reference datasets are observational or reanalysis datasets that diagnostics
+    compare model outputs against. They can be classified by their role in the analysis.
+    """
+
+    slug: str = Field(..., description="Unique identifier for the dataset(e.g., 'obs4mips.CERES-EBAF.v4.2')")
+    description: str | None = Field(
+        None, description="Description of how this dataset is used in the diagnostic"
+    )
+    type: Literal["primary", "secondary", "comparison"] = Field(
+        ...,
+        description=(
+            "Role of this reference dataset:\n"
+            "- 'primary': Main reference dataset for the diagnostic\n"
+            "- 'secondary': Additional reference for comparison or validation\n"
+            "- 'comparison': Used for comparative analysis"
+        ),
+    )
+
+
+class DiagnosticMetadata(BaseModel):
+    """
+    Metadata overrides for a diagnostic.
+
+    This model represents supplemental or override metadata for diagnostics,
+    loaded from a YAML file. All fields are optional to allow partial overrides.
+    """
+
+    reference_datasets: list[ReferenceDatasetLink] | None = Field(
+        None, description="Reference datasets used by this diagnostic"
+    )
+    display_name: str | None = Field(None, description="Display name override for the diagnostic")
+    tags: list[str] | None = Field(None, description="Tags for categorizing the diagnostic")
+
+
+def load_diagnostic_metadata(yaml_path: Path) -> dict[str, DiagnosticMetadata]:
+    """
+    Load diagnostic metadata from a YAML file.
+
+    This function loads metadata overrides from a YAML file, which should follow
+    the structure defined in DiagnosticMetadata. The file uses diagnostic keys
+    in the format "provider-slug/diagnostic-slug" to map metadata to diagnostics.
+
+    Args:
+        yaml_path: Path to the YAML metadata file
+
+    Returns
+    -------
+        Dictionary mapping diagnostic keys (provider/diagnostic) to their metadata.
+        Returns an empty dict if the file doesn't exist or cannot be parsed.
+
+    Example YAML structure:
+        ```yaml
+        pmp/annual-cycle:
+          reference_datasets:
+            - slug: "obs4mips.CERES-EBAF.v4.2"
+              description: "CERES Energy Balanced and Filled"
+              type: "primary"
+          display_name: "Annual Cycle Analysis"
+          tags: ["atmosphere", "seasonal-cycle"]
+        ```
+    """
+    if not yaml_path.exists():
+        logger.warning(
+            f"Diagnostic metadata file not found at {yaml_path}. "
+            "No metadata overrides will be applied. This is expected if you haven't "
+            "created the metadata file yet."
+        )
+        return {}
+
+    try:
+        with open(yaml_path) as f:
+            raw_data = yaml.safe_load(f)
+
+        if raw_data is None:
+            logger.info(f"Diagnostic metadata file at {yaml_path} is empty.")
+            return {}
+
+        # Parse each diagnostic's metadata
+        metadata_dict: dict[str, DiagnosticMetadata] = {}
+        for diagnostic_key, metadata_raw in raw_data.items():
+            try:
+                metadata = DiagnosticMetadata(**metadata_raw)
+                metadata_dict[diagnostic_key] = metadata
+                logger.debug(f"Loaded metadata for diagnostic: {diagnostic_key}")
+            except Exception as e:
+                logger.error(f"Failed to parse metadata for diagnostic '{diagnostic_key}': {e}")
+                continue
+
+        logger.info(f"Successfully loaded metadata for {len(metadata_dict)} diagnostics from {yaml_path}")
+        return metadata_dict
+
+    except yaml.YAMLError as e:
+        logger.error(f"Failed to parse YAML file at {yaml_path}: {e}")
+        return {}
+    except Exception as e:
+        logger.error(f"Unexpected error loading diagnostic metadata from {yaml_path}: {e}")
+        return {}

backend/src/ref_backend/models.py

@@ -1,6 +1,6 @@
 from collections.abc import Sequence
 from datetime import datetime
-from typing import TYPE_CHECKING, Generic, Literal, TypeVar, Union
+from typing import TYPE_CHECKING, ClassVar, Generic, Literal, TypeVar, Union
 
 from attr import define
 from loguru import logger
@@ -11,6 +11,11 @@
 from climate_ref.models.dataset import CMIP6Dataset
 from climate_ref.models.execution import ResultOutputType
 from climate_ref_core.metric_values import ScalarMetricValue
+from ref_backend.core.diagnostic_metadata import (
+    DiagnosticMetadata,
+    ReferenceDatasetLink,
+    load_diagnostic_metadata,
+)
 from ref_backend.core.json_utils import sanitize_float_list, sanitize_float_value
 
 if TYPE_CHECKING:
@@ -124,12 +129,33 @@ class DiagnosticSummary(BaseModel):
     """
     Associated AFT diagnostics
     """
+    reference_datasets: list[ReferenceDatasetLink] | None = None
+    """
+    Reference datasets used by this diagnostic (from metadata overrides)
+
+    These are manually curated and may not be complete at this time.
+    """
+    tags: list[str] | None = None
+    """
+    Tags for categorizing the diagnostic (from metadata overrides)
+    """
+
+    # Cache for loaded diagnostic metadata (class variable)
+    _metadata_cache: ClassVar[dict[str, DiagnosticMetadata] | None] = None
 
     @staticmethod
     def build(diagnostic: models.Diagnostic, app_context: "AppContext") -> "DiagnosticSummary":
         # Import here to avoid circular import issues
         from ref_backend.core.aft import get_aft_diagnostic_by_id, get_aft_for_ref_diagnostic
 
+        # Load metadata YAML on first use (cached)
+        if DiagnosticSummary._metadata_cache is None:
+            metadata_path = app_context.settings.diagnostic_metadata_path_resolved
+            DiagnosticSummary._metadata_cache = load_diagnostic_metadata(metadata_path)
+            logger.debug(
+                f"Loaded diagnostic metadata cache with {len(DiagnosticSummary._metadata_cache)} entries"
+            )
+
         concrete_diagnostic = app_context.provider_registry.get_metric(
             diagnostic.provider.slug, diagnostic.slug
         )
@@ -234,7 +260,8 @@ def build(diagnostic: models.Diagnostic, app_context: "AppContext") -> "Diagnost
             logger.warning(f"No AFT found for diagnostic {diagnostic.provider.slug}/{diagnostic.slug}")
             aft = None
 
-        return DiagnosticSummary(
+        # Build the base diagnostic summary
+        summary = DiagnosticSummary(
             id=diagnostic.id,
             provider=ProviderSummary.build(diagnostic.provider),
             slug=diagnostic.slug,
@@ -252,6 +279,23 @@ def build(diagnostic: models.Diagnostic, app_context: "AppContext") -> "Diagnost
             aft_link=aft,
         )
 
+        # Apply metadata overrides from YAML if available
+        diagnostic_key = f"{diagnostic.provider.slug}/{diagnostic.slug}"
+        if diagnostic_key in DiagnosticSummary._metadata_cache:
+            metadata = DiagnosticSummary._metadata_cache[diagnostic_key]
+
+            # Apply overrides: YAML values override database values
+            if metadata.display_name is not None:
+                summary.name = metadata.display_name
+            if metadata.reference_datasets is not None:
+                summary.reference_datasets = metadata.reference_datasets
+            if metadata.tags is not None:
+                summary.tags = metadata.tags
+
+            logger.debug(f"Applied metadata overrides for diagnostic {diagnostic_key}")
+
+        return summary
+
 
 class ExecutionOutput(BaseModel):
     id: int

backend/static/diagnostics/metadata.yaml

@@ -0,0 +1,53 @@
+# Diagnostic Metadata Overrides
+#
+# This file provides additional metadata for diagnostics that supplements or overrides
+# the default values from the diagnostic implementations. It's particularly useful for:
+# - Exposing which reference datasets are used by each diagnostic
+# - Providing display names and descriptions
+# - Adding tags for categorization
+#
+# Structure:
+#   provider-slug/diagnostic-slug:
+#     reference_datasets:
+#       - slug: "dataset-slug"
+#         description: "Description of how this dataset is used"
+#         type: "primary|secondary|comparison"
+#     display_name: "Display Name (overrides default)"
+#     tags: ["category1", "category2"]
+#
+# Example diagnostics (uncomment and populate with real diagnostics as needed):
+
+# pmp/annual-cycle:
+#   reference_datasets:
+#     - slug: "obs4mips.CERES-EBAF.v4.2"
+#       description: "CERES Energy Balanced and Filled - Primary reference for TOA radiation"
+#       type: "primary"
+#     - slug: "obs4mips.GPCP.v2.3"
+#       description: "Global Precipitation Climatology Project - Precipitation comparison"
+#       type: "secondary"
+#   display_name: "Annual Cycle Analysis"
+#   tags: ["atmosphere", "seasonal-cycle", "radiation"]
+
+# pmp/mean-state:
+#   reference_datasets:
+#     - slug: "obs4mips.ERA5.v1"
+#       description: "ERA5 Reanalysis - Primary climatology reference"
+#       type: "primary"
+#   display_name: "Mean State Climatology"
+#   tags: ["atmosphere", "climatology"]
+
+# Add your diagnostic metadata here
+
+# Real diagnostic from production database
+pmp/annual-cycle:
+  reference_datasets:
+    - slug: "obs4mips.CERES-EBAF.v4.2"
+      description: "CERES Energy Balanced and Filled - Primary reference for TOA radiation"
+      type: "primary"
+    # - slug: "obs4mips.GPCP.v2.3"
+    #   description: "Global Precipitation Climatology Project - Precipitation comparison"
+    #   type: "secondary"
+    # - slug: "ERA5.monthly.single-levels"
+    #   description: "ERA5 Reanalysis - Temperature and pressure fields"
+    #   type: "comparison"
+  display_name: "Annual Cycle Analysis"