0.9 (#47)

* treat reservoirs better in valudation, vocab name updates, rename bootstrap module, bug fix in assignments process * rename calibrate.py to saber.py * separate fdc functions to new module, consider cluster numbers when making bootstrap assignments, shorten bootstrap module name * revisions to the docs * increment version number. linting and formatting.
rileyhales · Dec 15, 2022 · 375a92b · 375a92b
1 parent 23279a7
commit 375a92b
Show file tree

Hide file tree

Showing 32 changed files with 584 additions and 562 deletions.
diff --git a/.gitignore b/.gitignore
@@ -128,15 +128,6 @@ dmypy.json
 # Pyre type checker
 .pyre/
 
-# Pycharm project folder
+# Pycharm project folders
 .idea/
-*.png
-
-# Spatial data
-*.zip
-*.nc*
-*.geojson
-south_america-geoglows-drainageline/
-south_america-geoglows-catchment/
-south_america-geoglows-boundary/
-magdalena_watershed_shp/
+.run/
diff --git a/docs/api/bs.md b/docs/api/bs.md
@@ -0,0 +1,3 @@
+# `saber.bs`
+
+::: saber.bs
diff --git a/docs/api/fdc.md b/docs/api/fdc.md
@@ -0,0 +1,3 @@
+# `saber.fdc`
+
+::: saber.fdc
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -1,7 +1,10 @@
 # `saber-hbc` API
 
 * [`saber.assign`](assign.md)
+* [`saber.bs`](bs.md)
 * [`saber.cluster`](cluster.md)
+* [`saber.fdc`](fdc.md)
 * [`saber.gis`](gis.md)
-* [`saber.prep`](prep.md)
-* [`saber.validate`](validate.md)
+* ['saber.io`](io.md)
+* [`saber.saber`](saber.md)
+* [`saber.table`](table.md)
diff --git a/docs/api/io.md b/docs/api/io.md
@@ -0,0 +1,3 @@
+# `saber.io`
+
+::: saber.io
diff --git a/docs/api/prep.md b/docs/api/prep.md
diff --git a/docs/api/saber.md b/docs/api/saber.md
@@ -0,0 +1,3 @@
+# `saber.saber`
+
+::: saber.saber
diff --git a/docs/api/table.md b/docs/api/table.md
@@ -0,0 +1,3 @@
+# `saber.table`
+
+::: saber.table
diff --git a/docs/api/validate.md b/docs/api/validate.md
diff --git a/docs/data/discharge-data.md b/docs/data/discharge-data.md
diff --git a/docs/data/gis-data.md b/docs/data/gis-data.md
diff --git a/docs/data/index.md b/docs/data/index.md
diff --git a/docs/demo/index.md b/docs/demo/index.md
@@ -1 +1 @@
-# Example in Magdalena River, Colombia
+# Bias Correcting the GEOGloWS Hydrologic Model
diff --git a/docs/user-guide/assignments_table.md b/docs/user-guide/assignments_table.md
@@ -1,72 +1,16 @@
-The Assignments Table is the core of the `saber` python package. It is a table which has a row for every stream segment 
-in the model and several columns which are populated by the GIS datasets and by the results of the SABER process.
-
-The Assignments Table is a `pandas` dataframe which is saved to disk as a `parquet` file.
-
-| downstream_model_id | model_id          | drainage_area | stream_order | gauge_id         |
-|---------------------|-------------------|---------------|--------------|------------------|
-| unique_stream_num   | unique_stream_num | area in km^2  | stream_order | unique_gauge_num |
-| unique_stream_num   | unique_stream_num | area in km^2  | stream_order | unique_gauge_num |
-| unique_stream_num   | unique_stream_num | area in km^2  | stream_order | unique_gauge_num |
-| ...                 | ...               | ...           | ...          | ...              |
-
-
-
-### 6 Assign basins by Location (streams which contain a gauge)
-This step involves editing the `assign_table.csv` and but does not change the file structure of the project.
-
-This step uses the information prepared in the previous steps to assign observed streamflow information to modeled 
-stream segments which will be used for calibration. This step does not produce any new files but it does edit the 
-existing assign_table csv file. After running these lines, use the `rbc.table.cache` function to write the changes to 
-disc.
-
-The justification for this is obvious. The observations are the actual streamflow for that basin. 
-
-- If a basin contains a gauge, the simulated basin should use the data from the gauge in that basin.
-- The reason listed for this assignment is "gauged"
-
-```python
-import saber as saber
-
-# assign_table = pandas DataFrame (see saber.table module)
-workdir = '/path/to/project/directory/'
-assign_table = saber.table.read(workdir)
-saber.assign.gauged(assign_table)
-```
-
-### 7 Assign basins by Propagation (hydraulically connected to a gauge)
-This step involves editing the `assign_table.csv` and does not change the file structure of the project.
-
-Theory: being up/down stream of the gauge but on the same stream order probably means that the seasonality of the flow is 
-probably the same (same FDC), but the monthly average may change depending on how many streams connect with/diverge from the stream. 
-This assumption becomes questionable as the stream order gets larger so the magnitude of flows joining the river may be larger, 
-be less sensitive to changes in flows up stream, may connect basins with different seasonality, etc.
-
-- Basins that are (1) immediately up or down stream of a gauge and (2) on streams of the same order should use that gauged data.
-- The reason listed for this assignment is "propagation-{direction}-{i}" where direction is either "upstream" or "downstream" and 
-  i is the number of stream segments up/down from the gauge the river is.
-
-```python
-import saber as saber
-
-# assign_table = pandas DataFrame (see saber.table module)
-workdir = '/path/to/project/directory/'
-assign_table = saber.table.read(workdir)
-saber.assign.propagation(assign_table)
-```
-
-### 8 Assign basins by Clusters (hydrologically similar basins)
-This step involves editing the `assign_table.csv` and but does not change the file structure of the project.
-
-Using the results of the optimal clusters
-- Spatially compare the locations of basins which were clustered for being similar on their flow duration curve.
-- Review assignments spatially. Run tests and view improvements. Adjust clusters and reassign as necessary.
-
-```python
-import saber as saber
-
-# assign_table = pandas DataFrame (see saber.table module)
-workdir = '/path/to/project/directory/'
-assign_table = saber.table.read(workdir)
-saber.assign.clusters_by_dist(assign_table)
-```
+# Assignment Table
+
+The Assignments Table is the core of the `saber` python package. It is a `pandas` dataframe which is saved to disk as a 
+`parquet` file. It has 1 row per subbasin in your hydrologic model. It is generated from the `drain_table`, `gauge_table`, 
+and `regulate_table` input files. The table has the following columns:
+
+1. `model_id`: The unique ID of the stream segment. This is the same as the `model_id` in the `drain_table` and `drain_gis`.
+2. `downstream_model_id`: The ID of the next downstream reach, used to trace the network programmatically. This comes from the `drain_table`.
+3. `strahler_order`: The strahler stream order of each reach. This comes from the `drain_table`.
+4. `x`: The x coordinate of the centroid of each subbasin. This comes from the `drain_table`.
+5. `y`: The y coordinate of the centroid of each subbasin. This comes from the `drain_table`.
+6. `gauge_id`: The unique ID of the gauge contained by the subbasin. This comes from the `gauge_table`. This will be blank for most rows.
+7. `regulated_id`: The unique ID of the regulatory structure contained by the subbasin. This comes from the `regulate_table`. This will be blank for most rows.
+8. `latitude`: The latitude of each gauge. This comes from the `gauge_table`.
+9. `longitude`: The longitude of each gauge. This comes from the `gauge_table`.
+10. `cluster_label`: The cluster label of each subbasin. This is used to group subbasins together for calibration. This column is generated by SABER.
diff --git a/docs/user-guide/bias_correction.md b/docs/user-guide/bias_correction.md
@@ -1,23 +1 @@
-### 10 Calibrate the region
-This step creates a netCDF of the best guess at historically simulated flows for all stream reaches in a region.
-
-```
-working_directory/
-    assign_table.csv
-    calibrated_simulated_flow.nc        <-- New
-    
-    kmeans_models/
-        (same as previous steps...)
-    kmeans_images/
-        (same as previous steps...)
-    data_inputs/
-        (same as previous steps...)
-    data_processed/
-        (same as previous steps...)
-    gis_inputs/
-        (same as previous steps...)
-    gis_outputs/
-        (same as previous steps...)
-    validation_sets/
-        (empty)
-```
+### SABER Bias Correction
diff --git a/docs/user-guide/data_preparation.md b/docs/user-guide/data_preparation.md
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		# Example in Magdalena River, Colombia
		# Bias Correcting the GEOGloWS Hydrologic Model