Metadata-Version: 2.4
Name: IEWQImodel
Version: 2.3.6
Summary: Irish Water Quality Index (IEWQI) - Full implementation (Uddin et al. 2022 & 2023)/ For details visit at https://scholar.google.com/citations?user=g6xaAOkAAAAJ&hl=en
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20
Requires-Dist: pandas>=1.3

# 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](mailto: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](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](https://doi.org/10.1016/j.scitotenv.2023.161614)

**Google Scholar**
[https://scholar.google.com/citations?user=g6xaAOkAAAAJ&hl=en](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

```bash
pip install IEWQImodel==2.3.6
```

---

## Required Input Columns

The model requires the following **input variables**.

### Accepted internal required columns

```python
["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

```python
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

```python
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:

```python
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**

```python
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:

```python
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:

```python
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](https://doi.org/10.1016/j.scitotenv.2023.161614)

---

## License

MIT License
