Merge pull request #59 from debpal/main

Performance metrics and Sobol indices

Author: debpal

README.md

@@ -38,6 +38,7 @@
 - Modify parameters via the `calibration.cal` file.
 - Run SWAT+ simulations.
 - Perform sensitivity analysis on model parameters using the [SALib](https://github.com/SALib/SALib) Python package, with support for parallel computation.
+- Compute performance metrics using widely adopted indicators and derive Sobol sensitivity indices.
 
 
 ## 📥 Install pySWATPlus

docs/changelog.md

@@ -1,5 +1,30 @@
 # Release Notes
 
+## Version 1.2.0 (Month DD, YYYY, not released yet)
+
+- Introduced the `pySWATPlus.DataManager` class with the following methods to support data processing workflows:
+  
+    - `read_sensitive_dfs`: Reads sensitivity simulation data generated by the `simulation_by_sobol_sample` method in the `pySWATPlus.SensitivityAnalyzer` class.  
+    - `simulated_timeseries_df`: Moved from the `pySWATPlus.SensitivityAnalyzer` class for improved modularity.
+
+- Introduced the `pySWATPlus.PerformanceMetrics` class to compute performance metrics between simulated and observed values using the following indicators:
+  
+    - Nash–Sutcliffe Efficiency  
+    - Kling–Gupta Efficiency  
+    - Mean Squared Error  
+    - Root Mean Squared Error  
+    - Percent Bias
+    - Mean Absolute Relative Error
+
+- Added the `sobol_indices` method to the `pySWATPlus.SensitivityAnalyzer`** class for computing Sobol indices using the available indicators in the `pySWATPlus.PerformanceMetrics` class.
+
+- Added new methods to the `pySWATPlus.TxtinoutReader` class:
+  
+    - `set_simulation_timestep`: Modifies the simulation timestep in the `time.sim` file.  
+    - `set_print_interval`: Modifies the print interval in the `print.prt` file.
+
+- All SWAT+ simulations with modified parameters are now configured through the `calibration.cal` file, eliminating the need to read and modify individual input files.
+
 
 ## Version 1.1.0 (August 26, 2025)
 

docs/userguide/data_analysis.md

@@ -0,0 +1,97 @@
+# Data Analysis
+
+This section explains how to analysis data generated by different interfaces.
+
+```python
+import pySWATPlus
+```
+
+
+## Time Series Data
+
+A standard `SWAT+` simulation generates TXT files with time series columns: `day`, `mon`, and `yr` for day, month, and year, respectively.
+The following method creates a time series `DataFrame` that includes a new `date` column with `datetime.date` objects and save the resulting DataFrame to a JSON file.
+
+```python
+import pySWATPlus
+
+output = pySWATPlus.DataManager().simulated_timeseries_df(
+    data_file=r"C:\Users\Username\custom_folder\channel_sd_mon.txt",
+    has_units=True,
+    begin_date='01-Jun-2011',
+    end_date='01-Jun-2013',
+    ref_day=15,
+    apply_filter={'name': ['cha561']},
+    usecols=['name', 'flo_out'],
+    json_file=r"C:\Users\Username\output_folder\tmp.json"
+)
+
+print(output)
+```
+
+
+## Read Sensitivity Simulation Data
+
+The sensitivity analysis performed using the [`simulation_by_sobol_sample`](https://swat-model.github.io/pySWATPlus/api/sensitivity_analyzer/#pySWATPlus.SensitivityAnalyzer.simulation_by_sobol_sample) method generates a file named `sensitivity_simulation.json` within the simulation directory.  
+This JSON file contains all the information required for Sobol sensitivity analysis, including:
+
+- `problem`: Sobol problem definition  
+- `sample`: List of generated samples  
+- `simulation`: Simulated `DataFrame` corresponding to each sample  
+
+To retrieve the selected `DataFrame` for all scenarios, use:
+
+```python
+output = pySWATPlus.DataManager().read_sensitive_dfs(
+    sim_file=r"C:\Users\Username\simulation_folder\sensitivity_simulation.json",
+    df_name='channel_sd_mon_df',
+    add_problem=True,
+    add_sample=True
+)
+```
+
+## Performance Metrics 
+
+For a selected `DataFrame`, performance metrics across all scenarios can be computed by comparing model outputs with observed data.
+
+To view the mapping between performance indicators and their abbreviations:
+
+```python
+indicators = pySWATPlus.PerformanceMetrics().indicator_names
+```
+
+To compute performance metrics for the desired indicators:
+
+
+```python
+output = pySWATPlus.SensitivityAnalyzer().scenario_indicators(
+    sim_file=r"C:\Users\Username\simulation_folder\sensitivity_simulation.json",
+    df_name='channel_sd_mon_df',
+    sim_col='flo_out',
+    obs_file=r"C:\Users\Username\observed_folder\discharge_monthly.csv",
+    date_format='%Y-%m-%d',
+    obs_col='discharge',
+    indicators=['NSE', 'MSE'],
+    json_file=r"C:\Users\Username\data_analysis\performance_metrics.json"
+)
+```
+
+## Sobol Indices
+
+The available indicators can also be used to compute Sobol indices (first, second, and total orders) along with their confidence intervals.
+
+```python
+output = pySWATPlus.SensitivityAnalyzer().sobol_indices(
+    sim_file=r"C:\Users\Username\simulation_folder\sensitivity_simulation.json",
+    df_name='channel_sd_mon_df',
+    sim_col='flo_out',
+    obs_file=r"C:\Users\Username\observed_folder\discharge_monthly.csv",
+    date_format='%Y-%m-%d',
+    obs_col='discharge',
+    indicators=['KGE', 'RMSE'],
+    json_file=r"C:\Users\Username\data_analysis\sobol_indices.json"
+)
+```
+
+
+