feat: allow creation and modification of class based calibrations

- Added router functionality for validation and standardization of class based calibration files.
- Added lib functionality for creation/modification of class based calibrations.
- Invoked lib functionality from routers to allow client creation/modification of class based calibrations.
- Introduced a new CSV file `calibration_classes.csv` containing variant URNs and their corresponding class names.
- Implemented tests for creating and updating score calibrations using class-based classifications.
- Enhanced existing test suite with parameterized tests to validate score calibration creation and modification.
- Ensured that the response includes correct functional classifications and variant counts.

Author: bencap

src/mavedb/lib/score_calibrations.py

@@ -1100,7 +1100,7 @@ def bulk_create_urns(n, score_set, reset_counter=False) -> list[str]:
     return child_urns
 
 
-def csv_data_to_df(file_data: BinaryIO) -> pd.DataFrame:
+def csv_data_to_df(file_data: BinaryIO, induce_hgvs_cols: bool = True) -> pd.DataFrame:
     extra_na_values = list(
         set(
             list(null_values_list)
@@ -1121,9 +1121,10 @@ def csv_data_to_df(file_data: BinaryIO) -> pd.DataFrame:
         dtype={**{col: str for col in HGVSColumns.options()}, "scores": float},
     )
 
-    for c in HGVSColumns.options():
-        if c not in ingested_df.columns:
-            ingested_df[c] = np.NaN
+    if induce_hgvs_cols:
+        for c in HGVSColumns.options():
+            if c not in ingested_df.columns:
+                ingested_df[c] = np.NaN
 
     return ingested_df
 

src/mavedb/lib/score_sets.py

@@ -1,40 +1,55 @@
 import logging
-
-from fastapi import APIRouter, Depends, HTTPException, Query
 from typing import Optional
+
+from fastapi import APIRouter, Depends, File, HTTPException, Query, UploadFile
 from sqlalchemy.orm import Session
 
 from mavedb import deps
+from mavedb.lib.authentication import UserData, get_current_user
+from mavedb.lib.authorization import require_current_user
+from mavedb.lib.flexible_model_loader import json_or_form_loader
 from mavedb.lib.logging import LoggedRoute
 from mavedb.lib.logging.context import (
     logging_context,
     save_to_logging_context,
 )
-from mavedb.lib.authentication import get_current_user, UserData
-from mavedb.lib.authorization import require_current_user
 from mavedb.lib.permissions import Action, assert_permission, has_permission
 from mavedb.lib.score_calibrations import (
     create_score_calibration_in_score_set,
-    modify_score_calibration,
     delete_score_calibration,
     demote_score_calibration_from_primary,
+    modify_score_calibration,
     promote_score_calibration_to_primary,
     publish_score_calibration,
+    variant_classification_df_to_dict,
 )
+from mavedb.lib.score_sets import csv_data_to_df
+from mavedb.lib.validation.constants.general import calibration_class_column_name, calibration_variant_column_name
+from mavedb.lib.validation.dataframe.calibration import validate_and_standardize_calibration_classes_dataframe
 from mavedb.models.score_calibration import ScoreCalibration
 from mavedb.routers.score_sets import fetch_score_set_by_urn
 from mavedb.view_models import score_calibration
 
-
 logger = logging.getLogger(__name__)
 
 router = APIRouter(
     prefix="/api/v1/score-calibrations",
-    tags=["score-calibrations"],
+    tags=["Score Calibrations"],
     responses={404: {"description": "Not found"}},
     route_class=LoggedRoute,
 )
 
+# Create dependency loaders for flexible JSON/form parsing
+calibration_create_loader = json_or_form_loader(
+    score_calibration.ScoreCalibrationCreate,
+    field_name="calibration_json",
+)
+
+calibration_modify_loader = json_or_form_loader(
+    score_calibration.ScoreCalibrationModify,
+    field_name="calibration_json",
+)
+
 
 @router.get(
     "/{urn}",
@@ -136,31 +151,126 @@ async def get_primary_score_calibrations_for_score_set(
 @router.post(
     "/",
     response_model=score_calibration.ScoreCalibrationWithScoreSetUrn,
-    responses={404: {}},
+    responses={404: {}, 422: {"description": "Validation Error"}},
+    openapi_extra={
+        "requestBody": {
+            "content": {
+                "application/json": {
+                    "schema": {"$ref": "#/components/schemas/ScoreCalibrationCreate"},
+                },
+                "multipart/form-data": {
+                    "schema": {
+                        "type": "object",
+                        "properties": {
+                            "calibration_json": {
+                                "type": "string",
+                                "description": "JSON string containing the calibration data",
+                                "example": '{"score_set_urn":"urn:mavedb:0000000X-X-X","title":"My Calibration","description":"Functional score calibration","baseline_score":1.0}',
+                            },
+                            "classes_file": {
+                                "type": "string",
+                                "format": "binary",
+                                "description": "CSV file containing variant classifications",
+                            },
+                        },
+                    }
+                },
+            },
+            "description": "Score calibration data. Can be sent as JSON body or multipart form data",
+        }
+    },
 )
 async def create_score_calibration_route(
     *,
-    calibration: score_calibration.ScoreCalibrationCreate,
+    calibration: score_calibration.ScoreCalibrationCreate = Depends(calibration_create_loader),
+    classes_file: Optional[UploadFile] = File(
+        None,
+        description=f"CSV file containing variant classifications. This file must contain two columns: '{calibration_variant_column_name}' and '{calibration_class_column_name}'.",
+    ),
     db: Session = Depends(deps.get_db),
     user_data: UserData = Depends(require_current_user),
 ) -> ScoreCalibration:
     """
     Create a new score calibration.
 
-    The score set URN must be provided to associate the calibration with an existing score set.
-    The user must have write permission on the associated score set.
+    This endpoint supports two different request formats to accommodate various client needs:
+
+    ## Method 1: JSON Request Body (application/json)
+    Send calibration data as a standard JSON request body. This method is ideal for 
+    creating calibrations without file uploads.
+
+    **Content-Type**: `application/json`
+
+    **Example**:
+    ```json
+    {
+        "score_set_urn": "urn:mavedb:0000000X-X-X",
+        "title": "My Calibration",
+        "description": "Functional score calibration",
+        "baseline_score": 1.0
+    }
+    ```
+
+    ## Method 2: Multipart Form Data (multipart/form-data)
+    Send calibration data as JSON in a form field, optionally with file uploads.
+    This method is required when uploading classification files.
+
+    **Content-Type**: `multipart/form-data`
+
+    **Form Fields**:
+    - `calibration_json` (string, required): JSON string containing the calibration data
+    - `classes_file` (file, optional): CSV file containing variant classifications
+
+    **Example**:
+    ```bash
+    curl -X POST "/api/v1/score-calibrations/" \\
+         -H "Authorization: Bearer your-token" \\
+         -F 'calibration_json={"score_set_urn":"urn:mavedb:0000000X-X-X","title":"My Calibration","description":"Functional score calibration","baseline_score":"1.0"}' \\
+         -F 'classes_file=@variant_classes.csv'
+    ```
+
+    ## Requirements
+    - The score set URN must be provided to associate the calibration with an existing score set
+    - User must have write permission on the associated score set
+    - If uploading a classes_file, it must be a valid CSV with variant classification data
+
+    ## File Upload Details
+    The `classes_file` parameter accepts CSV files containing variant classification data.
+    The file should have appropriate headers and contain columns for variant urns and class names.
+
+    ## Response
+    Returns the created score calibration with its generated URN and associated score set information.
     """
     if not calibration.score_set_urn:
         raise HTTPException(status_code=422, detail="score_set_urn must be provided to create a score calibration.")
 
     save_to_logging_context({"requested_resource": calibration.score_set_urn, "resource_property": "calibrations"})
 
     score_set = await fetch_score_set_by_urn(db, calibration.score_set_urn, user_data, None, False)
+    if not score_set:
+        logger.debug("The requested score set does not exist", extra=logging_context())
+        raise HTTPException(status_code=404, detail="The requested score set does not exist")
+
     # TODO#539: Allow any authenticated user to upload a score calibration for a score set, not just those with
     #           permission to update the score set itself.
     assert_permission(user_data, score_set, Action.UPDATE)
 
-    created_calibration = await create_score_calibration_in_score_set(db, calibration, user_data.user)
+    if classes_file:
+        try:
+            classes_df = csv_data_to_df(classes_file.file, induce_hgvs_cols=False)
+        except UnicodeDecodeError as e:
+            raise HTTPException(
+                status_code=400, detail=f"Error decoding file: {e}. Ensure the file has correct values."
+            )
+
+        standardized_classes_df = validate_and_standardize_calibration_classes_dataframe(
+            db, score_set, calibration, classes_df
+        )
+        variant_classes = variant_classification_df_to_dict(standardized_classes_df)
+
+    created_calibration = await create_score_calibration_in_score_set(
+        db, calibration, user_data.user, variant_classes if classes_file else None
+    )
 
     db.commit()
     db.refresh(created_calibration)
@@ -171,23 +281,108 @@ async def create_score_calibration_route(
 @router.put(
     "/{urn}",
     response_model=score_calibration.ScoreCalibrationWithScoreSetUrn,
-    responses={404: {}},
+    responses={404: {}, 422: {"description": "Validation Error"}},
+    openapi_extra={
+        "requestBody": {
+            "content": {
+                "application/json": {
+                    "schema": {"$ref": "#/components/schemas/ScoreCalibrationModify"},
+                },
+                "multipart/form-data": {
+                    "schema": {
+                        "type": "object",
+                        "properties": {
+                            "calibration_json": {
+                                "type": "string",
+                                "description": "JSON string containing the calibration update data",
+                                "example": '{"title":"Updated Calibration","description":"Updated description","baseline_score":2.0}',
+                            },
+                            "classes_file": {
+                                "type": "string",
+                                "format": "binary",
+                                "description": "CSV file containing updated variant classifications",
+                            },
+                        },
+                    }
+                },
+            },
+            "description": "Score calibration update data. Can be sent as JSON body or multipart form data",
+        }
+    },
 )
 async def modify_score_calibration_route(
     *,
     urn: str,
-    calibration_update: score_calibration.ScoreCalibrationModify,
+    calibration_update: score_calibration.ScoreCalibrationModify = Depends(calibration_modify_loader),
+    classes_file: Optional[UploadFile] = File(
+        None,
+        description=f"CSV file containing variant classifications. This file must contain two columns: '{calibration_variant_column_name}' and '{calibration_class_column_name}'.",
+    ),
     db: Session = Depends(deps.get_db),
     user_data: UserData = Depends(require_current_user),
 ) -> ScoreCalibration:
     """
     Modify an existing score calibration by its URN.
+
+    This endpoint supports two different request formats to accommodate various client needs:
+
+    ## Method 1: JSON Request Body (application/json)
+    Send calibration update data as a standard JSON request body. This method is ideal for 
+    modifying calibrations without file uploads.
+
+    **Content-Type**: `application/json`
+
+    **Example**:
+    ```json
+    {
+        "score_set_urn": "urn:mavedb:0000000X-X-X",
+        "title": "Updated Calibration Title",
+        "description": "Updated functional score calibration",
+        "baseline_score": 1.0
+    }
+    ```
+
+    ## Method 2: Multipart Form Data (multipart/form-data)
+    Send calibration update data as JSON in a form field, optionally with file uploads.
+    This method is required when uploading new classification files.
+
+    **Content-Type**: `multipart/form-data`
+
+    **Form Fields**:
+    - `calibration_json` (string, required): JSON string containing the calibration update data
+    - `classes_file` (file, optional): CSV file containing updated variant classifications
+
+    **Example**:
+    ```bash
+    curl -X PUT "/api/v1/score-calibrations/{urn}" \\
+         -H "Authorization: Bearer your-token" \\
+         -F 'calibration_json={"score_set_urn":"urn:mavedb:0000000X-X-X","title":"My Calibration","description":"Functional score calibration","baseline_score":"1.0"}' \\
+         -F 'classes_file=@updated_variant_classes.csv'
+    ```
+
+    ## Requirements
+    - User must have update permission on the calibration
+    - If changing the score_set_urn, user must have permission on the new score set
+    - All fields in the update are optional - only provided fields will be modified
+
+    ## File Upload Details
+    The `classes_file` parameter accepts CSV files containing updated variant classification data.
+    If provided, this will replace the existing classification data for the calibration.
+    The file should have appropriate headers and follow the expected format for variant
+    classifications within the associated score set.
+
+    ## Response
+    Returns the updated score calibration with all modifications applied and any new
+    classification data from the uploaded file.
     """
     save_to_logging_context({"requested_resource": urn})
 
     # If the user supplies a new score_set_urn, validate it exists and the user has permission to use it.
     if calibration_update.score_set_urn is not None:
         score_set = await fetch_score_set_by_urn(db, calibration_update.score_set_urn, user_data, None, False)
+        if not score_set:
+            logger.debug("The requested score set does not exist", extra=logging_context())
+            raise HTTPException(status_code=404, detail="The requested score set does not exist")
 
         # TODO#539: Allow any authenticated user to upload a score calibration for a score set, not just those with
         #           permission to update the score set itself.
@@ -200,7 +395,22 @@ async def modify_score_calibration_route(
 
     assert_permission(user_data, item, Action.UPDATE)
 
-    updated_calibration = await modify_score_calibration(db, item, calibration_update, user_data.user)
+    if classes_file:
+        try:
+            classes_df = csv_data_to_df(classes_file.file, induce_hgvs_cols=False)
+        except UnicodeDecodeError as e:
+            raise HTTPException(
+                status_code=400, detail=f"Error decoding file: {e}. Ensure the file has correct values."
+            )
+
+        standardized_classes_df = validate_and_standardize_calibration_classes_dataframe(
+            db, score_set, calibration_update, classes_df
+        )
+        variant_classes = variant_classification_df_to_dict(standardized_classes_df)
+
+    updated_calibration = await modify_score_calibration(
+        db, item, calibration_update, user_data.user, variant_classes if classes_file else None
+    )
 
     db.commit()
     db.refresh(updated_calibration)