nci-cidc-api-modules 1.2.16__py3-none-any.whl → 1.2.25__py3-none-any.whl

cidc_api/models/pydantic/stage2/specimen.py

@@ -0,0 +1,211 @@
+from datetime import datetime
+
+from .base import Base
+from cidc_api.models.types import (
+    UberonAnatomicalTerm,
+    ICDO3MorphologicalCode,
+    SpecimenType,
+    SpecimenDescription,
+    TumorType,
+    CollectionProcedure,
+    FixationStabilizationType,
+    PrimaryContainerType,
+    VolumeUnits,
+    ProcessedType,
+    ConcentrationUnits,
+    DerivativeType,
+    PBMCRestingPeriodUsed,
+    MaterialUnits,
+    MaterialStorageCondition,
+    QCCondition,
+    ReplacementRequested,
+    ResidualUse,
+    DiagnosisVerification,
+    AssayType,
+)
+
+
+class Specimen(Base):
+    __data_category__ = "specimen"
+    __cardinality__ = "many"
+
+    # The unique internal identifier for the specimen record
+    specimen_id: int | None = None
+
+    # 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
+
+    # 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.
+    cimac_id: str
+
+    # The external identifier for the pathology report
+    surgical_pathology_report_id: str | None = None
+
+    # The external identifier for the clinical report
+    clinical_report_id: str | None = None
+
+    # The unique identifier for the specimen from which this specimen was derived
+    parent_specimen_id: str | None = None
+
+    # The unique identifier for the specimen after undergoing processing
+    processed_specimen_id: str | None = None
+
+    # The location within the body from which a specimen was originally obtained as captured in the Uberon anatomical term.
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=12083894%20and%20ver_nr=1
+    organ_site_of_collection: UberonAnatomicalTerm | None = None
+
+    # ICD-O-3 code for histology and behavior. e.g. 9665/3"
+    # CDE: TBD
+    histology_behavior: ICDO3MorphologicalCode | None = None
+
+    # Histology description. e.g. Hodgkin lymphoma, nod. scler., grade 1",
+    histology_behavior_description: str | None = None
+
+    # 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
+
+    # The type of the specimen
+    specimen_type: SpecimenType | None = None
+
+    # The type of the specimen, if not captured by specimen_type
+    specimen_type_other: str | None = None
+
+    # A general description of the specimen
+    specimen_description: SpecimenDescription | None = None
+
+    # The type of the tumor present in the specimen
+    tumor_type: TumorType | None = None
+
+    # Description of the procedure used to collect the specimen from the participant
+    collection_procedure: CollectionProcedure | None = None
+
+    # Description of the procedure used to collect the specimen from the participant, if not captured by collection_procedure
+    collection_procedure_other: str | None = None
+
+    # The biopsy core number from which the sample was taken.
+    core_number: str | None = None
+
+    # Type of specimen fixation or stabilization that was employed by the site directly after collection.
+    fixation_stabilization_type: FixationStabilizationType | None = None
+
+    # The type of container in which the specimen was shipped
+    primary_container_type: PrimaryContainerType | None = None
+
+    # The type of container in which the specimen was shipped, if not captured by primary_container_type
+    primary_container_type_other: str | None = None
+
+    # Volume of the specimen
+    volume: float | None = None
+
+    # The unit of measure of the volume of the specimen
+    volume_units: VolumeUnits | None = None
+
+    # The type of processing that was performed on the collected specimen by the biobank
+    processed_type: ProcessedType | None = None
+
+    # The volume of the specimen after being processed by the biobank
+    processed_volume: float | None = None
+
+    # The unit of measure of the volume of the specimen after being processed by the biobank
+    processed_volume_units: VolumeUnits | None = None
+
+    # The concentration of the sample after being processed by the biobank
+    processed_concentration: float | None = None
+
+    # The unit of measure of the concentration of the sample after being processed by the biobank
+    processed_concentration_units: ConcentrationUnits | None = None
+
+    # The quantity of the sample after being processed by the biobank
+    processed_quantity: float | None = None
+
+    # The type of the sample derivative
+    derivative_type: DerivativeType | None = None
+
+    # The volume of the sample derivative
+    derivative_volume: float | None = None
+
+    # The unit of measure of the volume of the sample derivative
+    derivative_volume_units: VolumeUnits | None = None
+
+    # The concentration of the sample derivative
+    derivative_concentration: float | None = None
+
+    # The unit of measure of the concentration of the sample derivative
+    derivative_concentration_units: ConcentrationUnits | None = None
+
+    # Score the percentage of tumor (including tumor bed) tissue area of the slide (e.g. vs non-malignant or normal tissue) (0-100)
+    tumor_tissue_total_area_percentage: float | None = None
+
+    # Score the percentage of viable tumor cells comprising the tumor bed area
+    viable_tumor_area_percentage: float | None = None
+
+    # Score the evaluation of stromal elements (this indicates the % area of tumor bed occupied by non-tumor cells,
+    # including inflammatory cells [lymphocytes, histiocytes, etc], endothelial cells, fibroblasts, etc)
+    viable_stroma_area_percentage: float | None = None
+
+    # Score the percentage area of necrosis
+    necrosis_area_percentage: float | None = None
+
+    # Score the percentage area of Fibrosis
+    fibrosis_area_percentage: float | None = None
+
+    # Provides a DNA Integrity Number as an indication of extraction quality (values of 1-10)
+    din: float | None = None
+
+    # Provides an absorbance percentage ratio indicating purity of DNA (values of 0 to 2)
+    a260_a280: float | None = None
+
+    # Provides an absorbance percentage ratio indicating presence of contaminants (values of 0 to 3)
+    a260_a230: float | None = None
+
+    # Receiving site determines the percent recovered cells that are viable after thawing.
+    pbmc_viability: float | None = None
+
+    # Receiving site determines number for PBMCs per vial recovered upon receipt.
+    pbmc_recovery: float | None = None
+
+    # Receiving site indicates if a resting period was used after PBMC recovery.
+    pbmc_resting_period_used: PBMCRestingPeriodUsed | None = None
+
+    # Receiving site indicates how much material was used for assay purposes.
+    material_used: float | None = None
+
+    # Unit of measure for the amount of material used
+    material_used_units: MaterialUnits | None = None
+
+    # Receiving site indicates how much material remains after assay use.
+    material_remaining: float | None = None
+
+    # Unit of measure for the amount of material remaining.
+    material_remaining_units: MaterialUnits | None = None
+
+    # Storage condition of the material once it was received.
+    material_storage_condition: MaterialStorageCondition | None = None
+
+    # Final status of sample after QC and pathology review.
+    qc_condition: QCCondition | None = None
+
+    # Indication if sample replacement is/was requested.
+    replacement_requested: ReplacementRequested | None = None
+
+    # Indication if sample was sent to another location or returned back to biorepository.
+    residual_use: ResidualUse | None = None
+
+    # Additional comments on sample testing
+    comments: str | None = None
+
+    # Indicates whether the local pathology review was consistent with the diagnostic pathology report.
+    diagnosis_verification: DiagnosisVerification | None = None
+
+    # The assay that this sample is expected to be used as input for.
+    intended_assay: AssayType | None = None
+
+    # The datetime that CIDC ingested the sample/manifest
+    date_ingested: datetime | None = None
+
+    # Days from enrollment date to date specimen was collected.
+    days_to_specimen_collection: int | None = None

cidc_api/models/pydantic/stage2/stem_cell_transplant.py

@@ -0,0 +1,35 @@
+from pydantic import NonNegativeInt
+from .base import Base
+from cidc_api.models.types import (
+    StemCellDonorType,
+    AllogeneicDonorType,
+    StemCellSource,
+    ConditioningRegimenType,
+)
+
+
+class StemCellTransplant(Base):
+    __data_category__ = "stem_cell_transplant"
+    __cardinality__ = "many"
+
+    # The unique internal identifier for the stem cell transplant record
+    stem_cell_transplant_id: int | None = None
+
+    # The unique internal identifier for the associated Treatment record
+    treatment_id: int | None = None
+
+    # Indicates the stem cell donor type.
+    stem_cell_donor_type: StemCellDonorType
+
+    # If "stem_cell_donor_type" is "Allogeneic", specifies the relationship and
+    # compatibility of the donor relative to the receipient
+    allogeneic_donor_type: AllogeneicDonorType | None = None
+
+    # Source of the stem cells used for transplant.
+    stem_cells_source: StemCellSource
+
+    # Days from the enrollment date to the date of the stem cell transplant.
+    days_to_transplant: NonNegativeInt
+
+    # Specifies what type of conditioning regimen was used for the stem cell transplant if applicable.
+    conditioning_regimen_type: ConditioningRegimenType | None = None

cidc_api/models/pydantic/stage2/surgery.py

@@ -0,0 +1,49 @@
+from typing import Self
+
+from pydantic import NonNegativeInt, model_validator
+
+from .base import Base
+from cidc_api.models.types import SurgicalProcedure, UberonAnatomicalTerm, YNU
+
+
+class Surgery(Base):
+    __data_category__ = "surgery"
+    __cardinality__ = "many"
+
+    # The unique internal identifier for the surgery record
+    surgery_id: int | None = None
+
+    # The unique internal identifier for the associated treatment record
+    treatment_id: int | None = None
+
+    # The term that describes the kind of surgical procedure administered.
+    procedure: SurgicalProcedure
+
+    # The name of surgical procedure if the value provided for procedure is "Other, specify".
+    procedure_other: str | None = None
+
+    # Number of days from enrollment date to surgical procedure date.
+    days_to_procedure: NonNegativeInt
+
+    # The Uberon identifier for the location within the body targeted by a procedure that
+    # is intended to alter or stop a pathologic process.
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=14980609%20and%20ver_nr=1
+    anatomical_location: UberonAnatomicalTerm
+
+    # An indication as to whether the surgical procedure in question was performed with therapeutic intent.
+    therapeutic: YNU
+
+    # A narrative description of any significant findings observed during the surgical procedure in question.
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=14918773%20and%20ver_nr=1
+    findings: str | None = None
+
+    # A textual description of evidence for remaining tumor following primary treatment that is only
+    # apparent using highly sensitive techniques.
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=13362284%20and%20ver_nr=1
+    extent_of_residual_disease: str | None = None
+
+    @model_validator(mode="after")
+    def validate_procedure_other_cr(self) -> Self:
+        if self.procedure == "Other, specify" and not self.procedure_other:
+            raise ValueError('If procedure is "Other, specify", please provide procedure_other.')
+        return self

cidc_api/models/pydantic/stage2/therapy_agent_dose.py

@@ -0,0 +1,67 @@
+from typing import Self
+
+from pydantic import NonNegativeInt, NonNegativeFloat, PositiveFloat, model_validator
+
+from .base import Base
+from cidc_api.models.types import YNU, TherapyAgentDoseUnits
+
+
+class TherapyAgentDose(Base):
+    __data_category__ = "therapy_agent_dose"
+    __cardinality__ = "many"
+
+    # The unique internal identifier for the therapy agent dose record
+    therapy_agent_dose_id: int | None = None
+
+    # The unique internal identifier for the associated treatment record
+    treatment_id: int | None = None
+
+    # A numeric identifier used to indicate a specific course or cycle of treatment.
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=16391085%20and%20ver_nr=1
+    course_number: str | None = None
+
+    # The full generic name of the therapeutic agent, if available, as captured in the Pharmacological
+    # Substance (C1909) branch of the National Cancer Institute Thesaurus (NCIt).
+    therapy_agent_name: str
+
+    # Number of days from the enrollment date to the start date of the therapy dose.
+    days_to_start: NonNegativeInt
+
+    # Number of days from enrollment date to the end date of the therapy dose.
+    days_to_end: NonNegativeInt
+
+    # Number of individual doses the patient received of the therapy agent.
+    number_of_doses: NonNegativeInt
+
+    # The amount that represents the dose of the therapy agent received by the participant.
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=2182728%20and%20ver_nr=3
+    received_dose: NonNegativeFloat
+
+    # Unit of measure for the dose of the agent received by the participant.
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=2321160%20and%20ver_nr=4
+    received_dose_units: TherapyAgentDoseUnits
+
+    # The amount that represents the planned dose of the therapy agent to be received by the participant.
+    planned_dose: PositiveFloat | None = None
+
+    # Unit of measure for the planned dose of the agent to be received by the participant.
+    # TODO: This CDE will probably be 2321160 but needs to be finalized with Janice
+    planned_dose_units: TherapyAgentDoseUnits | None = None
+
+    # Indicates if the therapy agent dose was changed, missed, or delayed.
+    dose_changes_delays: YNU
+
+    # Description of the dose changes, misses, or delays.
+    changes_delays_description: str | None = None
+
+    @model_validator(mode="after")
+    def validate_changes_delays_description_cr(self) -> Self:
+        if self.dose_changes_delays == "Yes" and not self.changes_delays_description:
+            raise ValueError('If dose_changes_delays is "Yes", please provide changes_delays_description.')
+        return self
+
+    @model_validator(mode="after")
+    def validate_planned_dose_units_cr(self) -> Self:
+        if self.planned_dose and not self.planned_dose_units:
+            raise ValueError("If planned_dose is provided, please provide planned_dose_units.")
+        return self

cidc_api/models/pydantic/stage2/treatment.py

@@ -0,0 +1,50 @@
+from typing import Self
+
+from pydantic import model_validator
+
+from .base import Base
+from cidc_api.models.types import YNU, OffTreatmentReason
+
+
+class Treatment(Base):
+    __data_category__ = "treatment"
+    __cardinality__ = "many"
+
+    # The unique internal identifier for the Treatment record
+    treatment_id: int | None = None
+
+    # The unique internal identifier for the associated Participant record
+    participant_id: int | None = None
+
+    # The unique internal identifier for the associated Arm record
+    arm_id: int | None = None
+
+    # The unique internal identifier for the associated Cohort record
+    cohort_id: int | None = None
+
+    # A unique identifier used to describe a distinct, specific intervention or
+    # treatment that a group or subgroup of participants in a clinical trial receives.
+    treatment_description: str
+
+    # Indicates if the participant has stopped receiving this particular treatment at
+    # the time of data submission.
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=16391087%20and%20ver_nr=1
+    off_treatment: YNU
+
+    # An explanation describing why an individual is no longer receiving this particular treatment.
+    off_treatment_reason: OffTreatmentReason | None = None
+
+    # If "Other" is selected for "off_treatment_reason", provide a description of the reason.
+    off_treatment_reason_other: str | None = None
+
+    @model_validator(mode="after")
+    def validate_off_treatment_reason_cr(self) -> Self:
+        if self.off_treatment == "Yes" and not self.off_treatment_reason:
+            raise ValueError('If off_treatment is "Yes", please provide off_treatment_reason.')
+        return self
+
+    @model_validator(mode="after")
+    def validate_off_treatment_reason_other_cr(self) -> Self:
+        if self.off_treatment_reason == "Other" and not self.off_treatment_reason_other:
+            raise ValueError('If off_treatment_reason is "Other", please provide off_treatment_reason_other.')
+        return self

cidc_api/models/pydantic/stage2/trial.py

@@ -0,0 +1,85 @@
+from datetime import datetime
+from typing import List
+
+from .base import Base
+from cidc_api.models.types import TrialOrganization, TrialFundingAgency, TrialStatus, AssayType
+
+
+class Trial(Base):
+    __data_category__ = "study"
+    __cardinality__ = None
+
+    # 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
+
+    # The version number of the trial dataset. e.g. "1.0"
+    version: str | None = None
+
+    # ClinicalTrials.gov identifier. e.g. "NCT03731260"
+    # TODO need cde from janice, they will make one
+    nct_id: str | None = None
+
+    # NCI Trial Identifier. e.g. NCI22345
+    # TODO need cde from janice, they will make one
+    nci_id: str | None = None
+
+    # The short name for the trial
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=11459810%20and%20ver_nr=4
+    trial_name: str | None = None
+
+    # The type of clinical trial conducted
+    trial_type: str | None = None
+
+    # The long description of the trial name and purpose. e.g. "BACCI: A Phase II Randomized, Double-Blind,
+    # Placebo-Controlled Study of Capecitabine Bevacizumab plus Atezolizumab versus Capecitabine Bevacizumab
+    # plus Placebo in Patients with Refractory Metastatic Colorectal Cancer"
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=16188024%20and%20ver_nr=1
+    trial_description: str | None = None
+
+    # Name of the primary organization that oversees the clinical trial. e.g. "ECOG-ACRIN", "SWOG"
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=3938773%20and%20ver_nr=2
+    trial_organization: TrialOrganization | None = None
+
+    # The primary organization providing grant funding and supporting the trial.
+    # 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
+
+    # A description of the reasons why this study could provide insight into molecular biomarkers of immunotherapy.
+    justification: str | None = None
+
+    # The official day that study activity began
+    # CDE: https://cadsr.cancer.gov/onedata/dmdirect/NIH/NCI/CO/CDEDD?filter=CDEDD.ITEM_ID=16333702%20and%20ver_nr=1
+    dates_of_conduct_start: datetime
+
+    # The official day that study activity ended
+    # 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
+
+    # The image of the trial data schema
+    schema_file_id: int | None = None
+
+    # The description of the objectives and hypotheses for the proposed biomarkers.
+    biomarker_plan: str | None = None
+
+    # The description of the rules governing data sharing and publications.
+    data_sharing_plan: str | None = None
+
+    # 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