Facts
What is a Fact?
A Fact
is metadata attached to an event. Typically a Fact
will allow for distinguishing one event from another for the purpose of classification and analysis. The only limitation is that it must be expressible as a Dhall type. For example, a Fact
may contain other Fact
s. See how to define a new Fact
for details.
Existing Facts
This list specifies the currently available Fact
s. However, the fact-models
package makes it relatively easy to add new Facts.
Biomarker
Information about Biomarkers.
- Dhall
-
< ALK : { biomarker_detail : Text , biomarker_status : Text , biomarker_test_type : Text } | BRAF : { biomarker_detail : Text , biomarker_status : Text , biomarker_test_type : Text } | EGFR : { biomarker_detail : Text , biomarker_status : Text , biomarker_test_type : Text } | KRAS : { biomarker_detail : Text , biomarker_status : Text , biomarker_test_type : Text } | MET : { biomarker_detail : Text , biomarker_status : Text , biomarker_test_type : Text } | NTRK : { biomarker_detail : Text , biomarker_status : Text , biomarker_test_type : Text } | OtherBiomarker : { other_biomarker_detail : Text , other_biomarker_name : Text , other_biomarker_status : Text , other_biomarker_test_type : Text } | PDL1 : { pdl1_detail : Text , pdl1_percent_staining : Text , pdl1_status : Text , pdl1_test_type : Text } | RET : { biomarker_detail : Text , biomarker_status : Text , biomarker_test_type : Text } | ROS1 : { biomarker_detail : Text , biomarker_status : Text , biomarker_test_type : Text } >
- Example JSON
-
{ "contents": { "biomarker_detail": "", "biomarker_status": "Rearrangement positive", "biomarker_test_type": "NGS and RNA sequencing" }, "tag": "ALK" }
BiomarkerOther
This fact represents attributes of a simple biomarker.
- Dhall
-
{ other_biomarker_detail : Text , other_biomarker_name : Text , other_biomarker_status : Text , other_biomarker_test_type : Text }
- Example JSON
-
{ "other_biomarker_detail": "", "other_biomarker_name": "ALK", "other_biomarker_status": "Rearrangement positive", "other_biomarker_test_type": "NGS and RNA sequencing" }
BiomarkerPDL1
This fact represents attributes of the PDL1biomarker.
- Dhall
-
{ pdl1_detail : Text , pdl1_percent_staining : Text , pdl1_status : Text , pdl1_test_type : Text }
- Example JSON
-
{ "pdl1_detail": "", "pdl1_percent_staining": "< 1%", "pdl1_status": "Equivocal", "pdl1_test_type": "RNA sequencing" }
BiomarkerSimple
This fact represents attributes of a simple biomarker.
- Dhall
-
{ biomarker_detail : Text, biomarker_status : Text, biomarker_test_type : Text }
- Example JSON
-
{ "biomarker_detail": "", "biomarker_status": "Rearrangement positive", "biomarker_test_type": "NGS and RNA sequencing" }
Claim
The claim fact is used to capture claim information about an event. This would most commonly be used in insurance claim data.
- Dhall
-
{ claim_type : Optional Text , id : Text , index : Optional Integer , procedure : Optional Text }
- Example JSON
-
{ "claim_type": null, "id": "foo", "index": 7, "procedure": null }
ClaimFact
A collection of facts relevant to an insurance claim.
- Dhall
-
{ claim : { claim_type : Optional Text , id : Text , index : Optional Integer , procedure : Optional Text } , cost : Optional { allowed : Optional Double , category : Optional Text , charge : Optional Double , cost : Optional Double , description : Optional Text , transaction : Optional Text } , provider : Optional { provider_id : Text , provider_type : Optional Text , taxonomy : Optional Text } , service : Optional { place : Optional Text , service_location : < Inpatient | Outpatient > , service_type : Optional Text } }
- Example JSON
-
{ "claim": { "claim_type": null, "id": "foo", "index": 7, "procedure": null }, "cost": { "allowed": 1.2, "category": "expense", "charge": 0.5, "cost": 9, "description": null, "transaction": null }, "provider": { "provider_id": "1104089713", "provider_type": null, "taxonomy": "207RA0001X" }, "service": { "place": "somewhere", "service_location": "Inpatient", "service_type": "something" } }
Code
The code fact captures information about an event’s code, such as an ICD9/10 diagnosis code or NDC medication code.
- Dhall
-
{ code : Text , codebook : < CDT | CVX | HCPCS | ICD10 | ICD9 | LOINC | MedicaidCat | NABSP | NDC | NDC9 | UB92 | USSTATE > }
- Example JSON
-
{ "code": "a", "codebook": "ICD10" }
Codebook
Enumerates the possible codebooks used in the EDM.
- Dhall
-
< CDT | CVX | HCPCS | ICD10 | ICD9 | LOINC | MedicaidCat | NABSP | NDC | NDC9 | UB92 | USSTATE >
- Example JSON
-
"CDT"
Cost
The cost fact is used to capture cost information about a claim.
- Dhall
-
{ allowed : Optional Double , category : Optional Text , charge : Optional Double , cost : Optional Double , description : Optional Text , transaction : Optional Text }
- Example JSON
-
{ "allowed": 1.2, "category": "expense", "charge": 0.5, "cost": 9, "description": null, "transaction": null }
Demographic
The demo fact captures demographic information.
- Dhall
-
{ field : < BirthDate | BirthYear | County | CountyFIPS | Ethnicity | Gender | GeoAdiNatRank | GeoAdiStateRank | GeoPctAmIndian | GeoPctAsian | GeoPctBlack | GeoPctHispanic | GeoPctMutli | GeoPctOther | GeoPctWhite | GeoType | Race | RaceCodes | Region | State | UrbanRural | Zipcode > , info : Text }
- Example JSON
-
{ "field": "BirthYear", "info": "1970" }
Demographic Field
Enumerates the possible demographic fields
- Dhall
-
< BirthDate | BirthYear | County | CountyFIPS | Ethnicity | Gender | GeoAdiNatRank | GeoAdiStateRank | GeoPctAmIndian | GeoPctAsian | GeoPctBlack | GeoPctHispanic | GeoPctMutli | GeoPctOther | GeoPctWhite | GeoType | Race | RaceCodes | Region | State | UrbanRural | Zipcode >
- Example JSON
-
"BirthDate"
DiseaseMilestone
The DiseaseMilestone fact captures information on the type of diagnosis.
- Dhall
-
< Advanced | Initial | MissingDiseaseMilestone | OtherDiseaseMilestone | UnknownDiseaseMilestone >
- Example JSON
-
"Advanced"
ECOG
The ECOG fact captures ECOG values.
- Dhall
-
{ ecog_value : Text }
- Example JSON
-
{ "ecog_value": "1" }
FlatironMedication
Facts about a Flatiron Ordered/Administered Medication.
- Dhall
-
{ cancellation_status : Optional Bool , medication : { common_drug_name : Text , detailed_drug_category : Text , drug_category : Text , drug_name : Text } , medication_milestone : < Administered : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | ExpectedStart : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | Filled : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | MissingMedicationMilestone | Ordered : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | OtherMedicationMilestone : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | Prescribed : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | UnknownMedicationMilestone > , medication_practice : { practice_type : Text } }
- Example JSON
-
{ "cancellation_status": true, "medication": { "common_drug_name": "drug one", "detailed_drug_category": "Lots of drug details", "drug_category": "DrugCat", "drug_name": "DrugOne" }, "medication_milestone": { "contents": { "amount": { "units": "mg", "value": { "contents": 2.3, "tag": "NumberValue" } }, "days_supply": 2, "dose_number": 1, "quantity": 6, "route": "intravenous", "strength": "0.1%" }, "tag": "Administered" }, "medication_practice": { "practice_type": "ACADEMIC" } }
HospitalizationMilestone
Marks the kind of hospitalization event, as used in the Hospitalization fact.
These are:
-
a Discharge, with no admission in the temporal component,
-
an Admission, with no milestone in the temporal component,
-
or a hospital Stay, in which the temporal component has a begin and end associated with admission and milestone.
For example, if the event of interest is the discharge date _as well as length of stay, the Stay variant should be used, with length of stay represented as the duration of the temporal compoenent whose end-point is the discharge time.
Each of the three kinds of events can optionally hold Text data, which should be used to represent information such as discharge status. In the future, we might make this more detailed by providing a separate HopsitalizationMilestoneData fact, say, which is a record type with multiple fields.
- Dhall
-
< Admission : Optional Text | Discharge : Optional Text | Stay : Optional Text >
- Example JSON
-
{ "contents": null, "tag": "Stay" }
Hospitalization
Facts about hospitalization. This assumes the temporal component to which the fact is associated can mark one of the following:
-
a discharge, with no admission in the temporal component,
-
an admission, with no milestone in the temporal component,
-
or a hospital stay, in which the temporal component has a begin and end associated with admission and milestone.
- Dhall
-
{ cost : Optional { allowed : Optional Double , category : Optional Text , charge : Optional Double , cost : Optional Double , description : Optional Text , transaction : Optional Text } , milestone : < Admission : Optional Text | Discharge : Optional Text | Stay : Optional Text > , provider : Optional { provider_id : Text , provider_type : Optional Text , taxonomy : Optional Text } }
- Example JSON
-
{ "cost": { "allowed": 1.2, "category": "expense", "charge": 0.5, "cost": 9, "description": null, "transaction": null }, "milestone": { "contents": null, "tag": "Stay" }, "provider": null }
Lab
Facts about a lab.
- Dhall
-
{ code : { code : Text , codebook : < CDT | CVX | HCPCS | ICD10 | ICD9 | LOINC | MedicaidCat | NABSP | NDC | NDC9 | UB92 | USSTATE > } , cost : Optional { allowed : Optional Double , category : Optional Text , charge : Optional Double , cost : Optional Double , description : Optional Text , transaction : Optional Text } , service : Optional { place : Optional Text , service_location : < Inpatient | Outpatient > , service_type : Optional Text } , value : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } }
- Example JSON
-
{ "code": { "code": "a", "codebook": "ICD10" }, "cost": null, "service": null, "value": { "units": "mg", "value": { "contents": 2.3, "tag": "NumberValue" } } }
LineOfTherapy
The LineOfTherapy fact captures information on the treatment lines.
- Dhall
-
{ line_medication : { common_drug_name : Text , detailed_drug_category : Text , drug_category : Text , drug_name : Text } , line_milestone : < EpisodeStart | LineStart | MissingLineOfTherapyMilestone | OtherLineOfTherapyMilestone | UnknownLineOfTherapyMilestone > , line_name : Text , line_number : Natural , maintenance_therapy : Bool }
- Example JSON
-
{ "line_medication": { "common_drug_name": "drug one", "detailed_drug_category": "Lots of drug details", "drug_category": "DrugCat", "drug_name": "DrugOne" }, "line_milestone": "LineStart", "line_name": "cisplatin,carboplatin", "line_number": 1, "maintenance_therapy": false }
LineOfTherapyMilestone
The line of therapy milestone. Currently used in Flatiron data to differentiate between events where the begin value is the LineStartDate and events where the begin value is EpisodeDate. EpisodeDate refers to date a particular drug in a treatment line was administered.
- Dhall
-
< EpisodeStart | LineStart | MissingLineOfTherapyMilestone | OtherLineOfTherapyMilestone | UnknownLineOfTherapyMilestone >
- Example JSON
-
"LineStart"
MedicalServiceFact
The facts related to a medical encounter, such as diagnosis or procedure.
- Dhall
-
{ claim : Optional { claim_type : Optional Text , id : Text , index : Optional Integer , procedure : Optional Text } , code : { code : Text , codebook : < CDT | CVX | HCPCS | ICD10 | ICD9 | LOINC | MedicaidCat | NABSP | NDC | NDC9 | UB92 | USSTATE > } , cost : Optional { allowed : Optional Double , category : Optional Text , charge : Optional Double , cost : Optional Double , description : Optional Text , transaction : Optional Text } , provider : Optional { provider_id : Text , provider_type : Optional Text , taxonomy : Optional Text } , service : Optional { place : Optional Text , service_location : < Inpatient | Outpatient > , service_type : Optional Text } }
- Example JSON
-
{ "claim": null, "code": { "code": "a", "codebook": "ICD10" }, "cost": null, "provider": null, "service": null }
Medication
Facts for a medication-related event, which can hold detailed information about
the medication. For a more generic fact, use MedicalServiceFact
.
- Dhall
-
{ claim : Optional { claim_type : Optional Text , id : Text , index : Optional Integer , procedure : Optional Text } , code : { code : Text , codebook : < CDT | CVX | HCPCS | ICD10 | ICD9 | LOINC | MedicaidCat | NABSP | NDC | NDC9 | UB92 | USSTATE > } , cost : Optional { allowed : Optional Double , category : Optional Text , charge : Optional Double , cost : Optional Double , description : Optional Text , transaction : Optional Text } , manufacturer : Optional Text , milestone : < Administered : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | ExpectedStart : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | Filled : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | MissingMedicationMilestone | Ordered : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | OtherMedicationMilestone : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | Prescribed : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | UnknownMedicationMilestone > , provider : Optional { provider_id : Text , provider_type : Optional Text , taxonomy : Optional Text } , service : Optional { place : Optional Text , service_location : < Inpatient | Outpatient > , service_type : Optional Text } }
- Example JSON
-
{ "claim": null, "code": { "code": "a", "codebook": "ICD10" }, "cost": null, "manufacturer": null, "milestone": { "contents": { "amount": { "units": "mg", "value": { "contents": 2.3, "tag": "NumberValue" } }, "days_supply": 2, "dose_number": 1, "quantity": 6, "route": "intravenous", "strength": "0.1%" }, "tag": "Administered" }, "provider": null, "service": null }
MedicationMilestone
Information about the medication-related action an event represents, e.g. the
date when a prescription is Filled
.
- Dhall
-
< Administered : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | ExpectedStart : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | Filled : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | MissingMedicationMilestone | Ordered : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | OtherMedicationMilestone : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | Prescribed : Optional { amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text } | UnknownMedicationMilestone >
- Example JSON
-
{ "contents": { "amount": { "units": "mg", "value": { "contents": 2.3, "tag": "NumberValue" } }, "days_supply": 2, "dose_number": 1, "quantity": 6, "route": "intravenous", "strength": "0.1%" }, "tag": "Administered" }
MedicationMilestoneData
The MedicationMilestoneData fact may be used to provide information for a single MedicationMilestone event.
"amount" refers to the amount of medication issued in the medication milestone. The amount of the medication has two components. The first represents the value, which can be either a text or a number. The value refers to the amount of medication in one discrete unit of the medication. The second represents the units associated to the value, which are text.
"route" refers to the delivery mode of the medication issued in the medication milestone. Some examples would be "intravenous", "oral", etc.
"dose_number" refers to the position of the medication milestone dose in the sequence of all medication milestones doses.
"days_supply" refers to the number of days of medication issued in the medication milestone.
"strength" refers to the concentration of the medication issued in the medication milestone.
"quantity" refers to the number of discrete units of medication issued in the medication milestone. So, for example, the number of pills in a bottle of prescription medication.
In general this fact should be used within the MedicationMilestone fact. The code identifying the kind of medication would be put in a code fact, if relevant, wherever the MedicationMilestone fact is used. |
- Dhall
-
{ amount : { units : Optional Text , value : < NumberValue : Double | TextValue : Text > } , days_supply : Optional Natural , dose_number : Optional Natural , quantity : Optional Natural , route : Optional Text , strength : Optional Text }
- Example JSON
-
{ "amount": { "units": "mg", "value": { "contents": 2.3, "tag": "NumberValue" } }, "days_supply": 2, "dose_number": 1, "quantity": 6, "route": "intravenous", "strength": "0.1%" }
NSCLCDx
Information about NSCLC diagnosis.
- Dhall
-
{ disease_milestone : < Advanced | Initial | MissingDiseaseMilestone | OtherDiseaseMilestone | UnknownDiseaseMilestone > , group_stage : Optional Text , histology : Optional Text , smoking_status : Optional Text }
- Example JSON
-
{ "disease_milestone": "Advanced", "group_stage": "Stage IV", "histology": "Non-squamous cell carcinoma", "smoking_status": "History of smoking" }
Plan
The plan fact determines the health care plan under which an event occurred. The fields are based on fields commonly found in insurance claim data.
- Dhall
-
{ benefit : Optional Text , exchange : < Group | IndFederal | IndState | Medicaid | Medicare | None | ThirdParty | Unknown > , group_id : Optional Text , plan_id : Optional Text , subscriber_id : Optional Text , subscriber_relationship : Optional Text }
- Example JSON
-
{ "benefit": null, "exchange": "Group", "group_id": null, "plan_id": null, "subscriber_id": null, "subscriber_relationship": null }
Plan exchanges
Enumerates the possible insurance exchanges used in the EDM.
See ../fact/plan.dhall
for a fact that uses this type.
- Dhall
-
< Group | IndFederal | IndState | Medicaid | Medicare | None | ThirdParty | Unknown >
- Example JSON
-
"Group"
Practice
Information about the practice type (Flatiron).
- Dhall
-
{ practice_type : Text }
- Example JSON
-
{ "practice_type": "ACADEMIC" }
Provider
The provider fact determines an event’s health care provider. The fields are based on the National Provider Identifier (NPI) schema.
-
provider_id
: NPI number (Required) -
provider_type
: individual or organization -
taxonomy
: a CMS taxonomy code
- Dhall
-
{ provider_id : Text, provider_type : Optional Text, taxonomy : Optional Text }
- Example JSON
-
{ "provider_id": "1104089713", "provider_type": null, "taxonomy": "207RA0001X" }
Service
The service fact holds information about an inpatient or outpatient service provided to a patient.
- Dhall
-
{ place : Optional Text , service_location : < Inpatient | Outpatient > , service_type : Optional Text }
- Example JSON
-
{ "place": "somewhere", "service_location": "Inpatient", "service_type": "something" }
ServiceLocation
Enumerates the possible location that a service is performed.
- Dhall
-
< Inpatient | Outpatient >
- Example JSON
-
"Inpatient"
Text or Number Value
Data that could be either a text value or a number value.
- Dhall
-
< NumberValue : Double | TextValue : Text >
- Example JSON
-
{ "contents": 2.1, "tag": "NumberValue" }
TNValueInUnits
The labValue fact is either a text or numeric value possibly along with units.
The code identifying the kind of lab would be put in an domain’s code fact. |
- Dhall
-
{ units : Optional Text, value : < NumberValue : Double | TextValue : Text > }
- Example JSON
-
{ "units": "mg", "value": { "contents": 2.3, "tag": "NumberValue" } }
UncodedMedication
The UncodedMedication fact captures information on un-coded drugs.
- Dhall
-
{ common_drug_name : Text , detailed_drug_category : Text , drug_category : Text , drug_name : Text }
- Example JSON
-
{ "common_drug_name": "drug one", "detailed_drug_category": "Lots of drug details", "drug_category": "DrugCat", "drug_name": "DrugOne" }