a-small-fire

July 15, 2026 · View on GitHub

a-small-fire is a toolkit developed by the BBMRI.it Data Engineering team to facilitate the transformation step of the ETL (Extract, Transform, Load) process, converting datasets into the HL7 FHIR® (Fast Healthcare Interoperability Resources) standard.

The toolkit is built on the open-source FHIR Resources library.

NOTICE: THE BBMRI-ERIC ecosystem is transitioning towards MIABIS ON FHIR still unsupported from this toolkit. If you are part of BBMRI-ERIC please align with HQ-CS IT if considering employing this application to create new interoperable Federated Platform datasets. The BBMRI.it data team is reachable at data@bbmri.it.

If you use this toolkit please cite us at Cruoglio et. al, JDIQ 2025.

workflow

Input Data Requirements

Your input dataset should include the following essential fields:

Sampling Date
Donor Birth Date
Diagnosis Age Donor
Gender
Date of Diagnosis
Diagnosis ICD-10
Sample Type
Storage Temperature

In addition, the dataset must include unique identifiers for both the patient and the sample:

Patient_ID
Sample_ID

Data Format Notes

Data should follow the MIABIS Common Data Model.
If your dataset does not use MIABIS-standard, please define your own mappings in mapping_config.yml.

Field	Expected Format	Notes
SAMPLING_DATE	`YYYY-MM-DD`
BIRTH_DATE	`YYYY-MM-DD` or partial (`YYYY`)	If only a 4-digit year is provided, it will be interpreted as `YYYY-01-01`
DIAGNOSIS_AGE	Integer (e.g., `45`)
SEX	MIABIS vocabulary
DIAGNOSIS_DATE	`YYYY-MM-DD`
DIAGNOSIS	Valid ICD-10 code (e.g., `C50.9`)
MATERIAL_TYPE	MIABIS vocabulary
STORAGE_TEMPERATURE	MIABIS vocabulary
PATIENT_ID, SAMPLE_ID	Unique alphanumeric strings

Key Modules

The toolkit is structured into several key modules:

Conversion

The core module of the toolkit.
Takes an Excel file as input and generates a FHIR-structured JSON file ready for upload to the Biobank FHIR Store.

Normalization

Maps dataset fields that do not follow the MIABIS standard into MIABIS-compliant fields.

Input-Model

Contains all valid input values, which are used to validate and normalize data based on the MIABIS Common Data Model (CDM).

FHIR-Model

A high-level converter that transforms the input dataset into the FHIR format, following the BBMRI.de implementation guide.

FHIR-Resources

This module is responsible for mapping each field in the dataset to its appropriate FHIR Resource.

Installation and Setup

0. Requirements

Please notice that this toolkit requires Python 3.10 or 3.11. Python 3.12+ is untested, and Python 3.13/3.14 cause compatibility errors with Pydantic v1 (used by fhir.resources). It is recommended to create a dedicated virtual environment:

python3.11 -m venv .venv
source .venv/bin/activate  # on Windows: .venv\Scripts\activate

To get started with the toolkit, follow these steps:

1. Clone the Repository

git clone https://github.com/bbdataeng/a-small-fire.git

2. Install dependencies

cd a-small-fire
pip install -r requirements.txt

Usage

The toolkit offers two main options depending on whether your input data already conforms to the MIABIS standard:

1. Input Data in MIABIS Standard

If your input data already follows the MIABIS standard, you can use the --miabis flag for quicker conversion:

cd fhir_converter

python convert.py --filename <INPUT_DATA> --outdir "../output" --miabis

2. Input Data Not in MIABIS Standard

If your input data is not in the MIABIS standard, you’ll need to edit the mapping_config.yml file to map your local data fields into MIABIS CDM fields. After editing the mapping configuration, run the following command:

cd fhir_converter

python convert.py --filename <INPUT_DATA> --outdir "../output"

Configuration Files

There are two main configuration files:

biobank_config.yml: Stores general configuration information, such as organization ID, collection ID, and the Biobank Locator server URL.
mapping_config.yml: Defines how to map the fields in your local dataset to MIABIS CDM fields if your data is not already standardized.

Output

Two json files are generated from this tool:

bundle-<BUNDLE_ID>.json: Stores a transaction bundle with Patient and Specimen FHIR Resources.
organization.json: Stores a transaction bundle with Organization/Biobank and Organization/Collection FHIR Resources.

Additional Resources

For more information on the MIABIS standard and a sample dataset template, check out the minimum-dataset-template.