From 48d33884a99b5917d20462ffa1e69d7efa92acdc Mon Sep 17 00:00:00 2001 From: Ibrahim Ajiboye Date: Tue, 25 Aug 2026 21:09:38 +0100 Subject: [PATCH] Add adult social care data dictionary --- CHANGELOG.md | 1 + README.md | 12 + docs/domains/adult_social_care.md | 6 + .../adult_social_care_data_dictionary.md | 267 ++++++++++++++++++ 4 files changed, 286 insertions(+) create mode 100644 docs/domains/adult_social_care_data_dictionary.md diff --git a/CHANGELOG.md b/CHANGELOG.md index d3d7e3a..638ede9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -55,6 +55,7 @@ SynthOps is currently in early development and has not yet published a stable re - Added roadmap phases covering repository foundation, generator implementation, open-source product management and engineering maturity. - Updated Adult Social Care documentation to describe the implemented resident lifecycle generator. - Updated example generation script to output both care homes and residents. +- Added Adult Social Care data dictionary documenting implemented tables, columns, relationships, valid values and data quality rules. --- diff --git a/README.md b/README.md index 7ad377f..d96de88 100644 --- a/README.md +++ b/README.md @@ -134,6 +134,18 @@ synthops/ --- +## Documentation + +Key project documentation: + +- [Architecture](ARCHITECTURE.md) +- [Roadmap](ROADMAP.md) +- [Changelog](CHANGELOG.md) +- [Adult Social Care Domain Notes](docs/domains/adult_social_care.md) +- [Adult Social Care Data Dictionary](docs/domains/adult_social_care_data_dictionary.md) + +--- + ## Installation for Local Development Create and activate a virtual environment: diff --git a/docs/domains/adult_social_care.md b/docs/domains/adult_social_care.md index b95cc8e..a7695da 100644 --- a/docs/domains/adult_social_care.md +++ b/docs/domains/adult_social_care.md @@ -32,6 +32,12 @@ Planned tables: --- +## Related Documentation + +- [Adult Social Care Data Dictionary](adult_social_care_data_dictionary.md) + +--- + ## Current Table: `care_homes` The `care_homes` table represents fictional adult social care provider sites. diff --git a/docs/domains/adult_social_care_data_dictionary.md b/docs/domains/adult_social_care_data_dictionary.md new file mode 100644 index 0000000..976d6b1 --- /dev/null +++ b/docs/domains/adult_social_care_data_dictionary.md @@ -0,0 +1,267 @@ +# Adult Social Care Data Dictionary + +## Overview + +This data dictionary documents the currently implemented Adult Social Care domain tables in SynthOps. + +The Adult Social Care module generates fictional operational data for analytics engineering, business intelligence, AI prototyping and decision-intelligence use cases. + +All data generated by SynthOps is synthetic. It does not represent real residents, care providers, staff, organisations or services. + +--- + +## Current Implemented Tables + +| Table | Status | Description | +| ------------ | ----------- | --------------------------------------------------------- | +| `care_homes` | Implemented | Fictional adult social care provider sites | +| `residents` | Implemented | Fictional resident lifecycle records linked to care homes | + +Planned future tables include: + +* `resident_care_needs_history` +* `staff` +* `shifts` +* `incidents` +* `observations` +* `handover_notes` + +--- + +## Table: `care_homes` + +### Description + +The `care_homes` table represents fictional adult social care provider sites. + +It acts as the parent table for the Adult Social Care domain. Current and future child tables, such as `residents`, link back to `care_homes` using `care_home_id`. + +### Grain + +One row represents one fictional care home. + +### Primary Key + +| Column | Description | +| -------------- | ---------------------------------------------- | +| `care_home_id` | Unique synthetic identifier for each care home | + +### Columns + +| Column | Data Type | Example | Description | Notes | +| ------------------- | --------- | ----------------- | --------------------------------------------------- | ------------------------------------------------------------------- | +| `care_home_id` | string | `HM001` | Unique synthetic identifier for the care home | Generated using configurable ID prefix and width | +| `care_home_name` | string | `Willow House` | Fictional care home name | Names are generated and intended to be fictional | +| `region` | string | `South West` | UK region assigned to the care home | Region is selected from configured synthetic geography values | +| `local_authority` | string | `Gloucestershire` | Local authority linked to the selected region | Local authority must belong to the selected region | +| `care_home_type` | string | `Dementia` | Type of care setting | Scenario driver influencing occupancy and future downstream data | +| `turnover_profile` | string | `High` | Synthetic resident turnover profile | Used by resident lifecycle generation | +| `bed_capacity` | integer | `48` | Number of available beds | Used to calculate current residents and historical resident volume | +| `occupancy_rate` | float | `0.91` | Synthetic occupancy rate | Influenced by care home type | +| `current_residents` | integer | `44` | Number of residents active at the dataset end point | Used by the `residents` generator to create active resident records | +| `cqc_rating` | string | `Good` | Fictional quality-rating-style category | Synthetic only; not linked to real CQC data | +| `opened_date` | date | `2004-06-15` | Fictional care home opening date | Provides contextual operational history | + +### Valid Values + +#### `care_home_type` + +| Value | Meaning | +| ------------------------- | ------------------------------------- | +| `Residential` | General residential care setting | +| `Nursing` | Nursing care setting | +| `Dementia` | Dementia-focused care setting | +| `Residential and Nursing` | Mixed residential and nursing setting | +| `Specialist Care` | Specialist care setting | + +#### `turnover_profile` + +| Value | Meaning | +| ---------- | -------------------------------------------- | +| `Stable` | Lower expected resident movement | +| `Moderate` | Typical expected resident movement | +| `High` | Higher expected resident movement | +| `Variable` | Wider and less predictable resident movement | + +#### `cqc_rating` + +| Value | +| ---------------------- | +| `Outstanding` | +| `Good` | +| `Requires Improvement` | +| `Inadequate` | + +### Data Quality Rules + +The `care_homes` generator is expected to follow these rules: + +* `care_home_id` must be unique. +* `care_home_name` must be unique within the generated dataset. +* `care_home_type` must be one of the supported values. +* `turnover_profile` must be one of the supported values. +* `current_residents` must not exceed `bed_capacity`. +* `occupancy_rate` should align with the selected care home type profile. +* `local_authority` must belong to the selected `region`. +* Generated care home names should be fictional. + +--- + +## Table: `residents` + +### Description + +The `residents` table represents fictional resident lifecycle records. + +It includes residents whose stay overlaps the generated dataset period, rather than only residents active at a single point in time. + +This supports time-aware analytics such as admissions, exits, active occupancy, resident turnover, length-of-stay analysis and future care-needs history. + +### Grain + +One row represents one fictional resident stay lifecycle record. + +### Primary Key + +| Column | Description | +| ------------- | -------------------------------------------------------------- | +| `resident_id` | Unique synthetic identifier for each resident lifecycle record | + +### Foreign Keys + +| Column | References | Relationship | +| -------------- | ------------------------- | ------------------------------------------ | +| `care_home_id` | `care_homes.care_home_id` | Many residents can belong to one care home | + +### Columns + +| Column | Data Type | Example | Description | Notes | +| ----------------------- | -------------- | ------------------------------- | --------------------------------------- | ---------------------------------------------------- | +| `resident_id` | string | `RES00001` | Unique synthetic resident identifier | Generated using configurable ID prefix and width | +| `care_home_id` | string | `HM001` | Linked care home identifier | Must exist in `care_homes.care_home_id` | +| `date_of_birth` | date | `1938-04-12` | Synthetic resident date of birth | Used to derive age and age bands later | +| `gender` | string | `Female` | Synthetic resident gender category | Fictional demographic attribute | +| `admission_date` | date | `2021-09-03` | Date resident entered the care home | May be before or during the generated dataset period | +| `exit_date` | date or null | `2023-11-18` | Date resident left the care home | Null for active residents | +| `exit_reason` | string or null | `Moved to another care setting` | Reason resident left the care home | Null for active residents | +| `status_at_dataset_end` | string | `Active` | Resident status at the dataset end date | Supports point-in-time occupancy | + +### Valid Values + +#### `gender` + +| Value | +| ----------------------- | +| `Female` | +| `Male` | +| `Other / Not specified` | + +#### `status_at_dataset_end` + +| Value | Meaning | +| ------------ | ----------------------------------------------------------- | +| `Active` | Resident is active in the care home at the dataset end date | +| `Discharged` | Resident exited before or on the dataset end date | +| `Deceased` | Resident died before or on the dataset end date | + +#### `exit_reason` + +| Value | Applies To | +| ------------------------------- | ------------ | +| `Returned home` | `Discharged` | +| `Moved to another care setting` | `Discharged` | +| `Family decision` | `Discharged` | +| `Care needs changed` | `Discharged` | +| `Deceased` | `Deceased` | + +### Data Quality Rules + +The `residents` generator is expected to follow these rules: + +* `resident_id` must be unique. +* Every `care_home_id` must exist in the `care_homes` table. +* Active resident counts by care home must match `care_homes.current_residents`. +* Active residents must have null `exit_date`. +* Active residents must have null `exit_reason`. +* Inactive residents must have a valid `exit_date`. +* Inactive residents must have a valid `exit_reason`. +* `exit_date` must be after `admission_date`. +* `exit_date` must be on or before `dataset_end_date`. +* `admission_date` must be on or before `dataset_end_date`. +* `date_of_birth` must be before `admission_date`. +* Residents must be adults at admission. +* Resident stays must overlap the generated dataset period. +* Historical resident volume is influenced by `turnover_profile`, `bed_capacity`, dataset length and random variation. + +--- + +## Relationship Summary + +Current implemented relationship: + +```text +care_homes + 1 ──── many + residents +``` + +This means: + +* each care home can have many residents +* each resident must belong to one care home +* residents cannot exist without a valid care home reference + +--- + +## Derived Analytics Fields + +SynthOps stores base facts where possible. + +The following fields are not currently stored directly in the raw generated `residents` table because they can be derived later: + +| Derived Field | How It Can Be Derived | +| -------------------------- | ----------------------------------------------------------------------------------------- | +| `current_age` | `dataset_end_date - date_of_birth` | +| `age_at_admission` | `admission_date - date_of_birth` | +| `age_band` | grouped from derived age | +| `length_of_stay` | `exit_date - admission_date`, or `dataset_end_date - admission_date` for active residents | +| `is_active_at_dataset_end` | `status_at_dataset_end == "Active"` | +| `resident_tenure_group` | grouped from derived length of stay | + +This supports cleaner analytics engineering because derived values can be recalculated consistently during transformation. + +--- + +## Responsible Use + +The Adult Social Care data generated by SynthOps is fictional. + +It must not be used for: + +* clinical decision-making +* safeguarding decisions +* inspection judgements +* regulatory reporting +* real-world care-quality assessment +* real-world evaluation of residents, staff, providers or organisations + +Synthetic assumptions must not be presented as official statistics or real-world benchmarks. + +--- + +## Notes for Analysts and Analytics Engineers + +When using the Adult Social Care sample data: + +* treat `care_homes` as the current parent table +* join `residents` to `care_homes` using `care_home_id` +* use `status_at_dataset_end` to identify residents active at the dataset end date +* derive age and length-of-stay fields in downstream transformations +* avoid treating generated distributions as real care-sector distributions +* review domain documentation and ADRs before using the data for demos or analysis + +Relevant documentation: + +* `docs/domains/adult_social_care.md` +* `docs/design-decisions/0001-modular-domain-architecture.md` +* `docs/design-decisions/0002-time-aware-resident-lifecycle.md`