Metadata-Version: 2.4 Name: RSATSIModel Version: 2.5.1 Summary: Python package for computing ATSI and RS-ATSI using CHL, SAL, and Sentinel-3 OLCI-style data. Author-email: Dr Md Galal Uddin License: MIT Requires-Python: >=3.9 Description-Content-Type: text/markdown License-File: LICENSE Requires-Dist: pandas>=1.5.0 Requires-Dist: numpy>=1.23.0 Requires-Dist: matplotlib>=3.6.0 Requires-Dist: openpyxl>=3.1.0 Requires-Dist: scikit-learn>=1.2.0 Dynamic: license-file # ATSIModel ## Assessment of Trophic Status Index (ATSI) and RS-ATSI Python Package **ATSIModel** is an open-source Python package for computing: 1. **ATSI** from in-situ **chlorophyll-a (CHL)** and **salinity (SAL)** data. 2. **RS-ATSI** from **Sentinel-3 OLCI-style remote sensing reflectance inputs** using **Rhow_1 to Rhow_11**, with machine-learning-based CHL prediction, ATSI derivation, structured validation, and multi-format export. The package is designed for **transitional, estuarine, and coastal waters**, and supports both: - standard ATSI computation from field observations - remote-sensing based ATSI workflows for scientific research and operational platform development --- # Author **Dr Md Galal Uddin** School of Engineering, University of Galway, Ireland Email: **jalaluddinbd1987@gmail.com** ### Research Profiles - **Google Scholar**: https://scholar.google.com/citations?user=g6xaAOkAAAAJ&hl=en - **University of Galway / EHIRG**: EcoHydroInformatics Research Group --- # Scientific Background Assessing trophic status and eutrophication in marine, coastal, and transitional waters is scientifically important for: - ecosystem health assessment - eutrophication monitoring - ecological status evaluation - environmental management and policy support - marine water quality surveillance The **Assessment of Trophic Status Index (ATSI)** was developed as a **data-driven trophic assessment framework** tailored for transitional and coastal waters. The published ATSI framework emphasizes: - **chlorophyll-a (CHL)** as the core trophic-response variable - **salinity (SAL)** as a threshold-conditioning variable - a **novel linear rescaling interpolation function** - a **new classification scheme** for trophic ranking in transitional and coastal waters This package operationalizes that concept into a reproducible Python workflow for both **in-situ ATSI** and **remote sensing RS-ATSI** applications. ### Recommended scientific citation If you use this package in academic work, please cite the ATSI paper: **Uddin, M. G., Nash, S., Rahman, A., Dabrowski, T., & Olbert, A. I. (2024). Data-driven modelling for assessing trophic status in marine ecosystems using machine learning approaches. Environmental Research, 242, 117755. https://doi.org/10.1016/j.envres.2023.117755** --- # Package Scope This package includes **two main workflows**: ## 1) Standard ATSI workflow Use **CHL + SAL** to compute: - ATSI score - threshold-adjusted trophic status - ATSI class ## 2) RS-ATSI workflow Use: - `Rhow_1` to `Rhow_11` - `SAL` - `CHL` (for training / validation) to compute: - predicted chlorophyll-a (`CHL_RS`) - ATSI from in-situ CHL (`ATSI_INSITU`) - ATSI from remote sensing predicted CHL (`ATSI_RS`) - trophic classification - validation outputs - exported result tables --- # Package Structure ```text ATSIModel_RS/ │ ├── atsimodel/ │ ├── __init__.py │ ├── core.py │ ├── rs_core.py │ ├── io.py │ ├── preprocessing.py │ ├── thresholds.py │ ├── atsifunction.py │ ├── classification.py │ ├── olci_features.py │ ├── chl_models.py │ ├── validation.py │ ├── metrics.py │ ├── plotting.py │ └── utils.py │ ├── examples/ │ ├── sample_atsi_input.xlsx │ ├── sample_rs_atsi_input.xlsx │ ├── sample_rs_atsi_input.csv │ ├── sample_rs_atsi_input.txt │ ├── sample_rs_atsi_rhow_input.xlsx │ ├── sample_rs_atsi_rhow_input.csv │ └── sample_rs_atsi_rhow_input.txt │ ├── README.md ├── requirements.txt ├── pyproject.toml ├── setup.py ├── MANIFEST.in ├── LICENSE └── main.py ``` --- # Installation ## From local folder ```bash pip install . ``` ## From PyPI (after release) ```bash pip install ATSIModel ``` --- # Python Version - Recommended: **Python 3.9+** --- # Dependencies Main dependencies: - pandas - numpy - matplotlib - openpyxl - scikit-learn --- # PART I — STANDARD ATSI WORKFLOW ## Required Input Columns The standard ATSI workflow requires only **two variables**: | Column | Description | Unit | |--------|-------------|------| | `CHL` | Chlorophyll-a concentration | µg/L | | `SAL` | Salinity | PSU | ### Example input table | Site | Date | CHL | SAL | |------|------|-----|-----| | Site_01 | 2024-01-01 | 8.5 | 31.2 | | Site_02 | 2024-01-15 | 15.1 | 28.7 | | Site_03 | 2024-02-01 | 4.3 | 33.1 | | Site_04 | 2024-02-15 | 22.0 | 20.0 | Only `CHL` and `SAL` are required. --- ## Supported Input Formats The package reads: - Excel (`.xlsx`, `.xls`) - CSV (`.csv`) - TXT / TSV (`.txt`, `.tsv`) --- ## Standard ATSI Example — Basic Use ```python from atsimodel.core import run_atsi df = run_atsi("examples/sample_atsi_input.xlsx") print(df.head()) ``` ### Expected output columns After ATSI computation, the dataframe includes: - `CHL` - `SAL` - `SAL_BIN` - `CHL_TL` - `CHL_TU` - `ATSI` - `ATSI_Class` --- ## Standard ATSI Example — Export Results ```python from atsimodel.core import run_atsi from atsimodel.utils import export_single df = run_atsi("examples/sample_atsi_input.xlsx") export_single( df, out_base="outputs/ATSI_results", formats=("xlsx", "csv", "txt", "json") ) ``` ### Exported files This creates: - `ATSI_results.xlsx` - `ATSI_results.csv` - `ATSI_results.txt` - `ATSI_results.json` --- ## Standard ATSI Example — Plotting ```python from atsimodel.core import run_atsi from atsimodel.plotting import plot_atsi_distribution, plot_chl_vs_atsi df = run_atsi("examples/sample_atsi_input.xlsx") plot_atsi_distribution(df) plot_chl_vs_atsi(df) ``` ### Current built-in plots The package currently supports: - **ATSI distribution histogram** - **CHL vs ATSI scatter plot** These are useful for quick exploratory analysis and sanity checking. --- # ATSI Scientific Logic The ATSI framework is implemented as: 1. **CHL-driven trophic scoring** 2. **SAL-conditioned threshold assignment** 3. **linear rescaling interpolation** 4. **score clipping to 0–100** 5. **classification translation** ## Threshold logic ATSIModel does **not** use one fixed CHL threshold for all waters. Instead, it uses **salinity-dependent moving CHL thresholds**, because trophic expectations vary across the salinity continuum. The package determines: - `SAL_BIN` - `CHL_TL` (lower CHL threshold) - `CHL_TU` (upper CHL threshold) and computes ATSI accordingly. --- # PART II — RS-ATSI WORKFLOW ## RS-ATSI Concept RS-ATSI is implemented as a **two-stage workflow**: ### Stage 1 — Remote sensing CHL prediction Sentinel-3 OLCI style reflectance inputs are used to estimate: - `CHL_RS` ### Stage 2 — ATSI derivation The predicted CHL is then combined with salinity to compute: - `ATSI_RS` This preserves the ATSI scientific philosophy: - ATSI remains **CHL-driven** - SAL remains the **threshold-conditioning variable** --- # RS-ATSI Required Inputs ## Mandatory columns The RS-ATSI workflow requires: - `CHL` - `SAL` - `Rhow_1` - `Rhow_2` - `Rhow_3` - `Rhow_4` - `Rhow_5` - `Rhow_6` - `Rhow_7` - `Rhow_8` - `Rhow_9` - `Rhow_10` - `Rhow_11` ## Optional but strongly recommended columns - `SITE` - `SEASON` - `ZONE` - `SPLIT` --- ## Meaning of optional metadata columns ### `SITE` Used for: - site-wise CHL validation - site-wise ATSI validation - station-level comparison ### `SEASON` Used for: - seasonal ATSI agreement - station-season diagnostics ### `ZONE` Used for: - spatial realism evaluation - upper / middle / lower estuary comparison - hotspot consistency analysis ### `SPLIT` Used to define data subsets: - `TRAIN` - `TEST` - `INDEPENDENT` If `SPLIT` is not provided, the package automatically creates a train/test split, but **independent validation will not exist**. --- # Example RS Input Table | SITE | SEASON | ZONE | SPLIT | CHL | SAL | Rhow_1 | Rhow_2 | Rhow_3 | Rhow_4 | Rhow_5 | Rhow_6 | Rhow_7 | Rhow_8 | Rhow_9 | Rhow_10 | Rhow_11 | |------|--------|------|-------|-----|-----|--------|--------|--------|--------|--------|--------|--------|--------|--------|---------|---------| | S1 | Winter | Upper | TRAIN | 8.0 | 31.0 | 0.011 | 0.012 | 0.013 | 0.014 | 0.015 | 0.016 | 0.017 | 0.018 | 0.019 | 0.020 | 0.021 | | S2 | Spring | Middle | TEST | 15.0 | 28.5 | 0.010 | 0.011 | 0.012 | 0.013 | 0.014 | 0.016 | 0.017 | 0.018 | 0.019 | 0.020 | 0.022 | | S3 | Summer | Lower | INDEPENDENT | 5.2 | 33.0 | 0.009 | 0.010 | 0.011 | 0.012 | 0.013 | 0.015 | 0.016 | 0.017 | 0.018 | 0.019 | 0.020 | --- # RS-ATSI Example — Basic Run ```python from atsimodel.rs_core import run_rs_atsi_pipeline results = run_rs_atsi_pipeline( input_file="examples/sample_rs_atsi_rhow_input.xlsx", output_dir="outputs/RS_ATSI_demo" ) print(results["chl_validation_overall"]) print(results["atsi_validation_overall"]) ``` --- # RS-ATSI Example — CSV Input ```python from atsimodel.rs_core import run_rs_atsi_pipeline results = run_rs_atsi_pipeline( input_file="examples/sample_rs_atsi_rhow_input.csv", output_dir="outputs/RS_ATSI_demo_csv" ) ``` --- # RS-ATSI Example — TXT Input ```python from atsimodel.rs_core import run_rs_atsi_pipeline results = run_rs_atsi_pipeline( input_file="examples/sample_rs_atsi_rhow_input.txt", output_dir="outputs/RS_ATSI_demo_txt" ) ``` --- # What the RS Pipeline Does Automatically When you run the RS-ATSI pipeline, it performs the following steps: ## Step 1 — Read the input file Reads Excel / CSV / TXT input. ## Step 2 — Standardize columns Automatically converts names like: - `Rhow_1` - `rhow_1` - `RHOW_1` into a consistent internal structure. ## Step 3 — Engineer spectral features The package automatically generates derived features from `Rhow_1` to `Rhow_11`, including: - band ratios - normalized differences - adjacent band differences - log-transformed spectral features ## Step 4 — Split the dataset Uses: - explicit `SPLIT` column if available, or - automatic train/test split ## Step 5 — Train CHL model Trains the default machine-learning model for CHL prediction. ## Step 6 — Predict CHL Generates: - `CHL_RS` ## Step 7 — Compute ATSI Computes both: - `ATSI_INSITU` from measured CHL - `ATSI_RS` from predicted CHL ## Step 8 — Validate outputs Performs structured validation. ## Step 9 — Export results Exports all major outputs. --- # Validation Design This package implements a structured validation framework suitable for **serious RS-ATSI research papers and prototype platforms**. --- ## 1) CHL Validation The package evaluates **predicted chlorophyll-a (`CHL_RS`)** against measured CHL using: - **R²** - **RMSE** - **MAE** - **Bias** across: - training data - testing data - independent validation data (if supplied) ### Exported CHL validation outputs - `chl_validation_overall` - `chl_validation_by_site_test` - `chl_validation_by_site_independent` (if available) - `chl_model_metrics_summary` --- ## 2) ATSI Validation The package compares: - **RS-ATSI** vs - **in-situ ATSI** using: - **R²** - **RMSE** - **MAE** - **Bias** across: - train - test - independent validation ### Exported ATSI validation outputs - `atsi_validation_overall` - `atsi_validation_by_site_test` - `atsi_validation_by_site_independent` --- ## 3) ATSI Classification Validation The package compares trophic classes derived from: - `ATSI_INSITU` - `ATSI_RS` using: - **confusion matrix** - **agreement rate** ### Exported classification outputs - `atsi_class_summary_test` - `atsi_confusion_matrix_test` - `atsi_class_summary_independent` - `atsi_confusion_matrix_independent` --- ## 4) Station–Season Agreement Validation The package evaluates agreement by: - station (`SITE`) - season (`SEASON`) This helps assess whether the model behaves consistently across: - different monitoring locations - different seasonal conditions ### Exported station-season outputs - `station_season_agreement_test` - `station_season_agreement_independent` --- ## 5) Spatial Validation The package includes a practical spatial validation layer through the `ZONE` column to support: - **hotspot consistency** - **estuarine gradient realism** - **upper / middle / lower estuary comparison** ### Recommended `ZONE` labels - `Upper` - `Middle` - `Lower` ### Exported spatial outputs - `spatial_zone_summary_test` - `spatial_zone_summary_independent` --- # Exported RS Results The RS workflow exports a full bundle of outputs. ## Main prediction table ### `predictions_all` This includes: - observed `CHL` - predicted `CHL_RS` - threshold columns - ATSI values - ATSI classes - dataset labels ### Typical output columns | Column | Description | |--------|-------------| | `CHL` | observed in-situ chlorophyll-a | | `CHL_RS` | model-predicted chlorophyll-a | | `SAL` | salinity | | `SAL_BIN` | salinity bin | | `CHL_TL` | lower CHL threshold | | `CHL_TU` | upper CHL threshold | | `ATSI_INSITU` | ATSI from measured CHL | | `ATSI_RS` | ATSI from predicted CHL | | `ATSI_INSITU_CLASS` | trophic class from measured ATSI | | `ATSI_RS_CLASS` | trophic class from RS-ATSI | | `DATASET` | Train / Test / Independent | --- # Export Formats The package exports results to: - **Excel** - **CSV** - **TXT** - **JSON** ### Excel bundle All result tables are also written into a single workbook: ```text RS_ATSI_results_bundle.xlsx ``` --- # RS-ATSI Example — End-to-End Run ```python from atsimodel.rs_core import run_rs_atsi_pipeline results = run_rs_atsi_pipeline( input_file="examples/sample_rs_atsi_rhow_input.xlsx", output_dir="outputs/RS_ATSI_case_study", target_col="CHL", sal_col="SAL", site_col="SITE", season_col="SEASON", zone_col="ZONE" ) print(results["predictions_all"].head()) print(results["chl_validation_overall"]) print(results["atsi_validation_overall"]) print(results["atsi_confusion_matrix_test"]) ``` --- # Plotting The current release includes simple plotting utilities in: ```python atsimodel.plotting ``` ## Built-in plotting functions ### 1. ATSI distribution ```python from atsimodel.plotting import plot_atsi_distribution plot_atsi_distribution(df) ``` ### 2. CHL vs ATSI ```python from atsimodel.plotting import plot_chl_vs_atsi plot_chl_vs_atsi(df) ``` --- ## Suggested RS plotting workflow For RS-ATSI studies, you can additionally create: - observed vs predicted CHL plots - ATSI_INSITU vs ATSI_RS plots - site-wise error boxplots - seasonal agreement heatmaps - zone-wise performance bar charts - confusion matrix heatmaps These are not fully automated yet in this release, but the exported tables are structured to support them easily. --- # Scientific Notes ## 1. ATSI remains CHL-driven The ATSI philosophy is preserved. Even in RS-ATSI, the final trophic score is derived from CHL. ## 2. SAL is not directly aggregated SAL is used to determine the correct threshold context, not directly scored as trophic response. ## 3. RS-ATSI requires proper collocation Scientific performance depends strongly on the quality of: - spectral inputs - in-situ CHL - in-situ or matched SAL - spatial and temporal collocation ## 4. Spatial validation matters High overall accuracy can still hide local failures. This is why the package includes: - site-wise validation - station-season agreement - zone-level spatial realism summaries ## 5. Score control All ATSI scores are clipped to: - minimum = 0 - maximum = 100 This prevents physically or methodologically invalid values. --- # Current ATSI Classification The current release includes an **operational 4-class translation**: - `Unpolluted` - `Moderate` - `Eutrophic` - `Hypertrophic` If you want to apply exact final paper-based class boundaries, update: ```python atsimodel/classification.py ``` --- # Limitations This release is a strong operational and research prototype, but it does **not yet include**: - uncertainty quantification - prediction intervals - SHAP explainability - multi-model comparison - raster-based Sentinel-3 ingestion - atmospheric correction workflow - geospatial map production - kriging / hotspot surface interpolation - automated figure export suite --- # Recommended Future Upgrades Suggested next upgrades for a journal-grade RS-ATSI platform: - multi-model CHL prediction - best-model auto-selection - uncertainty-aware RS-ATSI - SHAP feature importance - raster image support - map generation - station-level diagnostic plotting - PDF report generation --- # Citation If you use this package in academic work, please cite: **Uddin, M. G., Nash, S., Rahman, A., Dabrowski, T., & Olbert, A. I. (2024). Data-driven modelling for assessing trophic status in marine ecosystems using machine learning approaches. Environmental Research, 242, 117755. https://doi.org/10.1016/j.envres.2023.117755** ### Suggested software citation **Uddin, M. G. (2026). ATSIModel: Python package for computing ATSI and RS-ATSI for transitional and coastal waters.** --- # Contact For scientific collaboration, package development, or method-related questions: **Dr Md Galal Uddin** School of Engineering, University of Galway, Ireland Email: **jalaluddinbd1987@gmail.com** --- # License This project is distributed under the **MIT License**.