Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Streamline getting started documentation #636

Closed
wants to merge 10 commits into from
Prev Previous commit
Next Next commit
fixed linter errors
sallymatson committed Dec 11, 2024
commit 5e64c6fd5170530005a9381cda6962e5099c8b75
15 changes: 11 additions & 4 deletions docs/source/using_the_ve/getting_started.md
Original file line number Diff line number Diff line change
@@ -56,7 +56,9 @@ configuration and data files to run a model.
ve_run --install-example /path/
```

You can then run the model itself. If you have already run the simulation you will need to delete or rename the output files, as previously generated output can prevent the simulation from running.
You can then run the model itself. If you have already run the simulation you will need
to delete or rename the output files, as previously generated output can prevent the
Copy link
Collaborator

@hrlai hrlai Dec 17, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Even though one could just remove the files using file explorer, should we give an example code to remove the files (e.g., using rm) for those who have little experience with the Terminal?

If so, probably write it after the ve_run chunk for a better flow...

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the other file I just realised that @jacobcook1995 had already written something, maybe ditto them here for completeness?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's generally not great practice to use bash scripts to delete directories, because you might end up deleting something by mistake. It's useful in that example because the files are being stored in a kind of weird location (in the user directory) which might be hard to find using Finder. But I personally would encourage users to keep the data files in the virtual_ecosystem directory, because they will likely need to access them while working, and it will all stay a lot more organized that way. That is why I used this method - and in addition, I just think it overcomplicates the task to run a bash script, when the files should be easy to find.

Let me know what you think about that reasoning!!

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All good. I agree that it is unnecessary :) The only thing left to decide if whether to list the filenames to be deleted, but this is not always the same (e.g., the initial states may not be saved depending on user setting.) When I first bumped into this I had to ask around which files to remove.

simulation from running.

```shell
ve_run /path/ve_example/config \
@@ -79,6 +81,11 @@ These files are written to the standard NetCDF data file format.

## Next steps

* To explore the simulation results further you can visit the [Visualising Virtual Ecosystem Output](virtual_ecosystem_in_use.md) tutorial, which walks you through basic graphs using model inputs and outputs.
* The [Example Data](./example_data.md) pages provides a detailed description of the contents of the `ve_example` directory. Here can dig into the strucutre of the models and inputs.
* When you are ready to set up your own simulation, you can visit [Configuring your model](configuration/config.md) and [Adding data to the model](data/data.md).
* To explore the simulation results further you can visit the [Visualising Virtual
Ecosystem Output](virtual_ecosystem_in_use.md) tutorial, which walks you through basic
graphs using model inputs and outputs.
* The [Example Data](./example_data.md) pages provides a detailed description of the
contents of the `ve_example` directory. Here can dig into the strucutre of the models
and inputs.
* When you are ready to set up your own simulation, you can visit [Configuring your
model](configuration/config.md) and [Adding data to the model](data/data.md).
14 changes: 9 additions & 5 deletions docs/source/using_the_ve/virtual_ecosystem_in_use.md
Original file line number Diff line number Diff line change
@@ -22,17 +22,21 @@ language_info:
version: 3.12.0rc3
---

+++ {"editable": true, "slideshow": {"slide_type": ""}, "tags": []}

# Exploring the Virtual Ecosystem outputs

The code below provides a walkthrough of some basic plots for the input and output of the Virtual Ecosystem simulation.
The code below provides a walkthrough of some basic plots for the input and output of
the Virtual Ecosystem simulation.

## Run the simulation

Before exploring the outputs you will need to run the simulation using the example data or your own input data. If you have already run the simulation and generated outtput data, you can skip to the [Initial state and input data](#initial-state-and-input-data) section below.
Before exploring the outputs you will need to run the simulation using the example data
or your own input data. If you have already run the simulation and generated outtput
data, you can skip to the
[Initial state and input data](#initial-state-and-input-data) section below.

The following commands allow you to run the simulation from a Jupyter Notebook. However, you can also run the script from the command line following the [Getting Started](getting_started.md) instructions.
The following commands allow you to run the simulation from a Jupyter Notebook.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is great to remind the users that they can run the python codes using Jupyter Notebook. However, I struggle to even comprehend where to type the following commands after launching Jupyter Notebook, sorry! Most ecologists or biologists would be more familiar with R than python, so it would be a shame to turn them away because we didn't ease them into python.

That said, I struggle between providing too much details about python coding here (some users may already know how and find it boring) versus hand-carrying new users. Should we dedicate a new page just for using python codes in Jupyter, or at least point the users to an external tutorial page?

However, you can also run the script from the command line following the [Getting
Started](getting_started.md) instructions.

```{code-cell} ipython3
---