### Install RavenPy Development Environment

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/installation.rst

Use this command to create and activate the development environment for RavenPy. This is recommended for contributors and for running documentation examples.

```console
conda env create -f environment-dev.yml
conda activate ravenpy-dev
(ravenpy-dev) make dev
```

--------------------------------

### Initialize Config with Start Date

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/configuration.md

Create a Config object and set the StartDate. The date can be provided in ISO format or as a datetime object.

```python
from ravenpy.config import Config
conf = Config(StartDate="2023-03-31")
conf.rvi
```

--------------------------------

### Run Docker Container for Building

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/releasing.rst

Starts a Docker container, mounts the current directory, and sets the working directory for building RavenPy.

```console
sudo docker run --rm -ti -v $(pwd):/src/ravenpy -w /src/ravenpy quay.io/pypa/manylinux_2_24_x86_64 bash
```

--------------------------------

### Initialize and Run Spotpy Sampler

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/06_Raven_calibration.ipynb

Initializes the Spotpy DDS sampler with the configured model setup and runs the calibration for a specified number of model evaluations.

```python
# Number of total model evaluations in the calibration. This value should be over 500 for real optimisation,
# and upwards of 10000 evaluations for models with many parameters. This will take a LONG period of time so
# be sure of all the configuration above before executing with a high number of model evaluations.
model_evaluations = 10

# Set up the spotpy sampler with the method, the setup configuration, a run name and other options. Please refer to
# the spotpy documentation for more options. We recommend sticking to this format for efficiency of most applications.
sampler = spotpy.algorithms.dds(
    spot_setup, dbname="RAVEN_model_run", dbformat="ram", save_sim=False
)

# Launch the actual optimization. Multiple trials can be launched, where the entire process is repeated and
# the best overall value from all trials is returned.
sampler.sample(model_evaluations, trials=1)
```

--------------------------------

### Install and Use Grayskull for Conda Recipe

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/releasing.rst

Install grayskull and use it to generate a conda build recipe from PyPI package information.

```console
python -m pip install grayskull
grayskull pypi RavenPy
```

--------------------------------

### Install System Dependencies on Ubuntu/Debian

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/installation.rst

Installs necessary system libraries for RavenPy's GIS functionalities on Ubuntu/Debian systems.

```console
sudo apt-get install gcc libnetcdf-dev gdal proj geos
```

--------------------------------

### Install RavenPy Locally (Windows)

Source: https://github.com/cshs-cwra/ravenpy/blob/main/CONTRIBUTING.rst

Installs RavenPy in an editable state on Windows and sets up pre-commit hooks. This allows immediate reflection of code changes and ensures code quality.

```console
python -m pip install --group dev
python -m pip install --editable .
prek install
```

--------------------------------

### Install RavenPy Development Environment on Windows

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/installation.rst

On Windows, use this command to install the development version of RavenPy. It is an alternative to 'make dev' for Windows users.

```console
(ravenpy-dev) python -m pip install -e .[dev]
```

--------------------------------

### Calibrate Hydrological Model with Spotpy

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/paper/Perform_a_climate_change_impact_study_on_a_watershed.ipynb

Sets up and launches the spotpy sampler for model calibration using the DDS algorithm. It configures the sampler with the setup, database name, and other options for optimization.

```python
sampler = spotpy.algorithms.dds(
    spot_setup,
    dbname="RAVEN_model_run",
    dbformat="ram",
    save_sim=False
)

sampler.sample(max_iterations, trials=1)
```

--------------------------------

### Install RavenPy with Pip (minimal)

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/installation.rst

Installs the core RavenPy package without GIS or raven-hydro, useful if providing a custom Raven binary.

```console
python -m pip install ravenpy
```

--------------------------------

### Define Emulator with Symbolic Parameters

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/configuration.md

This example demonstrates defining an emulator with symbolic parameters using pydantic dataclasses and pymbolic Variables. It shows how to set default symbolic values and use them in Raven command configurations.

```python
from typing import Union
from pydantic import ConfigDict
from pydantic.dataclasses import dataclass
from pymbolic.primitives import Variable
from ravenpy.config import Sym

@dataclass(config=ConfigDict(arbitrary_types_allowed=True))
class P:
  X01: Union[Variable, float] = Variable("X01")

class MyEmulator(Config):
  params: P = P()
  rain_snow_transition: rc.RainSnowTransition = Field(
  default=rc.RainSnowTransition(temp=P.X01, delta=2),
  alias="RainSnowTransition")
```

--------------------------------

### Setting Up GR4JCN Emulator Configuration

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/05_Advanced_RavenPy_configuration.ipynb

Configures the GR4JCN emulator with specific parameters, observed weather data, catchment properties, and simulation dates. This setup is for running a basic model simulation.

```python
# Get required packages
import datetime as dt

import matplotlib.pyplot as plt

from ravenpy import Emulator
from ravenpy.config import commands as rc
from ravenpy.config import emulators

# Observed weather data for the Salmon river. We extracted this using Tutorial Notebook 03 and the
# salmon_river.geojson file as the contour.
ts = get_file("notebook_inputs/ERA5_weather_data_Salmon.nc")

# Set alternate variable names in the timeseries data file
alt_names = {
    "TEMP_MIN": "tmin",
    "TEMP_MAX": "tmax",
    "PRECIP": "pr",
}

# Provide the type of data made available to Raven
data_type = ["TEMP_MAX", "TEMP_MIN", "PRECIP"]

# Prepare the catchment properties
hru = dict(
    area=4250.6,
    elevation=843.0,
    latitude=54.4848,
    longitude=-123.3659,
    hru_type="land",
)

# Add some information regarding station data
data_kwds = {
    "ALL": {
        "elevation": hru["elevation"],
        "latitude": hru["latitude"],
        "longitude": hru["longitude"],
    }
}

# Start and end dates of the simulation
start_date = dt.datetime(1985, 1, 1)
end_date = dt.datetime(1990, 1, 1)

# Set parameters
parameters = [0.529, -3.396, 407.29, 1.072, 16.9, 0.947]
```

--------------------------------

### Setting up and Running Model for Sensitivity Analysis

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Sensitivity_analysis.ipynb

This code block demonstrates the setup of a hydrological model (GR4JCN) for sensitivity analysis. It defines model configuration, iterates through parameter sets, writes model files, runs the simulation, and collects output diagnostics for sensitivity analysis.

```python
workdir = Path(tempfile.mkdtemp())

Y_NSE = np.zeros([param_values.shape[0]])
Y_ABS = np.zeros([param_values.shape[0]])

run_name = "SA_Sobol"

config = dict(
    ObservationData=[rc.ObservationData.from_nc(nc_file, alt_names="qobs")],
    Gauge=[rc.Gauge.from_nc(nc_file, alt_names=alt_names, data_kwds=data_kwds)],
    HRUs=[hru],
    StartDate=dt.datetime(1990, 1, 1),
    EndDate=dt.datetime(1999, 12, 31),
    RunName=run_name,
    EvaluationMetrics=eval_metrics,
    SuppressOutput=True,
)

for i, X in enumerate(tqdm(param_values)):
    m = emulators.GR4JCN(
        params=X.tolist(),
        **config,
    )

    m.write_rv(workdir=workdir, overwrite=True)

    outputs_path = run(modelname=run_name, configdir=workdir)

    outputs = OutputReader(run_name=run_name, path=outputs_path)

    Y_NSE[i] = outputs.diagnostics["DIAG_NASH_SUTCLIFFE"][0]
    Y_ABS[i] = outputs.diagnostics["DIAG_ABSERR"][0]
```

--------------------------------

### Configuring the Initial Raven Model Simulation

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/07_Making_and_using_hotstart_files.ipynb

Sets up the simulation parameters including start and end dates, HRU (Hydrological Response Unit) details, meteorological data source, and alternative names for netCDF variables. This configuration is used for the initial 'warm-up' simulation.

```python
# Start and end date for full simulation
# Make sure the end date is before the end of the hydrometeorological data NetCDF file.
start_date = dt.datetime(1986, 1, 1)
end_date = dt.datetime(1988, 1, 1)

# Define HRU
hru = dict(
    area=4250.6,
    elevation=843.0,
    latitude=54.4848,
    longitude=-123.3659,
    hru_type="land",
)

# Get dataset:
ERA5_full = get_file("notebook_inputs/ERA5_weather_data.nc")

# Set alternative names for netCDF variables
alt_names = {
    "TEMP_MIN": "tmin",
    "TEMP_MAX": "tmax",
    "PRECIP": "pr",
}

# Data types to extract from netCDF
data_type = ["TEMP_MAX", "TEMP_MIN", "PRECIP"]
data_kwds = {
    "ALL": {
        "elevation": hru["elevation"],
        "latitude": hru["latitude"],
        "longitude": hru["longitude"],
    }
}

# Model configuration
config = emulators.GR4JCN(
    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],
    Gauge=[
        rc.Gauge.from_nc(
            ERA5_full,
            data_type=data_type,
            alt_names=alt_names,
            data_kwds=data_kwds,
        )
    ],
    HRUs=[hru],
    StartDate=start_date,
    EndDate=end_date,
    RunName="full",
)
```

--------------------------------

### Import Libraries and Utilities

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Running_HMETS_with_CANOPEX_dataset.ipynb

Imports necessary Python libraries and utility functions for data handling, model configuration, and testing. Includes setup for temporary directories and warning filters.

```python
import datetime as dt
import tempfile
import warnings
from pathlib import Path

import pandas as pd
import spotpy
import xarray as xr
from numba.core.errors import NumbaDeprecationWarning

from ravenpy.config import commands as rc
from ravenpy.config import emulators

# Utility that simplifies working with test data hosted on GitHub
from ravenpy.testing.utils import get_file
from ravenpy.utilities.calibration import SpotSetup

# Make a temporary folder
tmp = Path(tempfile.mkdtemp())

warnings.simplefilter("ignore", category=NumbaDeprecationWarning)
```

--------------------------------

### Modify Start Date Configuration

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/configuration.md

Demonstrates accessing and modifying a configuration option in place. The StartDate option is accessed via its lowercase attribute `start_date` and updated.

```python
conf.start_date = "2023-04-01"
conf.start_date
```

--------------------------------

### Prepare Meteorological Data and Model Configuration

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/10_Data_assimilation.ipynb

Loads daily meteorological data, defines HRU parameters, and configures gauge data for Raven. This setup is crucial for initializing the hydrological model.

```python
# Import hydrometeorological data
salmon_meteo = get_file(
    "raven-gr4j-cemaneige/Salmon-River-Near-Prince-George_meteo_daily.nc"
)

# Define HRU
hru = dict(
    area=4250.6,
    elevation=843.0,
    latitude=54.4848,
    longitude=-123.3659,
    hru_type="land",
)

# Alternative names for variables in meteo forcing file
alt_names = {
    "RAINFALL": "rain",
    "TEMP_MIN": "tmin",
    "TEMP_MAX": "tmax",
    "SNOWFALL": "snow",
}

# The types of meteorological data available in the file
data_type = ["RAINFALL", "TEMP_MIN", "TEMP_MAX", "SNOWFALL"]

# Additional information about the weather station gauge required by Raven
data_kwds = {
    "ALL": {
        "elevation": hru["elevation"],
        "latitude": hru["latitude"],
        "longitude": hru["longitude"],
    }
}

# Force a test path.
tmp_path = Path(tempfile.mkdtemp())

# Generate the meteorological gauge data required by raven
gauge = [
    rc.Gauge.from_nc(
        salmon_meteo,
        data_type=data_type,
        alt_names=alt_names,
        data_kwds=data_kwds,
    ),
]
```

--------------------------------

### Setup GR4JCN Model in Open-Loop Configuration

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/10_Data_assimilation.ipynb

Configures and runs a GR4JCN hydrological model without data assimilation. Requires gauge data, HRU information, and observation data.

```python
conf_openloop = emulators.GR4JCN(
    params=[0.14, -0.005, 576, 7.0, 1.1, 0.92],
    Gauge=gauge,
    ObservationData=[rc.ObservationData.from_nc(salmon_meteo, alt_names="qobs")],
    HRUs=[hru],
    StartDate=start_date,
    EndDate=end_date,
    RunName="OPEN_LOOP",
    EvaluationMetrics=("NASH_SUTCLIFFE",),
)

openloop = Emulator(config=conf_openloop, workdir=tmp_path, overwrite=True).run(
    overwrite=True
)
```

--------------------------------

### Setup EnKF Forecast Configuration

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/10_Data_assimilation.ipynb

Configures the EnKF model for forecasting, using the final assimilation step's states as initial conditions. Specifies a 30-day forecast period and uses observed meteorological data for forcing.

```python
# Set up the forecast configuration, basing it on the previous (final) assimilation step.
conf_forecast = conf_loop.duplicate(
    EnKFMode=o.EnKFMode.FORECAST,
    RunName="forecast",
    SolutionRunName="loop",
    UniformInitialConditions=None,
    # Set the start date equal to the end date of the last assimilation run.
    StartDate=end_date,
    # Here we will do a 30-day forecast using the observed meteorological data as forecast data. However, it is
    # possible to replace the Gauge forcing data with that of a forecast, as we have done before.
    EndDate=end_date + dt.timedelta(days=30),
)

forecast = Emulator(config=conf_forecast, workdir=tmp_path, overwrite=True).run(
    overwrite=True
)
```

--------------------------------

### Writing Raven Model Configuration Files

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/04_Emulating_hydrological_models.ipynb

Generates .rvX files for a Raven model configuration in a temporary directory. These files define the model setup and can be exported or imported as needed.

```python
from pathlib import Path
import tempfile

workdir = Path(tempfile.mkdtemp(prefix="NB4"))
m.write_rv(workdir=workdir)
```

--------------------------------

### Configure Spin-up Period for Data Assimilation

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/10_Data_assimilation.ipynb

Sets the start and end dates for the model spin-up period. This phase generates initial model states that are more representative before applying data assimilation.

```python
# Spin up the model. This period will be used to do an initial spinup, at the end of which the model states
# will be assimilated to better represent the observed streamflow and thus setting up parameters for the next
# steps. We first need to specify the spinup dates:
start_date = dt.datetime(1996, 9, 1)
end_date = dt.datetime(1997, 8, 31)

# Prepare the configuration for the spinup. Since we have added information about Ensemble Kalman Filter data
```

--------------------------------

### Configuring GR4JCN Model for Forecasting

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/12_Performing_hindcasting_experiments.ipynb

Sets up the GR4JCN model for forecasting, including parameters, gauge data, HRUs, start date, duration, and run name. Initial states can be updated using `set_solution`.

```python
model_config_fcst = GR4JCN(
    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],
    Gauge=[
        rc.Gauge.from_nc(
            fname, data_type=data_type, alt_names=alt_names, data_kwds=data_kwds
        )
    ],
    HRUs=[hru],
    StartDate=end_date + dt.timedelta(days=1),
    Duration=7,
    RunName="NB12_forecast_run",
)

model_config_fcst = model_config_fcst.set_solution(hotstart)
```

--------------------------------

### Set Up Optimizer and Max Iterations

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/paper/Perform_a_climate_change_impact_study_on_a_watershed.ipynb

Initializes the `SpotSetup` object with the model configuration and parameter bounds. It also sets the maximum number of model evaluations for the calibration process, with a note to increase this for operational use.

```python
# Build the optimizer object
spot_setup = SpotSetup(
    config=model_config,
    low=low,
    high=high,
)

# Maximum number of model evaluations.
# We only use 200 here to keep the computation time as low as possible, but you will want to increase this for operational use, perhaps to 2000-5000 depending on the model.
max_iterations = 200
```

--------------------------------

### Import Seaborn after Installation

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Managing_Jupyter_Environments.ipynb

Imports the 'seaborn' package after it has been successfully installed in the environment.

```python
# This will now work.
import seaborn
```

--------------------------------

### Install Seaborn using Mamba

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Managing_Jupyter_Environments.ipynb

Installs the 'seaborn' package using 'mamba', a faster alternative to 'conda'. The '--yes' option automatically confirms the installation. This command can also be used with 'pip' by replacing 'mamba' with 'pip'.

```shell
!mamba install seaborn --yes
```

--------------------------------

### Initialize and Run DDS Sampler

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Running_HMETS_with_CANOPEX_dataset.ipynb

Initializes the DDS sampler from SPOTPY for model calibration and launches the sampling process for a specified number of trials. Ensure 'spot_setup' and 'model_evaluations' are defined prior to execution.

```python
sampler = spotpy.algorithms.dds(
    spot_setup,
    dbname="CANOPEX_test",
    dbformat="ram",
    save_sim=False,
)

sampler.sample(model_evaluations, trials=1)
```

--------------------------------

### Install RavenPy with Conda

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/installation.rst

Installs the RavenPy package and its dependencies from the conda-forge channel into the active 'ravenpy' environment.

```console
(ravenpy) $ conda install -c conda-forge ravenpy
```

--------------------------------

### Set Up Spotpy Calibration Parameters

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/06_Raven_calibration.ipynb

Defines the lower and upper bounds for the GR4JCN model parameters and initializes the SpotSetup object for calibration.

```python
# In order to calibrate your model, you need to give the lower and higher bounds of the model. In this case, we are passing
# the boundaries for a GR4JCN, but it's important to change them, if you are using another model. Note that the list of these
# boundaries for each model is at the end of this notebook.
low_params = (0.01, -15.0, 10.0, 0.0, 1.0, 0.0)
high_params = (2.5, 10.0, 700.0, 7.0, 30.0, 1.0)


spot_setup = SpotSetup(
    config=model_config,
    low=low_params,
    high=high_params,
)
```

--------------------------------

### Install RavenPy with Pip (with GIS)

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/installation.rst

Installs RavenPy along with GIS functionalities and the raven-hydro package using pip.

```console
python -m pip install ravenpy[gis,raven-hydro]
```

--------------------------------

### Configure and Run Spotpy Sampler

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Running_HMETS_with_CANOPEX_dataset.ipynb

Sets up the Spotpy sampler for model calibration, specifying the number of model evaluations. This prepares the system to run the optimization process.

```python
# We'll definitely want to adjust the random seed and number of model evaluations:
model_evaluations = (
    50  # This is to keep computing time fast for the demo, increase as necessary
)

# Set up the spotpy sampler with the method, the setup configuration, a run name and other options. Please refer to
```

--------------------------------

### Install Mamba Solver

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/installation.rst

Installs the Mamba solver for faster Conda environment resolution. This is recommended for managing complex dependencies.

```console
conda install -n base conda-libmamba-solver
conda config --set solver libmamba
```

--------------------------------

### Build and Release Packages

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/releasing.rst

Build the pip-installable packages (sources and wheel) and upload them to PyPI using make commands.

```console
# To build the packages (sources and wheel)
make dist

# To upload to PyPI
make release
```

--------------------------------

### Configure and Run Initial Closed-Loop Assimilation

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/10_Data_assimilation.ipynb

This snippet shows how to configure and run an initial closed-loop assimilation. It involves duplicating an existing configuration, setting assimilation parameters like EnKFMode, RunName, and SolutionRunName, and then initializing and running the Emulator.

```python
conf_loop = conf_spinup.duplicate(
    EnKFMode=o.EnKFMode.CLOSED_LOOP,
    # This will be the name of the output files in the closed-loop run.
    RunName="loop",
    # This is the name of the run we will start from, i.e. the assimilated spinup states from earlier!
    SolutionRunName="spinup",
    # We need to tell the model not to set the default initial conditions (it will use the assimilated states)
    UniformInitialConditions=None,
    # Set the new dates
    StartDate=start_date,
    EndDate=end_date,
)

# Now that the configuration is ready, launch the assimilation run. Raven will run 25 times: Once for each member
# With the same perturbed meteorological and hydrometric data and parameters as defined previously, but for this
# new 3-day period.
loop = Emulator(config=conf_loop, workdir=tmp_path, overwrite=True).run(overwrite=True)

# Get the paths to all the ens_1...ens_N folders, one per member
paths_loop = list(tmp_path.glob("ens_*"))

# Repeat the same process as the spinup to look at model results:
ens_loop = EnsembleReader(run_name=conf_loop.run_name, paths=paths_loop)

# We can now plot the results
ens_loop.hydrograph.q_sim[:, :, 0].plot.line("b", x="time", add_legend=False, lw=0.5)
ens_loop.hydrograph.q_sim[1, :, 0].plot.line("b", x="time", label="Forecasts", lw=0.5)
ens_loop.hydrograph.q_obs[1, :, 0].plot.line(
    x="time", color="black", label="Observation"
)
plt.legend(loc="lower left")
plt.ylabel("Streamlfow (m³/s)")
plt.title("First closed-loop period")
plt.show()
```

--------------------------------

### Install PyPI Version of RavenPy

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/installation.rst

This command installs the PyPI version of RavenPy into an existing Anaconda environment. This is not recommended if all requirements are not met.

```console
python -m pip install -e .[dev]
```

--------------------------------

### Creating and Running a Simulation Ensemble

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/outputs.md

Configure a base model and run it multiple times with different parameters to create an ensemble. Each run returns an OutputReader instance.

```python
# Output directory for all simulations
from pathlib import Path
p = Path("/tmp/ensemble")

# Create base model configuration
conf = HMETS(**kwds)

# Run the model for each parameter set in `params`
runs = [Emulator(conf.set_params(param), workdir=p / f"m{i}").run() for i, param in enumerate(params)]
```

--------------------------------

### Install RavenPy with Pip (without GIS)

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/installation.rst

Installs RavenPy with the raven-hydro package but without GIS functionalities, resulting in fewer dependencies.

```console
python -m pip install ravenpy[raven-hydro]
```

--------------------------------

### Configure and Run Warm-up Model Simulation

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/12_Performing_hindcasting_experiments.ipynb

Sets up and runs a GR4JCN hydrological model for a warm-up period using historical ERA5 weather data. This run generates initial states for the subsequent forecast simulations.

```python
# Prepare a RAVEN model run using historical data, GR4JCN in this case.
# This is a dummy run to get initial states. In a real forecast situation,
# this run would end on the day before the forecast, but process is the same.

# Here we need a file of observation data to run a simulation to generate initial conditions for our forecast.
# ts = str(
#    get_file("raven-gr4j-cemaneige/Salmon-River-Near-Prince-George_meteo_daily.nc")
# )

# TODO: We will use ERA5 data for Salmon River because it covers the correct period.
t = get_file("notebook_inputs/ERA5_weather_data_Salmon.nc")

# This is the model start date, on which the simulation will be launched for a certain duration
# to set up the initial states. We will then save the final states as a launching point for the
# forecasts.

start_date = dt.datetime(2000, 1, 1)
end_date = dt.datetime(2018, 6, 2)

# Define HRU to build the hydrological model
hru = dict(
    area=4250.6,
    elevation=843.0,
    latitude=54.4848,
    longitude=-123.3659,
    hru_type="land",
)

# Set alternative names for netCDF variables
alt_names = {
    "TEMP_MIN": "tmin",
    "TEMP_MAX": "tmax",
    "PRECIP": "pr",
}

# Data types to extract from netCDF
data_type = ["TEMP_MAX", "TEMP_MIN", "PRECIP"]
data_kwds = {
    "ALL": {
        "elevation": hru["elevation"],
        "Latitude": hru["latitude"],
        "Longitude": hru["longitude"],
    },
}
# Model configuration
model_config_warmup = GR4JCN(
    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],
    Gauge=[
        rc.Gauge.from_nc(
            ts, data_type=data_type, alt_names=alt_names, data_kwds=data_kwds
        )
    ],
    HRUs=[hru],
    StartDate=start_date,
    EndDate=end_date,
    RunName="NB12_warmup_run",
)

# Run the model and get the outputs.
out1 = Emulator(config=model_config_warmup).run()


# Extract the path to the final states file that will be used as the next initial states
hotstart = out1.files["solution"]

```

--------------------------------

### Build and Test Documentation Locally

Source: https://github.com/cshs-cwra/ravenpy/blob/main/CONTRIBUTING.rst

Commands to generate HTML documentation and test build checks locally before submitting a pull request.

```console
make docs
make autodoc
make -C docs html
python -m tox -e docs
```

--------------------------------

### Configuring and Running a Simulation with Hotstart Data

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/07_Making_and_using_hotstart_files.ipynb

Initializes a new simulation using the final state variables from a previous run (hotstart file). It updates the simulation dates and run name before executing and plotting the results.

```python
# The path to the solution (final model states)
hotstart = out1.files["solution"]

# Configure and run the model, this time with the next two years first 3 years (1988-1990).
conf2 = config.set_solution(hotstart)
conf2.start_date = dt.datetime(1988, 1, 1)
conf2.end_date = dt.datetime(1990, 1, 1)
conf2.run_name = "part_2"

out2 = Emulator(config=conf2).run()

# Plot the model output
out2.hydrograph.q_sim.plot(label="Part 2")
plt.legend()
```

--------------------------------

### Set Dates for Closed-Loop Assimilation

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/10_Data_assimilation.ipynb

Updates the start and end dates to initiate a closed-loop assimilation period. The start date is set to the end date of the previous run, and the end date is advanced by 3 days for the assimilation process.

```python
# Set the start date equal to the assimilated date of the prior run, as we want to start from the assimilated
# states. The end date is set 3 days later, after which assimilation will be automatically performed.
start_date = end_date
end_date = end_date + dt.timedelta(days=3)

```

--------------------------------

### Run Full Simulation and Compare Parts

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/07_Making_and_using_hotstart_files.ipynb

Compares a full simulation with two parts initialized from a hotstart file. Useful for verifying simulation integrity and identifying precision differences.

```python
full = config.copy()
full.end_date = dt.datetime(1990, 1, 1)
full.run_name = "full"

out = Emulator(config=full).run(overwrite=True)

out.hydrograph.q_sim.plot(label="Full", color="gray", lw=4)
out1.hydrograph.q_sim.plot(
    label="Part 1",
    color="blue",
    lw=0.5,
)
out2.hydrograph.q_sim.plot(label="Part 2", color="orange", lw=0.5)
plt.legend()
```

--------------------------------

### Prepare forecast data and set simulation start date

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Hydrological_realtime_forecasting.ipynb

Adjusts data types and names for ECCC forecast data, specifying processing for precipitation and temperature. Opens the forecast NetCDF file and determines the simulation start date.

```python
# Length of the desired forecast, in days
duration = 7

# We need to adjust the data_type and alt_names according to the data in the forecast:
# Set alternative names for netCDF variables
alt_names = {
    "TEMP_AVE": "tas",
    "PRECIP": "pr",
}

# Data types to extract from netCDF
data_type = ["TEMP_AVE", "PRECIP"]

# We will need to reuse this for GR4J. Update according to your needs. For example, here we will also pass
# the catchment latitude and longitude as our CaSPAr data has been averaged at the catchment scale.
# We also need to tell the model to deaccumulate the precipitation and shift it in time by 6 hours for our
# catchment (UTC timezones):
data_kwds = {
    "ALL": {
        "elevation": hru["elevation"],
        "Latitude": hru["latitude"],
        "Longitude": hru["longitude"],
    },
    "PRECIP": {
        "Deaccumulate": True,
        "TimeShift": -0.25,
        "LinearTransform": {
            "scale": 1.0
        },  # Since we are deaccumulating, we need to manually specify scale.
    },  # We are already in mm, so leave it like so (scale = 1.0).
    "TEMP_AVE": {
        "TimeShift": -0.25,
    },
}

# Handle CFTime encoding
time_coder = xr.coders.CFDatetimeCoder(use_cftime=True)

# ECCC forecast time format is a bit complex to work with, so we will use cftime to make it more manageable.
fcst_tmp = xr.open_dataset(fname, decode_times=time_coder)

# Get the first timestep that will be used for the model simulation
start_date = fcst_tmp.time.data[0] + dt.timedelta(days=1)

```

--------------------------------

### Import Required Packages

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Sensitivity_analysis.ipynb

Imports necessary libraries for data handling, modeling, and sensitivity analysis. Ensure these packages are installed before running.

```python
# Import required packages:
import datetime as dt
import tempfile
from pathlib import Path

import numpy as np
from SALib.analyze import sobol as sobol_analyzer
from SALib.sample import sobol as sobol_sampler
from tqdm.notebook import tqdm

from ravenpy import OutputReader, run
from ravenpy.config import commands as rc
from ravenpy.config import emulators

# Utility that simplifies working with test data hosted on GitHub
from ravenpy.testing.utils import get_file
```

--------------------------------

### Prepare Boilerplate Items

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/paper/Perform_a_climate_change_impact_study_on_a_watershed.ipynb

Sets up the environment by disabling warnings and defining the connection URL for the PAVICS-Hydro Raven WPS server. It also creates a temporary directory for data storage.

```python
# The platform provides lots of user warnings and information points. We will disable them for now.
warnings.filterwarnings("ignore")

# This is the URL of the Geoserver that will perform the computations for us.
url = os.environ.get(
    "WPS_URL", "https://pavics.ouranos.ca/twitcher/ows/proxy/raven/wps"
)

# Connect to the PAVICS-Hydro Raven WPS server to get the geospatial data from GeoServer.
wps = WPSClient(url)

# Make a temporary path where the data will be stored and used by Raven.
tmp = Path(tempfile.mkdtemp())
```

--------------------------------

### Print xarray Version

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/00_Introduction_to_JupyterLab.ipynb

Tests if the xarray package was successfully imported by printing its version. This helps verify the installation and import process.

```python
print(xr.__version__)
```

--------------------------------

### Get Marker Coordinates

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/01_Getting_watershed_boundaries.ipynb

Retrieves the current latitude and longitude coordinates from the draggable marker on the Leaflet map. These coordinates are then printed to the console.

```python
# Display the lat/lon coordinates of the marker location.
user_lonlat = list(reversed(marker.location))
print(user_lonlat)
```

--------------------------------

### Configure Model for Warm-up Period

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Comparing_hindcasts_and_ESP_forecasts.ipynb

Sets up the GR4JCN model configuration for a warm-up period, including defining dates, catchment properties, and observed weather data. This prepares the model for generating forecasts by creating a hotstart file.

```python
# Define the warmup period dates
start_date_wu = dt.datetime(2010, 1, 1)
end_date_wu = dt.datetime(2018, 6, 30)

# Define the catchment contour. Here we use the Salmon River file we previously generated using the Delineator
# in Tutorial Notebook 01.
basin_contour = get_file("notebook_inputs/salmon_river.geojson")

# Define some of the catchment properties. Could also be replaced by a call to the properties WPS as in
# the Tutorial Notebook 02.
hru = dict(
    area=4250.6,
    elevation=843.0,
    latitude=54.4848,
    longitude=-123.3659,
    hru_type="land",
)

# Observed weather data for the Salmon river. We extracted this using Tutorial Notebook 03 and the
# salmon_river.geojson file as the contour.
ts = get_file("notebook_inputs/ERA5_weather_data_Salmon.nc")

# Set alternative names for netCDF variables
alt_names = {
    "TEMP_MIN": "tmin",
    "TEMP_MAX": "tmax",
    "PRECIP": "pr",
}

# Data types to extract from netCDF
data_type = ["TEMP_MAX", "TEMP_MIN", "PRECIP"]
data_kwds = {
    "ALL": {
        "elevation": hru["elevation"],
        "Latitude": hru["latitude"],
        "Longitude": hru["longitude"],
    },
}

# Model configuration
model_config_warmup = GR4JCN(
    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],
    Gauge=[
        rc.Gauge.from_nc(
            ts, data_type=data_type, alt_names=alt_names, data_kwds=data_kwds
        )
    ],
    HRUs=[hru],
    StartDate=start_date_wu,
    EndDate=end_date_wu,
    RunName="ESP_vs_NWP_warmup",
)

# Run the model and get the outputs.
out1 = Emulator(config=model_config_warmup).run()

# Extract the path to the final states file that will be used as the next initial states
hotstart = out1.files["solution"]
```

--------------------------------

### Reset Dates for Open-Loop Comparison

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/10_Data_assimilation.ipynb

This snippet resets the start and end dates to cover the entire simulation period, preparing for a comparison with open-loop results.

```python
# Reset the start and end-dates to cover the entire period (spinup + 30 * 3-day steps)
start_date = dt.datetime(1996, 9, 1)
end_date = dt.datetime(1997, 8, 31) + dt.timedelta(days=30 * 3)
```

--------------------------------

### Import necessary libraries for Ravenpy

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/11_Climatological_ESP_forecasting.ipynb

Imports essential modules from datetime, matplotlib, and ravenpy for hydrological modeling and forecasting. This setup is required before running any simulations.

```python
import datetime as dt

from matplotlib import pyplot as plt

from ravenpy.config import commands as rc
from ravenpy.config import emulators

# Utility that simplifies working with test data hosted on GitHub
from ravenpy.testing.utils import get_file
from ravenpy.utilities import forecasting
```

--------------------------------

### List PotentialMeltMethod Options

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/configuration.md

Displays all valid options for the PotentialMeltMethod configuration. This is useful for understanding the available choices for this parameter.

```python
from ravenpy.config import options as o

list(o.PotentialMeltMethod)
```

--------------------------------

### Attempt to Import Seaborn (Failing)

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Managing_Jupyter_Environments.ipynb

This code attempts to import the 'seaborn' package. It is commented out by default to prevent notebook checks from failing due to the package not being installed.

```python
# Attempt to install seaborn. This will fail when run for the first time!

# UNCOMMENT THE FOLLOWING LINE TO TEST THE EXISTENCE OF THE SEABORN PACKAGE. It is currently commented to ensure the automatic notebook checks do not fail for an obvious reason.
# import seaborn
```

--------------------------------

### Importing Raven Model Configuration Files

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/05_Advanced_RavenPy_configuration.ipynb

Fetches the necessary .rvX configuration files for a Raven model, including links to hydrometeorological data.

```python
# Get the .rv files. It could also be the .rv files returned from the previous notebook, but here we are using a new basin that contains observed streamflow
# to make the calibration possible in the next notebook. Note that these configuration files also include links to the
# required hydrometeorological database (NetCDF file).
config = [
    get_file(f"raven-gr4j-cemaneige/raven-gr4j-salmon.{ext}")
    for ext in ["rvt", "rvc", "rvi", "rvh", "rvp"]
]
config
```

--------------------------------

### Get Resource Files

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks-notworking/HydroShare_integration.ipynb

Retrieve a list of files associated with a specific HydroShare resource using its resource ID. Set validate=False to bypass validation if needed.

```python
res = hs.resource("51d1539bf6e94b15ac33f7631228118c", validate=False)
res.files()
```

--------------------------------

### Define Model Parameter Bounds for Calibration

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Running_HMETS_with_CANOPEX_dataset.ipynb

Specifies the lower and upper bounds for model parameters used in the calibration process. These bounds guide the optimization algorithm.

```python
# The model parameters bounds can either be set independently or we can use the defaults.
low_params = (
    0.3,
    0.01,
    0.5,
    0.15,
    0.0,
    0.0,
    -2.0,
    0.01,
    0.0,
    0.01,
    0.005,
    -5.0,
    0.0,
    0.0,
    0.0,
    0.0,
    0.00001,
    0.0,
    0.00001,
    0.0,
    0.0,
)
high_params = (
    20.0,
    5.0,
    13.0,
    1.5,
    20.0,
    20.0,
    3.0,
    0.2,
    0.1,
    0.3,
    0.1,
    2.0,
    5.0,
    1.0,
    3.0,
    1.0,
    0.02,
    0.1,
    0.01,
    0.5,
    2.0,
)

# Setup the spotpy optimizer
spot_setup = SpotSetup(
    config=model_config,
    low=low_params,
    high=high_params,
)
```

--------------------------------

### Running the Initial Simulation and Plotting Output

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/07_Making_and_using_hotstart_files.ipynb

Executes the configured Raven model simulation and suppresses Raven warnings. The resulting simulated streamflow ('q_sim') is then plotted.

```python
# Silence the Raven warnings
warnings.simplefilter("ignore", category=RavenWarning)

# Run the model and get the outputs.
out1 = Emulator(config=config).run()

# Plot the model output
out1.hydrograph.q_sim.plot(label="Part 1")
plt.legend()
```

--------------------------------

### Import Libraries and Connect to WPS Server

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/02_Extract_geographical_watershed_properties.ipynb

This code snippet imports necessary Python libraries and establishes a connection to the PAVICS-Hydro Raven WPS server. It sets up environment variables and defines the Geoserver URL. This is boilerplate code and generally should not be modified.

```python
# We need to import a few packages required to do the work
import os

os.environ["USE_PYGEOS"] = "0"
import geopandas as gpd
import matplotlib as mpl
import matplotlib.pyplot as plt
import numpy as np
import rasterio
from birdy import WPSClient

# Utility that simplifies working with test data hosted on GitHub
from ravenpy.testing.utils import get_file

# This is the URL of the Geoserver that will perform the computations for us.
url = os.environ.get(
    "WPS_URL", "https://pavics.ouranos.ca/twitcher/ows/proxy/raven/wps"
)

# Connect to the PAVICS-Hydro Raven WPS server
wps = WPSClient(url)
```

--------------------------------

### Process and Plot Land-Use Raster

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/02_Extract_geographical_watershed_properties.ipynb

This snippet retrieves the raster data from the response and plots it as a grid. It requires pymetalink to be installed for automatic transformation of the GeoTIFF file to a DataArray.

```python
features, statistics, raster = stats_resp.get(asobj=True)
grid = raster[0]
grid.plot()
```

--------------------------------

### Run RavenPy Test Suite

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/installation.rst

Execute this command to run the test suite and verify that RavenPy has been installed correctly. This command assumes the 'ravenpy' Conda environment is active.

```console
(ravenpy) python -m pytest tests
```

--------------------------------

### Import Necessary Packages

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/06_Raven_calibration.ipynb

Imports essential libraries for model configuration, emulation, testing, and calibration.

```python
import datetime as dt

import spotpy

from ravenpy.config import commands as rc
from ravenpy.config import emulators

# Utility that simplifies working with test data hosted on GitHub
from ravenpy.testing.utils import get_file
from ravenpy.utilities.calibration import SpotSetup
```

--------------------------------

### Define Simulation Dates

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/04_Emulating_hydrological_models.ipynb

Sets the start and end dates for the hydrological simulation. These should be Python datetime objects. If not provided, the simulation defaults to the period covered by the driving data.

```python
start_date = dt.datetime(1985, 1, 1)
end_date = dt.datetime(1990, 1, 1)
```

--------------------------------

### Import Required Packages

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/paper/Perform_a_climate_change_impact_study_on_a_watershed.ipynb

Imports essential Python packages for data handling, geographical processing, hydrological modeling, and interacting with PAVICS-Hydro services. Ensure all these packages are installed in your environment.

```python
# We need to import a few packages required to do the work:

import datetime as dt

# Basic system packages:
import os
import tempfile
import warnings
from pathlib import Path

# Packages for data extraction on remote servers/filesystems:
import gcsfs
import geopandas as gpd

# Packages for geographic processing:
import intake
import matplotlib.pyplot as plt
import numpy as np

# Packages related to ravenpy and hydrological modelling:
import spotpy
import xarray as xr

# Packages required for data processing:
import xclim
import xsdba
from birdy import WPSClient
from clisops.core import average, subset
from dask.diagnostics import ProgressBar

from ravenpy import Emulator
from ravenpy.config import commands as rc
from ravenpy.config.emulators import GR4JCN

# Utility that simplifies fetching and caching test data hosted on GitHub
from ravenpy.testing.utils import get_file
```

--------------------------------

### Visualize Forecast Hydrograph

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Hydrological_realtime_forecasting.ipynb

Plots the simulated forecast streamflow against observed streamflow. This example simulates observed data for demonstration; replace it with actual observed timeseries for real-world use.

```python
# Simulate an observed streamflow timeseries: Here we take a member from the ensemble, but you should use your own
# observed timeseries:
qq = forecast_sims.hydrograph.q_sim[0, :, 0]

# This is to be replaced with a call to the forecast graphing WPS as soon as merged.
# model.q_sim.plot.line("b", x="time")
forecast_sims.hydrograph.q_sim[:, :, 0].plot.line("b", x="time", add_legend=False)
forecast_sims.hydrograph.q_sim[1, :, 0].plot.line("b", x="time", label="forecasts")
qq.plot.line("r", x="time", label="observations")
plt.legend(loc="upper left")
plt.show()
```

--------------------------------

### Import Libraries and Utilities

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Comparing_hindcasts_and_ESP_forecasts.ipynb

Imports necessary libraries for hydrological modeling, data manipulation, and forecast generation. Includes utilities for accessing test data and configuring the Emulator.

```python
%matplotlib inline

import datetime as dt
import warnings

import matplotlib.pyplot as plt
import xarray as xr
from clisops.core import subset

# ignore warnings from xsdba
warnings.simplefilter("ignore", category=UserWarning)

from ravenpy import Emulator
from ravenpy.config import commands as rc
from ravenpy.config.emulators import GR4JCN
from ravenpy.extractors.forecasts import get_CASPAR_dataset

# Utility that simplifies working with test data hosted on GitHub
from ravenpy.testing.utils import get_file
from ravenpy.utilities import forecasting
```

--------------------------------

### Configure and Run Hindcast Model

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/12_Performing_hindcasting_experiments.ipynb

Configures and runs a new hydrological model simulation for hindcasting. It utilizes the initial states derived from the warm-up run and prepares for forecast execution.

```python
# Configure and run a new model by setting the initial states (equal to the previous run's final states) and prepare

```

--------------------------------

### Running a Raven Model with Custom Configuration

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/04_Emulating_hydrological_models.ipynb

Imports custom Raven configuration files and forcing data to run the model exactly as designed. The model outputs are saved in a subfolder named 'outputs'.

```python
from ravenpy import OutputReader, ravenpy

run_name = run_name
configdir = workdir

outputs_path = ravenpy.run(modelname=run_name, configdir=configdir)

outputs = OutputReader(run_name=run_name, path=outputs_path)
```

--------------------------------

### Export Conda Environment Cross-Platform

Source: https://github.com/cshs-cwra/ravenpy/blob/main/docs/notebooks/Managing_Jupyter_Environments.ipynb

Exports the current conda environment to a file named 'ENV.yml' based on the packages explicitly installed by the user (from history). This format is generally more cross-platform compatible.

```shell
conda env export --from-history>ENV.yml
```