Record
Open-source Python library · built for health data
Synthetic patients who add up to a real population.
meddies-faker generates fake people and patients from published census, survey and hospital statistics. Age, region, ethnicity, insurance, diagnosis, IDs and addresses agree with each other, and every value can tell you which table it came from. Test health software, train de-identification models and teach without a single real patient record.
pip install "meddies-faker[vn]"- –country packs
- –languages
- –cited sources
- –PII kinds per pack
Healthcare
Patients without patient data.
Clinical text is full of identifiers: names, birth dates, record numbers, insurance cards, hospitals, diagnoses. meddies-faker writes realistic patient documents with every identifier labelled, so a de-identification model can learn from text that never belonged to anyone.
Discharge note
Person nameDateIdentifier
AddressOrganisationDiagnosis codeContact
De-identification and PII detection
Labelled clinical notes, forms and transcripts in the patient's language, with the spans and kinds a NER model needs.
Testing hospital software
Fill an EHR, HIS or insurance system with patients whose age, diagnosis, insurance and stay hang together, at any volume.
Demos, teaching and research
Show a dashboard or teach a course on data that behaves like a real patient population, with no privacy review needed.
Compare
A Faker record looks fine until you check it.
The same Vietnamese fields from the upstream Faker library (vi_VN) and from meddies-faker, checked field by field against the rules a real record follows.
Faker
meddies-faker
Statistics
Generate 100,000 people and you get the country back.
Every pack benchmarked on 100,000 profiles against its own national tables, next to the same number of records from Faker's locale for that country where one exists. The deviation is the share of probability that differs from the source (0 % is identical); sampling noise is what a perfect sampler of the same size still shows.
–
–
–
Age pyramid, flattened
Share of people in each age group (%).
Census tablemeddies-fakerFaker
Most common surnames
Share of people with each name (%).
Source tablemeddies-fakerFaker
| National statistic | Universe | Deviation | Sampling noise | Source |
|---|
Provenance
Every value knows where it came from.
Each variable is drawn from a sourced table, conditioned on the variables before it. This is the full trace of the person on the record above (g.explain(profile)).
| Variable | Value | Conditioned on | Source | Confidence |
|---|
Search every table and rule a pack applies
Statistical tables with the census or survey they come from, and the laws, decrees and agency rules behind each identifier and document format. Taken from each pack's source registry, built from the research for that country.
| Field | Applies to | Source | Confidence | How it is used |
|---|
Coverage
Country packs
Each country is a separate package of sourced tables, written in its own script and formats. Pick one to load its people into the record above.
For NLP
One person, every way a document writes them.
Built for training and testing PII detection: each value comes in the forms real text uses, in the country's language. Shown for the person on the record above.
| Field | Full | Short mention | Spoken | Masked |
|---|
The same name as documents write it
Quickstart
Four lines to a population.
Outputs below are the real results of each call.
Principles
Built like a statistics office, shipped like a library.
Every number has a source
Each table carries its publisher, locator and retrieval date; estimates are marked and explained. No unsourced figures.
Faithful by default
Populations such as inpatients and tail controls act at sampling time and never rewrite the sourced tables.
Deterministic and offline
Same seed, same people. No network at runtime; runtime dependencies are pydantic and PyYAML.
No real identifiers
IDs are structurally valid and consistent with the person, never a real person's number.
Contribute
Open source, and only as good as its sources.
meddies-faker is being opened to the community. The most valuable help is a better figure with a citable source: an official table that replaces an estimate. Clinicians, statisticians, health researchers and developers all have something to add.
Bring a better source
Know the official table behind an estimate (a census table, a ministry report, a statute)? Open a New data source issue with the link and page.
Report a wrong figure
A value that differs from its cited source, or a document format that hospitals in your country write differently.
Add a country or a field
A country is one directory of sourced tables; a field is one YAML file. Both guides walk through a complete example.
Add a countryAdd a clinical identifier
Record numbers, insurance cards, prescription and lab formats your system uses: add a PII kind with its structure and source.
Estimated figures waiting for an official source
Statistical tables per pack, official vs estimated. meddies-faker gaps <pack> lists each one with the reason.
OfficialEstimated
- Find a gap:
meddies-faker gaps vn - Set up:
uv sync, thenuv run pytest -q - Change the table with its
sourceblock: publisher, locator, confidence - Open a pull request signed off with
git commit -s