Modified variable and function names for a stable release

Author: debpal

pySWATPlus/data_manager.py

@@ -14,7 +14,7 @@ class DataManager:
 
     def simulated_timeseries_df(
         self,
-        target_file: str | pathlib.Path,
+        sim_file: str | pathlib.Path,
         has_units: bool,
         begin_date: typing.Optional[str] = None,
         end_date: typing.Optional[str] = None,
@@ -29,7 +29,7 @@ def simulated_timeseries_df(
         A new `date` column is constructed using `datetime.date` objects from the `yr`, `mon`, and `day` columns.
 
         Args:
-            target_file (str | pathlib.Path): Path to the input file containing time series data generated by
+            sim_file (str | pathlib.Path): Path to the input file containing time series data generated by
                 the method [`run_swat`](https://swat-model.github.io/pySWATPlus/api/txtinout_reader/#pySWATPlus.TxtinoutReader.run_swat).
                 The file must contain `yr`, `mon`, and `day` columns.
 
@@ -72,13 +72,13 @@ def simulated_timeseries_df(
         )
 
         # Absolute file path
-        target_file = pathlib.Path(target_file).resolve()
+        sim_file = pathlib.Path(sim_file).resolve()
 
         # DataFrame from input file
-        skip_rows = [0, 2] if has_units else [0]
-        df = utils._load_file(
-            path=target_file,
-            skip_rows=skip_rows
+        skiprows = [0, 2] if has_units else [0]
+        df = utils._df_extract(
+            input_file=sim_file,
+            skiprows=skiprows
         )
 
         # DataFrame columns
@@ -92,7 +92,7 @@ def simulated_timeseries_df(
         ]
         if len(missing_cols) > 0:
             raise ValueError(
-                f'Missing required time series columns "{missing_cols}" in file "{target_file.name}"'
+                f'Missing required time series columns "{missing_cols}" in file "{sim_file.name}"'
             )
         df[date_col] = pandas.to_datetime(
             df[time_cols].rename(columns={'yr': 'year', 'mon': 'month'})
@@ -105,9 +105,9 @@ def simulated_timeseries_df(
 
         # Fix reference day
         if ref_day is not None:
-            if target_file.stem.endswith(('_day', '_subday')):
+            if sim_file.stem.endswith(('_day', '_subday')):
                 raise ValueError(
-                    f'Parameter "ref_day" is not applicable for daily or sub-daily time series in file "{target_file.name}" '
+                    f'Parameter "ref_day" is not applicable for daily or sub-daily time series in file "{sim_file.name}" '
                     f'because it would assign the same day to all records within a month.'
                 )
             df[date_col] = df[date_col].apply(
@@ -116,9 +116,9 @@ def simulated_timeseries_df(
 
         # Fix reference month
         if ref_month is not None:
-            if target_file.stem.endswith('_mon'):
+            if sim_file.stem.endswith('_mon'):
                 raise ValueError(
-                    f'Parameter "ref_month" is not applicable for monthly time series in file "{target_file.name}" '
+                    f'Parameter "ref_month" is not applicable for monthly time series in file "{sim_file.name}" '
                     f'because it would assign the same month to all records within a year.'
                 )
             df[date_col] = df[date_col].apply(
@@ -128,26 +128,26 @@ def simulated_timeseries_df(
         # Check if filtering by date removed all rows
         if df.empty:
             raise ValueError(
-                f'No data found between "{begin_date}" and "{end_date}" in file "{target_file.name}"'
+                f'No data found between "{begin_date}" and "{end_date}" in file "{sim_file.name}"'
             )
 
         # Filter rows by dictionary criteria
         if apply_filter is not None:
             for col, val in apply_filter.items():
                 if col not in df_cols:
                     raise ValueError(
-                        f'Column "{col}" in apply_filter was not found in file "{target_file.name}"'
+                        f'Column "{col}" in apply_filter was not found in file "{sim_file.name}"'
                     )
                 if not isinstance(val, list):
                     raise TypeError(
-                        f'Column "{col}" in apply_filter for file "{target_file.name}" must be a list, '
+                        f'Column "{col}" in apply_filter for file "{sim_file.name}" must be a list, '
                         f'but got type "{type(val).__name__}"'
                     )
                 df = df.loc[df[col].isin(val)]
                 # Check if filtering removed all rows
                 if df.empty:
                     raise ValueError(
-                        f'Filtering by column "{col}" with values "{val}" returned no rows in "{target_file.name}"'
+                        f'Filtering by column "{col}" with values "{val}" returned no rows in "{sim_file.name}"'
                     )
 
         # Reset DataFrame index
@@ -162,7 +162,7 @@ def simulated_timeseries_df(
             for col in usecols:
                 if col not in df_cols:
                     raise ValueError(
-                        f'Column "{col}" specified in "usecols" was not found in file "{target_file.name}"'
+                        f'Column "{col}" specified in "usecols" was not found in file "{sim_file.name}"'
                     )
             retain_cols = [date_col] + usecols
 
@@ -191,22 +191,23 @@ def simulated_timeseries_df(
 
     def read_sensitive_dfs(
         self,
-        sim_file: pathlib.Path,
+        sensim_file: str | pathlib.Path,
         df_name: str,
         add_problem: bool = False,
         add_sample: bool = False
     ) -> dict[str, typing.Any]:
         '''
-        Read sensitivity simulation data generated by the [`simulation_by_sobol_sample`](https://swat-model.github.io/pySWATPlus/api/sensitivity_analyzer/#pySWATPlus.SensitivityAnalyzer.simulation_by_sobol_sample)
-        method, and return a dictionary mapping each scenario integer to its corresponding `DataFrame`.
+        Read sensitivity simulation data generated by the method
+        [`simulation_by_sample_parameters`](https://swat-model.github.io/pySWATPlus/api/sensitivity_analyzer/#pySWATPlus.SensitivityAnalyzer.simulation_by_sample_parameters),
+        and return a dictionary mapping each scenario integer to its corresponding `DataFrame`.
 
         The returned dictionary may include the following keys:
         - `scenario` (default): A mapping between each scenario integer and its corresponding DataFrame.
         - `problem` (optional): The problem definition.
         - `sample` (optional): The sample list used in the sensitivity simulation.
 
         Args:
-            sim_file (str | pathlib.Path): Path to the `sensitivity_simulation.json` file generated by `simulation_by_sobol_sample`.
+            sensim_file (str | pathlib.Path): Path to the `sensitivity_simulation.json` file generated by `simulation_by_sample_parameters`.
 
             df_name (str): Name of the `DataFrame` within `sensitivity_simulation.json`.
 
@@ -218,12 +219,24 @@ def read_sensitive_dfs(
             A dictionary with the following keys:
 
                 - `scenario` (default): A mapping between each scenario integer and its corresponding DataFrame.
-                - `problem` (optional): The problem definition.
+                - `problem` (optional):  The definition dictionary passed to sampling.
                 - `sample` (optional): The sample list used in the sensitivity simulation.
         '''
 
+        # Check input variables type
+        validators._variable_origin_static_type(
+            vars_types=typing.get_type_hints(
+                obj=self.read_sensitive_dfs
+            ),
+            vars_values=locals()
+        )
+
+        # Absolute file path
+        sensim_file = pathlib.Path(sensim_file).resolve()
+
+        # Sensitiivty output data
         output = utils._retrieve_sensitivity_output(
-            sim_file=sim_file,
+            sensim_file=sensim_file,
             df_name=df_name,
             add_problem=add_problem,
             add_sample=add_sample

pySWATPlus/performance_metrics.py

@@ -48,6 +48,14 @@ def compute_nse(
             obs_col (str): Name of the column containing observed values.
         '''
 
+        # Check input variables type
+        validators._variable_origin_static_type(
+            vars_types=typing.get_type_hints(
+                obj=self.compute_nse
+            ),
+            vars_values=locals()
+        )
+
         # Simulation values
         sim_arr = df[sim_col].astype(float)
 
@@ -79,6 +87,14 @@ def compute_kge(
             obs_col (str): Name of the column containing observed values.
         '''
 
+        # Check input variables type
+        validators._variable_origin_static_type(
+            vars_types=typing.get_type_hints(
+                obj=self.compute_kge
+            ),
+            vars_values=locals()
+        )
+
         # Simulation values
         sim_arr = df[sim_col].astype(float)
 
@@ -106,7 +122,7 @@ def compute_mse(
         obs_col: str
     ) -> float:
         '''
-        Calculate the Mean Squared Error metric between simulated and observed values
+        Calculate the `Mean Squared Error` metric between simulated and observed values
 
         Args:
             df (pandas.DataFrame): DataFrame containing at least two columns with simulated and observed values.
@@ -116,6 +132,14 @@ def compute_mse(
             obs_col (str): Name of the column containing observed values.
         '''
 
+        # Check input variables type
+        validators._variable_origin_static_type(
+            vars_types=typing.get_type_hints(
+                obj=self.compute_mse
+            ),
+            vars_values=locals()
+        )
+
         # Simulation values
         sim_arr = df[sim_col].astype(float)
 
@@ -134,7 +158,7 @@ def compute_rmse(
         obs_col: str
     ) -> float:
         '''
-        Calculate the Root Mean Squared Error metric between simulated and observed values.
+        Calculate the `Root Mean Squared Error` metric between simulated and observed values.
 
         Args:
             df (pandas.DataFrame): DataFrame containing at least two columns with simulated and observed values.
@@ -144,6 +168,14 @@ def compute_rmse(
             obs_col (str): Name of the column containing observed values.
         '''
 
+        # Check input variables type
+        validators._variable_origin_static_type(
+            vars_types=typing.get_type_hints(
+                obj=self.compute_rmse
+            ),
+            vars_values=locals()
+        )
+
         # computer MSE error
         mse_value = self.compute_mse(
             df=df,
@@ -163,7 +195,7 @@ def compute_pbias(
         obs_col: str
     ) -> float:
         '''
-        Calculate the Percent Bias metric between simulated and observed values.
+        Calculate the `Percent Bias` metric between simulated and observed values.
 
         Args:
             df (pandas.DataFrame): DataFrame containing at least two columns with simulated and observed values.
@@ -173,6 +205,14 @@ def compute_pbias(
             obs_col (str): Name of the column containing observed values.
         '''
 
+        # Check input variables type
+        validators._variable_origin_static_type(
+            vars_types=typing.get_type_hints(
+                obj=self.compute_pbias
+            ),
+            vars_values=locals()
+        )
+
         # Simulation values
         sim_arr = df[sim_col].astype(float)
 
@@ -191,7 +231,7 @@ def compute_mare(
         obs_col: str
     ) -> float:
         '''
-        Calculate the Mean Absolute Relative Error metric between simulated and observed values
+        Calculate the `Mean Absolute Relative Error` metric between simulated and observed values
 
         Args:
             df (pandas.DataFrame): DataFrame containing at least two columns with simulated and observed values.
@@ -201,6 +241,14 @@ def compute_mare(
             obs_col (str): Name of the column containing observed values.
         '''
 
+        # Check input variables type
+        validators._variable_origin_static_type(
+            vars_types=typing.get_type_hints(
+                obj=self.compute_mare
+            ),
+            vars_values=locals()
+        )
+
         # Simulation values
         sim_arr = df[sim_col].astype(float)
 
@@ -214,7 +262,7 @@ def compute_mare(
 
     def scenario_indicators(
         self,
-        sim_file: str | pathlib.Path,
+        sensim_file: str | pathlib.Path,
         df_name: str,
         sim_col: str,
         obs_file: str | pathlib.Path,
@@ -224,20 +272,20 @@ def scenario_indicators(
         json_file: typing.Optional[str | pathlib.Path] = None
     ) -> dict[str, typing.Any]:
         '''
-        Compute performance indicators for sample scenarios obtained using
-        the [`simulation_by_sobol_sample`](https://swat-model.github.io/pySWATPlus/api/sensitivity_analyzer/#pySWATPlus.SensitivityAnalyzer.simulation_by_sobol_sample) method.
+        Compute performance indicators for sample scenarios obtained using the method
+        [`simulation_by_sample_parameters`](https://swat-model.github.io/pySWATPlus/api/sensitivity_analyzer/#pySWATPlus.SensitivityAnalyzer.simulation_by_sample_parameters).
 
         Before computing the indicators, simulated and observed values are normalized using the formula `(v - min_v) / (max_v - min_v)`,
         where `min_v` and `max_v` represent the minimum and maximum of all simulated and observed values combined.
 
         The method returns a dictionary with two keys:
 
-        - `problem`: The definition dictionary passed to Sobol sampling.
+        - `problem`: The definition dictionary passed to sampling.
         - `indicator`: A `DataFrame` containing the `Scenario` column and one column per indicator,
           with scenario indices and corresponding indicator values.
 
         Args:
-            sim_file (str | pathlib.Path): Path to the `sensitivity_simulation.json` file produced by `simulation_by_sobol_sample`.
+            sensim_file (str | pathlib.Path): Path to the `sensitivity_simulation.json` file produced by `simulation_by_sobol_sample`.
 
             df_name (str): Name of the `DataFrame` within `sensitivity_simulation.json` from which to compute scenario indicators.
 
@@ -284,7 +332,7 @@ def scenario_indicators(
                 )
 
         # Observed DataFrame
-        obs_df = utils._df_observed(
+        obs_df = utils._df_observe(
             obs_file=pathlib.Path(obs_file).resolve(),
             date_format=date_format,
             obs_col=obs_col
@@ -293,7 +341,7 @@ def scenario_indicators(
 
         # Retrieve sensitivity output
         sensitivity_sim = utils._retrieve_sensitivity_output(
-            sim_file=pathlib.Path(sim_file).resolve(),
+            sensim_file=pathlib.Path(sensim_file).resolve(),
             df_name=df_name,
             add_problem=True,
             add_sample=False