flepimop.org documentation updates for information pertaining to new users #460
Conversation
Changing documentation to reflect upcoming changes in user local installation processes and moving towards eliminating `flepimop_sample` as a step in running for new users.
TimothyWillard
added
documentation
|
My question to reviewers is: should I go ahead and search for all references to |
My vote would be to do it all in one pass as to minimize confusion. |
|
places where HOW TO RUN
GEMPYOR: MODELING INFECTIOUS DISEASE DYNAMICS
MODEL INFERENCE
|
I'm going to hold off on reviewing until this, unless you want me to review now @emprzy? |
|
A question for @pearsonca (or anyone else that cares to chime in). We are very close to purging 
from how-to-run quick start guide
from how-to-run useful commands
|
This does not change `--data_path`, the CL option, just the envvar `DATA_PATH`.
|
Sorry for the mid-way expansion of what this PR covers, but it's ready for review now! |
TimothyWillard
added
the
next release
Co-authored-by: Timothy Willard <[email protected]>
Co-authored-by: Timothy Willard <[email protected]>
|
|
||
| * the directory containing the flepimop code (likely the folder you cloned from Github), which we'll call `FLEPI_PATH` | ||
| * the directory containing your project code including input configuration file and population structure (again likely from Github), which we'll call `DATA_PATH` | ||
| Take note of the location of the directory on your local computer where you cloned the flepiMoP model code (which we'll call `FLEPI_PATH`). |
There was a problem hiding this comment.
is it too much to also explain that it is literally defined as an environmental variable with the same name? we don't want to overwhelm folks, but that also seems like a useful note.
| If you're on a **Mac** or Linux/Unix based operating system, define the FLEPI\_PATH and PROJECT\_PATH environmental variables to be your directory locations, for example | ||
|
|
||
| ```bash | ||
| export FLEPI_PATH=$(pwd)/flepiMoP | ||
| export DATA_PATH=$(pwd)/flepimop_sample | ||
| export FLEPI_PATH=/Users/YourName/Github/flepiMoP | ||
| export PROJECT_PATH=/Users/YourName/Github/flepiMoP/examples/tutorials | ||
| ``` |
There was a problem hiding this comment.
we don't want people to do some of this, right? as in, installing flepimop should set the flepipath?
| <summary>Help! I have errors in installation</summary> | ||
|
|
||
| If you get an error because no cran mirror is selected, just create in your home directory a `.Rprofile` file: | ||
| You can check that the variables have been set by either typing `env` to see all defined environmental variables, or typing `echo $FLEPI_PATH` to see the value of `FLEPI_PATH`. |
There was a problem hiding this comment.
probably shouldn't suggest people env - going to spam them confusingly.
| <pre class="language-bash"><code class="lang-bash"><strong>set FLEPI_PATH=C:\Users\YourName\Github\flepiMoP | ||
| </strong>set PROJECT_PATH=C:\Users\YourName\Github\flepiMoP\examples\tutorials | ||
| </code></pre> |
There was a problem hiding this comment.
again, what part of this is now in the install action, such that we don't want them to do it?
|
|
||
| Other environmental variables can be set at any point in process of setting up your model run. These options are listed in ... ADD ENVAR PAGE | ||
| Other environmental variables can be set at any point in process of setting up your model run. These options are listed in ... **ADD ENVAR PAGE** |
There was a problem hiding this comment.
I don't mind a live TODO, but it should be in a comment, rather than actively displayed. Probably a better version is to convert this to an item on an explicit issue, e.g. the new environmental variables one. Basically an explicit note "in file XYZ, section ABC, ..."
|
|
||
| For example, some frequently used environmental variables which we recommend setting are: | ||
| For example, some frequently used environmental variables we recommend setting are: |
There was a problem hiding this comment.
do we recommend setting these? i don't think this is true
| rm -r model_output/ # delete the outputs of past run if there are | ||
| ``` | ||
|
|
||
| #### Inference run | ||
|
|
||
| An inference run requires a configuration file that has an `inference` section. Stay in the `$DATA_PATH` folder, and run the inference script, providing the name of the configuration file you want to run (ex. `config.yml`). In the example data folder (flepimop\_sample), try out the example config XXX. | ||
| An inference run requires a configuration file that has an `inference` section. Stay in the `$PROJECT_PATH` folder, and run the inference script, providing the name of the configuration file you want to run (ex. `config.yml`). |
There was a problem hiding this comment.
the inference action, right? it's a script under the hood, but not from the user perspective
| @@ -82,7 +81,7 @@ If you'd like to have more control, you can specify the arguments manually: | |||
| $ python $FLEPI_PATH/batch/inference_job_launcher.py --slurm \ | |||
| -c $CONFIG_PATH \ | |||
| -p $FLEPI_PATH \ | |||
| --data-path $DATA_PATH \ | |||
| --data-path $PROJECT_PATH \ | |||
There was a problem hiding this comment.
this shouldn't be --data-path any more, right?
| @@ -11,7 +11,7 @@ description: >- | |||
| See the [Before any run](../before-any-run.md) section to ensure you have access to the correct files needed to run. On your local machine, determine the file paths to: | |||
|
|
|||
| * the directory containing the flepimop code (likely the folder you cloned from Github), which we'll call `<dir1>` | |||
| * the directory containing your project code including input configuration file and population structure (again likely from Github), which we'll call `<dir2>` | |||
| * the directory containing your project code including input configuration file and population structure, which we'll call `<dir2>` | |||
There was a problem hiding this comment.
...weird. why isn't this environmental variables again? docker supports those. maybe not something to fix here, but if not, should make it into an issue.
|
|
||
| This repository mirrors the contents in the **examples/tutorial** folder of the FlepiMoP repository ([link](https://github.com/HopkinsIDD/flepiMoP/tree/main/examples/tutorials)). It can be used to try out running simple projects using `flepimop` code and as a template for new projects. | ||
| This directory can be used to try out running simple projects using `flepimop` code and as a template for new projects. It mirrors now deprecated example repository `flepimop_sample`. |
There was a problem hiding this comment.
| This directory can be used to try out running simple projects using `flepimop` code and as a template for new projects. It mirrors now deprecated example repository `flepimop_sample`. | |
| This directory can be used to try out running simple projects using `flepimop` code and as a template for new projects. |
Describe your changes.
This pull request...
flepimop_samplefrom code and documentation; replacing it with theflepiMoP/examples/tutorialsdirectory,DATA_PATHwithPROJECT_PATH. It does not attempt to adjust the command line option--data_path, as I believe @TimothyWillard said he was working on editing the CLI options.Does this pull request make any user interface changes? If so please describe.
New users will be able to install flepiMoP (all packages and dependencies along with initialization of a
condaenvironment) with a single script that they can run from CL.What does your pull request address? Tag relevant issues.
This pull request addresses necessary documentation changes resulting from issue GH #401 and pull request GH #418.
Because of eradication of
flepimop_sample, it also serves GH #368.