IEWQImodel

IEWQImodel is a Python package for computing the Irish Water Quality Index (IEWQI) and related comparative water quality indices for transitional and coastal waters.

The package implements:

• IEWQI / WQM-WQI (Weighted Quadratic Mean)
• RMS-WQI (Root Mean Square)
• AM-WQI (Arithmetic Mean)
• Sub-index (SI) computation
• Salinity-adjusted thresholds
• Classification
• Eclipsing detection
• Ambiguity detection
• Export-ready outputs

---

Author

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

---

Scientific References

If you use this package, please cite:

1. Uddin, M.G. et al. (2022) A comprehensive method for improvement of water quality index (WQI) models for coastal water quality assessment Water Research DOI: https://doi.org/10.1016/j.watres.2022.118532

2. Uddin, M.G. et al. (2023) A sophisticated model for rating water quality Science of the Total Environment DOI: https://doi.org/10.1016/j.scitotenv.2023.161614

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

---

Features

• Compute IEWQI / WQM-WQI

• Compute RMS-WQI

• Compute AM-WQI

• Compute Sub-index (SI) values

• Apply salinity-adjusted thresholds

• Classify water quality into:

  • Good
  • Fair
  • Marginal
  • Poor

• Diagnose:

  • Eclipsing
  • Ambiguity

• Export results to Excel or CSV

---

Installation

pip install IEWQImodel==2.3.6

---

Required Input Columns

The model requires the following input variables.

Accepted internal required columns

["bod5", "dox", "din", "mrp", "ph", "sal", "temp", "ton", "tran"]

Typical user-facing input names

Variable	Description
BOD5	Biological Oxygen Demand
DOX	Dissolved Oxygen (%)
DIN	Dissolved Inorganic Nitrogen
MRP	Molybdate Reactive Phosphorus
pH	Acidity / alkalinity
SAL	Salinity
TEMP	Water Temperature
TON	Total Organic Nitrogen
TRAN	Transparency

Important notes

• SAL is mandatory because the package derives moving thresholds for:

  • DOX
  • DIN
  • MRP

• Thresholds are computed from the median salinity of the input dataset unless you manually provide sal_median.

---

Example Input File

The input file should contain these columns (case-insensitive aliases are supported internally):

BOD5	DOX	DIN	MRP	pH	SAL	TEMP	TON	TRAN
2.1	96	0.35	0.021	8.1	31.2	16.5	0.85	1.4
4.3	88	0.52	0.030	7.9	29.8	18.1	1.10	1.1

---

Quick Start

Example 1 — Compute from a Python dictionary

from IEWQImodel import IEWQI

model = IEWQI()

data = {
    "BOD5": 2.3,
    "DOX": 95,
    "DIN": 0.4,
    "MRP": 0.02,
    "pH": 8.1,
    "SAL": 30,
    "TEMP": 15,
    "TON": 0.8,
    "TRAN": 1.5
}

result = model.compute(data)
print(result)

---

Basic Usage with Excel File

import pandas as pd
from IEWQImodel import IEWQI

# Input and output paths
input_file = "/content/data_WQ25.xlsx"
output_file = "IEWQI_results45.xlsx"

# Load dataset
df = pd.read_excel(input_file)

# Initialize model
model = IEWQI()

# Compute:
# - IEWQI (WQM-WQI)
# - RMS-WQI
# - AM-WQI
# - Sub-index (SI) values
# - Water quality classes
# - Eclipsing and ambiguity diagnostics
results = model.compute(df)

# Export results
results.to_excel(output_file, index=False)

# Preview
print(results.head())

---

Optional: Use a Fixed Salinity Median

By default, the package computes thresholds using the median SAL from the dataset.

If needed, you can manually specify a fixed salinity median:

import pandas as pd
from IEWQImodel import IEWQI

df = pd.read_excel("/content/data_WQ25.xlsx")

model = IEWQI()

results = model.compute(df, sal_median=30.5)

print(results.head())

---

Optional: Strict Validation

Strict validation ensures that all:

• Sub-index (SI) values remain within 0–100
• Final WQI scores remain within 0–100

import pandas as pd
from IEWQImodel import IEWQI

df = pd.read_excel("/content/data_WQ25.xlsx")

model = IEWQI(strict_validation=True)

results = model.compute(df)

print(results.head())

---

Direct Export Example

You can export results directly without manually reading/writing files:

from IEWQImodel import IEWQI

model = IEWQI()

model.export_results(
    data="/content/data_WQ25.xlsx",
    output_path="IEWQI_results45.xlsx"
)

You can also export to CSV:

from IEWQImodel import IEWQI

model = IEWQI()

model.export_results(
    data="/content/data_WQ25.xlsx",
    output_path="IEWQI_results45.csv"
)

---

Output

The package returns a results table containing the original variables, thresholds used, sub-index values, final scores, classification, and diagnostics.

Original variables

• BOD5
• DOX
• DIN
• MRP
• pH
• SAL
• TEMP
• TON
• TRAN

Thresholds used

• SAL_Median_Used
• BOD5_L, BOD5_U
• DOX_L, DOX_U
• DIN_L, DIN_U
• MRP_L, MRP_U
• pH_L, pH_U
• TEMP_U
• TON_L, TON_U
• TRAN_L

Sub-index values

• SI_BOD5
• SI_DOX
• SI_DIN
• SI_MRP
• SI_pH
• SI_TEMP
• SI_TON
• SI_TRAN

Final scores

• IEWQI_score
• RMS_WQI_score
• AM_WQI_score

Water quality classes

• IEWQI_Class
• RMS_WQI_Class
• AM_WQI_Class

Diagnostics

• Breach_Count
• Breach_Indicators
• IEWQI_Eclipsing
• RMS_WQI_Eclipsing
• AM_WQI_Eclipsing
• IEWQI_Ambiguity
• RMS_WQI_Ambiguity
• AM_WQI_Ambiguity

Summary columns

• Min_SI
• Max_SI

---

Classification Scheme

Score Range	Water Quality Class
80–100	Good
50–79	Fair
30–49	Marginal
0–29	Poor

---

Scientific Notes

IEWQI / WQM-WQI

The package computes the Irish Water Quality Index (IEWQI) using the Weighted Quadratic Mean (WQM) formulation:

[ WQM = \sqrt{\sum_{i=1}^{n} w_i s_i^2} ]

where:

• (w_i) = normalized indicator weights
• (s_i) = sub-index values on a 0–100 scale
• (n) = number of indicators included in the computation

The implemented default weights correspond to the published IEWQI structure.

RMS-WQI

The Root Mean Square Water Quality Index (RMS-WQI) is computed as:

[ RMS = \sqrt{\frac{1}{n}\sum_{i=1}^{n} s_i^2} ]

This provides an unweighted comparison index that is more sensitive to lower-performing sub-indices than a simple arithmetic mean.

AM-WQI

The Arithmetic Mean Water Quality Index (AM-WQI) is computed as:

[ AM = \frac{1}{n}\sum_{i=1}^{n} s_i ]

This is the simplest comparative aggregation and is useful for benchmarking against WQM- and RMS-based scores.

Sub-index (SI) scaling

All indicators are first converted into sub-index (SI) values on a 0–100 scale before aggregation.

• 0 = worst water quality condition
• 100 = best water quality condition

The package uses:

• monotonic decreasing SI functions for indicators where lower values are better (e.g., BOD5, DIN, MRP, TON)
• band-based SI functions for indicators such as DOX and pH
• binary threshold logic for indicators such as TEMP and TRAN

Salinity-adjusted thresholds

The package uses SAL (salinity) to derive moving thresholds for:

• DOX
• DIN
• MRP

This follows the published IEWQI methodology where salinity is used to obtain water-quality standards for transitional and coastal systems.

Classification

Final index scores are interpreted using the following four-class system:

• Good: 80–100
• Fair: 50–79
• Marginal: 30–49
• Poor: 0–29

Eclipsing and ambiguity diagnostics

The package includes diagnostic checks for:

• Eclipsing: whether aggregated scores mask the number of breached indicators
• Ambiguity: whether the final class appears inconsistent with the severity of the worst-performing sub-indices

These diagnostics are intended to help users compare the behavior of different aggregation approaches.

Score bounding and validity

To preserve scientific consistency:

• all sub-index values are constrained to 0–100
• all final WQI scores are constrained to 0–100
• negative values are automatically converted to 0
• values above 100 are automatically converted to 100

This prevents invalid scores caused by input anomalies or computational overflow.

---

Citation

If you use this package in academic work, please cite:

Uddin, M.G. et al. (2023) A sophisticated model for rating water quality Science of the Total Environment https://doi.org/10.1016/j.scitotenv.2023.161614

---

License

MIT License