Open nickrsan opened 4 years ago
nickrsan
commented
4 years ago Going to build the 4 steps into the FFC processor class, make it underlie the evaluate_timeseries_alteration call, and then move some of the other subfunctions into the class as long as they aren't exported. It'll clean a few things up - most things don't need a separate low-level API without the class, so it should be safe to move them in. Check with Ryan about if he's using any of those other functions directly
nickrsan
commented
4 years ago Some progress on this issues in f18833d72b70ad514ecaf054c2fc6184922cc286 - incorporates the first step of CEFF process. Example code:
library(ffcAPIClient)
ffc <- FFCProcessor$new()
ffc$step_one_functional_flow_results(gage_id=111111111, token="your token value here", output_folder = "Folder Path to Put Plots and CSVs in")Considering making a shortcut function for it.
nickrsan
commented
4 years ago > ffc <- FFCProcessor$new()
> ffc$step_one_functional_flow_results(gage_id=11336000, token=mytoken, output_folder = "C:/Users/myusername/Downloads/test")
[1] "### Step 1 - Get Functional Flow Results ###"
[1] "Retrieving results, please wait..."
[1] "Using date format string %m/%d/%Y"
[1] "COMID 3953273 is of stream class RGW - sending parameters to FFC online for that stream class. This may produce different results than if you run data through the FFC yourself using their default parameters."
[1] "Results ready."
[1] "Writing FFC results as CSVs to C:/Users/myusername/Downloads/test"
[1] "Writing observed plots to C:/Users/myusername/Downloads/test"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_DS__observed_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_FA__observed_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Wet__observed_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_SP__observed_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Peak_Tim_observed_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Peak_Dur_observed_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Peak_Fre_observed_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Peak__observed_only.png"
[1] "Printing Observed/FFC Percentiles. You can also access attributes $ffc_results on this object for the annual values for each metric, $ffc_percentiles for calculated percentile values, and $doh_data for the Dimensionless Observed Hydrograph data."
p10 p25 p50 p75 p90 metric comid result_type
DS_Dur_WS 1.246000e+02 1.430000e+02 1.640000e+02 1.880000e+02 2.194000e+02 DS_Dur_WS 3953273 observed
DS_Tim 2.463000e+02 2.605000e+02 2.720000e+02 2.860000e+02 3.000000e+02 DS_Tim 3953273 observed
DS_Mag_50 0.000000e+00 0.000000e+00 0.000000e+00 9.400000e+00 2.760000e+01 DS_Mag_50 3953273 observed
DS_Mag_90 1.001400e+01 3.160000e+01 6.440000e+01 9.960000e+01 1.333200e+02 DS_Mag_90 3953273 observed
FA_Dur 2.000000e+00 2.000000e+00 3.000000e+00 6.000000e+00 8.000000e+00 FA_Dur 3953273 observed
FA_Mag 4.399288e+01 7.149487e+01 1.289939e+02 1.894926e+02 4.829999e+02 FA_Mag 3953273 observed
FA_Tim 9.000000e+00 1.600000e+01 2.900000e+01 4.350000e+01 4.900000e+01 FA_Tim 3953273 observed
Wet_Tim 3.480000e+01 4.500000e+01 7.500000e+01 9.900000e+01 1.084000e+02 Wet_Tim 3953273 observed
SP_ROC 4.914735e-02 5.456762e-02 6.896194e-02 8.459344e-02 9.503582e-02 SP_ROC 3953273 observed
SP_Dur 3.090000e+01 4.450000e+01 5.800000e+01 7.000000e+01 9.010000e+01 SP_Dur 3953273 observed
SP_Mag 4.127000e+02 8.325000e+02 1.320000e+03 2.732500e+03 6.950000e+03 SP_Mag 3953273 observed
SP_Tim 1.637000e+02 1.977500e+02 2.130000e+02 2.302500e+02 2.374000e+02 SP_Tim 3953273 observed
Wet_BFL_Dur 8.600000e+01 1.095000e+02 1.330000e+02 1.630000e+02 1.776000e+02 Wet_BFL_Dur 3953273 observed
Wet_BFL_Mag_10 6.564000e+01 9.100000e+01 1.260000e+02 2.198000e+02 3.371200e+02 Wet_BFL_Mag_10 3953273 observed
Wet_BFL_Mag_50 2.886000e+02 5.030000e+02 8.720000e+02 1.077500e+03 1.560000e+03 Wet_BFL_Mag_50 3953273 observed
Peak_Tim_10 6.380000e+01 8.300000e+01 8.300000e+01 1.600000e+02 1.744000e+02 Peak_Tim_10 3953273 observed
Peak_Tim_2 8.700000e+01 1.060000e+02 1.220000e+02 1.530000e+02 1.560000e+02 Peak_Tim_2 3953273 observed
Peak_Tim_5 7.660000e+01 8.300000e+01 1.050000e+02 1.240000e+02 1.458000e+02 Peak_Tim_5 3953273 observed
Peak_Dur_10 1.000000e+00 1.000000e+00 1.000000e+00 1.000000e+00 1.600000e+00 Peak_Dur_10 3953273 observed
Peak_Dur_2 1.000000e+00 3.000000e+00 4.000000e+00 8.000000e+00 1.100000e+01 Peak_Dur_2 3953273 observed
Peak_Dur_5 1.000000e+00 1.000000e+00 2.000000e+00 2.000000e+00 3.400000e+00 Peak_Dur_5 3953273 observed
Peak_10 2.077000e+04 2.077000e+04 2.077000e+04 2.077000e+04 2.077000e+04 Peak_10 3953273 observed
Peak_2 7.080000e+03 7.080000e+03 7.080000e+03 7.080000e+03 7.080000e+03 Peak_2 3953273 observed
Peak_5 1.674000e+04 1.674000e+04 1.674000e+04 1.674000e+04 1.674000e+04 Peak_5 3953273 observed
Peak_Fre_10 1.000000e+00 1.000000e+00 1.000000e+00 1.000000e+00 1.000000e+00 Peak_Fre_10 3953273 observed
Peak_Fre_2 1.000000e+00 2.000000e+00 3.000000e+00 3.000000e+00 4.000000e+00 Peak_Fre_2 3953273 observed
Peak_Fre_5 1.000000e+00 1.000000e+00 1.000000e+00 1.000000e+00 1.200000e+00 Peak_Fre_5 3953273 observed
[1] "Step 1 complete"
Warning message:
In get_predicted_flow_metrics_online(comid, wyt = wyt) :
Flow metric data from API contained duplicated records for some flow metrics that we automatically removed. This is a data quality issue in the predicted data - it can occasionally produce incorrect results - check the values of the predicted flow metrics at https://flows.codefornature.org
> ffc$step_two_explore_ecological_flow_criteria()
[1] "### Step 2 - Explore Ecological Flow Criteria ###"
[1] "Printing Predicted Percentiles. You can also access attributes $predicted_percentiles on this object for these data."
comid p10 p25 p50 p75 p90 source result_type metric
1 3953273 103.96000 133.50000 160.0000 189.0200 221.5300 model predicted DS_Dur_WS
5 3953273 0.00000 0.00000 0.0000 9.4000 27.6000 observed predicted DS_Mag_50
9 3953273 10.01400 31.60000 64.4000 99.6000 133.3200 observed predicted DS_Mag_90
13 3953273 227.19000 246.50000 265.0000 280.7500 301.0400 model predicted DS_Tim
17 3953273 2.00000 2.00000 3.0000 6.0000 8.0000 observed predicted FA_Dur
18 3953273 43.99288 71.49487 128.9939 189.4926 482.9999 observed predicted FA_Mag
22 3953273 7.11000 13.40000 27.7500 40.2100 50.6000 model predicted FA_Tim
26 3953273 11771.90000 21810.53000 25518.8300 31070.7600 36097.2900 model predicted Peak_10
30 3953273 3734.67000 7557.57000 13434.3500 20921.8600 37408.4200 model predicted Peak_2
34 3953273 10425.45000 14620.45000 21096.7600 30182.3600 43452.6300 model predicted Peak_5
38 3953273 1.00000 1.00000 1.0000 1.0000 1.6000 observed predicted Peak_Dur_10
39 3953273 1.00000 1.00000 3.0000 7.0000 16.0000 inferred predicted Peak_Dur_2
40 3953273 1.00000 1.00000 1.0000 3.0000 4.8000 inferred predicted Peak_Dur_5
41 3953273 1.00000 1.00000 1.0000 1.0000 1.0000 observed predicted Peak_Fre_10
42 3953273 1.00000 1.00000 2.0000 3.0000 5.0000 inferred predicted Peak_Fre_2
43 3953273 1.00000 1.00000 1.0000 1.0000 1.2000 observed predicted Peak_Fre_5
44 3953273 30.90000 44.50000 58.0000 70.0000 90.1000 observed predicted SP_Dur
48 3953273 412.70000 832.50000 1320.0000 2732.5000 6950.0000 observed predicted SP_Mag
52 3953273 0.04000 0.05000 0.0700 0.1000 0.1600 inferred predicted SP_ROC
53 3953273 162.00000 179.28000 195.6100 211.6300 227.0200 model predicted SP_Tim
57 3953273 69.38000 91.20000 115.0000 146.5700 175.6700 model predicted Wet_BFL_Dur
61 3953273 55.07000 100.70000 159.3200 268.8900 352.2600 model predicted Wet_BFL_Mag_10
65 3953273 253.45000 366.40000 579.9600 823.6500 1111.1200 model predicted Wet_BFL_Mag_50
69 3953273 34.80000 45.00000 75.0000 99.0000 108.4000 observed predicted Wet_Tim
[1] "Writing Predicted Percentiles as CSV to C:/Users/myusername/Downloads/test"
[1] "Writing predicted metric plots to C:/Users/myusername/Downloads/test"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_DS__predicted_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_FA__predicted_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Wet__predicted_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_SP__predicted_only.png"
[1] "Skipping plot for Peak_Tim. No data"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Peak_Dur_predicted_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Peak_Fre_predicted_only.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Peak__predicted_only.png"
[1] "Step 2 complete"
> ffc$step_three_assess_alteration()
[1] "### Step 3 - Assess Alteration ###"
[1] "Printing alteration assessment data. You can also access attributes $alteration on this object for these data"
metric status_code status alteration_type median_in_iqr comid
DS_Dur_WS DS_Dur_WS 1 likely_unaltered none_found TRUE 3953273
DS_Tim DS_Tim 1 likely_unaltered none_found TRUE 3953273
DS_Mag_50 DS_Mag_50 1 likely_unaltered none_found TRUE 3953273
DS_Mag_90 DS_Mag_90 1 likely_unaltered none_found TRUE 3953273
FA_Dur FA_Dur 1 likely_unaltered none_found TRUE 3953273
FA_Mag FA_Mag 1 likely_unaltered none_found TRUE 3953273
FA_Tim FA_Tim 1 likely_unaltered none_found TRUE 3953273
Wet_Tim Wet_Tim 1 likely_unaltered none_found TRUE 3953273
SP_ROC SP_ROC 1 likely_unaltered none_found TRUE 3953273
SP_Dur SP_Dur 1 likely_unaltered none_found TRUE 3953273
SP_Mag SP_Mag 1 likely_unaltered none_found TRUE 3953273
SP_Tim SP_Tim 1 likely_unaltered none_found FALSE 3953273
Wet_BFL_Dur Wet_BFL_Dur 1 likely_unaltered none_found TRUE 3953273
Wet_BFL_Mag_10 Wet_BFL_Mag_10 1 likely_unaltered none_found TRUE 3953273
Wet_BFL_Mag_50 Wet_BFL_Mag_50 1 likely_unaltered none_found FALSE 3953273
Peak_Dur_10 Peak_Dur_10 1 likely_unaltered none_found TRUE 3953273
Peak_Dur_2 Peak_Dur_2 1 likely_unaltered none_found TRUE 3953273
Peak_Dur_5 Peak_Dur_5 1 likely_unaltered none_found TRUE 3953273
Peak_10 Peak_10 1 likely_unaltered none_found FALSE 3953273
Peak_2 Peak_2 1 likely_unaltered none_found FALSE 3953273
Peak_5 Peak_5 1 likely_unaltered none_found TRUE 3953273
Peak_Fre_10 Peak_Fre_10 1 likely_unaltered none_found TRUE 3953273
Peak_Fre_2 Peak_Fre_2 1 likely_unaltered none_found TRUE 3953273
Peak_Fre_5 Peak_Fre_5 1 likely_unaltered none_found TRUE 3953273
[1] "Writing alteration assessment as CSV to C:/Users/myusername/Downloads/test"
[1] "Writing comparison plots to C:/Users/myusername/Downloads/test"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_DS_.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_FA_.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Wet_.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_SP_.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Peak_Tim.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Peak_Dur.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Peak_Fre.png"
[1] "Writing C:/Users/myusername/Downloads/test/3953273_Peak_.png"
[1] "Step 3 complete"@alyssaobester See above for a full example output, including messages it gives the user. Here's a bit of just how to use it.
library(ffcAPIClient)
ffc <- FFCProcessor$new() # make a new object we can use to run the commands
# configure the object and run CEFF step 1 plus outputs
ffc$step_one_functional_flow_results(gage_id=11336000,
token=token,
output_folder = "C:/Users/myusername/Downloads/test")That command will output DOH data + image, observed annual data, observed percentiles, and observed plots to the specified folder. It will output the percentiles to the console as well.
It also makes that data available for further analysis on the object ffc, so you can now access the FFC results by year as ffc$ffc_results, the processed percentiles as ffc$ffc_percentiles, and the underlying DOH data as ffc$doh_data if you want to view them again in R or feed them into other code and visualizations.
For step 2, we now run simply ffc$step_two_explore_ecological_flow_criteria() and it continues where we left off. In fact, everything is run in step 1, and we just control what is output with these functions. This outputs the predicted metric percentile data as a CSV and to the console, and plots the predicted values on their own.
Now we can access ffc$predicted_percentiles if we want to feed that into other processing or visualizations too.
For step 3, same thing. Run ffc$step_three_assess_alteration() and get the alteration data frame saved as a CSV and printed to the console. Full comparison plots of predicted vs. observed percentiles are output now to the screen and to the folder specified in step 1 (where everything is saved).
And now we get one more thing we can access - ffc$alteration contains the alteration assessment results. In fact everything is accessible after step 1, but conceptually, this is the data frame that corresponds with this step.
There's also more that's available as part of the ffc object, but we'll document that elsewhere.
Let me know if you have any questions. I'm going to leave this open until true documentation is complete.
nickrsan
commented
4 years ago The code here was just pushed earlier - it shouldn't interfere with any of the other code (very few changes outside of these functions), but let me know if you have any issues after reinstalling the package.
nickrsan
commented
4 years ago OK, I adapted the documentation I wrote on this above as the beginnings of a vignette in the package documentation too: https://ceff-tech.github.io/ffc_api_client/articles/ceff-steps.html
Notes from our call today - I'll split these out into separate items soon, but wanted to file it immediately so it's visible.
[x] add source column to observed percentiles
[x] add comid or gage_id column to ffc_results df
[ ] batch shortcut that returns a big dataframe with everything.
[x] add assess_alteration to evaluate_alteration functions
[ ] Add documentation for evaluate_alteration
[x] change Metric columns to "metric"
[ ] Create three functions that mirror the steps in the document:
[ ] Store data in a named environment for the run between these functions.
Potential new names for shortcuts assess_alteration assess_gage_alteration evaluate_fc_alteration or evaluate_flow_criteria_alteration.