fmda/README.md

   1 # FMDA Readme
   2
   3 Code repository for project to build RNN models to predict dead fuel moisture content
   4
   5 ## Setup
   6
   7 Clone repository:
   8         git clone https://github.com/openwfm/notebooks
   9
  10 Build and activate environment:
  11
  12 * cd ./fmda/install
  13 * conda env create -f fmda_ml.yml
  14 * conda activate fmda_ml
  15
  16
  17 ## Main Notebooks
  18
  19 * version_control/rnn_train_versions.ipynb
  20     - Runs model in testing type mode where exact initial and fitted hashes are checked against known history
  21         - Shows reproducibility changes and major code restructuring
  22
  23 * fmda_rnn_serial.ipynb
  24     - Automatically retrieves fmda dictionary from OpenWFM Demo
  25     - Trains and predicts the model at multiple locations in serial fashion
  26          1. Train separate models at multiple locations and compare predictions on that location itself
  27          2. Train single model with data from multiple locations. Take same model object and call .fit multiple times. Compare predictions for new locations
  28
  29 * fmda_rnn_spatial.ipynb
  30     - Automatically retrieves fmda dictionary from OpenWFM Demo
  31     - Runs RNN with spatial training scheme, RNN with serial training scheme (see above), and ODE+KF
  32     - Compares prediction RMSE
  33
  34 * synoptic_tutorial.ipynb
  35     - Use to manually read in RAWS data from Synoptic
  36
  37
  38 ## Data
  39
  40 The data structure used for this project is nested dictionaries. A "case" of data consists of FMC observations and atmospheric data at a particular location. The FMC data always comes from RAWS ground-level observations, and the atmospheric data can be from a variety of sources. The data acquisition for this project is built off a branch of `wrfxpy`, branch "develop-72-jh", which merges RAWS and HRRR data
  41
  42 - Saved within the repository is a dataset used to ensure reproducibility. As of 20-6-2024, that file is: `data\reproducibility_dict2.pickle`
  43 - Other formatted FMDA dictionaries are staged at the OpenWFM demo page and retrieved via wget:
  44 https://demo.openwfm.org/web/data/fmda/dicts/
  45
  46 ## RNN Code
  47
  48 The source code lives in the module "moisture_rnn.py". The module has:
  49
  50 * Superclass RNNModel
  51         - Child class for SimpleRNN
  52         - Child class for LSTM
  53 * Helper code to format data for RNN
  54         - staircase_2 used to batch/sequence timeseries data
  55
  56
  57