Skip to content

Add Adult Social Care data dictionary #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Phoenix-maho merged 1 commit into from
Aug 25, 2026
Merged

Add Adult Social Care data dictionary #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down
12 changes: 12 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
6 changes: 6 additions & 0 deletions docs/domains/adult_social_care.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
267 changes: 267 additions & 0 deletions docs/domains/adult_social_care_data_dictionary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`
Loading