Merge pull request #66 from debpal/main

Pull request summary

Author: debpal

README.md

@@ -35,7 +35,7 @@
 
 ## ✨ Key Features
 
-- Run `SWAT+` simulations by modifying model parameters through the  `calibration.cal` file..
+- Run `SWAT+` simulations by modifying model parameters through the  `calibration.cal` file.
 - Evaluate model performance against observed data using widely recognized statistical indicators.
 - Perform sensitivity analysis on model parameters using the [`SALib`](https://github.com/SALib/SALib) Python package.
 - Calibrate model parameters through multi-objective optimization and evolutionary algorithms using the [`pymoo`](https://github.com/anyoptimization/pymoo) Python package. 

docs/changelog.md

@@ -6,6 +6,8 @@
 
 - Added the `pySWATPlus.SensitivityAnalyzer.simulation_and_indices` method to compute sensitivity indices directly against observed data without saving detailed simulation results.
 
+- Added the `pySWATPlus.PerformanceMetrics.indicator_from_file` method to compute performance metrics directly for simulated and observed files.
+
 
 ## Version 1.2.0 (October 13, 2025)
 

docs/userguide/data_analysis.md

@@ -2,7 +2,12 @@
 
 This section explains how to analysis data generated by different interfaces.
 
-## Time Series Data
+## Simulation Data
+
+This section analyzes the simulation data generated using the
+[`run_swat`](https://swat-model.github.io/pySWATPlus/api/txtinout_reader/#pySWATPlus.TxtinoutReader.run_swat) method.
+
+### Extract 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.
@@ -22,13 +27,33 @@ output = pySWATPlus.DataManager().simulated_timeseries_df(
 )
 ```
 
-## Statistics from Daily Time Series
+### Model Performance
+
+Model performance can be evaluated by comparing simulated outputs with observed data, using selected indicators available in the property [`indicator_names`](https://swatmodel.github.io/pySWATPlus/api/performance_metrics/#pySWATPlus.PerformanceMetrics.indicator_names).
+
+
+```python
+output = pySWATPlus.PerformanceMetrics().indicator_from_file(
+    sim_file=r"C:\Users\Username\custom_folder\channel_sd_day.txt",
+    sim_col='flo_out',
+    extract_sim={
+        'has_units': True,
+        'apply_filter': {'name': ['cha561']}
+    },
+    obs_file=r"C:\Users\Username\observed_folder\discharge_daily.csv",
+    date_format='%Y-%m-%d',
+    obs_col='discharge',
+    indicators=['NSE', 'KGE', 'RMSE']
+)
+```
+
+### Statistics from Daily Time Series
 
 Monthly and yearly statistics such as maximum, minimum, mean, and standard deviation derived from daily time series data help summarize and interpret simulation variability over time.
 The following interface computes monthly and yearly statistical summaries for a Hydrological Response Unit (HRU) based on daily simulated flow discharge data. These metrics provide insight into seasonal patterns, flow extremes, and overall hydrological stability.
 
 ```python
-output = pySWATPlus.DataManager().simulated_timeseries_df(
+output = pySWATPlus.DataManager().hru_stats_from_daily_simulation(
     sim_file=r"C:\Users\Username\custom_folder\channel_sd_day.txt",
     has_units=True,
     gis_id=561,
@@ -37,7 +62,11 @@ output = pySWATPlus.DataManager().simulated_timeseries_df(
 )
 ```
 
-## Read Sensitivity Simulation Data
+## Sensitivity Simulation Scenarios
+
+This section analyzes the time series scenarios generated from the sensitivity analysis based on sampled parameters.
+
+### Read Time Series Scenarios
 
 The sensitivity analysis performed using the
 [`simulation_by_sample_parameters`](https://swat-model.github.io/pySWATPlus/api/sensitivity_analyzer/#pySWATPlus.SensitivityAnalyzer.simulation_by_sample_parameters) method generates a file named `sensitivity_simulation.json`. This JSON file contains all the information required for sensitivity analysis, including:
@@ -46,7 +75,7 @@ The sensitivity analysis performed using the
 - `sample`: List of generated samples  
 - `simulation`: Simulated `DataFrame` corresponding to each sample  
 
-To retrieve the selected `DataFrame` for all scenarios, use:
+To retrieve the selected time series `DataFrame` for all scenarios, use:
 
 ```python
 output = pySWATPlus.DataManager().read_sensitive_dfs(
@@ -57,31 +86,23 @@ output = pySWATPlus.DataManager().read_sensitive_dfs(
 )
 ```
 
-## Scenario Metrics
-
-For a selected `DataFrame`, scenario metrics across all simulations can be computed by comparing model outputs with observed data.
+### Scenario Performance
 
+For a selected `DataFrame`, the performance of all sensitivity scenarios can be assessed by comparing simulated outputs with observed data, using selected indicators available in the property [`indicator_names`](https://swatmodel.github.io/pySWATPlus/api/performance_metrics/#pySWATPlus.PerformanceMetrics.indicator_names).
 
-- To get the mapping between available indicators and their abbreviations:
 
-    ```python
-    indicators = pySWATPlus.PerformanceMetrics().indicator_names
-    ```
-
-- To compute metrics for all scenarios using the desired indicators:
-
-    ```python
-    output = pySWATPlus.SensitivityAnalyzer().scenario_indicators(
-        sensim_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"
-    )
-    ```
+```python
+output = pySWATPlus.SensitivityAnalyzer().scenario_indicators(
+    sensim_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"
+)
+```
 
 
 

docs/userguide/sensitivity_interface.md

@@ -61,8 +61,14 @@ Currently, it supports [Sobol](https://doi.org/10.1016/S0378-4754(00)00270-6) sa
 - Structured export of results for downstream analysis
 
 
+!!! warning
+    Before executing the following high-level interafce, comment out the code shown in
+    [`Configuration Settings`](https://swat-model.github.io/pySWATPlus/userguide/sensitivity_interface/#configuration-settings)
+    to avoid overwriting configuration files that may occur when rerunning the setup, which could affect the target results.
+
+
 ```python
-# Sensitivity parameter space
+# Define parameter space
 parameters = [
     {
         'name': 'esco',
@@ -78,7 +84,7 @@ parameters = [
     }
 ]
 
-# Target data extraction from sensitivity simulation
+# Configuration of data extraction
 extract_data = {
     'channel_sdmorph_yr.txt': {
         'has_units': True,
@@ -108,12 +114,6 @@ if __name__ == '__main__':
     print(output)
 ```
 
-
-!!! tip "Troubleshooting Parallel Processing Errors"
-    If you encounter an error related to `concurrent.futures.ProcessPoolExecutor` and  `multiprocessing` without a clear description,
-    try closing the current command terminal and restarting it. This issue can occasionally occur due to lingering background processes
-    or locked resources from previous runs.
-
 ## Sensitivity Indices
 
 Sensitivity indices (first, second, and total orders) are computed using the indicators available in the `pySWATPlus.PerformanceMetrics` class, along with their confidence intervals.
@@ -135,7 +135,7 @@ output = pySWATPlus.SensitivityAnalyzer().parameter_sensitivity_indices(
 
 ## Integrated Simulation and Sensitivity
 
-To compute sensitivity indices directly for multiple outputs against observed data and skip saving the detailed simulation results, use the following interface:
+To compute sensitivity indices for multiple outputs against observed data without saving detailed simulation time series for each parameter sample, use the following interface.
 
 
 ```python
@@ -156,7 +156,7 @@ parameters = [
 ]
 
 
-# Extract data configuration
+# Configuration of simulation data extraction
 extract_data = {
     'channel_sd_day.txt': {
         'has_units': True,
@@ -169,7 +169,7 @@ extract_data = {
     }
 }
 
-# Observe data configuration
+# Configuration of observes data
 observe_data = {
     'channel_sd_day.txt': {
         'obs_file': r"C:\Users\Username\observed_folder\discharge_daily.csv",
@@ -181,7 +181,7 @@ observe_data = {
     }
 }
 
-# Metric configuration
+# Configuration of performance metrics
 metric_config = {
     'channel_sd_day.txt': {
         'sim_col': 'flo_out',
@@ -200,11 +200,18 @@ if __name__ == '__main__':
     output = pySWATPlus.SensitivityAnalyzer().simulation_and_indices(
         parameters=parameters,
         sample_number=1,
-        sensim_dir=r"C:\Users\dpal22\Desktop\swat_run\experiment_dominant_hru\empty_dir",
-        txtinout_dir=r"C:\Users\dpal22\Desktop\swat_run\experiment_dominant_hru\txtinout_copy",
+        sensim_dir=sim_dir,
+        txtinout_dir=r"C:\Users\Username\custom_folder",
         extract_data=extract_data,
         observe_data=observe_data,
         metric_config=metric_config
     )
     print(output)
-```
+```
+
+
+
+!!! tip "Troubleshooting Parallel Processing Errors"
+    If you encounter an error related to `concurrent.futures.ProcessPoolExecutor` and  `multiprocessing` without a clear description,
+    try closing the current command terminal and restarting it. This issue can occasionally occur due to lingering background processes
+    or locked resources from previous runs.

docs/userguide/swatplus_simulation.md

@@ -4,7 +4,7 @@
 
 To run a `SWAT+` simulation, the `TxtInOut` folder must include all required input files, which are created during simulation setup in the [SWAT+ Editor](https://github.com/swat-model/swatplus-editor) via `QSWAT+`.
 
-Additionally, the `TxtInOut` folder must contain the `SWAT+` executable. If you need help locating it, open the **`Run SWAT+`** tab in the `SWAT+ Editor` to find its path. Once located, copy the executable file into the `TxtInOut` folder. If the executable is missing, the simulation will fail.
+Additionally, the `TxtInOut` folder must contain the `SWAT+` executable. The executable file compatible with your operating system and `SWAT+` version can be obtained from the [official GitHub releases](https://github.com/swat-model/swatplus/releases).
 
 Once the `TxtInOut` folder is properly configured with the necessary input files and the `SWAT+` executable, you can initialize the `TxtinoutReader` class to interact with the `SWAT+` model:
 
@@ -14,6 +14,7 @@ import pySWATPlus
 # Replace this with the path to your project's TxtInOut folder
 txtinout_dir = r"C:\Users\Username\project\Scenarios\Default\TxtInOut"
 
+# Initialize TxtinoutReader class
 txtinout_reader = pySWATPlus.TxtinoutReader(
     tio_dir=txtinout_dir
 )
@@ -142,31 +143,30 @@ The following steps demonstrate how to configure parameters in a custom director
 Instead of performing each step separately as explained above, you can run a `SWAT+` simulation in a separate empty directory by configuring all options at once using a single function:
 
 ```python
-# Configure modified parameters
-parameters = [
-    {
-        'name': 'esco',
-        'change_type': 'absval',
-        'value': 0.3
-    },
-    {
-        'name': 'perco',
-        'change_type': 'absval',
-        'value': 0.6
-    }
-]
-
-# Run SWAT+ simulation from the original `TxtInOut` folder
+# Run SWAT+ simulation to a custom directory
 txtinout_reader.run_swat(
-    sim_dir=r"C:\Users\Username\custom_folder",  # mandatory
-    parameters=parameters,  # optional
-    begin_date='01-Jan-2012',  # optional
-    end_date= '31-Dec-2016',  # optional
-    simulation_timestep=0,  # optional
-    warmup=1,  # optional
-    print_prt_control={'channel_sd': {'daily': False}},  # optional
-    print_begin_date='15-Jun-2012',  # optional
-    print_end_date='15-Jun-2016',  # optional
-    print_interval=1  # optional
+    sim_dir=r"C:\Users\Username\empty_folder",  # directory (optional)
+    parameters=[
+        {
+            'name': 'esco',
+            'change_type': 'absval',
+            'value': 0.3
+        },
+        {
+            'name': 'perco',
+            'change_type': 'absval',
+            'value': 0.6
+        }
+    ],  # modified parameter value (optional)
+    begin_date='01-Jan-2012',  # simulation begin date (optional)
+    end_date= '31-Dec-2016',  # simulation end date (optional)
+    simulation_timestep=0,  # simulation time step (optional)
+    warmup=1,  # warm-up years (optional)
+    print_prt_control={
+        'channel_sd': {'daily': False}
+    },  # control print.prt file (optional)
+    print_begin_date='15-Jun-2012',  # begin date to print output (optional)
+    print_end_date='15-Jun-2016',  # end date to print output (optional)
+    print_interval=1  # interval to print output (optional)
 )
 ```

pySWATPlus/calibration.py

@@ -18,9 +18,6 @@
 
 class Calibration(pymoo.core.problem.Problem):  # type: ignore[misc]
     '''
-    Warning:
-        This class is currently under development.
-
     A `Problem` subclass from the [`pymoo`](https://github.com/anyoptimization/pymoo) Python package
     for performing model calibration against observed data using multi-objective optimization
     and evolutionary algorithms.
@@ -376,17 +373,14 @@ def _evaluate(
                     df=merge_df[['sim', 'obs']],
                     norm_col='obs'
                 )
-                # Indicator method from abbreviation
+                # Indicator abbreviation
                 obj_ind = self.objective_config[obj]['indicator']
-                indicator_method = getattr(
-                    PerformanceMetrics(),
-                    f'compute_{obj_ind.lower()}'
-                )
-                # Indicator value computed from method
-                ind_val = indicator_method(
+                # Indicator value
+                ind_val = PerformanceMetrics().compute_from_abbr(
                     df=norm_df,
                     sim_col='sim',
-                    obs_col='obs'
+                    obs_col='obs',
+                    indicator=obj_ind
                 )
                 # Objective value based on maximize or minimize direction
                 obj_val = - ind_val if objs_dirs[obj_ind] == 'max' else ind_val