ATSIModel 2.0.5

Python package for computing ATSI (Assessment of Trophic Status Index) and trophic classification using CHL and SAL data.

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: [e-mail]

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

pip install .

From PyPI (after release)

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

from atsimodel.core import run_atsi

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

---

Export results

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

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)

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: [e-mail]