update readme

README.md

@@ -4,68 +4,29 @@
 
 
 # statemodify
-A package to modify StateMod's input and output files for exploratory modeling
+`statemodify` is an open-source Python package that provides users with a way to easily modify [StateMod](https://github.com/OpenCDSS/cdss-app-statemod-fortran)'s input and output files to enable exploratory modeling. StateMod is written in Fortran and conducting high-performance computing enabled ensemble exploratory modeling with it requires a systematic and automated approach. Due to the model’s complexity, there are also nontrivial computational challenges in comprehensively sampling the model’s input space and managing the outputs of interest, especially for large ensembles. These challenges limit its use among researchers and broader operational users. Thus, we developed `statemodify`, a Python package and framework that allows users to easily interact with StateMod using Python exclusively. The user can implement statemodify functions to manipulate StateMod’s input files to develop alternative demand, hydrology, infrastructure, and institutional scenarios for Colorado’s West Slope basins and run these scenarios through StateMod. We also create methods to compress and extract model output into easily readable data frames and provide guidance on analysis and visualization of output in a series of Jupyter notebooks that step through the functionality of the package.
 
-## In development
-While in development, install `statemodify` using the following steps:
-- Clone the repo using `git clone https://github.com/IMMM-SFA/statemodify.git`
-- Navigate to the directory in which `statemodify` was cloned and run `python setup.py develop`.  Ensure your `python` points to a Python 3.8 and up instance.
-- Test the install by entering into a Python prompt and running:  `import statemodify`, if no errors, you are all good.
+## Documentation
+Full documentation and tutorials are provided [here](https://immm-sfa.github.io/statemodify).
 
-## Functionality
-### Generate a set of .ddm files using a LHS
-```python
-import statemodify as stm
-
-# a dictionary to describe what you want to modify and the bounds for the LHS
-setup_dict = {
-    "names": ["municipal", "standard"],
-    "ids": [["7200764", "7200813CH"], ["7200764_I", "7200818"]],
-    "bounds": [[-1.0, 1.0], [-1.0, 1.0]]
-}
-
-output_directory = "<your desired output directory>"
-scenario = "<your scenario name>"
-
-# the number of samples you wish to generate
-n_samples = 4
-
-# seed value for reproducibility if so desired
-seed_value = None
-
-# my template file.  If none passed into the `modify_ddm` function, the default file will be used.
-template_file = "<your ddm template file>"
+## Installation
+Install `statemodify` using pip:
+```bash
+pip install statemodify
+```
 
-# the field that you want to use to query and modify the data
-query_field = "id"
+## Online quickstarter tutorials
+Take a `statemodify` for a spin in one of our no-install Jupyter quickstarters [here](https://statemodify.msdlive.org):
 
-# generate a batch of files using generated LHS
-stm.modify_ddm(modify_dict=setup_dict,
-               output_dir=output_directory,
-               scenario=scenario,
-               n_samples=n_samples,
-               seed_value=seed_value,
-               query_field=query_field,
-               template_file=template_file)
-```
+- **Notebook 1**:  Getting Started and using the DDM and DDR modification functions in the San Juan Subbasin.  This notebook has more general intro information on `statemodify` and shows how changes to demand and water rights can lead to changes to user shortages in the San Juan Subbasin.
 
-### Convert output .xdd files to .parquet files
-Parquet files are efficient columnar data stores that easily interoperate with pandas dataframes.
-```python
-from statemodify.xdd import XddConverter
+- **Notebook 2**:  Using the EVA modification functions in the Gunnison Subbasin.  This notebook looks at how changes in evaporation in reservoirs in the Gunnison subbasin lead to changes to reservoir levels.
 
-# set up the converter
-converter = XddConverter(
-    output_path='./output',
-    allow_overwrite=False,
-    xdd_files='**/*.xdd',
-    id_subset=None,
-    parallel_jobs=4,
-)
+- **Notebook 3**:  Using the RES modification function in the Upper Colorado Subbasin.  This notebook looks at how changes in storage in reservoirs in the Upper Colorado subbasin lead to changes to user shortages.
 
-# convert the files
-converter.convert()
+- **Notebook 4**:  Using the XBM and IWR modification functions across all basins.  This notebook debuts the stationary Hidden Markov Model to generate alternative streamflow scenarios across the basins.
 
-# look for your parquet files in './output'!
+- **Notebook 5**:  Sampling multiple uncertainties.  This notebook demonstrates how to create a global Latin hypercube sample to consider multiple uncertainties in a basin.
 
-```
+## Contributing to `statemodify`
+Whether you find a typo in the documentation, find a bug, or want to develop functionality that you think will make statemodify more robust, you are welcome to contribute!  See the full contribution guidelines in our [online documentation](https://immm-sfa.github.io/statemodify/reference/contributing.html).