Merge pull request #57 from debpal/main

Refactor Sensitivity Analysis Workflow

Author: debpal

README.md

@@ -31,14 +31,12 @@
 
 ## 📦 About
 
-`pySWATPlus` is an open-source Python package that provides a programmatic interface to the [SWAT+](https://swat.tamu.edu/software/plus/) model, allowing users to run simulations, modify input files, and streamline custom experimentation through the model’s `TxtInOut` folder.
-
+`pySWATPlus` is an open-source Python package that provides a programmatic interface to the [SWAT+](https://swat.tamu.edu/software/plus/) model, allowing users to run simulations and conduct custom experiments.
 
 ## ✨ Key Features
 
-- Navigate and read files in the SWAT+ `TxtInOut` folder.
-- Modify input parameters and save the updated files.
-- Run SWAT+ simulations either in the main `TxtInOut` folder or in a user-specified directory.
+- 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.
 
 

docs/api/types.md

@@ -1,3 +1,4 @@
-::: pySWATPlus.types.ParametersType
+::: pySWATPlus.types.ModifyType
+
+::: pySWATPlus.types.BoundType
 
-::: pySWATPlus.types.ParametersBoundedType

docs/index.md

@@ -4,14 +4,12 @@
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14889319.svg)](https://doi.org/10.5281/zenodo.14889319)
 
 
-`pySWATPlus` is an open-source Python package that provides a programmatic interface to the [SWAT+](https://swat.tamu.edu/software/plus/) model, allowing users to run simulations, modify input files, and streamline custom experimentation through the model’s `TxtInOut` folder.
-
+`pySWATPlus` is an open-source Python package that provides a programmatic interface to the [SWAT+](https://swat.tamu.edu/software/plus/) model, allowing users to run simulations and conduct custom experiments.
 
 ## ✨ Key Features
 
-- Navigate and read files in the SWAT+ `TxtInOut` folder.
-- Modify input parameters and save the updated files.
-- Run SWAT+ simulations either in the main `TxtInOut` folder or in a user-specified directory.
+- 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.
 
 

docs/userguide/read_output.md

@@ -3,27 +3,33 @@
 This section explains how to read output data generated from `SWAT+` simulations.  
 It covers accessing results from both standard simulations and Sobol-based sensitivity analyses.
 
----
 
 ## Read Time Series Data
 
-A standard `SWAT+` simulation generates TXT files with time series columns: `day`, `mon`, and `yr` for day, month, and year, respectively. To create a time series `DataFrame` that includes a new `date` column with `datetime.date` objects. Additionally, the method can optionally save the resulting DataFrame to a JSON file. This is controlled by the parameters `save_df` and `json_file`: setting `save_df=True` enables the saving process, and `json_file` specifies the path where the DataFrame will be written.
+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.SensitivityAnalyzer.simulated_timeseries_df(
-    data_file=r"C:\Users\Username\simulation_folder_2\channel_sd_mon.txt",
+    data_file=r"C:\Users\Username\custom_folder\channel_sd_mon.txt",
     has_units=True,
-    start_date='2014-06-01',
-    apply_filter={'yr': [2014, 2015], 'gis_id': [561]},
-    usecols=['gis_id', 'flo_out'],
-    save_df=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 high-level [Sobol-Based Simulation Interface](https://swat-model.github.io/pySWATPlus/userguide/sensitivity_analysis/#sobol-based-simulation-interface) automates the sensitivity analysis workflow using Sobol samples. By default, it generates a file named `sensitivity_simulation_sobol.json` in the simulation folder. This JSON file contains all the information needed to analyze Sobol simulations, including:
+The [sensitivity analysis](https://swat-model.github.io/pySWATPlus/userguide/sensitivity_analysis/) generates a file called `sensitivity_simulation.json` within the simulation folder.
+This JSON file stores all information necessary for Sobol simulation analysis, including:
 
 - `problem`: the Sobol problem definition  
 - `sample`: the generated sample array  
@@ -33,8 +39,8 @@ To retrieve and process this data for further analysis:
 
 ```python
 import json
-import numpy as np
-import pandas as pd
+import numpy
+import pandas
 import io
 
 # Path to the JSON file generated by the Sobol interface
@@ -48,25 +54,23 @@ with open(json_file, 'r') as input_json:
 problem_dict = sensitivity_dict['problem']
 
 # Retrieve the Sobol sample array
-sample_array = np.array(sensitivity_dict['sample'])
+sample_array = numpy.array(sensitivity_dict['sample'])
 
-# Retrieve targeted simulation DataFrames
+# Retrieve targeted DataFrames from sensitivity simulations
 simulation_dict = sensitivity_dict['simulation']
-df_name = 'channel_sd_yr_df'  # Example output
+df_name = 'channel_sd_mon_df'  # Example output
 df_dict = {}
 
 for sim_key, sim_val in simulation_dict.items():
     # Convert JSON string to pandas DataFrame
-    df = pd.read_json(
+    df = pandas.read_json(
         path_or_buf=io.StringIO(sim_val[df_name])
     )
     # Ensure 'date' column is in datetime.date format
     df['date'] = df['date'].dt.date
     df_dict[sim_key] = df
 ```
 
-> **Notes:** `df_dict` contains a `DataFrame` for each simulation key, which can be easily analyzed or plotted. Replace `'channel_sd_yr_df'` with any other output `DataFrame` as needed.
-