biodata-cache 0.32.0__py3-none-any.whl

biodata_cache/__init__.py

@@ -0,0 +1,32 @@
+"""Zombie-squirrel: caching and synchronization for AIND metadata.
+
+Provides functions to fetch and cache project names, subject IDs, and asset
+metadata from the AIND metadata database with support for multiple backends.
+Also exposes get_cache_registry to retrieve the cache_registry.json registry of all
+available cache tables and their metadata.
+"""
+
+__version__ = "0.32.0"
+
+from biodata_cache.cache_table_helpers.asset_basics import asset_basics  # noqa: F401
+from biodata_cache.cache_table_helpers.behavior_curriculum import behavior_curriculum  # noqa: F401
+from biodata_cache.cache_table_helpers.custom import custom  # noqa: F401
+from biodata_cache.cache_table_helpers.foraging_sessions import foraging_sessions  # noqa: F401
+from biodata_cache.cache_table_helpers.metadata_upgrade import metadata_upgrade  # noqa: F401
+from biodata_cache.cache_table_helpers.platform_exaspim import platform_exaspim  # noqa: F401
+from biodata_cache.cache_table_helpers.platform_fib import platform_fib  # noqa: F401
+from biodata_cache.cache_table_helpers.platform_qc import platform_qc  # noqa: F401
+from biodata_cache.cache_table_helpers.platform_smartspim import assets_smartspim  # noqa: F401
+from biodata_cache.cache_table_helpers.qc import qc, qc_columns  # noqa: F401
+from biodata_cache.cache_table_helpers.raw_to_derived import raw_to_derived  # noqa: F401
+from biodata_cache.cache_table_helpers.source_data import source_data  # noqa: F401
+from biodata_cache.cache_table_helpers.unique_genotypes import (  # noqa: F401
+    unique_genotypes,
+)
+from biodata_cache.cache_table_helpers.unique_project_names import (  # noqa: F401
+    unique_project_names,
+)
+from biodata_cache.cache_table_helpers.unique_subject_ids import (  # noqa: F401
+    unique_subject_ids,
+)
+from biodata_cache.utils import get_cache_registry  # noqa: F401

biodata_cache/backend.py

@@ -0,0 +1,310 @@
+"""Storage backend interfaces for caching data."""
+
+import io
+import json
+import logging
+from abc import ABC, abstractmethod
+
+import boto3
+import duckdb
+import pandas as pd
+
+from biodata_cache.utils import BDC_VERSION, CacheLogMessage
+
+_CACHE_ROOT = "data-asset-cache"
+_VERSION_FOLDER = f"bdc-v{BDC_VERSION}"
+
+HIVE_PARTITION_KEYS = {
+    "qc": "subject_id",
+    "qc_tag_status": "subject_id",
+    "platform_qc": "platform",
+}
+
+
+class Backend(ABC):
+    """Base class for a cache storage backend."""
+
+    def __init__(self) -> None:
+        """Initialize the Backend."""
+        super().__init__()
+
+    @abstractmethod
+    def write(self, table_name: str, data: pd.DataFrame) -> None:
+        """Write records to the cache."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def read(self, table_name: str | list[str]) -> pd.DataFrame:
+        """Read records from the cache.
+
+        Args:
+            table_name: Single table name or list of table names.
+                When a list is provided, merges all tables and adds
+                an 'asset_name' column to differentiate sources.
+
+        """
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_location(self, table_name: str, partitioned: bool = False) -> str:
+        """Return the storage location string for a given table."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def put_json(self, key: str, data: str) -> None:
+        """Write a JSON string to the storage root under the given key."""
+        pass  # pragma: no cover
+
+    @abstractmethod
+    def get_json(self, key: str) -> str:
+        """Read a JSON string from the storage root under the given key."""
+        pass  # pragma: no cover
+
+
+class S3Backend(Backend):
+    """Stores and retrieves caches using AWS S3 with parquet files."""
+
+    def __init__(self) -> None:
+        """Initialize S3Backend with S3 client."""
+        self.bucket = "allen-data-views"
+        self.s3_client = boto3.client("s3")
+
+    def write(self, table_name: str, data: pd.DataFrame) -> None:
+        """Store DataFrame as parquet file in S3."""
+        if "/" in table_name:
+            base, value = table_name.split("/", 1)
+            partition_key = HIVE_PARTITION_KEYS[base]
+            s3_key = f"{_CACHE_ROOT}/{_VERSION_FOLDER}/{base}/{partition_key}={value}/data.pqt"
+            json_key = f"{_CACHE_ROOT}/{_VERSION_FOLDER}/{base}.json"
+        else:
+            s3_key = f"{_CACHE_ROOT}/{_VERSION_FOLDER}/{table_name}.pqt"
+            json_key = f"{_CACHE_ROOT}/{_VERSION_FOLDER}/{table_name}.json"
+
+        parquet_buffer = io.BytesIO()
+        data.to_parquet(parquet_buffer, index=False)
+        parquet_buffer.seek(0)
+
+        self.s3_client.put_object(
+            Bucket=self.bucket,
+            Key=s3_key,
+            Body=parquet_buffer.getvalue(),
+        )
+        logging.info(
+            CacheLogMessage(
+                backend="S3Backend", table=table_name, message=f"Stored cache to s3://{self.bucket}/{s3_key}"
+            ).to_json()
+        )
+
+        metadata = {"columns": data.columns.tolist()}
+        self.s3_client.put_object(
+            Bucket=self.bucket,
+            Key=json_key,
+            Body=json.dumps(metadata),
+        )
+
+    def read(self, table_name: str | list[str]) -> pd.DataFrame:
+        """Fetch DataFrame from S3 parquet file(s).
+
+        When given a list of table names, merges them using DuckDB
+        and adds an 'asset_name' column.
+        """
+        if isinstance(table_name, list):
+            return self._read_multiple(table_name)
+        return self._read_single(table_name)
+
+    def _read_single(self, table_name: str) -> pd.DataFrame:
+        """Fetch a single table from S3."""
+        if "/" in table_name:
+            base, value = table_name.split("/", 1)
+            partition_key = HIVE_PARTITION_KEYS[base]
+            s3_key = f"{_CACHE_ROOT}/{_VERSION_FOLDER}/{base}/{partition_key}={value}/data.pqt"
+        else:
+            s3_key = f"{_CACHE_ROOT}/{_VERSION_FOLDER}/{table_name}.pqt"
+
+        try:
+            query = f"""
+                SELECT * FROM read_parquet(
+                    's3://{self.bucket}/{s3_key}'
+                )
+            """
+            result = duckdb.query(query).to_df()
+            logging.info(
+                CacheLogMessage(
+                    backend="S3Backend", table=table_name, message=f"Retrieved cache from s3://{self.bucket}/{s3_key}"
+                ).to_json()
+            )
+            return result
+        except Exception as e:
+            logging.warning(
+                CacheLogMessage(
+                    backend="S3Backend", table=table_name, message=f"Error fetching from cache {s3_key}: {e}"
+                ).to_json()
+            )
+            return pd.DataFrame()
+
+    def get_location(self, table_name: str, partitioned: bool = False) -> str:
+        """Return the S3 URI for a given table."""
+        if partitioned:
+            return f"s3://{self.bucket}/{_CACHE_ROOT}/{_VERSION_FOLDER}/{table_name}/"
+        if "/" in table_name:
+            base, value = table_name.split("/", 1)
+            partition_key = HIVE_PARTITION_KEYS[base]
+            return f"s3://{self.bucket}/{_CACHE_ROOT}/{_VERSION_FOLDER}/{base}/{partition_key}={value}/data.pqt"
+        return f"s3://{self.bucket}/{_CACHE_ROOT}/{_VERSION_FOLDER}/{table_name}.pqt"
+
+    def put_json(self, key: str, data: str) -> None:  # pragma: no cover
+        """Write a JSON string to the versioned folder in S3 and update the index."""
+        s3_key = f"{_CACHE_ROOT}/{_VERSION_FOLDER}/{key}"
+        self.s3_client.put_object(
+            Bucket=self.bucket,
+            Key=s3_key,
+            Body=data.encode(),
+            ContentType="application/json",
+        )
+        logging.info(
+            CacheLogMessage(
+                backend="S3Backend", table=key, message=f"Published metadata to s3://{self.bucket}/{s3_key}"
+            ).to_json()
+        )
+        index_key = f"{_CACHE_ROOT}/cache_versions.json"
+        try:
+            response = self.s3_client.get_object(Bucket=self.bucket, Key=index_key)
+            existing = json.loads(response["Body"].read().decode())
+        except Exception:
+            existing = []
+        if _VERSION_FOLDER not in existing:
+            existing.append(_VERSION_FOLDER)
+        self.s3_client.put_object(
+            Bucket=self.bucket,
+            Key=index_key,
+            Body=json.dumps(existing).encode(),
+            ContentType="application/json",
+        )
+
+    def get_json(self, key: str) -> str:  # pragma: no cover
+        """Read a JSON string from the versioned folder in S3."""
+        s3_key = f"{_CACHE_ROOT}/{_VERSION_FOLDER}/{key}"
+        response = self.s3_client.get_object(Bucket=self.bucket, Key=s3_key)
+        return response["Body"].read().decode()
+
+    def _read_multiple(self, table_names: list[str]) -> pd.DataFrame:
+        """Fetch and merge multiple tables from S3."""
+        parquet_paths = []
+        asset_names = []
+
+        for tbl_name in table_names:
+            s3_key = f"{_CACHE_ROOT}/{_VERSION_FOLDER}/{tbl_name}.pqt"
+            s3_path = f"s3://{self.bucket}/{s3_key}"
+            parquet_paths.append(f"'{s3_path}'")
+            asset_names.append(tbl_name)
+
+        try:
+            union_query = " UNION ALL ".join(
+                [
+                    f"SELECT *, '{asset}' as asset_name FROM read_parquet({path})"
+                    for path, asset in zip(parquet_paths, asset_names, strict=False)
+                ]
+            )
+            result = duckdb.query(union_query).to_df()
+            logging.info(
+                CacheLogMessage(
+                    backend="S3Backend", table="merged", message=f"Merged {len(table_names)} tables from S3"
+                ).to_json()
+            )
+            return result
+        except Exception as e:
+            logging.warning(
+                CacheLogMessage(backend="S3Backend", table="merged", message=f"Error merging tables: {e}").to_json()
+            )
+            return pd.DataFrame()
+
+
+class MemoryBackend(Backend):
+    """A simple in-memory backend for testing or local development."""
+
+    def __init__(self) -> None:
+        """Initialize MemoryBackend with empty store."""
+        super().__init__()
+        self._store: dict[str, pd.DataFrame] = {}
+        self._json_store: dict[str, str] = {}
+
+    def write(self, table_name: str, data: pd.DataFrame) -> None:
+        """Store DataFrame in memory."""
+        logging.info(
+            CacheLogMessage(
+                backend="MemoryBackend", table=table_name, message=f"Storing cache in memory for {table_name}"
+            ).to_json()
+        )
+        self._store[table_name] = data
+
+    def read(self, table_name: str | list[str]) -> pd.DataFrame:
+        """Fetch DataFrame from memory.
+
+        When given a list of table names, merges them and adds
+        an 'asset_name' column.
+        """
+        if isinstance(table_name, list):
+            return self._read_multiple(table_name)
+        return self._read_single(table_name)
+
+    def _read_single(self, table_name: str) -> pd.DataFrame:
+        """Fetch a single table from memory."""
+        logging.info(
+            CacheLogMessage(
+                backend="MemoryBackend", table=table_name, message=f"Fetching cache from memory for {table_name}"
+            ).to_json()
+        )
+        return self._store.get(table_name, pd.DataFrame())
+
+    def get_location(self, table_name: str, partitioned: bool = False) -> str:
+        """Return the in-memory identifier for a given table."""
+        if partitioned:
+            return f"{_VERSION_FOLDER}/{table_name}/"
+        if "/" in table_name:
+            base, value = table_name.split("/", 1)
+            partition_key = HIVE_PARTITION_KEYS[base]
+            return f"{_VERSION_FOLDER}/{base}/{partition_key}={value}/data.pqt"
+        return f"{_VERSION_FOLDER}/{table_name}.pqt"
+
+    def put_json(self, key: str, data: str) -> None:
+        """Store a JSON string in the versioned in-memory JSON store and update index."""
+        logging.info(
+            CacheLogMessage(
+                backend="MemoryBackend", table=key, message=f"Storing metadata in memory for {key}"
+            ).to_json()
+        )
+        self._json_store[f"{_VERSION_FOLDER}/{key}"] = data
+        existing = json.loads(self._json_store.get("cache_versions.json", "[]"))
+        if _VERSION_FOLDER not in existing:
+            existing.append(_VERSION_FOLDER)
+        self._json_store["cache_versions.json"] = json.dumps(existing)
+
+    def get_json(self, key: str) -> str:
+        """Read a JSON string from the versioned in-memory JSON store."""
+        return self._json_store.get(f"{_VERSION_FOLDER}/{key}", "{}")
+
+    def _read_multiple(self, table_names: list[str]) -> pd.DataFrame:
+        """Fetch and merge multiple tables from memory."""
+        dfs = []
+        for tbl_name in table_names:
+            df = self._store.get(tbl_name, pd.DataFrame())
+            if not df.empty:
+                df = df.copy()
+                df["asset_name"] = tbl_name
+                dfs.append(df)
+
+        if not dfs:
+            logging.warning(
+                CacheLogMessage(
+                    backend="MemoryBackend", table="merged", message=f"No valid tables found among {table_names}"
+                ).to_json()
+            )
+            return pd.DataFrame()
+
+        result = pd.concat(dfs, ignore_index=True)
+        logging.info(
+            CacheLogMessage(
+                backend="MemoryBackend", table="merged", message=f"Merged {len(dfs)} tables from memory"
+            ).to_json()
+        )
+        return result

biodata_cache/cache_table_helpers/__init__.py

@@ -0,0 +1,20 @@
+"""Acorns module: individual data fetching functions."""
+
+from biodata_cache.cache_table_helpers import (  # noqa: F401
+    asset_basics,
+    behavior_curriculum,
+    custom,
+    foraging_sessions,
+    metadata_core,
+    metadata_upgrade,
+    platform_exaspim,
+    platform_fib,
+    platform_qc,
+    platform_smartspim,
+    qc,
+    raw_to_derived,
+    source_data,
+    unique_genotypes,
+    unique_project_names,
+    unique_subject_ids,
+)

biodata_cache/cache_table_helpers/asset_basics.py

@@ -0,0 +1,271 @@
+"""Asset basics cache table."""
+
+import logging
+
+import pandas as pd
+from aind_data_access_api.document_db import MetadataDbClient
+
+import biodata_cache.registry as registry
+from biodata_cache.models import Column
+from biodata_cache.utils import (
+    CacheLogMessage,
+    apply_first_name_map,
+    build_first_name_map,
+    normalize_experimenters,
+    normalize_instrument_id,
+    setup_logging,
+)
+
+
+@registry.register_table(registry.NAMES["basics"])
+def asset_basics(force_update: bool = False) -> pd.DataFrame:
+    """Fetch basic asset metadata including modalities, projects, and subject info.
+
+    Returns a DataFrame with columns: _id, _last_modified, modalities,
+    project_name, data_level, subject_id, acquisition_start_time, and
+    acquisition_end_time. Uses incremental updates based on _last_modified
+    timestamps to avoid re-fetching unchanged records.
+
+    Args:
+        force_update: If True, bypass cache and fetch fresh data from database.
+
+    Returns:
+        DataFrame with basic asset metadata.
+
+    """
+    df = registry.BACKEND.read(registry.NAMES["basics"])
+
+    FIELDS = [
+        "data_description.modalities",
+        "data_description.project_name",
+        "data_description.data_level",
+        "subject.subject_id",
+        "acquisition.acquisition_start_time",
+        "acquisition.acquisition_end_time",
+        "acquisition.acquisition_type",
+        "acquisition.subject_details.date_of_birth",
+        "acquisition.subject_details.year_of_birth",
+        "processing.data_processes.start_date_time",
+        "subject.subject_details.genotype",
+        "other_identifiers",
+        "location",
+        "name",
+        "acquisition.experimenters",
+        "acquisition.instrument_id",
+        "data_description.investigators",
+    ]
+
+    if df.empty or force_update:
+        setup_logging()
+        logging.info(
+            CacheLogMessage(
+                backend=registry.BACKEND.__class__.__name__, table=registry.NAMES["basics"], message="Updating cache"
+            ).to_json()
+        )
+        df = pd.DataFrame(
+            columns=[
+                "_id",
+                "_last_modified",
+                "modalities",
+                "project_name",
+                "data_level",
+                "subject_id",
+                "acquisition_start_time",
+                "acquisition_end_time",
+                "code_ocean",
+                "process_date",
+                "genotype",
+                "age",
+                "acquisition_type",
+                "location",
+                "name",
+                "experimenters",
+                "experimenters_normalized",
+                "instrument_id",
+                "instrument_id_normalized",
+                "investigators",
+                "investigators_normalized",
+            ]
+        )
+        client = MetadataDbClient(
+            host=registry.API_GATEWAY_HOST,
+            version="v2",
+        )
+        # It's a bit complex to get multiple fields that aren't indexed in a database
+        # as large as DocDB. We'll also try to limit ourselves to only updating fields
+        # that are necessary
+        record_ids = client.retrieve_docdb_records(
+            filter_query={},
+            projection={"_id": 1, "_last_modified": 1},
+            limit=0,
+        )
+        keep_ids = []
+        # Drop all _ids where _last_modified matches cache
+        for record in record_ids:
+            cached_row = df[df["_id"] == record["_id"]]
+            if cached_row.empty or cached_row["_last_modified"].values[0] != record["_last_modified"]:
+                keep_ids.append(record["_id"])
+
+        # Now batch by 100 IDs at a time to avoid overloading server, and fetch all the fields
+        BATCH_SIZE = 100
+        asset_records = []
+        for i in range(0, len(keep_ids), BATCH_SIZE):
+            logging.info(
+                CacheLogMessage(
+                    backend=registry.BACKEND.__class__.__name__,
+                    table=registry.NAMES["basics"],
+                    message=f"Fetching batch {i // BATCH_SIZE + 1}",
+                ).to_json()
+            )
+            batch_ids = keep_ids[i : i + BATCH_SIZE]
+            batch_records = client.retrieve_docdb_records(
+                filter_query={"_id": {"$in": batch_ids}},
+                projection={field: 1 for field in FIELDS + ["_id", "_last_modified"]},
+                limit=0,
+            )
+            asset_records.extend(batch_records)
+
+        # Unwrap nested fields
+        records = []
+        for record in asset_records:
+            modalities = record.get("data_description", {}).get("modalities", [])
+            modality_abbreviations = [modality["abbreviation"] for modality in modalities if "abbreviation" in modality]
+
+            # Get the process date, convert to YYYY-MM-DD if present
+            data_processes = record.get("processing", {}).get("data_processes", [])
+            if data_processes:
+                latest_process = data_processes[-1]
+                process_datetime = latest_process.get("start_date_time", None)
+                process_date = process_datetime.split("T")[0]
+            else:
+                process_date = None
+
+            # Get the CO asset ID
+            other_identifiers = record.get("other_identifiers", {})
+            if other_identifiers:
+                code_ocean = other_identifiers.get("Code Ocean", None)
+            else:
+                code_ocean = None
+
+            # Calculate age in days from acquisition_start_time and date_of_birth or year_of_birth
+            acquisition_start = record.get("acquisition", {}).get("acquisition_start_time", None)
+            acq_subject_details = record.get("acquisition", {}).get("subject_details", {}) or {}
+            date_of_birth = acq_subject_details.get("date_of_birth", None)
+            year_of_birth = acq_subject_details.get("year_of_birth", None)
+            age = None
+            if acquisition_start and (date_of_birth or year_of_birth):
+                try:
+                    acq_date = pd.to_datetime(acquisition_start)
+                    if date_of_birth:
+                        dob = pd.to_datetime(date_of_birth)
+                    else:
+                        dob = pd.Timestamp(int(year_of_birth), 1, 1)
+                    age = (acq_date - dob).days
+                except Exception:
+                    age = None
+
+            flat_record = {
+                "_id": record["_id"],
+                "_last_modified": record.get("_last_modified", None),
+                "modalities": modality_abbreviations,
+                "project_name": record.get("data_description", {}).get("project_name", None),
+                "data_level": record.get("data_description", {}).get("data_level", None),
+                "subject_id": record.get("subject", {}).get("subject_id", None),
+                "acquisition_start_time": record.get("acquisition", {}).get("acquisition_start_time", None),
+                "acquisition_end_time": record.get("acquisition", {}).get("acquisition_end_time", None),
+                "code_ocean": code_ocean,
+                "process_date": process_date,
+                "genotype": record.get("subject", {}).get("subject_details", {}).get("genotype", None),
+                "age": age,
+                "acquisition_type": record.get("acquisition", {}).get("acquisition_type", None),
+                "location": record.get("location", None),
+                "name": record.get("name", None),
+                "experimenters": [
+                    e if isinstance(e, str) else e.get("name", "")
+                    for e in (record.get("acquisition", {}).get("experimenters", []) or [])
+                ],
+                "experimenters_normalized": normalize_experimenters(
+                    [
+                        e if isinstance(e, str) else e.get("name", "")
+                        for e in (record.get("acquisition", {}).get("experimenters", []) or [])
+                    ]
+                ),
+                "instrument_id": record.get("acquisition", {}).get("instrument_id", None),
+                "instrument_id_normalized": normalize_instrument_id(
+                    record.get("acquisition", {}).get("instrument_id", None)
+                ),
+                "investigators": [
+                    i.get("name", "") for i in (record.get("data_description", {}).get("investigators", []) or [])
+                ],
+                "investigators_normalized": normalize_experimenters(
+                    [i.get("name", "") for i in (record.get("data_description", {}).get("investigators", []) or [])]
+                ),
+            }
+            records.append(flat_record)
+
+        # Combine new records with the old df and store in cache
+        new_df = pd.DataFrame(records)
+        df = pd.concat([df[~df["_id"].isin(keep_ids)], new_df], ignore_index=True)
+
+        def _iter_names(cell):
+            """Helper to iterate over names in a cell that may be a list or a single string."""
+            if hasattr(cell, "__iter__") and not isinstance(cell, str):
+                return list(cell)
+            return []
+
+        all_names = [
+            name
+            for col in ("experimenters_normalized", "investigators_normalized")
+            for cell in df[col]
+            for name in _iter_names(cell)
+        ]
+        first_name_map = build_first_name_map(list(dict.fromkeys(all_names)))
+        if first_name_map:
+            df["experimenters_normalized"] = df["experimenters_normalized"].apply(
+                lambda x: apply_first_name_map(_iter_names(x), first_name_map)
+            )
+            df["investigators_normalized"] = df["investigators_normalized"].apply(
+                lambda x: apply_first_name_map(_iter_names(x), first_name_map)
+            )
+
+        registry.BACKEND.write(registry.NAMES["basics"], df)
+
+    return df
+
+
+def asset_basics_columns() -> list[Column]:
+    """Return asset basics cache table column definitions."""
+    return [
+        Column(name="_id", description="DocDB record ID for the asset"),
+        Column(name="_last_modified", description="DocDB last modified timestamp for the asset record"),
+        Column(name="modalities", description="Modalities present in the asset as a list of abbreviations"),
+        Column(name="project_name", description="Project name associated with the asset"),
+        Column(name="data_level", description="Data level of the asset (e.g. raw, derived)"),
+        Column(name="subject_id", description="Subject ID"),
+        Column(name="acquisition_start_time", description="Acquisition start time in ISO format"),
+        Column(name="acquisition_end_time", description="Acquisition end time in ISO format"),
+        Column(name="code_ocean", description="Code Ocean asset ID if available"),
+        Column(name="process_date", description="Date of latest processing in YYYY-MM-DD format"),
+        Column(name="genotype", description="Genotype information for the subject if available"),
+        Column(
+            name="age",
+            description="Age of the subject in days at time of acquisition, derived from date_of_birth or year_of_birth",
+        ),
+        Column(name="acquisition_type", description="Acquisition type (e.g. multiplane-2photon)"),
+        Column(name="location", description="Location of the asset in S3"),
+        Column(name="name", description="Asset name"),
+        Column(name="experimenters", description="Acquisition experimenters as a list of raw names"),
+        Column(
+            name="experimenters_normalized",
+            description="Normalized, deduplicated list of experimenter display names in original order",
+        ),
+        Column(name="instrument_id", description="Instrument ID used for the acquisition"),
+        Column(
+            name="instrument_id_normalized", description="Normalized short instrument name derived from instrument_id"
+        ),
+        Column(name="investigators", description="Investigators from data_description as a list of names"),
+        Column(
+            name="investigators_normalized",
+            description="Normalized, deduplicated list of investigator display names in original order",
+        ),
+    ]