nci-cidc-api-modules 1.2.29__py3-none-any.whl → 1.2.45__py3-none-any.whl

cidc_api/models/pydantic/stage2/response_by_system.py

@@ -1,8 +1,8 @@
 from typing import Self
 
-from pydantic import PositiveInt, model_validator
+from pydantic import PositiveInt, model_validator, NonNegativeInt
 
-from .base import Base
+from cidc_api.models.pydantic.base import Base
 from cidc_api.models.types import ResponseSystem, ResponseSystemVersion, BestOverallResponse, YNUNA
 
 
@@ -26,7 +26,7 @@ class ResponseBySystem(Base):
 
     # The unique internal identifier for the associated participant
     # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=12220014%20and%20ver_nr=1
-    participant_id: int | None = None
+    participant_id: str | None = None
 
     # A standardized method used to evaluate and categorize the participant’s clinical response to treatment based on predefined criteria.
     # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=13381490%20and%20ver_nr=1
@@ -41,6 +41,9 @@ class ResponseBySystem(Base):
     # Days from first response to progression.
     response_duration: PositiveInt | None = None
 
+    # The number of days from the start of the treatment to the first signs of disease progression.
+    duration_of_stable_disease: NonNegativeInt | None = None
+
     # Indicates whether a patient achieved a durable clinical benefit.
     durable_clinical_benefit: bool | None = None
 
@@ -67,8 +70,8 @@ class ResponseBySystem(Base):
     def validate_response_duration_cr(self) -> Self:
         if self.best_overall_response in negative_response_values and self.response_duration:
             raise ValueError(
-                "If best_overall_response does not indicate a positive response, \
-                please leave response_duration blank."
+                "If best_overall_response does not indicate a positive response, "
+                "please leave response_duration blank."
             )
         return self
 
@@ -76,8 +79,8 @@ class ResponseBySystem(Base):
     def validate_days_to_first_response_cr(self) -> Self:
         if self.best_overall_response in negative_response_values and self.days_to_first_response:
             raise ValueError(
-                "If best_overall_response does not indicate a positive response, \
-                please leave days_to_first_response blank."
+                "If best_overall_response does not indicate a positive response, "
+                "please leave days_to_first_response blank."
             )
         return self
 

cidc_api/models/pydantic/stage2/shipment.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 
-from .base import Base
+from cidc_api.models.pydantic.base import Base
 from cidc_api.models.types import AssayPriority, AssayType, Courier, ShipmentCondition, ShipmentQuality
 
 
@@ -12,7 +12,7 @@ class Shipment(Base):
     institution_id: int | None = None
 
     # The unique internal identifier for the associated trial.
-    trial_id: int | None = None
+    trial_id: str | None = None
 
     # The version number of the trial dataset
     version: str | None = None

cidc_api/models/pydantic/stage2/shipment_specimen.py

@@ -1,4 +1,4 @@
-from .base import Base
+from cidc_api.models.pydantic.base import Base
 
 
 class ShipmentSpecimen(Base):

cidc_api/models/pydantic/stage2/specimen.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 
-from .base import Base
+from cidc_api.models.pydantic.base import Base
 from cidc_api.models.types import (
     UberonAnatomicalTerm,
     ICDO3MorphologicalCode,
@@ -26,7 +26,7 @@ from cidc_api.models.types import (
 
 
 class Specimen(Base):
-    __data_category__ = "specimen"
+    # __data_category__ = "specimen"
     __cardinality__ = "many"
 
     # The unique internal identifier for the specimen record
@@ -34,7 +34,7 @@ class Specimen(Base):
 
     # The unique internal identifier for the associated participant
     # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=12220014%20and%20ver_nr=1
-    participant_id: int | None = None
+    participant_id: str | None = None
 
     # The unique specimen identifier assigned by the CIMAC-CIDC Network.
     # Formatted as CTTTPPPSS.AA for trial code TTT, participant PPP, sample SS, and aliquot AA.
@@ -66,7 +66,7 @@ class Specimen(Base):
     # Categorical description of timepoint at which the sample was taken.
     # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=5899851%20and%20ver_nr=1
     # Note: CIDC doesn't conform to this CDE's PVs
-    collection_event_name: str | None = None
+    collection_event_name: str
 
     # The type of the specimen
     specimen_type: SpecimenType | None = None
@@ -208,4 +208,7 @@ class Specimen(Base):
     date_ingested: datetime | None = None
 
     # Days from enrollment date to date specimen was collected.
-    days_to_specimen_collection: int | None = None
+    days_to_specimen_collection: int
+
+    # The location within the body from which a specimen was originally obtained as captured in the Uberon anatomical term.
+    organ_site_of_collection: UberonAnatomicalTerm

cidc_api/models/pydantic/stage2/stem_cell_transplant.py

@@ -1,5 +1,5 @@
 from pydantic import NonNegativeInt
-from .base import Base
+from cidc_api.models.pydantic.base import Base
 from cidc_api.models.types import (
     StemCellDonorType,
     AllogeneicDonorType,
@@ -26,7 +26,7 @@ class StemCellTransplant(Base):
     allogeneic_donor_type: AllogeneicDonorType | None = None
 
     # Source of the stem cells used for transplant.
-    stem_cells_source: StemCellSource
+    stem_cell_source: StemCellSource
 
     # Days from the enrollment date to the date of the stem cell transplant.
     days_to_transplant: NonNegativeInt

cidc_api/models/pydantic/stage2/surgery.py

@@ -2,7 +2,7 @@ from typing import Self
 
 from pydantic import NonNegativeInt, model_validator
 
-from .base import Base
+from cidc_api.models.pydantic.base import Base
 from cidc_api.models.types import SurgicalProcedure, UberonAnatomicalTerm, YNU
 
 

cidc_api/models/pydantic/stage2/therapy_agent_dose.py

@@ -2,7 +2,7 @@ from typing import Self
 
 from pydantic import NonNegativeInt, NonNegativeFloat, PositiveFloat, model_validator
 
-from .base import Base
+from cidc_api.models.pydantic.base import Base
 from cidc_api.models.types import YNU, TherapyAgentDoseUnits
 
 

cidc_api/models/pydantic/stage2/treatment.py

@@ -2,7 +2,7 @@ from typing import Self
 
 from pydantic import model_validator
 
-from .base import Base
+from cidc_api.models.pydantic.base import Base
 from cidc_api.models.types import YNU, OffTreatmentReason
 
 
@@ -14,7 +14,7 @@ class Treatment(Base):
     treatment_id: int | None = None
 
     # The unique internal identifier for the associated Participant record
-    participant_id: int | None = None
+    participant_id: str | None = None
 
     # The unique internal identifier for the associated Arm record
     arm_id: int | None = None

cidc_api/models/pydantic/stage2/trial.py

@@ -1,8 +1,9 @@
 from datetime import datetime
-from typing import List
+from pydantic import BeforeValidator
+from typing import List, Annotated
 
-from .base import Base
-from cidc_api.models.types import TrialOrganization, TrialFundingAgency, TrialStatus, AssayType
+from cidc_api.models.pydantic.base import Base
+from cidc_api.models.types import TrialOrganization, TrialFundingAgency, AssayType, AgeGroup, PrimaryPurposeType
 
 
 class Trial(Base):
@@ -11,11 +12,20 @@ class Trial(Base):
 
     # The unique identifier for the clinical trial. e.g. "GU16-287","BACCI"
     # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=5054234%20and%20ver_nr=1
-    trial_id: str
+    trial_id: str | None = None
 
     # The version number of the trial dataset. e.g. "1.0"
     version: str | None = None
 
+    # A broad textual description of the primary endpoint(s) of the trial.
+    primary_endpoint: str | None = None
+
+    # The identifiable class of the study participant based upon their age.
+    age_group: Annotated[List[AgeGroup], BeforeValidator(Base.split_list)]
+
+    # Clinical and/or molecular characteristics of the cancer(s) in the study population.
+    study_population: str | None = None
+
     # ClinicalTrials.gov identifier. e.g. "NCT03731260"
     # TODO need cde from janice, they will make one
     nct_id: str | None = None
@@ -45,10 +55,6 @@ class Trial(Base):
     # e.g. "Duke University - Duke Cancer Institute LAO"
     grant_or_affiliated_network: TrialFundingAgency | None = None
 
-    # What stage the trial is at in its process.
-    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=15607838%20and%20ver_nr=1
-    trial_status: TrialStatus
-
     # The id of the primary organization responsible for storing biospecimens from this study.
     biobank_institution_id: int | None = None
 
@@ -63,6 +69,10 @@ class Trial(Base):
     # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=16333703%20and%20ver_nr=1
     dates_of_conduct_end: datetime | None = None
 
+    # A classification of the study based upon the primary intent of the study's activities.
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=11160683%20and%20ver_nr=1
+    primary_purpose_type: PrimaryPurposeType
+
     # The image of the trial data schema
     schema_file_id: int | None = None
 
@@ -75,11 +85,5 @@ class Trial(Base):
     # The list of assays that CIDC expects to receive for this trial.
     expected_assays: List[AssayType] = []
 
-    # Is the cancer studying a liquid tumor type?
-    is_liquid_tumor_trial: bool = False
-
     # The dbgap study accession number associated with the trial.
-    dbgap_study_accession: str | None = None
-
-    # The internal version identifier for this specific trial dataset.
-    version: str
+    dbgap_study_accession: str

cidc_api/models/types.py

@@ -20,6 +20,13 @@ from cidc_api.reference.gvhd import is_gvhd_organ
 # As python Enums are rather cumbersome when we only want a list of permissible values for a string, use Literal instead
 
 
+AgeGroup = Literal[
+    "Adolescent and Young Adult",
+    "Adult",
+    "Pediatric",
+]
+
+
 TrialOrganization = Literal[
     "ECOG-ACRIN",
     "SWOG",
@@ -53,10 +60,31 @@ TrialFundingAgency = Literal[
 ]
 
 
-TrialStatus = Literal[
-    "Active Study",
-    "Completed Study",
-    "Provisional Study",
+PrimaryPurposeType = Literal[
+    "Adverse Effect Mitigation Study",
+    "Ancillary Study",
+    "Basic Science  Research ",
+    "Correlative Study",
+    "Cure Study",
+    "Device Feasibility Study",
+    "Diagnosis Study",
+    "Disease Modifying Treatment Study",
+    "Early Detection Study",
+    "Education Training Clinical Study",
+    "Epidemiology  Research ",
+    "Genomics Research",
+    "Health Services Research",
+    "Imaging Research",
+    "Interventional Study",
+    "Observational Study",
+    "Outcomes Research",
+    "Prevention Study",
+    "Proteomic Research",
+    "Rehabilitation Clinical Study ",
+    "Screening Study",
+    "Supportive Care Study",
+    "Transcriptomics Research",
+    "Treatment Study",
 ]
 
 
@@ -85,6 +113,7 @@ AssayType = Literal[
     "snRNA-Seq",
     "Visium",
     "Olink HT",
+    "TCRseq RNA",
 ]
 
 
@@ -217,24 +246,6 @@ FileFormat = Literal[
 ]
 
 
-PrimaryDiagnosisDiseaseGroup = Literal[
-    "Ovarian epithelial cancer",
-    "Esophageal cancer, NOS",
-    "Primary peritoneal carcinoma",
-    "Gastric cancer, NOS",
-    "Fallopian tube carcinoma",
-    "Invasive breast carcinoma",
-    "Small cell lung cancer",
-    "Prostate cancer, NOS",
-    "Non-small cell lung cancer, NOS",
-    "Myeloma, NOS",
-    "Melanoma",
-    "Adenocarcinoma of the gastroesophageal junction",
-    "Acute myeloid leukemia, NOS",
-    "Colorectal cancer, NOS",
-]
-
-
 TumorGrade = Literal[
     "G1 Low Grade",
     "G2 Intermediate Grade",
@@ -255,12 +266,20 @@ CancerStageSystem = Literal[
 ]
 
 
-CancerStageSystemVersionAJCC = Literal["8",]
+CancerStageSystemVersionAJCC = Literal["8th Edition",]
 
-CancerStageSystemVersionRISS = Literal["2"]
+CancerStageSystemVersionRISS = Literal["10.1200/JCO.2015.61.2267"]
 
-
-CancerStageSystemVersionFIGO = Literal["2021"]
+CancerStageSystemVersionFIGO = Literal[
+    "10.1002/ijgo.14923",
+    "10.1002/ijgo.13881",
+    "10.1002/ijgo.13867",
+    "10.1002/ijgo.13865",
+    "10.1002/ijgo.13866",
+    "10.1002/ijgo.13878",
+    "10.1002/ijgo.13877",
+    "10.1002/ijgo.12613",
+]
 
 CancerStageSystemVersion = CancerStageSystemVersionAJCC | CancerStageSystemVersionFIGO | CancerStageSystemVersionRISS
 
@@ -296,7 +315,6 @@ CancerStageAJCC = Literal[
 
 
 CancerStageFIGO = Literal[
-    "value",
     "Stage I",
     "Stage IA",
     "Stage IA1",
@@ -1027,21 +1045,6 @@ GVHDDiagnosisChronicGlobalSeverity = Literal["Mild", "Moderate", "Severe"]
 GVHDOrganChronicScore = Literal["0", "1", "2", "3"]
 
 
-PriorTreatmentType = Literal[
-    "Surgery",
-    "Radiotherapy",
-    "Immunotherapy",
-    "Chemotherapy",
-    "Targeted therapy",
-    "Other therapy",
-    "Radiopharmaceutical",
-    "Stem cell transplant",
-    "Immunosuppressive therapy/GVHD prophylaxis for transplant",
-    "Conditioning therapy",
-    "Post-transplant salvage therapy",
-]
-
-
 ConditioningRegimenType = Literal["Myeloablative", "Reduced-intensity", "Non-myeloablative", "Other"]
 
 StemCellDonorType = Literal["Autologous", "Allogeneic"]

cidc_api/shared/assay_handling.py

@@ -0,0 +1,68 @@
+from datetime import datetime
+from urllib.parse import quote
+
+from werkzeug.exceptions import BadRequest
+
+from cidc_api.models import IngestionJobs
+from . import gcloud_client
+from ..shared.auth import get_current_user
+
+JOB_TYPE_ASSAY = "assay"
+JOB_TYPE_CLINICAL = "clinical"
+ALLOWED_JOB_TYPES = {JOB_TYPE_CLINICAL, JOB_TYPE_ASSAY}
+
+
+def resolve_job_type_and_assay_fields(data: dict) -> tuple[str, str | None, str | None]:
+    """Decide job_type and gather assay_type/batch_id from request JSON."""
+    assay_type = data.get("assay_type")
+    # If job_type is assay or assay_type is present, treat this as an assay job.
+    job_type = data.get("job_type") or (JOB_TYPE_ASSAY if assay_type else JOB_TYPE_CLINICAL)
+
+    if job_type not in ALLOWED_JOB_TYPES:
+        raise BadRequest("Invalid job_type. Allowed values are 'clinical' or 'assay'.")
+
+    if job_type == JOB_TYPE_ASSAY and (not assay_type or not isinstance(assay_type, str)):
+        raise BadRequest("assay_type must be provided for job_type='assay'.")
+
+    assay_type = assay_type.strip() if assay_type else None
+    batch_id = data.get("batch_id").strip() if isinstance(data.get("batch_id"), str) else None
+
+    return job_type, assay_type, batch_id
+
+
+def prepare_assay_job(trial_id: str, assay_type: str, batch_id: str) -> tuple[str, str, str, datetime, int, str]:
+    """
+    Validate assay job uniqueness and generate submission_id, start_date, version, and the trial’s GCS intake path.
+    """
+    if not assay_type:
+        raise BadRequest("assay_type must be provided for job_type='assay'.")
+
+    # Enforce uniqueness of (trial_id, assay_type, batch_id) when batch_id is present.
+    if batch_id:
+        existing_job = IngestionJobs.get_unique_assay_job(trial_id, assay_type, batch_id)
+        if existing_job:
+            raise BadRequest(
+                f"Assay job {existing_job.id} already exists for this exact trial_id/assay_type/batch_id combination."
+            )
+
+    submission_id = IngestionJobs.next_assay_submission_id(trial_id, assay_type)
+    job_status = "INITIAL SUBMISSION"
+    error_status = "Upload Incomplete"  # job starts with 'Incomplete' notifier
+    start_date = datetime.now()
+    version = 1
+
+    # Create or retrieve intake bucket corresponding to the trial
+    intake_bucket = gcloud_client.create_intake_bucket(get_current_user().email, trial_id=trial_id)
+    gcs_path = f"{intake_bucket.name}/{assay_type}/{submission_id}"
+
+    return submission_id, job_status, error_status, start_date, version, gcs_path
+
+
+def get_google_links(intake_path: str) -> tuple[str, str]:
+    """Build the GCS URI and GCS Console URL corresponding to the intake path."""
+    gcs_uri = f"gs://{intake_path}"
+    # Encode path to ensure link opens correctly
+    encoded_path = quote(intake_path)
+    console_url = f"https://console.cloud.google.com/storage/browser/{encoded_path}"
+
+    return gcs_uri, console_url

cidc_api/shared/auth.py

@@ -1,16 +1,14 @@
 from functools import wraps
 from typing import List
 
-from packaging import version
-
 from flask import g, request, current_app as app, Flask
+from packaging import version
 from werkzeug.exceptions import Unauthorized, BadRequest, PreconditionFailed
 
-from ..models import Users, UserSchema
-
 from ..config.logging import get_logger
-
+from ..models import Users, UserSchema
 from ..shared.jose import decode_id_token
+from ..telemetry import trace_
 
 logger = get_logger(__name__)
 
@@ -144,6 +142,7 @@ def get_current_user() -> Users:
 _user_schema = UserSchema()
 
 
+@trace_()
 def authenticate() -> Users:
     id_token = _extract_token()
     token_payload = decode_id_token(id_token)
@@ -172,6 +171,7 @@ def _extract_token() -> str:
 
 
 ### Authorization logic ###
+@trace_()
 def authorize(user: Users, allowed_roles: List[str], resource: str, method: str) -> bool:
     """Check if the current user is authorized to act on the current request's resource.
     Raises Unauthorized

cidc_api/shared/file_handling.py

@@ -10,22 +10,33 @@ from ..config.settings import GOOGLE_CLINICAL_DATA_BUCKET
 from ..models import PreprocessedFiles, TRIAL_APPENDIX_A_CELL_THAT_ENDS_THE_HEADER
 from ..shared.auth import get_current_user
 from ..shared.gcloud_client import upload_file_to_gcs, move_gcs_file
+from ..telemetry import trace_
 
 logger = get_logger(__name__)
 
 
+@trace_()
 def set_current_file(
-    file: FileStorage, file_category: str, gcs_folder: str, session: Session, uploader_email: str, job_id: int = None
+    file: FileStorage,
+    file_category: str,
+    gcs_folder: str,
+    session: Session,
+    uploader_email: str,
+    job_id: int = None,
+    append_timestamp: bool = None,
 ) -> PreprocessedFiles:
     """
     Archives any existing 'current' files for the given category and job,
     then uploads the new file as the latest 'current' version.
     """
     latest_version = PreprocessedFiles.archive_current_files(file_category, job_id=job_id, session=session)
-    latest_file = create_file(file, gcs_folder, file_category, session, uploader_email, job_id, latest_version + 1)
+    latest_file = create_file(
+        file, gcs_folder, file_category, session, uploader_email, job_id, latest_version + 1, append_timestamp
+    )
     return latest_file
 
 
+@trace_()
 def create_file(
     file: FileStorage,
     gcs_folder: str,
@@ -34,11 +45,12 @@ def create_file(
     uploader_email: str,
     job_id: int = None,
     version: int = None,
+    append_timestamp: bool = None,
 ) -> PreprocessedFiles:
     """Upload file to GCS and create corresponding metadata record in the database."""
     status = "pending" if gcs_folder.endswith("pending/") else "current"
-    # only need timestamp for current/versioned files
-    append_timestamp = status == "current"
+    # only need timestamp for current/versioned files, if not specified otherwise
+    append_timestamp = append_timestamp if append_timestamp is not None else (status == "current")
     # create file in GCS
     gcs_file_path = upload_file_to_gcs(file, GOOGLE_CLINICAL_DATA_BUCKET, gcs_folder, append_timestamp=append_timestamp)
     # create corresponding record in db