Metadata-Version: 2.4
Name: s4d-tools
Version: 0.1.0
Summary: s4d_tools is a library designated to parse, transform and aggregate the data of StanForD files.
Author-email: Smaragda Luchia Sarana <smaragda.sarana@gmail.com>
License: MIT License
        
        Copyright (c) 2024 Smaragda Luchia Sarana
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Documentation, https://smaragdaluchia.github.io/s4d_tools/#/
Keywords: stanford,forest,harvester,data,parsing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Dynamic: license-file

# s4d_tools — StanForD Parser

A Python library and web-based visualization tool for analyzing StanForD (Standard for Forest Data) harvester files. `s4d_tools` parses production data from forest harvesters, normalizes every supported format into one standardized report shape, and provides aggregations for analysis — with an optional Streamlit app on top.

**Documentation:** <https://smaragdaluchia.github.io/s4d_tools/#/>

## Features

- **File parsing** for both StanForD format families:
  - `.prd` — production summary (Classic)
  - `.pri` — production-individual, log-level detail (Classic, combine with PRD)
  - `.apt` — bucking / price instructions (Classic, adds the relative price matrix)
  - `.hpr` — harvested production (StanForD 2010 XML)
  - `.pin` — product instructions (StanForD 2010 XML, adds the price matrix for HPR)
- **Standardized report**: every format is transformed into the same dict-of-DataFrames schema, so downstream code never cares which file type the data came from
- **Aggregations**: stems by species, volume by species × product, price-matrix heatmaps, productivity rates

## Quickstart (use the library)

Full walkthrough with explanations: **<https://smaragdaluchia.github.io/s4d_tools/#/quickstart>**

### 1. Install

Requires Python 3.11+.

```bash
pip install s4d-tools
```

### 2. Get files to test with

No harvester files at hand? Download the sample files — one per supported format, all describing the same small harvest:

**[Download sample files (.zip)](https://smaragdaluchia.github.io/s4d_tools/samples/s4d-tools-samples.zip)**

Extract the archive so the `s4d-tools-samples/` folder sits next to your script.

### 3. Parse, standardize, aggregate

```python
from s4d_tools import (
    HPRParser,
    transform_hpr_to_standardized,
    aggregate_stems_by_species,
)

raw = HPRParser("s4d-tools-samples/sample.hpr").parse()
report = transform_hpr_to_standardized(raw)

print(report["species_table"])
#   species_name  stems  volume_m3
# 0         Pine      3      1.870
# 1       Spruce      2      1.105

print(aggregate_stems_by_species(report["stems"], report["species_groups"]))
#   species_name  stem_count
# 0         Pine           3
# 1       Spruce           2
```

More recipes — combining PRD + PRI, adding price matrices from APT, exporting to CSV/Excel — are in [EXAMPLE_USAGE.md](EXAMPLE_USAGE.md).

## Development setup (work on the code)

### 1. Clone the repository

```bash
git clone https://github.com/SmaragdaLuchia/s4d_tools.git
cd s4d_tools
```

### 2. Create a virtual environment

```bash
python3 -m venv .venv

# On macOS/Linux:
source .venv/bin/activate

# On Windows:
# .venv\Scripts\activate
```

### 3. Install in editable mode

```bash
pip install --upgrade pip
pip install -e ".[all]"      # library + Streamlit UI + test dependencies
# or pick what you need:
# pip install -e ".[dev]"    # library + pytest
# pip install -e ".[ui]"     # library + Streamlit UI
```

### 4. Run the tests

```bash
pytest tests/ -v
```

Test fixtures live in `tests/fixtures/` — they are hand-crafted minimal files, and the parser tests assert exact values against them. The downloadable sample files (`docs-site/public/samples/`) are richer variants meant for trying the library out.

### 5. Run the Streamlit application

```bash
streamlit run streamlit/app.py       # English UI
# or
streamlit run streamlit/app_et.py    # Estonian UI
```

### Using the application

1. Upload a `.prd` or `.hpr` file (try the sample files from the Quickstart above)
2. Optionally add a `.pri` file (with PRD) and/or `.apt` / `.pin` files for price matrices
3. Explore the parsed data through the interactive tabs:
   - **Overview** — summary statistics and key metrics
   - **Basic Info** — file header and object information
   - **Species** — species groups and distribution
   - **Products** — product information
   - **Statistics** — production statistics and assortment breakdown
   - **Price matrix** — per-assortment diameter × length matrices (when APT/PIN uploaded)
   - **Machine / Stems / Logs** — machine specs and row-level data
4. The **Data redaction (GDPR)** tab produces a copy of a StanForD 2010 XML file with sensitive fields replaced by a placeholder
