From 75e7969d3995d2ee7416f88173d7524963d4d7c0 Mon Sep 17 00:00:00 2001 From: rmshkv Date: Wed, 14 Feb 2024 15:01:01 -0700 Subject: [PATCH 1/9] Added simplest instructions --- docs/addingnotebookstocollection.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/addingnotebookstocollection.md diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md new file mode 100644 index 00000000..72dae72a --- /dev/null +++ b/docs/addingnotebookstocollection.md @@ -0,0 +1,27 @@ +# How to add diagnostics notebooks + +1. Put your new diagnostic notebook in the folder called `examples/nblibrary`. +2. In your notebook, move all variables you might want to change (paths to data, dates to select, etc.) to a cell near the top. For example: + + sname = "run_name" + data_path = "path/to/data" + dates = {"start_date" = "01/01/01", + "end_date" = "01/01/02"} + +3. Tag this cell as `parameters`. This means that when the notebook is executed by `cupid`, a new cell will be inserted just below this one with all of the parameters you specify in `config.yml` (see step 4). To tag it, in Jupyter Lab, click on the cell and click the button with two gears in the top right ("Property Inspector"). Open "Common Tools." There, you can see a section called "Cell Tags." Click "Add Tag," and add one called `parameters` (exactly as written). + +4. Open `config.yml`. First, add your new notebook (as its name, minus the `.ipynb`) to the list of notebooks that will be computed (`compute_notebooks`). For example: + + your_new_nb_name: + parameter_groups: + none: + param_specific_to_this_nb: some_value + another_param: another_value + + If you just want the notebook run once on one set of parameters, keep the`parameter_groups: none:` notation as above. If you want the notebook executed multiple times with different parameter sets, see [this config.yml](https://github.com/rmshkv/nbscuid-examples/blob/main/tutorial/config.yml) for an example of setting this up. + +6. If you'd like your new notebook included in the final Jupyter Book, add it to the Jupyter Book table of contents (`book_toc`). See [Jupyter Book's documentation](https://jupyterbook.org/en/stable/structure/toc.html) for different things you can do with this. + +7. Update your parameters. Parameters that are specific to just this notebook should go under `parameter_groups` in the notebook's entry under `compute_notebooks`. Global parameters that you want passed in to every notebook in the collection should go under `global_params`. When `cupid` executes your notebook, all of these parameters will get put in a new cell below the cell tagged `parameters` that you added in step 3. This means they will supercede the values of the parameters that you put in the cell above---the names, notation, etc. should match to make sure your notebook is able to find the variables it needs. + +8. All set! Your collection can now be run and built with `cupid-run config.yml` and `cupid-build config.yml` as usual. From e4561aaf4227cf3632ee4473fda0d70b46f142a7 Mon Sep 17 00:00:00 2001 From: rmshkv Date: Wed, 14 Feb 2024 15:01:18 -0700 Subject: [PATCH 2/9] Made sure other changes were included --- docs/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 25f6649d..cdd43d15 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,4 +5,5 @@ CUPiD Documentation :maxdepth: 2 :hidden: - Installation Guide \ No newline at end of file + Installation Guide + Adding Notebooks \ No newline at end of file From a8be3f970c11b8185e56fdd57844056c40a3f633 Mon Sep 17 00:00:00 2001 From: rmshkv Date: Wed, 14 Feb 2024 15:13:37 -0700 Subject: [PATCH 3/9] Added explicit multiple param group instructions --- docs/addingnotebookstocollection.md | Bin 2518 -> 2899 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index 72dae72a7fce657529a909654d3101e7c2a771b9..da963f201b7c50771e5482c86514b2ec1737f882 100644 GIT binary patch delta 528 zcma)(zY4-I5XJ-Il2vfNSzKD3@-k_(R}F2FlBSd*(pM6E6v5qxa5q}(AF60>IJocb zyZe#j=rG>#VdK^a+Bo5)(NLK(iy<>6g-oUhZY>K&X%s~i?yokbwhcy5I delta 144 zcmYMtJqiLb5J2H#5f30(PpO5O-m8c%Nz5jL`6DwCt-O-pQ3P*dFNk3O_}+8*THMFk zjh%y?1Y)oyPvq4##r-OXRNf+blF*H^C1Fb(PG`)9ZKvbLU399^F`8HmCQTWoOKGGd d{-rfcrGd`y%b`rbPK2_D?{w%@Jr48t@BwwAHNOA= From 622a82587d7040eb02ada8c6416e609b36bdc68a Mon Sep 17 00:00:00 2001 From: rmshkv Date: Wed, 14 Feb 2024 15:23:42 -0700 Subject: [PATCH 4/9] Fixing formatting --- docs/addingnotebookstocollection.md | Bin 2899 -> 2892 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index da963f201b7c50771e5482c86514b2ec1737f882..16d84f3510533e8e21ee74405b316f59e2704102 100644 GIT binary patch delta 17 ZcmcaCc1CPNGwbGd)+>ygjc3EsgGb?jKLc-=I)~k$QMmYOdW&nQJ31a{N From 5e9a9ddb7297f1d8aedac6138598686b17edb131 Mon Sep 17 00:00:00 2001 From: rmshkv Date: Wed, 14 Feb 2024 15:29:37 -0700 Subject: [PATCH 5/9] Trying again to fix formatting --- docs/addingnotebookstocollection.md | Bin 2892 -> 2931 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index 16d84f3510533e8e21ee74405b316f59e2704102..f0adf316fdce7e8772a47db4e16aed3bfa290e1b 100644 GIT binary patch delta 106 zcmX>j_E~JhBNj%5$&XkTGI4TF?q-!@Q2>I;iY#K29od8@pJJ7p9Kgmh`30*InC48Kq@;x>&pgMD)xZGw(c5W5`mAD>( delta 129 zcmew?c1CQ&BbLdJSr%F-KtW}GX;FM$YI%HKQhZ)wZmJa*OeU8hmBEUEi$MVj3m6g^ zthgrcW7VDfo>ghGD4XJBKX$gs4s6OmT5575o7&`atZb7vvWbJ`Kf&cWCabcmZuVnW GWdQ(ljw6@= From df631ae8b797e44e5a0ddd5d8ee543dcfbe48926 Mon Sep 17 00:00:00 2001 From: rmshkv Date: Wed, 14 Feb 2024 15:30:57 -0700 Subject: [PATCH 6/9] Simplified example in docs --- docs/addingnotebookstocollection.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index f0adf316..2ad2ce74 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -15,21 +15,17 @@ your_new_nb_name: parameter_groups: none: - param_specific_to_this_nb: some_value - another_param: another_value + param_specific_to_this_nb: some_value + another_param: another_value If you just want the notebook run once on one set of parameters, keep the `parameter_groups: none:` notation as above. If you want the notebook executed multiple times with different parameter sets, the notation would look like this: your_new_nb_name: parameter_groups: group_1: - sname: *sname - nb_number: 3 param_1: some_string param_2: {key1: dict_entry1, key2: dict_entry2} group_2: - sname: *sname - nb_number: 4 param_1: some_different_string param_2: {key1: dict_entry3, key2: dict_entry4} From 5fe8ef34239c721f06bb02a4a7e2cf7909c8a2c1 Mon Sep 17 00:00:00 2001 From: Lev Romashkov <48655356+rmshkv@users.noreply.github.com> Date: Wed, 14 Feb 2024 15:32:00 -0700 Subject: [PATCH 7/9] Fixed spacing --- docs/addingnotebookstocollection.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index 2ad2ce74..2f470504 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -13,21 +13,21 @@ 4. Open `config.yml`. First, add your new notebook (as its name, minus the `.ipynb`) to the list of notebooks that will be computed (`compute_notebooks`). For example: your_new_nb_name: - parameter_groups: - none: - param_specific_to_this_nb: some_value - another_param: another_value + parameter_groups: + none: + param_specific_to_this_nb: some_value + another_param: another_value If you just want the notebook run once on one set of parameters, keep the `parameter_groups: none:` notation as above. If you want the notebook executed multiple times with different parameter sets, the notation would look like this: your_new_nb_name: - parameter_groups: - group_1: - param_1: some_string - param_2: {key1: dict_entry1, key2: dict_entry2} - group_2: - param_1: some_different_string - param_2: {key1: dict_entry3, key2: dict_entry4} + parameter_groups: + group_1: + param_1: some_string + param_2: {key1: dict_entry1, key2: dict_entry2} + group_2: + param_1: some_different_string + param_2: {key1: dict_entry3, key2: dict_entry4} 6. If you'd like your new notebook included in the final Jupyter Book, add it to the Jupyter Book table of contents (`book_toc`). See [Jupyter Book's documentation](https://jupyterbook.org/en/stable/structure/toc.html) for different things you can do with this. From ad237ff26f99fb517cc8990386b482153bab835f Mon Sep 17 00:00:00 2001 From: Lev Romashkov <48655356+rmshkv@users.noreply.github.com> Date: Wed, 14 Feb 2024 15:33:23 -0700 Subject: [PATCH 8/9] Fixing spacing again --- docs/addingnotebookstocollection.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index 2f470504..7894bcb7 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -21,13 +21,13 @@ If you just want the notebook run once on one set of parameters, keep the `parameter_groups: none:` notation as above. If you want the notebook executed multiple times with different parameter sets, the notation would look like this: your_new_nb_name: - parameter_groups: + parameter_groups: group_1: - param_1: some_string - param_2: {key1: dict_entry1, key2: dict_entry2} - group_2: - param_1: some_different_string - param_2: {key1: dict_entry3, key2: dict_entry4} + param_1: some_string + param_2: {key1: dict_entry1, key2: dict_entry2} + group_2: + param_1: some_different_string + param_2: {key1: dict_entry3, key2: dict_entry4} 6. If you'd like your new notebook included in the final Jupyter Book, add it to the Jupyter Book table of contents (`book_toc`). See [Jupyter Book's documentation](https://jupyterbook.org/en/stable/structure/toc.html) for different things you can do with this. From ac9ce97208e414586ddb88bf5c2b9c8d274e9c2b Mon Sep 17 00:00:00 2001 From: Lev Romashkov <48655356+rmshkv@users.noreply.github.com> Date: Thu, 15 Feb 2024 12:48:09 -0700 Subject: [PATCH 9/9] Small updates to text per Teagan's comments --- docs/addingnotebookstocollection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index 7894bcb7..27735e9b 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -1,6 +1,6 @@ # How to add diagnostics notebooks -1. Put your new diagnostic notebook in the folder called `examples/nblibrary`. +1. Put your new diagnostic notebook in the folder called `examples/nblibrary`. Generally, a good fit for a diagnostic notebook is one that reads in CESM output, does some processing, and outputs plots, values, and/or new files (images, data, etc.) that are useful for evaluating the run. 2. In your notebook, move all variables you might want to change (paths to data, dates to select, etc.) to a cell near the top. For example: sname = "run_name" @@ -10,7 +10,7 @@ 3. Tag this cell as `parameters`. This means that when the notebook is executed by `cupid`, a new cell will be inserted just below this one with all of the parameters you specify in `config.yml` (see step 4). To tag it, in Jupyter Lab, click on the cell and click the button with two gears in the top right ("Property Inspector"). Open "Common Tools." There, you can see a section called "Cell Tags." Click "Add Tag," and add one called `parameters` (exactly as written). -4. Open `config.yml`. First, add your new notebook (as its name, minus the `.ipynb`) to the list of notebooks that will be computed (`compute_notebooks`). For example: +4. Open `config.yml`. First, add your new notebook (as its name, minus the `.ipynb`) to the list of notebooks that will be computed (`compute_notebooks`). The notebooks will be executed in the order they are listed here. For example: your_new_nb_name: parameter_groups: