FHexchange: Resources for Family Health History Extraction and Normalization From Consumer Dialog Sources

Introduction to this resource

Thanks for visiting this repository. Here you can access the annotated datasets from the paper:

FHexchange: Resources for Family Health History Extraction and Normalization From Consumer Dialog Sources (Nguyen et al., BioNLP 2026)

Folder structure

The repository is organized by the data and other code as follows:

project/
├── data/
│   ├── FHexchange_KIT/
│   │   ├── transcripts/
│   │   └── FHexchange_KIT_ann.json
│   └── FHexchange_MTS/
│       └── FHexchange_MTS_ann.json
├── src/
│   ├── __init__.py
│   ├── core.py
│   ├── prompts.py
│   └── run_experiment.py
├── requirements.txt
└── README.md

Data

Dataset sources

FHexchange is a resource that consists of annotated data from two existing dialog corpora:

1. 104 Chatbot transcripts from Nguyen et al., 2024, JMIR ¹ referred to as FHexchange-KIT, and
2. 154 family-health-history (FHX)-related dialogs from the openly available MTS-Dialog dataset from Ben Abacha et al., 2023, Proceedings of the 17th Conference of the European Chapter of the Association for Computational Linguistics ², referred to as FHexchange-MTS.

The FHexchange-KIT transcripts are .txt files within the transcripts/ folder. The FHexchange_MTS transcripts can be downloaded from the MTS-Dialog repository .

Annotation file convention

Each annotation file (FHexchange_KIT_ann.json and FHexchange_MTS_ann.json) is a single JSON dictionary where:

• keys correspond to transcript/dialog IDs
• values are lists of annotated family history mentions for that record

Each individual family history mention contains the following fields:

• family_member: the relative mentioned in the family history
• age_of_onset: age when the condition began, if available
• observation: the condition, symptom, or health-related observation
• side_of_family: maternal/paternal side, if specified
• living_status: whether the family member is living or deceased, if available
• age: age of the family member, if mentioned
• age_of_death: age at death, if mentioned
• cause_of_death: reported cause of death, if available
• negated: whether the condition is negated/confirmed within the text to be not present (true/false)

if not mentioned, the value is null.

Example

{
  "1": [
    {
      "family_member": "Mother",
      "age_of_onset": null,
      "observation": "High blood pressure (hypertension)",
      "side_of_family": null,
      "living_status": null,
      "age": null,
      "age_of_death": null,
      "cause_of_death": null,
      "negated": false
    }
...
  ]
}

Note

The set with UMLS CUI annotations includes an additional field labeled cui. Please complete the form to verify your UMLS Terminology Services account in order to access the data.

Code

We included scripts for reproducing FHx extraction experiments on the FHexchange datasets using structured LLM outputs using Microsoft Azure endpoints, but as approaches for structured outputs develop and progress, the syntax may change.

Files

File	Description
core.py	Main extraction logic, including schema definition, batching, tokenization, and response parsing.
prompts.py	Zero-shot and few-shot prompts used for FHx extraction.
run_experiment.py	Entry-point script for running extraction experiments.
__init__.py	Marks the directory as a Python package.
requirements.txt	Python dependencies needed to run the scripts.

Usage

The script expects a pickled dictionary of pandas DataFrames, where each key is a dataset name and each value contains at least the dataset name and then the data.

Example:

python
{
    "fhexchange_kit": pd.DataFrame(...),
    "fhexchange_mts": pd.DataFrame(...),
}

Example command

python src/run_experiment.py \
  --input-pkl path/to/datasets.pkl \
  --output-dir outputs \
  --results-dir results \
  --backend openai \
  --model-name gpt-4o \
  --mode few_shot

Reproducibility notes

To run the code, set the required environment variables for your model endpoint and API key. The prompts and schema are included in the repository so that the extraction setup can be reproduced.

Citation

If you use this resource, please cite our paper:

@inproceedings{nguyen-etal-2026-fhexchange,
  title = "{FH}exchange: Resources for Family Health History Extraction and Normalization From Consumer Dialog Sources",
  author = "Nguyen, Michelle and Soley, Nidhi and Zirikly, Ayah and Sedoc, Jo{\"a}o and Taylor, Casey",
  editor = "Demner-Fushman, Dina and Ananiadou, Sophia and Roberts, Kirk and Tsujii, Junichi",
  booktitle = "{B}io{NLP} 2026",
  month = jul,
  year = "2026",
  address = "San Diego, California",
  publisher = "Association for Computational Linguistics",
  url = "https://aclanthology.org/2026.bionlp-1.82/",
  pages = "1014--1028",
  ISBN = "979-8-89176-434-7"
}

Acknowledgments

We'd like to acknowledge the genetic counselors who assisted us in developing the annotation guideline. Additionally, thank you to the MTS-Dialog dataset authors, Drs. Asma Ben Abacha, Wen-wai Yim, Yadan Fan, Thomas Lin for making the resource accessible for the clinical NLP research community!

References

Footnotes

1. Nguyen M, Sedoc J, Taylor C. Usability, Engagement, and Report Usefulness of Chatbot-Based Family Health History Data Collection: Mixed Methods Analysis. J Med Internet Res 2024;26:e55164. URL: https://www.jmir.org/2024/1/e55164. DOI: 10.2196/55164 ↩

2. Asma Ben Abacha, Wen-wai Yim, Yadan Fan, and Thomas Lin. 2023. An Empirical Study of Clinical Note Generation from Doctor-Patient Encounters. In Proceedings of the 17th Conference of the European Chapter of the Association for Computational Linguistics, pages 2291–2302, Dubrovnik, Croatia. Association for Computational Linguistics. ↩