Metadata-Version: 2.4
Name: ATSIModel
Version: 2.0.5
Summary: Python package for computing ATSI (Assessment of Trophic Status Index) and trophic classification using CHL and SAL data.
Author-email: Dr Md Galal Uddin <jalaluddinbd1987@gmail.com>
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
Dynamic: license-file

# ATSIModel

## Assessment of Trophic Status Index (ATSI) Python Package

**ATSIModel** is an open-source Python package for computing the **Assessment of Trophic Status Index (ATSI)** for **transitional and coastal waters** using **chlorophyll-a (CHL)** and **salinity (SAL)** data.

The package is designed to provide a **simple, reproducible, and scientifically structured workflow** for assessing trophic status in aquatic ecosystems, especially in **marine, estuarine, and transitional water environments**.

---

# 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**: School of Engineering / EcoHydroInformatics Research Group (EHIRG)

---

# Scientific Background

Assessing eutrophication and trophic status in coastal and transitional waters is critical for:

- ecosystem health monitoring
- marine environmental management
- eutrophication assessment
- water quality reporting
- decision-support for policy and management

Traditional trophic status assessment methods often suffer from:

- multicollinearity among water quality indicators
- data redundancy
- rigid or inappropriate classification structures
- limited transferability across salinity gradients
- inconsistent transformation and scoring approaches

To address these limitations, the **Assessment of Trophic Status Index (ATSI)** was developed as a more flexible and data-driven framework for trophic assessment in **transitional and coastal waters**.

In the ATSI methodology, **chlorophyll-a (CHL)** is treated as the principal trophic response indicator, while **salinity (SAL)** is used to determine **moving guideline threshold values** across the estuarine-to-marine salinity continuum.

This package implements a **CHL-based ATSI computation workflow** with **salinity-dependent thresholding**.

---

# Scientific Basis of This Package

This package implements the ATSI concept as a **CHL-driven trophic status model** where:

- **CHL** is the direct trophic status input
- **SAL** is used to determine the **appropriate CHL thresholds**
- ATSI is computed using a **linear rescaling interpolation function**
- ATSI score is translated into a **trophic classification**

---

# Related Scientific Work

This software is conceptually aligned with the broader research development and evolution of advanced water quality assessment frameworks and modelling approaches, including the author’s work on:

### Example related research theme:
**Data-driven modelling for assessing trophic status in marine ecosystems using machine learning approaches; Details can be found at https://doi.org/10.1016/j.envres.2023.117755**

This package also aligns with broader scientific efforts in:

- water quality index development
- machine learning-based environmental assessment
- eutrophication monitoring
- uncertainty-aware environmental modelling
- ecohydroinformatics and intelligent environmental systems

For more of the author's scientific outputs, please see the **Google Scholar profile** above.

---

# Key Features

## ATSIModel can:

- Compute **ATSI scores** from:
  - Excel files (`.xlsx`, `.xls`)
  - CSV files (`.csv`)
  - text files (`.txt`)
- Use **CHL + SAL** as required inputs
- Automatically determine **moving CHL thresholds** from salinity
- Compute ATSI scores on a **0–100 scale**
- Prevent invalid ATSI values:
  - no negative scores
  - no scores > 100
- Translate ATSI scores into **trophic status classes**
- Export results to:
  - Excel
  - CSV
  - JSON
- Generate basic plots for:
  - ATSI distribution
  - CHL vs ATSI relationship

---

# Installation

## From local folder

```bash
pip install .
```

## From PyPI (after release)

```bash
pip install ATSIModel
```

---

# Required Python Version

- Python **3.9+** recommended

---

# Dependencies

The package requires:

- `pandas`
- `numpy`
- `matplotlib`
- `openpyxl`

These are automatically installed if using `pip`.

---

# Required Input Data

## Minimum required columns

The ATSIModel package requires only **two input variables**:

| Column | Description | Unit |
|--------|-------------|------|
| `CHL`  | Chlorophyll-a concentration | µg/L |
| `SAL`  | Salinity | PSU |

### Important:
- Column names should preferably be exactly:
  - `CHL`
  - `SAL`
- Input data can contain additional columns (e.g., Date, Site, Station, Latitude, Longitude), but ATSIModel only requires `CHL` and `SAL`.

---

# Input File Formats

The package supports:

- **Excel** → `.xlsx`, `.xls`
- **CSV** → `.csv`
- **Text files** → `.txt`

---

# Example Input Data Pattern

## Example 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 for ATSI calculation.

---

# Example Usage (Python)

## Basic use

```python
from atsimodel.core import run_atsi

df = run_atsi("sample_atsi_input.xlsx")
print(df.head())
```

---

## Export results

```python
from atsimodel.core import run_atsi
from atsimodel.utils import export_results

df = run_atsi("sample_atsi_input.xlsx")

export_results(
    df,
    out_base="outputs/ATSI_results",
    formats=("xlsx", "csv", "json")
)
```

---

## Plot ATSI outputs

```python
from atsimodel.core import run_atsi
from atsimodel.plotting import plot_atsi_distribution, plot_chl_vs_atsi

df = run_atsi("sample_atsi_input.xlsx")

plot_atsi_distribution(df)
plot_chl_vs_atsi(df)
```

---

# Example Usage (Full Script)

```python
from atsimodel.core import run_atsi
from atsimodel.utils import export_results
from atsimodel.plotting import plot_atsi_distribution, plot_chl_vs_atsi

file_path = "examples/sample_atsi_input.xlsx"

df = run_atsi(file_path)

print(df.head())

export_results(df, out_base="outputs/ATSI_results", formats=("xlsx", "csv", "json"))

plot_atsi_distribution(df)
plot_chl_vs_atsi(df)
```

---

# How ATSIModel Works

The workflow of ATSIModel consists of the following steps:

## Step 1 — Read Input Data
The package reads CHL and SAL values from a supported input file.

## Step 2 — Standardize and Validate Inputs
Input columns are cleaned and validated to ensure the required fields are present.

## Step 3 — Determine Moving CHL Thresholds
The package assigns **CHL threshold values** based on the **salinity median values**.

This step follows the ATSI concept where threshold values vary across the salinity continuum rather than remaining fixed.

## Step 4 — Compute ATSI Score
ATSI is computed using a **linear rescaling interpolation function**.

The ATSI score is always constrained to:

- **minimum = 0**
- **maximum = 100**

## Step 5 — Translate ATSI Score into Trophic Class
The ATSI score is converted into a categorical trophic status label.

---

# ATSI Score Range

The ATSI score ranges from:

- **0 = worst trophic condition**
- **100 = best trophic condition**

This package automatically ensures that ATSI values:

- cannot be negative
- cannot exceed 100

---

# Threshold Determination

## Important scientific note

ATSIModel does **not use a fixed CHL threshold** for all waters.

Instead, it uses **salinity-dependent moving threshold values**, because:

- estuarine waters and marine waters behave differently
- trophic expectations vary across the salinity gradient
- a single static threshold can misrepresent ecological condition

Thus, ATSIModel dynamically determines:

- `CHL_TL` → lower threshold
- `CHL_TU` → upper threshold

based on the supplied **SAL** value.

---

# Output Columns

After running the model, the following columns are typically added:

| Column | Description |
|--------|-------------|
| `SAL_BIN` | Rounded salinity median bin used for threshold lookup |
| `CHL_TL` | Lower CHL threshold |
| `CHL_TU` | Upper CHL threshold |
| `ATSI` | Computed ATSI score |
| `ATSI_Class` | ATSI trophic class |

---

# Example Output

| CHL | SAL | SAL_BIN | CHL_TL | CHL_TU | ATSI | ATSI_Class |
|-----|-----|---------|--------|--------|------|------------|
| 8.5 | 31.2 | 31 | 11.1 | 22.2 | 100.0 | Unpolluted |
| 15.1 | 28.7 | 29 | 11.7 | 23.3 | 85.4 | Unpolluted |
| 4.3 | 33.1 | 33 | 10.6 | 21.1 | 100.0 | Unpolluted |

---

# Scientific Notes

## 1. ATSI is CHL-driven
This package computes ATSI from **chlorophyll-a only**, while using **salinity to define the threshold context**.

## 2. SAL is a threshold-conditioning variable
SAL is not directly transformed into ATSI. Instead, it is used to identify the correct CHL threshold values.

## 3. ATSI is a relative ecological scoring framework
ATSI should be interpreted as a **structured trophic assessment score**, not simply a raw concentration transformation.

## 4. This package is intended for:
- transitional waters
- estuaries
- coastal waters
- salinity-gradient systems

## 5. This package should not be blindly used for:
- freshwater lakes
- rivers
- highly unusual salinity regimes
without scientific justification or threshold adjustment.

---

# Recommended Good Practice

For best scientific use, users should:

- ensure CHL values are quality controlled
- ensure SAL values are representative of the sampling condition
- use consistent units
- avoid mixing incompatible monitoring programmes
- inspect outliers before analysis
- use ATSI alongside ecological and regulatory context

---

# Limitations

This package currently focuses on the **core ATSI workflow**.

Current release does **not yet include**:

- uncertainty quantification
- Monte Carlo ATSI
- machine learning CHL prediction
- remote sensing ATSI
- spatial ATSI mapping
- ATSI sensitivity analysis
- ATSI confidence intervals

These may be included in future releases.

---

# Future Development

Planned future upgrades may include:

- ML-based CHL prediction
- uncertainty-aware ATSI
- ATSI mapping and GIS integration
- remote sensing ATSI workflows
- batch station processing
- interactive dashboards
- journal-ready reporting outputs

---

# Citation

If you use this package in scientific work, please cite the associated ATSI methodology and relevant publications by the author.

### Suggested software citation
**Uddin, M. G. (2026). ATSIModel: Python package for computing the Assessment of Trophic Status Index (ATSI).**

---

# Author’s Broader Research

For additional related scientific work, see:

- Google Scholar profile:  
  https://scholar.google.com/citations?user=g6xaAOkAAAAJ&hl=en

This includes work on:

- Irish Water Quality Index (IEWQI)
- trophic status modelling
- machine learning for water quality
- ecohydroinformatics
- uncertainty-aware environmental assessment
- environmental intelligence systems

---

# License

This project is distributed under the **MIT License**.

---

# Contact

For scientific collaboration, methodological questions, or package improvement suggestions:

**Dr Md Galal Uddin**  
School of Engineering, University of Galway, Ireland  
Email: **jalaluddinbd1987@gmail.com**
