Metadata-Version: 2.4
Name: standard-area-measurements
Version: 1.0.0
Summary: ONS Geography Standard Area Measurements Pipeline
Author-email: Dan Harris <Dan.Harris@ONS.gov.uk>
License: MIT
Project-URL: Homepage, https://github.com/ONSdigital/standard-area-measurements
Project-URL: Documentation, https://github.com/ONSdigital/standard-area-measurements#readme
Keywords: geography,area measurements,land area,inland water
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: geopandas
Requires-Dist: pandas
Requires-Dist: shapely
Requires-Dist: openpyxl
Requires-Dist: PyYAML
Requires-Dist: tqdm
Dynamic: license-file

# Standard Area Measurements (SAM)

![Python](https://img.shields.io/badge/Python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)
![License](https://img.shields.io/badge/License-MIT-orange)

## ⚠️**Warning:**
Releases of Standard Area Measurements from ONS Geography have been produced out of line with GSS Geography Policy - Standard Area Measurements.
It is expected that this section of the GSS Geography Policy will be redesigned as a result, which may prompt redevelopment of the pipeline to be released in V2.
This pipeline has not been used in the production of the Standard Area Measurements to date.

<p align = "center">
<img src="standard_area_measurements.png" width="500" class = "center" />
</p>

## Introduction
Four types of measurements are included: total extent (AREAEHECT), area to mean high water (coastline) (AREACHECT), area of inland water (AREAIHECT) and area to mean high water excluding area of inland water (land area) (AREALHECT). The Eurostat-recommended approach is to use the ‘land area’ measurement to compile population density figures.

The pipeline has been designed to be robust to schema changes and to produce SAM in line with a range of standards and definitions across Inland Water and Land Area (EUROSTAT, UN) by providing toggling capability on Inland Water Features from the Ordnance Survey National Geographic Database (OS NGD).

## Setting up SAM
To install the package, run:
```
pip install standard-area-measurements
```
To set up the pipeline, run:
```
from sam.setup import Config, SAMPipeline

config = Config(boundary_type = 'LSOA',
                boundary_year = '2011',
                extents = 'EW',
                bfc_boundary_path = r"data/LSOA_2011_EW_BFC_V3.shp",
                bfe_boundary_path = r"data/LSOA_2011_EW_BFE_V3.shp",
                water_data_path = r"data/wtr_fts_water/wtr_fts_water.gpkg")

pipeline = SAMPipeline(config)
```

## Procedures
| Method | Description |
| ------------- | ------------- |
| `setup_structure()` | Sets up the directory structure to store results |
| `validate_input_data()` | Validates the ONS Geo Boundaries and OS NGD Water Data |
| `generate_water_data_configuration()` | Generates the water data configuration from the OS NGD Water Data, the `review_items` parameter allows the user to pass in items from the NGD Water Data to configure. A size toggle is added by default |
| `process_water_data()` | Processes the OS NGD Water Data in line with the configuration set. If wishing to use an alternative configuration file from the same NGD Water Data release, this can be set in the `configuration_file` parameter. Additionally, the `resolve_duplicates` parameter will remove duplicates detected on geometric centroid if toggled |
| `calculate_sam_statistics()` | Calculates the Standard Area Measurements |
| `calculate_sam_changes()` | Calculates the changes to a prior SAM release |
| `enrich_to_boundaries()` | Enriches the measurements to the boundaries passed |

## Output Structure
The output folder name is formatted as `SAM_{BoundaryType}_{BoundaryYear}_{BoundaryExtents}` and will be structured as shown below.
```
├───configurations
├───input_data
│   ├───boundaries
│   └───inland_water
├───logs
├───metadata
└───sam_results
```

## Usage
See `tutorial.ipynb` for detailed walkthrough.
