fixed index

docs/source/index.rst

@@ -34,36 +34,36 @@ The steps of the workflow are outlined below:
 
     <ul>
 
-    <li>*modify_eva( ):* Modifies StateMod’s *.eva* file, or net reservoir annual evaporation data file. Users can either impose a specific change to the evaporation rate or use a Latin hypercube sample to create many scenarios of evaporation rate changes (typically between -15.24 and 30.46 cm/month (-0.5 to +1 ft); Hadjimichael et al., 2020) across specific reservoirs or all larger reservoirs across the West Slope basins.</li>
-    <li>*modify_ddm( ):* Modifies StateMod’s *.ddm* file, or monthly water demand data file. Users can either impose a specific change to monthly demands for a list of stakeholders or use a Latin hypercube sample to multiply the current demand time series for the users by a value between 0.5 to 1.5. </li>
-   <li>*modify_ddr( ):* Modifies StateMod’s *.ddr* file, or water rights data file.  In this function, the user can specify a list of the IDs of the stakeholders and (1) sample from a range and apply a multiplier to how much water is decreed to a stakeholder (2) hard code in a new decree for a stakeholder or (3) adjust the rank of the stakeholder to be more or less senior. </li>
-   <li>*modify_res( ):* Modifies StateMod’s *.res* file, or the reservoir account data file. This file lists the accounts associated with each reservoir and the amount of water allocated to specific stakeholders. In this function, we sample losses of up to 20% of the capacity of the reservoirs (informed by Graf et al. (2010)) which can be due to erosion and sedimentation of reservoirs resulting in reduced storage. The accounts associated with the reservoirs are also reduced equally to accommodate the new storage level. Users can change the reservoir storage for a specific set of reservoirs by specifying the reservoir IDs or can decrease storage at all reservoirs in the basin.  </li>
-   <li>*• modify_xbm_iwr( ):* Modifies StateMod’s *.xbm* (monthly streamflow) and *.iwr* (irrigation demand) data files. The *.xbm* file is overwritten with synthetic streamflow that is simultaneously generated across the outlet nodes of the five West Slope basins using a multi-basin Hidden Markov Model-based approach that effectively maintains the spatial correlation in the generated streamflow (Gold et al., in prep). A statistical disaggregation approach is used to partition aggregated flow at the outlet nodes to StateMod gauge nodes upstream (Nowak et al., 2010). The HMM-based approach is fit to observed annual streamflow but can create synthetic traces characterized by more flood and drought events (Gold et al., in prep). The irrigation demands (in the *.iwr* file) are also inherently tied to the generation of the streamflow, as irrigation demands will increase in dry years. Thus, a regression is fit across historical irrigation anomalies and historical annual flow anomalies and the appropriate irrigation anomaly is determined from this regression for every synthetically generated flow anomaly. More information on this method can be found in Hadjimichael et al. (2020).</li> 
+    <li><i>modify_eva( ):</i> Modifies StateMod’s <i>.eva</i> file, or net reservoir annual evaporation data file. Users can either impose a specific change to the evaporation rate or use a Latin hypercube sample to create many scenarios of evaporation rate changes (typically between -15.24 and 30.46 cm/month (-0.5 to +1 ft); Hadjimichael et al., 2020) across specific reservoirs or all larger reservoirs across the West Slope basins.</li>
+    <li><i>modify_ddm( ):</i> Modifies StateMod’s <i>.ddm</i> file, or monthly water demand data file. Users can either impose a specific change to monthly demands for a list of stakeholders or use a Latin hypercube sample to multiply the current demand time series for the users by a value between 0.5 to 1.5. </li>
+   <li><i>modify_ddr( ):</i> Modifies StateMod’s <i>.ddr</i> file, or water rights data file.  In this function, the user can specify a list of the IDs of the stakeholders and (1) sample from a range and apply a multiplier to how much water is decreed to a stakeholder (2) hard code in a new decree for a stakeholder or (3) adjust the rank of the stakeholder to be more or less senior. </li>
+   <li><i>modify_res( ):</i> Modifies StateMod’s <i>.res</i> file, or the reservoir account data file. This file lists the accounts associated with each reservoir and the amount of water allocated to specific stakeholders. In this function, we sample losses of up to 20% of the capacity of the reservoirs (informed by Graf et al. (2010)) which can be due to erosion and sedimentation of reservoirs resulting in reduced storage. The accounts associated with the reservoirs are also reduced equally to accommodate the new storage level. Users can change the reservoir storage for a specific set of reservoirs by specifying the reservoir IDs or can decrease storage at all reservoirs in the basin.  </li>
+   <li><i>modify_xbm_iwr( ):</i> Modifies StateMod’s <i>.xbm</i> (monthly streamflow) and <i>.iwr</i> (irrigation demand) data files. The <i>.xbm</i> file is overwritten with synthetic streamflow that is simultaneously generated across the outlet nodes of the five West Slope basins using a multi-basin Hidden Markov Model-based approach that effectively maintains the spatial correlation in the generated streamflow (Gold et al., in prep). A statistical disaggregation approach is used to partition aggregated flow at the outlet nodes to StateMod gauge nodes upstream (Nowak et al., 2010). The HMM-based approach is fit to observed annual streamflow but can create synthetic traces characterized by more flood and drought events (Gold et al., in prep). The irrigation demands (in the <i>.iwr</i> file) are also inherently tied to the generation of the streamflow, as irrigation demands will increase in dry years. Thus, a regression is fit across historical irrigation anomalies and historical annual flow anomalies and the appropriate irrigation anomaly is determined from this regression for every synthetically generated flow anomaly. More information on this method can be found in Hadjimichael et al. (2020).</li> 
   </ul>
 
 
   <li><p>Extracting output of interest: Users can extract time series of either individual stakeholder shortages or reservoir storage levels for any simulation using the following functions:  </p>
   <ul>
 
-    <li>*convert_xdd( ):* Stakeholder shortages resulting from a StateMod simulation are aggregated in the *.xdd* output file. Users can specify a list of stakeholder IDs to extract shortages for and results are stored in a highly compressed and columnar *.parquet* file which easily interoperates with Pandas data frames.</li>
-    <li>*extract_xre_data( ):* Reservoir storage resulting from a StateMod simulation is aggregated in the *.xre* output file. Users can specify the list of reservoir IDs or the name of the reservoir that storage needs to be extracted for and the resulting storage can be stored in *.parquet* or *.csv* files.</li>
+    <li><i>convert_xdd( ):</i> Stakeholder shortages resulting from a StateMod simulation are aggregated in the <i>.xdd</i> output file. Users can specify a list of stakeholder IDs to extract shortages for and results are stored in a highly compressed and columnar <i>.parquet</i> file which easily interoperates with Pandas data frames.</li>
+    <li><i>extract_xre_data( ):</i> Reservoir storage resulting from a StateMod simulation is aggregated in the <i>.xre</i> output file. Users can specify the list of reservoir IDs or the name of the reservoir that storage needs to be extracted for and the resulting storage can be stored in <i>.parquet</i> or <i>.csv</i> files.</li>
 
   </ul>
 
-  <p>Visualizations: Within the Jupyter notebooks are examples of simple functions that can be used to visualized changes in shortages and reservoir storage relative to a historic baseline. However, within **statemodify**, there are more complex visualization functions that summarize reservoir storage across many simulations. These functions can be further adapted by the user to explore stakeholder shortages. </p></li>
+  <p>Visualizations: Within the Jupyter notebooks are examples of simple functions that can be used to visualized changes in shortages and reservoir storage relative to a historic baseline. However, within <b>statemodify</b>, there are more complex visualization functions that summarize reservoir storage across many simulations. These functions can be further adapted by the user to explore stakeholder shortages. </p></li>
 
 
-    <li>*plot_reservoir_boxes( ):* This function allows the user to create boxplots to compare the range of monthly historical reservoir storage experienced at a given reservoir vs. the range of reservoir storage that can result from synthetically generated streamflow. </li>
-    <li>*plot_res_quantiles( ):* This function allows the user to visualize the historical monthly distribution of reservoir levels at a given location versus the distribution that results under an array of simulated scenarios.</li>
+    <li><i>plot_reservoir_boxes( ):</i> This function allows the user to create boxplots to compare the range of monthly historical reservoir storage experienced at a given reservoir vs. the range of reservoir storage that can result from synthetically generated streamflow. </li>
+    <li><i>plot_res_quantiles( ):</i> This function allows the user to visualize the historical monthly distribution of reservoir levels at a given location versus the distribution that results under an array of simulated scenarios.</li>
 
   </ol>
 
 Why do we need **statemodify**?
 --------------------------------
 
-Sustainable management of Colorado’s West Slope basins is necessary to support inflow into the Colorado River and, by extension, the 40 million people that depend on it for water, hydropower, agriculture, and recreation (Flavelle, 2023). Because it is unknown how the future will manifest in the West Slope, exploratory modeling with StateMod is a valuable approach to comprehensively identify the most important drivers of change and vulnerabilities to different stakeholders. Sustainable management of the region will also ultimately require combining expert knowledge across diverse groups, ranging from federal and state institutions who are prescribing larger policy and conservation efforts down to the practical knowledge acquired from individual stakeholders, many of whom have livelihoods that have been supported by the river for many generations. In an effort to better maintain StateMod and expand their user base, CWCB and DWR have developed the CDSS Open Source Initiative (OpenCDSS), which provides Java-based TSTool and StateDMI software to create and modify StateMod input files. The statemodify package seeks to complement and expand this toolset to accommodate large ensemble exploratory modeling and a Linux-based workflow and to provide additional options to develop more targeted file adjustments and richer streamflow scenarios. The use of Python for all <b>statemodify<b> methods as well as the ease of interacting through Jupyter notebooks can further broaden the user base that can interact with StateMod and serve as a sandbox environment for quickly testing hypotheses that a user might have without the user needing to invest large amounts of time to learn how to use StateMod and develop a workflow. Examples of such questions could be: What happens to user shortages in the Gunnison if evaporation were to change over the Blue Mesa Reservoir? If user X gains a more senior water right, does this have a bigger impact on reducing their shortages than shifts to a wetter hydroclimate? 
+Sustainable management of Colorado’s West Slope basins is necessary to support inflow into the Colorado River and, by extension, the 40 million people that depend on it for water, hydropower, agriculture, and recreation (Flavelle, 2023). Because it is unknown how the future will manifest in the West Slope, exploratory modeling with StateMod is a valuable approach to comprehensively identify the most important drivers of change and vulnerabilities to different stakeholders. Sustainable management of the region will also ultimately require combining expert knowledge across diverse groups, ranging from federal and state institutions who are prescribing larger policy and conservation efforts down to the practical knowledge acquired from individual stakeholders, many of whom have livelihoods that have been supported by the river for many generations. In an effort to better maintain StateMod and expand their user base, CWCB and DWR have developed the CDSS Open Source Initiative (OpenCDSS), which provides Java-based TSTool and StateDMI software to create and modify StateMod input files. The statemodify package seeks to complement and expand this toolset to accommodate large ensemble exploratory modeling and a Linux-based workflow and to provide additional options to develop more targeted file adjustments and richer streamflow scenarios. The use of Python for all **statemodify** methods as well as the ease of interacting through Jupyter notebooks can further broaden the user base that can interact with StateMod and serve as a sandbox environment for quickly testing hypotheses that a user might have without the user needing to invest large amounts of time to learn how to use StateMod and develop a workflow. Examples of such questions could be: What happens to user shortages in the Gunnison if evaporation were to change over the Blue Mesa Reservoir? If user X gains a more senior water right, does this have a bigger impact on reducing their shortages than shifts to a wetter hydroclimate? 
 
-Though <b>statemodify<b> focuses on Colorado’s West Slope basins, this case study is representative of a broader group of institutionally complex basins that are experiencing extreme conditions due to their own regionally-specific deep uncertainties. Discovering vulnerabilities of users in these regions will likely require similar finely resolved models along with extensive computational resources. It is important to note that not every user has access to the computational resources required to do exploratory modeling. At this point in time, those users are unable to participate in this type of modeling effort. To help overcome this barrier, we demonstrate <b>statemodify<b> and the associated notebooks in containers hosted by MSD-LIVE that allow any user to conduct a small scale analysis. Users can also use the associated Dockerfiles to download and compile StateMod and run the same Jupyter notebooks on their own personal computers or high performance computing (HPC) resources. Work is currently in progress to connect statemodify with cloud platforms, such as Amazon Web Services, Microsoft Azure, and Google Cloud, which provide more accessible tiers of computing to students and researchers who don’t have access to HPC. Overall, the statemodify framework will not only broaden the user base that can interact with StateMod, but also can serve as a guide on how to make exploratory modeling accessible to diverse groups whose inclusion can lead to more robust basin management.    
+Though **statemodify** focuses on Colorado’s West Slope basins, this case study is representative of a broader group of institutionally complex basins that are experiencing extreme conditions due to their own regionally-specific deep uncertainties. Discovering vulnerabilities of users in these regions will likely require similar finely resolved models along with extensive computational resources. It is important to note that not every user has access to the computational resources required to do exploratory modeling. At this point in time, those users are unable to participate in this type of modeling effort. To help overcome this barrier, we demonstrate **statemodify** and the associated notebooks in containers hosted by MSD-LIVE that allow any user to conduct a small scale analysis. Users can also use the associated Dockerfiles to download and compile StateMod and run the same Jupyter notebooks on their own personal computers or high performance computing (HPC) resources. Work is currently in progress to connect statemodify with cloud platforms, such as Amazon Web Services, Microsoft Azure, and Google Cloud, which provide more accessible tiers of computing to students and researchers who don’t have access to HPC. Overall, the statemodify framework will not only broaden the user base that can interact with StateMod, but also can serve as a guide on how to make exploratory modeling accessible to diverse groups whose inclusion can lead to more robust basin management.    
 
 
 Planning and Management Models