feat: reupload the revised version with ray optimization

Author: tamnva

README.md

@@ -21,7 +21,7 @@ hydroecolstm.interface.show_gui()
 
 ### The GUI
 
-- After lanching the GUI, you should see the following window (the latest version could look different)
+- After lanching the GUI, you should see the following window (the latest version could look different).
 
 <p align="center">
   <img src="https://github.com/tamnva/hydroecolstm/blob/master/docs/images/intro_figure.gif" width=100% title="hover text">

docs/source/examples.rst

@@ -8,26 +8,38 @@ The configuration file ``config.yml`` and data for this example can be found `he
 
 .. code-block:: python
 
-   # Import hydroecolstm function
-   from hydroecolstm.model_run import run_train
+   from hydroecolstm.model_run import run_config
    from hydroecolstm.utility.plot import plot
    from hydroecolstm.data.read_config import read_config
+   from hydroecolstm.model.create_model import create_model
    from hydroecolstm.utility.evaluation_function import EvaluationFunction
    from hydroecolstm.data.read_data import read_forecast_data
    import matplotlib.pyplot as plt
    from pathlib import Path
    import torch
-
-   # Read configuration file
-   # Please modify the path to the config.yml and link to data
-   config = read_config("C:/example/1_streamflow_simulation/config.yml")
-
-   # Create model and train
-   model, x_scaler, y_scaler, data = run_train(config)
-
-   # Plot training and validation losses
-   data["trainer"].loss.drop(['epoch', 'best_model'], axis=1).plot()
-
+   
+   #-----------------------------------------------------------------------------#
+   #                        Set up, train, test model                            #
+   #-----------------------------------------------------------------------------#
+   
+   # Read configuration file, please modify the path to the config.yml file
+   config = read_config("C:/hydroecolstm/examples/1_streamflow_simulation/config.yml")
+   
+   # Create model and train from config 
+   model, data, best_config = run_config(config)
+   
+   # Evaluate the model and transform to normal scale
+   data['y_train_simulated'] = data["y_scaler"].inverse(model.evaluate(data["x_train_scale"]))
+   data['y_valid_simulated'] = data["y_scaler"].inverse(model.evaluate(data["x_valid_scale"]))
+   data['y_test_simulated'] = data["y_scaler"].inverse(model.evaluate(data["x_test_scale"]))
+   
+   # Plot train and validation loss with epoch
+   data["loss_epoch"].plot()
+   plt.show() 
+   
+   # Want to see all keys in data
+   data.keys()
+   
    # Objective function values: MAE, NSE, RMSE, MSE
    objective = EvaluationFunction(config['eval_function'], config['warmup_length'])
    objective(data['y_train'], data['y_train_simulated'])
@@ -39,18 +51,18 @@ The configuration file ``config.yml`` and data for this example can be found `he
        for target in config["target_features"]:
            p = plot(data, object_id=str(object_id), target_feature=target)
            p.show()
-
+   
    # Application of the model for (assumed) ungagued basins
    forecast_dataset = read_forecast_data(config)
-   x_forecast_scale = x_scaler.transform(forecast_dataset["x_forecast"])
+   x_forecast_scale = data["x_scaler"].transform(forecast_dataset["x_forecast"])
    y_forecast_scale = model.evaluate(x_forecast_scale)
    
    # Application of the model for (assumed) ungagued basins
    forecast_dataset = read_forecast_data(config)
-   x_forecast_scale = x_scaler.transform(forecast_dataset["x_forecast"])
+   x_forecast_scale = data["x_scaler"].transform(forecast_dataset["x_forecast"])
    y_forecast_scale = model.evaluate(x_forecast_scale)
-   y_forecast_simulated = y_scaler.inverse(y_forecast_scale)
-
+   y_forecast_simulated = data["y_scaler"].inverse(y_forecast_scale)
+   
    # Visualize result: train_test_period = "train" or "test"
    for object_id in y_forecast_simulated.keys():
        plt.plot(forecast_dataset["time_forecast"][object_id],
@@ -61,14 +73,27 @@ The configuration file ``config.yml`` and data for this example can be found `he
                 color = 'red', label = "Simulated", alpha=0.9, linewidth=0.75)
        plt.legend()
        plt.show()
-
+   
    # Objective function for forecast
    objective(forecast_dataset['y_forecast'], y_forecast_simulated)
-
+   
    # Save all data and model state dicts to the output_directory
    torch.save(data, Path(config["output_directory"][0], "data.pt"))
-   #torch.save(model.state_dict(), Path(config["output_directory"][0], "model.pt"))
-
+   torch.save(model.state_dict(), 
+              Path(config["output_directory"][0], "model_state_dict.pt"))
+   
+   #-----------------------------------------------------------------------------#
+   #                   Incase you close this file and open again,                #
+   #                    you can load your data, model as follows                 #
+   #-----------------------------------------------------------------------------#
+   config = read_config("C:/hydroecolstm/examples/1_streamflow_simulation/config.yml")
+   
+   model = create_model(config)
+   model.load_state_dict(torch.load(Path(config["output_directory"][0], 
+                                         "model_state_dict.pt")))
+   
+   data = torch.load(Path(config["output_directory"][0], "data.pt"))
+   
 
 Multiple outputs simulation
 ---------------------------
@@ -78,25 +103,38 @@ The configuration file ``config.yml`` and data for this example can be found `he
 .. code-block:: python
 
    # Import hydroecolstm function
-   from hydroecolstm.model_run import run_train
+   
+   from hydroecolstm.model_run import run_config
    from hydroecolstm.utility.plot import plot
    from hydroecolstm.data.read_config import read_config
+   from hydroecolstm.model.create_model import create_model
    from hydroecolstm.utility.evaluation_function import EvaluationFunction
-   from hydroecolstm.data.read_data import read_forecast_data
    import matplotlib.pyplot as plt
    from pathlib import Path
    import torch
-
-   # Read configuration file
-   # Please modify the path to the config.yml and link to data
-   config = read_config("C:/example/2_streamflow_isotope_simulation/config.yml")
-
-   # Create model and train
-   model, x_scaler, y_scaler, data = run_train(config)
-
-   # Plot training and validation losses
-   data["trainer"].loss.drop(['epoch', 'best_model'], axis=1).plot()
-
+   
+   #-----------------------------------------------------------------------------#
+   #                        Set up, train, test model                            #
+   #-----------------------------------------------------------------------------#
+   
+   # Read configuration file, please modify the path to the config.yml file
+   config = read_config("C:/hydroecolstm/examples/2_streamflow_isotope_simulation/config.yml")
+   
+   # Create model and train from config 
+   model, data, best_config = run_config(config)
+   
+   # Evaluate the model and transform to normal scale
+   data['y_train_simulated'] = data["y_scaler"].inverse(model.evaluate(data["x_train_scale"]))
+   data['y_valid_simulated'] = data["y_scaler"].inverse(model.evaluate(data["x_valid_scale"]))
+   data['y_test_simulated'] = data["y_scaler"].inverse(model.evaluate(data["x_test_scale"]))
+   
+   # Plot train and validation loss with epoch
+   data["loss_epoch"].plot()
+   plt.show() 
+   
+   # Want to see all keys in data
+   data.keys()
+   
    # Objective function values: MAE, NSE, RMSE, MSE
    objective = EvaluationFunction(config['eval_function'], config['warmup_length'])
    objective(data['y_train'], data['y_train_simulated'])
@@ -108,7 +146,19 @@ The configuration file ``config.yml`` and data for this example can be found `he
        for target in config["target_features"]:
            p = plot(data, object_id=str(object_id), target_feature=target)
            p.show()
-
+   
    # Save all data and model state dicts to the output_directory
    torch.save(data, Path(config["output_directory"][0], "data.pt"))
-   #torch.save(model.state_dict(), Path(config["output_directory"][0], "model.pt"))
+   torch.save(model.state_dict(), 
+              Path(config["output_directory"][0], "model_state_dict.pt"))
+   
+   #-----------------------------------------------------------------------------#
+   #                   Incase you close this file and open again,                #
+   #                    you can load your data, model as follows                 #
+   #-----------------------------------------------------------------------------#
+   config = read_config("C:/hydroecolstm/examples/2_streamflow_isotope_simulation/config.yml")
+   model = create_model(config)
+   model.load_state_dict(torch.load(Path(config["output_directory"][0], 
+                                         "model_state_dict.pt")))
+   data = torch.load(Path(config["output_directory"][0], "data.pt"))
+   

examples/1_streamflow_simulation/best_config.yml

@@ -0,0 +1,147 @@
+# path to time series data file, input and target features should be in this file
+dynamic_data_file:
+  - C:/hydroecolstm/examples/1_streamflow_simulation/data/time_series.csv
+
+# (optional input) path to catchment attributes file
+static_data_file:
+  - C:/hydroecolstm/examples/1_streamflow_simulation/data/static_attributes.csv
+
+# ouptut directory, model output will be save in this file
+output_directory:
+  - C:/hydroecolstm/examples/1_streamflow_simulation/results
+
+# input static features - column name(s) of the static_data_file
+input_static_features:
+  - elev_mean
+  - slope_mean
+  - p_seasonality
+  - aridity
+  - pet_mean
+
+# input dynamic features - column name(s) of the dynamic_data_file
+input_dynamic_features:
+  - precipitation_mm_d
+  - temperature_mean_degC
+
+# target output - column name(s) of the dynamic_data_file
+target_features:
+  - discharge_vol_m3_s
+
+# selected catchments (object_id) used for traning/validation/test the model
+object_id:
+  - 2009
+  - 2016
+  - 2018
+  - 2019
+  - 2020
+  - 2024
+  - 2030
+  - 2033
+
+# start and ending of the train period, must be in yyyy-mm-dd hh:mm format
+train_period: 
+  - 2010-01-01 00:00
+  - 2020-12-31 00:00
+
+# start and ending of the validation period, must be in yyyy-mm-dd hh:mm format
+valid_period: 
+  - 2006-01-01 00:00
+  - 2009-12-31 00:00
+
+# start and ending of the test period, must be in yyyy-mm-dd hh:mm format
+test_period: 
+  - 2001-01-01 00:00
+  - 2005-12-31 00:00
+
+# model class: LSTM
+# model_class: EA-LSTM
+model_class: LSTM
+
+# Model head: currently only regression model (multi-layer neural network was implemented)
+Regression:
+  # Activation function of each layer (layer 1 - output layer): Identity, ReLu, Sigmoid, Tanh, Softplus
+  activation_function:
+    - Identity
+  # Number of neural each layer (number of neuraon in last layer = number of target features; put "None" for the last layer)
+  num_neurons:
+    - None
+  # Number of layer
+  num_layers: 1
+
+# E.g., model head of 2 layers
+#Regression:
+#  activation_function:
+#    - Sigmoid
+#    - Identity
+#  num_neurons:
+#    - 6
+#    - None
+#  num_layers: 2
+
+# Scaler for input dynamic features: Z-score, MinMaxScaler, or None
+scaler_input_dynamic_features:
+  - Z-score
+  
+# Scaler for input static features: Z-score, MinMaxScaler, or None
+scaler_input_static_features:
+  - Z-score
+
+# Scaler for target features: Z-score, MinMaxScaler, or None
+scaler_target_features:
+  - MinMaxScaler
+
+# Hidden size of the LSTM network
+hidden_size: 30
+
+# Number of LSTM layers
+num_layers: 1
+
+# Number of training epoch
+n_epochs: 300
+
+# Learning rate
+learning_rate: 0.005
+
+# Dropout rate (applied to output of each LSTM layers)
+dropout: 0.3
+
+# Warmup length
+warmup_length: 30
+
+# Loss function: RMSE, MSE, MAE
+loss_function: RMSE
+
+# Sequence length
+sequence_length: 365
+
+# Batch size
+batch_size: 8
+
+# Patience length
+patience: 30
+
+# (optional input) function to evaluate the selected model: NSE, RMSE, MAE, MSE
+eval_function: NSE
+
+# optional input - applied the selected model for prediction/ungagued catchments
+
+# path to the static data file contains static features for forecast catchments 
+# if these data inside the "static_data_file" file, type static_data_file
+static_data_file_forecast:
+  - static_data_file
+
+# path to the dynamic data file contains dynamic features for forecast catchments 
+# if these data inside the "dynamic_data_file" file, type dynamic_data_file
+dynamic_data_file_forecast:
+  - dynamic_data_file
+
+# start and ending of the forecast period, must be in yyyy-mm-dd hh:mm format
+forecast_period: 
+  - 2001-01-01 00:00
+  - 2009-12-31 00:00
+
+# selected catchments (object_id) for forecast
+object_id_forecast:
+  - 2011
+  - 2029
+

examples/1_streamflow_simulation/config.yml

@@ -1,14 +1,14 @@
 # path to time series data file, input and target features should be in this file
 dynamic_data_file:
-  - C:/example/1_streamflow_simulation/data/time_series.csv
+  - C:/hydroecolstm/examples/1_streamflow_simulation/data/time_series.csv
 
 # (optional input) path to catchment attributes file
 static_data_file:
-  - C:/example/1_streamflow_simulation/data/static_attributes.csv
+  - C:/hydroecolstm/examples/1_streamflow_simulation/data/static_attributes.csv
 
 # ouptut directory, model output will be save in this file
 output_directory:
-  - C:/example/1_streamflow_simulation/results
+  - C:/hydroecolstm/examples/1_streamflow_simulation/results
 
 # input static features - column name(s) of the static_data_file
 input_static_features: