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

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

pip install .

From PyPI (after release)

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

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

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

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

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

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

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:

RS_ATSI_results_bundle.xlsx

---

RS-ATSI Example — End-to-End Run

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:

atsimodel.plotting

Built-in plotting functions

1. ATSI distribution

from atsimodel.plotting import plot_atsi_distribution
plot_atsi_distribution(df)

2. CHL vs ATSI

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:

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.