Quality LAC data beta: Python validator

We want to build a tool that improves the quality of data on Looked After Children so that Children’s Services Departments have all the information needed to enhance their services.

We believe that a tool that highlights and helps fixing data errors would be valuable for:

1. Reducing the time analysts, business support and social workers spend cleaning data.
2. Enabling leadership to better use evidence in supporting Looked After Children.

About this project

The aim of this project is to deliver a tool to relieve some of the pain-points of reporting and quality in children's services data. This project focuses, in particular, on data on looked after children (LAC) and the SSDA903 return.

The project consists of a number of related pieces of work:

• Hosted Tool
• React & Pyodie Front-End
• Python Validator Engine & Rules [this repo]
• Local Authority Reference Data
• Postcode Reference Data

The core parts consist of a Python validator engine and rules using Pandas with Poetry for dependency management. The tool is targeted to run either standalone, or in pyodide in the browser for a zero-install deployment with offline capabilities.

It provides methods of finding the validation errors defined by the DfE in 903 data. The validator needs to be provided with a set of input files for the current year and, optionally, the previous year. These files are coerced into a common format and sent to each of the validator rules in turn. The validators report on rows not meeting the rules and a report is provided highlight errors for each row and which fields were included in the checks.

Data pipeline

• Loading of files
• Identification of tables - currently matched on exact filename
• Conversion of CSV to tabular format - no type checking
• Enrichment of provided data with Postcode distances
• Evaluation of rules
• Report

Project Structure

These are the key files

project
├─── pyproject.toml           - Project details and dependencies
├─── validator903
│    ├─── config.py           - High-level configuration
│    ├─── ingress.py          - Data ingress (handling CSV and XML files)
│    ├─── types.py            - Classes used across the work
│    ├─── validator.py        - The core validator process
│    └─── validators.py       - All individual validator codes
└─── tests                    - Unit tests

Most of the work from contributors will be in validators.py and the associated testing files under tests. Please do not submit a pull-request without a comprehensive test.

Development

To install the code and dependencies, from the main project directory run:

poetry install

If this does not work, it might be because you're running the wrong version of Python, the version of Numpy used by the 903 validator is locked at 3.9. The devcontainer and dockerfile should ensure you are running 3.9 and you may simply require a rebuild. If not, ensure you are working in an environment or venv with Python 3.9 as your interpreter.

Adding validators

Validators are simple functions, usually called validate_XXX() which take no arguments and return a tuple of an ErrorDefinition and a test function. The test function itself takes a single argument, the datastore, which is a Mapping (a dict-like) following the structure below.

The following is the expected structure for the input data that is given to each validator (the dfs object). You should assume that not all of these keys are present and handle that appropriately.

Any XML uploads are converted into CSV form to give the same inputs.

{
    # This years data
    'Header':   # header dataframe
    'Episodes': # episodes dataframe
    'Reviews':  # reviews dataframe
    'UASC':     # UASC dataframe
    'OC2':      # OC2 dataframe
    'OC3':      # OC3 dataframe
    'AD1':      # AD1 dataframe
    'PlacedAdoption':  # Placed for adoption dataframe
    'PrevPerm': # Previous permanence dataframe
    'Missing':  # Missing dataframe
    # Last years data
    'Header_last':   # header dataframe
    'Episodes_last': # episodes dataframe
    'Reviews_last':  # reviews dataframe
    'UASC_last':     # UASC dataframe
    'OC2_last':      # OC2 dataframe
    'OC3_last':      # OC3 dataframe
    'AD1_last':      # AD1 dataframe
    'PlacedAdoption_last':  # Placed for adoption dataframe
    'PrevPerm_last': # Previous permanence dataframe
    'Missing_last':  # Missing dataframe
    # Metadata
    'metadata': {
        'collection_start': # A datetime with the collection start date (year/4/1)
        'collection_end':   # A datetime with the collection end date (year + 1/4/1)
        'postcodes':        # Postcodes dataframe, columns laua, oseast1m, osnrth1m, pcd
        'localAuthority:    # The local authority code entered (long form, e.g. E07000026)
        'collectionYear':   # The raw collection year string - unlikely to need this (e.g. '2019/20')
    }
}

Releases

To build and release a new version, make sure all your unit tests pass.

We use semantic versioning, so update the project version in pyproject.toml accordingly and commit, creating a PR. Once the release version is on GitHub, create a GitHub release naming the release with the current release name, e.g. 1.0 and the tag with the release name prefixed with a v, i.e. v1.0. Alpha and beta releases can be flagged by appending -alpha.<number> and -beta.<number>.