> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.emtelligent.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emtelligent.com/_mcp/server. # Social History ## Goal of Extraction The Core Clinical Social History Library is a social history-focused clinical data extraction tool designed to identify, extract, and ontologically map social determinants and lifestyle factors from unstructured clinical narratives and patient health record documentation. It extracts social and behavioral information documented across social history sections, clinical notes, and patient interviews, standardizing representation through SNOMED CT concept mapping. ## Extraction Methodology The extraction process operates at the sentence level, capturing each social history element with precise character-level locations (start and end positions) that enable direct traceability back to the "document". Each extracted social history record includes substance use patterns (alcohol, nicotine, drugs), consumption and cessation information, marital status and length, and employment history. Status fields (alcohol_status, nicotine_status, substance_status, marriage_status, employment_status) are standardized to controlled vocabulary. A social history record will only be extracted if at least one of the following is present: \[alcohol_status, nicotine_status, substance_status, marital_status, employment_status]. When a patient's social history element appears multiple times within a single document—whether from repeated documentation, updates across different note sections, or serial assessments—each instance is extracted and recorded separately to preserve the complete social history documentation. The library performs extraction on a document-by-document basis; there is no automatic cross-document reconciliation or cross-patient data merging. Note: A document is determined by our intelligent document splitting feature. Medical PDFs can contain a single document or multiple documents. A document's type can provide clinical context important for the data extraction. This feature separates and categorizes an input PDF into individual documents by document type to prepare them for data extraction. An input PDF can remain one document or can be split into multiple documents through this process. A "document" in the context of this data extraction refers to the documents identified after the intelligent document splitting process. ## Interpretation & Validation Status fields (alcohol_status, nicotine_status, substance_status, marriage_status, employment_status) are standardized to controlled vocabulary to ensure consistent representation. These standardized classifications guide appropriate reliance on extracted data and support informed clinical interpretation. ## Clinical Considerations Social history context is critical for clinical decision-making. Understanding substance use patterns, employment status, and marital circumstances directly impacts patient management, risk assessment, and care planning. The distinction between current and former substance use patterns has significant implications for clinical decision-making and patient counseling. Duration and intensity of substance use provide essential context for health risk stratification. Clinical judgment should be applied when interpreting extracted results, particularly for sensitive social history elements. ## Target Concepts ### Coding System: SNOMED CT All extracted social history elements are mapped to SNOMED CT (Systematized Nomenclature of Medicine Clinical Terms), with each element assigned a valid, active SNOMED concept identifier (6–18 digit numeric codes), along with its associated full SNOMED concept description. This structure provides both the standardized data needed for system integration and the contextual information needed for informed clinical interpretation. ### Clinical Concepts Extracted Social history elements are clinically documented information about patient substance use, employment, and marital circumstances. This includes substance use patterns (alcohol, nicotine, drugs), consumption and cessation information, marital status and length, and employment history. We define social history status fields with SNOMED concepts. Status fields (alcohol_status, nicotine_status, substance_status, marriage_status, employment_status) are standardized to controlled vocabulary. The extracted concept must be a specific, named element. Vague qualifier terms, attributes, and organism concepts are excluded — we are looking for identifiable, valid social history concepts. ## Extracted Fields | Field Name | Data Type | Description | | ------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | filename | string | The source PDF name with a suffix appended. The suffix refers to the subdocument after document splitting | | subdoc_id | string | Unique subdocument identifier | | manifest_index | integer | The row index of the file in the manifest submitted with the processing request. Used to retrieve the corresponding OCR output from the [document metadata JSONL](/extract/reference/output#document-metadata). | | measure | const string | Row-label indicating extraction type | | chartdate | string | Clinical note or chart date; standardized to YYYY-MM-DD format | | subject_id | string | Patient identifier as assigned in the manifest.csv (required) | | processing_date | string | Date/time record was processed; system-generated | | alcohol_status | string | Current alcohol use status; controlled vocabulary: “current_drinker”, “ex_drinker”, “non_drinker”, “never_drinker”; if not mentioned, return “no_mentions” | | alcohol_drinker_type | string | Type of alcohol use pattern; controlled vocabulary: “heavy”, “moderate”, “light”, “occasional”, “social”, “rare”, “alcoholic”; if not a drinker or no mention of drinking, return “n/a” | | alcohol_consumption | string | Quantity of alcohol use per week, if a drinker; if not a drinker or no mention of drinking, return “n/a” | | alcohol_quitting | string | A date or temporal terms associated with drinking cessation, if applicable; if no history of drinking, is a current drinker, or there is no mention of drinking, return “n/a” | | alcohol_sentence | string | Most relevant sentence or paragraph about alcohol use; if no mention of alcohol use, return “no mentions” | | alcohol_concept_id | string | SNOMED concept for alcohol use status | | alcohol_description | string | The SNOMED fully specified name (FSN); derived from alcohol_concept_id | | alcohol_mention_start | integer | Character start position in sentence related to alcohol use mention | | alcohol_mention_end | integer | Character end position in sentence related to alcohol use mention | | nicotine_status | string | Current nicotine use status; controlled vocabulary: “smoker”, “ex_smoker”, “non_smoker”, “never_smoker” (for smoked product users); “user”, “ex_user”, “non_user”, “never_user” (for non-smoked product users); if not mentioned, return “no_mentions” | | nicotine_products | string | Type of nicotine product(s) used; if not applicable, not a user, or if data is not present, return “n/a” | | nicotine_consumption | string | The quantity of nicotine use per day (e.g. 1 pack/day) and/or per year (e.g. 10 pack-year history), if present; if not applicable, not a user, or if data is not present, return “n/a” | | nicotine_quitting | string | A date or temporal terms related to nicotine cessation, if applicable; if no history of use or is a current user, return “n/a” | | nicotine_sentence | string | Most relevant sentence or paragraph about nicotine use; if no mention of use, returns “no mentions” | | nicotine_concept_id | string | SNOMED concept for nicotine use status | | nicotine_description | string | The SNOMED fully specified name (FSN); derived from nicotine_concept_id | | nicotine_mention_start | integer | Character start offset of the sentence for this mention relative to the start of the document text | | nicotine_mention_end | integer | Character end offset of the sentence for this mention relative to the start of the document text | | substance_status | string | Current illicit or recreational substance use other than alcohol, nicotine, and caffeine-containing products; controlled vocabulary: “current_user”, “ex_user”, “non_user”, “never_user”; if not mentioned, return “no_mentions” | | substance_products | string | Type of substances used (excludes alcohol, nicotine, and caffeine-containing products); if not a user, then return “n/a” | | substance_consumption | string | The quantity of substance use per day or per year; if not applicable or no history of use, return “n/a” | | substance_quitting | string | A date or temporal terms related to substance use cessation, if applicable; if no history of use or is a current user, return “n/a” | | substance_sentence | string | Most relevant sentence or paragraph about substance use/abuse; if no mention of use, return “no_mentions” | | substance_concept_id | string | SNOMED concept for substance use status | | substance_description | string | The SNOMED fully specified name (FSN); derived from substance_concept_id | | substance_mention_start | integer | Character start offset of the sentence for this mention relative to the start of the document text | | substance_mention_end | integer | Character end offset of the sentence for this mention relative to the start of the document text | | marriage_status | string | Current marital/partnership status; controlled vocabulary: “married”, “unmarried”, “common_law”, “separated”, “divorced”, “widowed”, “engaged”; if not mentioned, return “no_mentions” | | marriage_length | string | Duration of current marriage, if married; if not married, returns “n/a” | | marriage_sentence | string | Most relevant sentence or paragraph about marital/partnership status; if no mention of status, return “no mentions” | | marriage_concept_id | string | SNOMED concept for marital status | | marriage_description | string | The SNOMED fully specified name (FSN); derived from marriage_concept_id | | marriage_mention_start | integer | Character start offset of the sentence for this mention relative to the start of the document text | | marriage_mention_end | integer | Character end offset of the sentence for this mention relative to the start of the document text | | employment_status | string | Current employment status; controlled vocabulary: “employed_full_time”, “employed_part_time”, “employed_seasonal”, “employed_intermittent”, “unemployed”, “retired”, “student”; if not mentioned, return “no_mentions” | | employment_type | string | Type of work or job title; if not applicable, return “n/a” | | employment_length | string | Duration of employment, unemployment, student, etc; if not specified, return “n/a” | | employment_status | string | Most relevant sentence or paragraph about employment status; if no mention of status, return “no mentions” | | employment_concept_id | string | SNOMED concept for employment status | | employment_description | string | The SNOMED fully specified name (FSN); derived from employment_concept_id | | employment_mention_start | integer | Character start offset of the sentence for this mention relative to the start of the document text | | employment_mention_end | integer | Character end offset of the sentence for this mention relative to the start of the document text | Social History Extraction Fields ## Example of Extracted Output * *Note: This example demonstrates the content of the output, not the structure* | nicotine_sentence | nicotine_status | nicotine_consumption | nicotine_concept_id | nicotine_description | | ------------------------------------------ | --------------- | -------------------- | ------------------- | -------------------- | | Patient currently smokes 1 pack/day | smoker | 1 pack/day | 77176002 | Smoker (finding) | | Social hx: non-smoker, drinks occasionally | non_smoker | n/a | 8392000 | Non-smoker (finding) | Social History Illustrative Output Example * Example JSONL object showing a typical extraction result ```json { "filename": "Case_1_APS_HSHS_Redacted2.pdf", "subdoc_id": "Case_1_APS_HSHS_Redacted2.pdf-0009", "manifest_index": 0, "measure": "social_history", "chartdate": "2021-05-19", "subject_id": "10000001", "processing_date": "2024-03-28T00:00:00", "data": [ { "employment_status": "retired", "employment_type": "n/a", "employment_length": "n/a", "employment_sentence": "no mentions", "employment_concept_id": "105493001", "employment_description": "Retired, life event (finding)", "employment_mention_start": null, "employment_mention_end": null, "marriage_status": "no_mentions", "marriage_length": "n/a", "marriage_sentence": "no mentions", "marriage_concept_id": "n/a", "marriage_description": "n/a", "marriage_mention_start": null, "marriage_mention_end": null, "substance_status": "never_user", "substance_products": "n/a", "substance_consumption": "n/a", "substance_quitting": "n/a", "substance_sentence": "Drug use: | Never", "substance_concept_id": "228368007", "substance_description": "Has never misused drugs (situation)", "substance_mention_start": 6759, "substance_mention_end": 6774, "nicotine_status": "ex_smoker", "nicotine_products": "cigars", "nicotine_consumption": "n/a", "nicotine_quitting": "1991", "nicotine_sentence": "Tobacco Use | | Smoking status:\tFormer Smoker | Types:\tCigars | Quit date:\t1991 | Years since quitting:\t30.4 | Smokeless tobacco:\tNever Used", "nicotine_concept_id": "8517006", "nicotine_description": "Ex-smoker (finding)", "nicotine_mention_start": 6373, "nicotine_mention_end": 6501, "alcohol_status": "current_drinker", "alcohol_drinker_type": "social", "alcohol_consumption": "n/a", "alcohol_quitting": "n/a", "alcohol_sentence": "Alcohol use: | Comment: social | Yes", "alcohol_concept_id": "219006", "alcohol_description": "Current drinker of alcohol (finding)", "alcohol_mention_start": 6723, "alcohol_mention_end": 6756 } ] } ```