Welcome to phenopackets-to-fhir’s documentation!¶

Introduction¶

phenopackets-to-fhir is a service to convert derived phenopackets objects to FHIR resources. The service is a part of the ongoing work for CHORD Metadata service. The phenopackets schemas are project-specific adaptations of Phenopackets schema standard.

The package contains:

json schemas for Phenopacket and its elements derived/based on Phenopackets schema standard.
functions to transform phenopackets objects to FHIR resources.
mappings derived from Phenopackets on FHIR Implementation Guide.

The conversion uses Python SMART on FHIR client that provides validation of generated FHIR resources.

Converters¶

converters.resources.age_to_fhir(obj, mapping, field)¶

Generic function to convert Phenopackets Age or AgeRange to FHIR Age.

Parameters

obj – object to which field Age or AgeRange belongs to
mapping – mapping from PHENOPACKETS_ON_FHIR
field – name of the field that stores age

Returns

age extension object

converters.resources.biosample_to_fhir(obj)¶

Converts Biosample to FHIR Specimen.

Parameters: obj – Biosample json
Returns: FHIR Specimen json

converters.resources.check_disease_onset(disease)¶

Phenopackets schema allows age to be represented by ISO8601 string, whereis Pheno-FHIR guide requires it to be represented by CodeableConcept. This function checks how age is represented in data.

Parameters: disease – disease json object
Returns: True/False

converters.resources.codeable_concepts_fields(field_list, profile, obj)¶

Converts a list of fields to FHIR CodeableConcepts and returns a list of extensions.

Parameters

field_list – fields to convert to codeable concepts
profile – name of an object in phenopackets mappings
obj – object to which fields belong to

Returns

list of extensions

converters.resources.disease_to_fhir(obj)¶

Converts Disease to FHIR Condition.

Parameters: obj – Disease json
Returns: FHIR Condition json

converters.resources.fhir_codeable_concept(obj)¶: Generic function to convert object to FHIR CodeableConcept.

converters.resources.fhir_coding_util(obj)¶: Genenric function to convert object to FHIR Coding.

converters.resources.gene_to_fhir(obj)¶

Convert Gene to Observation.component:gene property. GA4GH Phenopackets Implementation Guide provides a link to Genomics Reporting Implementation Guide (STU1) mapping http://hl7.org/fhir/uv/genomics-reporting/StructureDefinition/region-studied .

Parameters: obj – gene json
Returns: Observation.component:gene json

converters.resources.hts_file_to_fhir(obj)¶

Converts HTS file to FHIR DocumentReference.

Parameters: obj – HTS file json
Returns: FHIR DocumentReference json

converters.resources.individual_to_fhir(obj)¶

Converts Individual to FHIR Patient.

Parameters: obj – Individual json
Returns: FHIR Patient json

converters.resources.phenopacket_to_fhir(obj)¶

Converts Phenopacket to FHIR Composition.

Parameters: obj – Phenopacket json
Returns: FHIR Composition json

converters.resources.phenotypic_feature_to_fhir(obj)¶

Converts Phenotypic feature to FHIR Observation.

Parameters: obj – PhenotypicFeature json
Returns: FHIR Observation json

converters.resources.procedure_to_fhir(obj)¶: Converts Procedure to FHIR Specimen collection.

converters.resources.variant_to_fhir(obj)¶

Variant corresponds to Observation.component:variant. GA4GH Phenopackets Implementation Guide provides a link to Genomics Reporting Implementation Guide (STU1) mapping http://hl7.org/fhir/uv/genomics-reporting/STU1/variant.html.

Parameters: obj – Variant json
Returns: Observation.component:variant json

Validation¶

converters.validate.validate_schema(schema, data)¶

Validates the instance against corresponding json schema.

Parameters

schema – the json schema to validate with
data – the instance to validate

Returns

True if the instance is valid, False if not

Raises

ValidationError if the instance is invalid

Mappings¶

HL7 Genomics Mappings¶

# All fixed values provided by Phenopackets on FHIR Mapping guide
# Mappings from http://build.fhir.org/ig/HL7/genomics-reporting/index.html

HL7_GENOMICS_MAPPING = {
    "gene": {
        "url": "http://hl7.org/fhir/uv/genomics-reporting/StructureDefinition/region-studied",
        "geneStudied_Code": {
            "system": "https://loinc.org",
            "id": "48018-6",
            "label": "Gene studied [ID]"
        },
        "geneStudiedValue": {
            "system": "https://www.genenames.org/"
        }
    },
    "variant": {
        "url": "http://hl7.org/fhir/uv/genomics-reporting/StructureDefinition/variant",
        "variantLengthCode": {
            "system": "https://loinc.org",
            "id": "81300-6",
            "label": "Structural variant [Length]"
        }
    }
}

Phenopackets on FHIR Mappings¶

# All fixed values provided by Phenopackets on FHIR Mapping guide

PHENOPACKETS_ON_FHIR_MAPPING = {
    "individual": {
        "title": "Individual",
        "url": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/Individual",
        "age": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/individual-age",
        "karyotypicSex": {
            "url": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/individual-karyotypic-sex",
            "system": "http://ga4gh.org/fhir/phenopackets/CodeSystem/karyotypic-sex"
        },
        "taxonomy": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/individual-taxonomy"
    },
    "phenopacket": {
        "title": "Phenopacket",
        "code": {
            "system": "http://ga4gh.org/fhir/phenopackets/CodeSystem/document-type",
            "code": "phenopacket"
        },
        "url": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/Phenopacket",
        "phenotypicFeatures": {
            "title": "Phenotypic Features",
            "code": {
                "system": "http://ga4gh.org/fhir/phenopackets/CodeSystem/section-type",
                "version": "0.1.0",
                "code": "phenotypic-features",
                "display": "Phenotypic Features"
            }
        },
        "biosamples": {
                "title": "Biosamples",
                "code": {
                    "system": "http://ga4gh.org/fhir/phenopackets/CodeSystem/section-type",
                    "version": "0.1.0",
                    "code": "biosamples",
                    "display": "Biosamples"
                }
            },
        "variants": {
            "title": "Variants",
            "code": {
                "system": "http://ga4gh.org/fhir/phenopackets/CodeSystem/section-type",
                "version": "0.1.0",
                "code": "variants",
                "display": "Variants"
            }
        },
        "diseases": {
            "title": "Diseases",
            "code": {
                "system": "http://ga4gh.org/fhir/phenopackets/CodeSystem/section-type",
                "version": "0.1.0",
                "code": "diseases",
                "display": "Diseases"
            }
        },
        "htsFiles": {
            "title": "HTS Files",
            "code": {
                "system": "http://ga4gh.org/fhir/phenopackets/CodeSystem/section-type",
                "version": "0.1.0",
                "code": "hts-files",
                "display": "HTS Files"
            }
        }
    },
    "biosample": {
        "title": "Biosample",
        "url": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/Biosample",
        "individualAgeAtCollection": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/biosample-individual-age-at-collection",
        "histologicalDiagnosis": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/biosample-histological-diagnosis",
        "tumorProgression": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/biosample-tumor-progression",
        "tumorGrade": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/biosample-tumor-grade",
        "diagnosticMarkers": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/biosample-diagnostic-markers",
        "isControlSample": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/biosample-control"
    },
    "phenotypicFeature": {
        "title": "Phenotypic Feature",
        "url": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/PhenotypicFeature",
        "severity": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/phenotypic-feature-severity",
        "modifier": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/phenotypic-feature-modifier",
        "onset": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/phenotypic-feature-onset",
        "evidence": {
            "url": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/evidence",
            # fixed value
            "evidenceCode": "evidenceCode"
        }
    },
    "externalReference": {
        "url": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/external-reference",
        # fixed values
        "idUrl": "id",
        "descriptionUrl": "description"
    },
    "htsFile": {
        "url": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/HtsFile",
        "genomeAssembly": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/htsfile-genome-assembly",
        # fixed value
        "status": "current",
        "htsFormat": "http://ga4gh.org/fhir/phenopackets/CodeSystem/hts-format"
    },
    "disease": {
        "url": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/Disease",
        "onset": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/disease-onset",
        "disease_stage": "http://ga4gh.org/fhir/phenopackets/StructureDefinition/disease-tumor-stage",
    }
}

Welcome to phenopackets-to-fhir’s documentation!¶

Introduction¶

Converters¶

Validation¶

Mappings¶

HL7 Genomics Mappings¶

Phenopackets on FHIR Mappings¶

Indices and tables¶