From 57f4569692050747b00eb328ae5c2c810ec3e364 Mon Sep 17 00:00:00 2001 From: Lev Romashkov <48655356+rmshkv@users.noreply.github.com> Date: Wed, 28 Feb 2024 14:54:46 -0700 Subject: [PATCH 1/4] Adding environment testing and short version to notebook adding instructions I added a step telling people to install the cupid-analysis environment and test there. I also noted where people can stop if they don't want to fully run the notebook with CUPiD themselves yet, so they can pass it along to us at that point instead. --- docs/addingnotebookstocollection.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index 27735e9..2951159 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -1,6 +1,8 @@ # How to add diagnostics notebooks -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. +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. + +1. Install the `environments/cupid-analysis.yml` environment (see [installation instructions](https://ncar.github.io/CUPiD/index.html#installing)). Make sure that your notebook runs properly in this environment. If there are conflicts or missing dependencies, open an issue or talk to CUPiD developers so we can find a solution. 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" @@ -8,9 +10,11 @@ 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). +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). **If you don't want to fully set up CUPiD, stop here and we can integrate the notebook into a CUPiD workflow from here.** +--- +4. Move your new diagnostic notebook to the folder called `examples/nblibrary`. -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: +5. 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: @@ -32,6 +36,6 @@ 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. +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 00d26a5b5749795eeeb8aa8d10f3740e18c632b0 Mon Sep 17 00:00:00 2001 From: Lev Romashkov <48655356+rmshkv@users.noreply.github.com> Date: Thu, 29 Feb 2024 13:31:41 -0700 Subject: [PATCH 2/4] Fixed spacing, step reference, and added text below line --- docs/addingnotebookstocollection.md | 36 +++++++++++++++-------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index 2951159..2eba598 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -5,33 +5,35 @@ Generally, a good fit for a diagnostic notebook is one that reads in CESM output 1. Install the `environments/cupid-analysis.yml` environment (see [installation instructions](https://ncar.github.io/CUPiD/index.html#installing)). Make sure that your notebook runs properly in this environment. If there are conflicts or missing dependencies, open an issue or talk to CUPiD developers so we can find a solution. 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", + 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). **If you don't want to fully set up CUPiD, stop here and we can integrate the notebook into a CUPiD workflow from here.** +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 specified in `config.yml` (see step 5). 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). **If you don't want to fully set up CUPiD, stop here and we can integrate the notebook into a CUPiD workflow from here.** --- +**If you want to run your notebook through the `CUPiD` workflow yourself, follow the rest of the instructions:** + 4. Move your new diagnostic notebook to the folder called `examples/nblibrary`. 5. 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: - none: - param_specific_to_this_nb: some_value - another_param: another_value + 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, 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} + 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} 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 1e389b8f54a5756be9e70aaf92881eabc87b2026 Mon Sep 17 00:00:00 2001 From: Lev Romashkov <48655356+rmshkv@users.noreply.github.com> Date: Thu, 29 Feb 2024 14:05:02 -0700 Subject: [PATCH 3/4] Fixed more tab characters --- docs/addingnotebookstocollection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index 2eba598..5e9fcfc 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -8,9 +8,9 @@ Generally, a good fit for a diagnostic notebook is one that reads in CESM output sname = "run_name" data_path = "path/to/data" dates = {"start_date" = "01/01/01", - "end_date" = "01/01/02"} + "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 specified in `config.yml` (see step 5). 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). **If you don't want to fully set up CUPiD, stop here and we can integrate the notebook into a CUPiD workflow from here.** +4. 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 specified in `config.yml` (see step 5). 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). **If you don't want to fully set up CUPiD, stop here and we can integrate the notebook into a CUPiD workflow from here.** --- **If you want to run your notebook through the `CUPiD` workflow yourself, follow the rest of the instructions:** From 18a4dd1d0bfa01dd407e55da82f41bb834478951 Mon Sep 17 00:00:00 2001 From: Lev Romashkov <48655356+rmshkv@users.noreply.github.com> Date: Thu, 29 Feb 2024 14:06:21 -0700 Subject: [PATCH 4/4] One more tab character --- docs/addingnotebookstocollection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/addingnotebookstocollection.md b/docs/addingnotebookstocollection.md index 5e9fcfc..0034efa 100644 --- a/docs/addingnotebookstocollection.md +++ b/docs/addingnotebookstocollection.md @@ -24,7 +24,7 @@ Generally, a good fit for a diagnostic notebook is one that reads in CESM output 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: + 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: