From 8c8df8bb8e5f371a5e41e654614801332757c058 Mon Sep 17 00:00:00 2001 From: Emily Przykucki Date: Mon, 9 Dec 2024 12:41:25 -0500 Subject: [PATCH 1/7] New documentation and installation script Created two files (`local-installation.md` and `local_install_or_update.sh`) that will likely make it easier for new flepiMoP users to install flepiMoP onto their machine. --- build/local_install_or_update.sh | 59 +++++++++++++++++++ .../gitbook/how-to-run/local-installation.md | 58 ++++++++++++++++++ 2 files changed, 117 insertions(+) create mode 100755 build/local_install_or_update.sh create mode 100644 documentation/gitbook/how-to-run/local-installation.md diff --git a/build/local_install_or_update.sh b/build/local_install_or_update.sh new file mode 100755 index 000000000..38aa7ac03 --- /dev/null +++ b/build/local_install_or_update.sh @@ -0,0 +1,59 @@ +#!/usr/bin/env bash + +# Generic setup +set -e + +# Ensure we have a $FLEPI_PATH +if [ -z "${FLEPI_PATH}" ]; then + export USERDIR=$(pwd) + export FLEPI_PATH="$USERDIR/flepiMoP" + export FLEPI_PATH=$( realpath "$FLEPI_PATH" ) + echo "Using '$FLEPI_PATH' for \$FLEPI_PATH." +fi + +# Test that flepiMoP is located there, exit if not +if [ ! -d "$FLEPI_PATH" ]; then + echo "Could not find flepiMoP repository in your directory. Please make sure you have correctly cloned flepiMoP in this directory." + exit 1 +fi + +# Ensure that conda environment is named flepimop-env +if [ -z "${FLEPI_CONDA}" ]; then + export FLEPI_CONDA="flepimop-env" + echo "Using '$FLEPI_CONDA' for \$FLEPI_CONDA." +fi + +# Check that the name of the FLEPI_CONDA variable matches the environment that has been set up, exit if not +FLEPI_CONDA_ENV_MATCHES=$( conda info --envs | awk '{print $1}' | grep -x "$FLEPI_CONDA" | wc -l ) +if [ "$FLEPI_CONDA_ENV_MATCHES" -eq 0 ]; then + echo "Issue with conda environment: ensure you have set up your conda environment and it has the correct name." + exit 1 +fi + +# Load the conda environment +conda activate $FLEPI_CONDA +[ -e "$CONDA_PREFIX/conda-meta/pinned" ] && rm $CONDA_PREFIX/conda-meta/pinned +cat << EOF > $CONDA_PREFIX/conda-meta/pinned +r-arrow==17.0.0 +arrow==17.0.0 +EOF + +# Install the gempyor package from local +pip install --editable $FLEPI_PATH/flepimop/gempyor_pkg + +# Install the local R packages +R -e "install.packages('covidcast', repos='https://cloud.r-project.org')" +RETURNTO=$( pwd ) +cd $FLEPI_PATH/flepimop/R_packages/ +for d in $( ls ); do + R CMD INSTALL $d +done +cd $RETURNTO +R -e "library(inference); inference::install_cli()" + +# Done +echo "> Done installing/updating flepiMoP." +set +e + + + diff --git a/documentation/gitbook/how-to-run/local-installation.md b/documentation/gitbook/how-to-run/local-installation.md new file mode 100644 index 000000000..c50d07745 --- /dev/null +++ b/documentation/gitbook/how-to-run/local-installation.md @@ -0,0 +1,58 @@ +--- +description: >- + Instructions on how to proceed with the installations necessary for local flepiMoP use. +--- + + +# Local flepiMoP installation + +## ⇅ Get set up to use Github + +You need to interact with Github to run and edit `flepiMoP` code. [Github](https://github.com/) is a web platform for people to share and manage software, and it is based on a 'version control' software called `git` that helps programmers keep track of changes to code. Flepimop core code as well as example projects using flepimop code are all stored on Github, and frequently being updated. The first step to using flepimop for your own project is making sure you're set up to interact with code shared on Github. + +If you are totally new to Github, navigate to [Github.com](https://github.com/) and Sign Up for a new account. Read about the [basics of git](https://docs.github.com/en/get-started/getting-started-with-git/set-up-git). + +To work with `flepimop` code, you can do some tasks from the Github website, but you'll also need a way to 'clone' the code to your own local computer and keep it up to date with versions hosted online. You can do this either using a user interface like [Github Desktop](https://desktop.github.com/), or, using [`git` ](https://git-scm.com/downloads)commands from the command line. Make sure you have one or both installed. + +If you are a veteran user, make sure you're signed in on Github.com and through whatever method you use locally on your computer to interact with Github. + +## 🔐 Access the flepiMoP model code + +In order to run a model with flepiMoP, you will need to clone the flepiMoP **code** to your machine. + +**To clone the `flepiMoP` code repository:** + +* If you're using the command line in a terminal, first navigate to the local directory you'll use as the directory for the files that make up `flepiMoP`. Then, use the command:\ + `git clone https://github.com/HopkinsIDD/flepiMoP` +* If you're using Github Desktop, go File -> Clone Repository, switch to the "URL" tab and copy the URL `https://github.com/HopkinsIDD/flepiMoP` there. For the "Local Path" option, make sure you choose your desired directory. + +## 🐍 Installing `conda` + +In order to complete `flepiMoP` installation, you must have [`conda`](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html) installed on your machine. `conda` is a tool that will assist you in managing software environments and code packages on your device. To install `conda` follow the directions according to your operating system: + +* [Windows](https://docs.conda.io/projects/conda/en/latest/user-guide/install/windows.html) +* [macOS](https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html) +* [Linux](https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html) + +We would recommend selecting the `Anaconda Distribution` installer of `conda`. + +Once installed, you must set up your `conda` environmnet. To do this, navigate to your `flepiMoP` directory, and run the following commands: + +```bash +conda env create -f /build/renv/conda_environment.yml +``` +This will create a `conda` environment called `flepimop-env`, that you will activate with the command: + +```bash +conda activate flepimop-env +``` + +## ⬇️ Installing flepiMoP packages and dependencies + +While in the `flepiMoP` directory, run the following command: + +```bash +/build/local_install_or_update.sh +``` + +This command will install the flepiMoP Python package, `gempyor`, along with all its dependencies, as well as all necessary R packages and dependencies. \ No newline at end of file From 0ebbf08c2ede8fb5dba20360815422e2e9304654 Mon Sep 17 00:00:00 2001 From: Emily Przykucki Date: Mon, 9 Dec 2024 13:14:32 -0500 Subject: [PATCH 2/7] Update local-installation.md --- documentation/gitbook/how-to-run/local-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/gitbook/how-to-run/local-installation.md b/documentation/gitbook/how-to-run/local-installation.md index c50d07745..3379a147c 100644 --- a/documentation/gitbook/how-to-run/local-installation.md +++ b/documentation/gitbook/how-to-run/local-installation.md @@ -55,4 +55,4 @@ While in the `flepiMoP` directory, run the following command: /build/local_install_or_update.sh ``` -This command will install the flepiMoP Python package, `gempyor`, along with all its dependencies, as well as all necessary R packages and dependencies. \ No newline at end of file +This command will install the flepiMoP Python package, `gempyor`, along with all its dependencies, as well as all necessary R packages and dependencies. This command will also verify that your `conda` environment settings are corretly configured for flepiMoP use. \ No newline at end of file From 0b9c351dac23e907bd92fcac2cb112089dfe4d4e Mon Sep 17 00:00:00 2001 From: Emily Przykucki Date: Mon, 16 Dec 2024 15:13:03 -0500 Subject: [PATCH 3/7] Update `local_install_or_update` and `local-installation.md` --- build/local_install_or_update.sh | 13 +++++---- .../gitbook/how-to-run/local-installation.md | 27 +++++++++---------- 2 files changed, 19 insertions(+), 21 deletions(-) diff --git a/build/local_install_or_update.sh b/build/local_install_or_update.sh index 38aa7ac03..7440a76ad 100755 --- a/build/local_install_or_update.sh +++ b/build/local_install_or_update.sh @@ -5,15 +5,17 @@ set -e # Ensure we have a $FLEPI_PATH if [ -z "${FLEPI_PATH}" ]; then - export USERDIR=$(pwd) - export FLEPI_PATH="$USERDIR/flepiMoP" - export FLEPI_PATH=$( realpath "$FLEPI_PATH" ) + export FLEPI_PATH=$(realpath "$(pwd)") + if [ "$(basename "$FLEPI_PATH")" != "flepiMoP" ]; then + echo "Could not find flepiMoP repository in your current directory." + exit 1 + fi echo "Using '$FLEPI_PATH' for \$FLEPI_PATH." fi # Test that flepiMoP is located there, exit if not if [ ! -d "$FLEPI_PATH" ]; then - echo "Could not find flepiMoP repository in your directory. Please make sure you have correctly cloned flepiMoP in this directory." + echo "Could not find flepiMoP repository in your current directory. Please make sure you have correctly cloned flepiMoP in this directory." exit 1 fi @@ -54,6 +56,3 @@ R -e "library(inference); inference::install_cli()" # Done echo "> Done installing/updating flepiMoP." set +e - - - diff --git a/documentation/gitbook/how-to-run/local-installation.md b/documentation/gitbook/how-to-run/local-installation.md index 3379a147c..f8fd85afa 100644 --- a/documentation/gitbook/how-to-run/local-installation.md +++ b/documentation/gitbook/how-to-run/local-installation.md @@ -4,7 +4,7 @@ description: >- --- -# Local flepiMoP installation +# Local flepiMoP installation ## ⇅ Get set up to use Github @@ -22,24 +22,17 @@ In order to run a model with flepiMoP, you will need to clone the flepiMoP **cod **To clone the `flepiMoP` code repository:** -* If you're using the command line in a terminal, first navigate to the local directory you'll use as the directory for the files that make up `flepiMoP`. Then, use the command:\ - `git clone https://github.com/HopkinsIDD/flepiMoP` +* If you're using the command line in a terminal, first navigate to the local directory you'll use as the directory for the files that make up `flepiMoP`. Then, use the command: `git clone https://github.com/HopkinsIDD/flepiMoP` * If you're using Github Desktop, go File -> Clone Repository, switch to the "URL" tab and copy the URL `https://github.com/HopkinsIDD/flepiMoP` there. For the "Local Path" option, make sure you choose your desired directory. ## 🐍 Installing `conda` -In order to complete `flepiMoP` installation, you must have [`conda`](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html) installed on your machine. `conda` is a tool that will assist you in managing software environments and code packages on your device. To install `conda` follow the directions according to your operating system: +In order to complete `flepiMoP` installation, you must have [`conda`](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html) installed on your machine. `conda` is a tool that will assist you in managing software environments and code packages on your device, and it will be very helpful in ensuring consistent, reproducible environments across different projects. To install `conda` follow [the directions](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) according to your operating system. We would recommend selecting the `Anaconda Distribution` installer of `conda`. -* [Windows](https://docs.conda.io/projects/conda/en/latest/user-guide/install/windows.html) -* [macOS](https://docs.conda.io/projects/conda/en/latest/user-guide/install/macos.html) -* [Linux](https://docs.conda.io/projects/conda/en/latest/user-guide/install/linux.html) - -We would recommend selecting the `Anaconda Distribution` installer of `conda`. - -Once installed, you must set up your `conda` environmnet. To do this, navigate to your `flepiMoP` directory, and run the following commands: +Once installed, you must set up your `conda` environment. To do this, navigate to your `flepiMoP` directory, and run the following commands: ```bash -conda env create -f /build/renv/conda_environment.yml +conda env create --name flepimop-env --file environment.yml ``` This will create a `conda` environment called `flepimop-env`, that you will activate with the command: @@ -47,12 +40,18 @@ This will create a `conda` environment called `flepimop-env`, that you will acti conda activate flepimop-env ``` +Installation and activation of `conda` may take a few minutes. + ## ⬇️ Installing flepiMoP packages and dependencies While in the `flepiMoP` directory, run the following command: +**Note: This installation script is currently only designed for Mac/Linux operating systems. Windows installation script coming soon.** ```bash -/build/local_install_or_update.sh +./build/local_install_or_update ``` -This command will install the flepiMoP Python package, `gempyor`, along with all its dependencies, as well as all necessary R packages and dependencies. This command will also verify that your `conda` environment settings are corretly configured for flepiMoP use. \ No newline at end of file +1. Determine `$FLEPI_PATH` and `$FLEPI_CONDA` environment variables +2. Activate your conda environment +3. Install `gempyor` and related Python dependencies +4. Install necessary R packages and dependencies From d8122208a2e66087262d9d02d02a571f949f4a16 Mon Sep 17 00:00:00 2001 From: Emily Przykucki Date: Wed, 18 Dec 2024 16:25:44 -0500 Subject: [PATCH 4/7] Removing file extension from `local_install_or_update` file --- build/{local_install_or_update.sh => local_install_or_update} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename build/{local_install_or_update.sh => local_install_or_update} (100%) diff --git a/build/local_install_or_update.sh b/build/local_install_or_update similarity index 100% rename from build/local_install_or_update.sh rename to build/local_install_or_update From 67ccbffe4fb063bbcf297c7dbbd26b77e34c2b99 Mon Sep 17 00:00:00 2001 From: Emily Przykucki Date: Thu, 19 Dec 2024 12:11:54 -0500 Subject: [PATCH 5/7] Update local_install_or_update --- build/local_install_or_update | 1 + 1 file changed, 1 insertion(+) diff --git a/build/local_install_or_update b/build/local_install_or_update index 7440a76ad..2a19a1bd0 100755 --- a/build/local_install_or_update +++ b/build/local_install_or_update @@ -33,6 +33,7 @@ if [ "$FLEPI_CONDA_ENV_MATCHES" -eq 0 ]; then fi # Load the conda environment +eval "$(conda shell.bash hook)" conda activate $FLEPI_CONDA [ -e "$CONDA_PREFIX/conda-meta/pinned" ] && rm $CONDA_PREFIX/conda-meta/pinned cat << EOF > $CONDA_PREFIX/conda-meta/pinned From cbecd91ce9def5cced6ba71cefd87adcf409d8cf Mon Sep 17 00:00:00 2001 From: Emily Przykucki Date: Fri, 20 Dec 2024 15:36:02 -0500 Subject: [PATCH 6/7] Incorporate `conda` env setup into installation script and update documentation --- build/local_install_or_update | 8 ++++++++ .../gitbook/how-to-run/local-installation.md | 15 ++------------- 2 files changed, 10 insertions(+), 13 deletions(-) diff --git a/build/local_install_or_update b/build/local_install_or_update index 2a19a1bd0..0add13f90 100755 --- a/build/local_install_or_update +++ b/build/local_install_or_update @@ -19,12 +19,20 @@ if [ ! -d "$FLEPI_PATH" ]; then exit 1 fi +# Create the conda environment if it doesn't exist +if ! conda env list | grep -q "$FLEPI_CONDA"; then + conda env create --name flepimop-env --file $FLEPI_PATH/environment.yml +fi + # Ensure that conda environment is named flepimop-env if [ -z "${FLEPI_CONDA}" ]; then export FLEPI_CONDA="flepimop-env" echo "Using '$FLEPI_CONDA' for \$FLEPI_CONDA." fi +# Activate the conda environment +conda activate $FLEPI_CONDA + # Check that the name of the FLEPI_CONDA variable matches the environment that has been set up, exit if not FLEPI_CONDA_ENV_MATCHES=$( conda info --envs | awk '{print $1}' | grep -x "$FLEPI_CONDA" | wc -l ) if [ "$FLEPI_CONDA_ENV_MATCHES" -eq 0 ]; then diff --git a/documentation/gitbook/how-to-run/local-installation.md b/documentation/gitbook/how-to-run/local-installation.md index f8fd85afa..44eeb6472 100644 --- a/documentation/gitbook/how-to-run/local-installation.md +++ b/documentation/gitbook/how-to-run/local-installation.md @@ -29,22 +29,11 @@ In order to run a model with flepiMoP, you will need to clone the flepiMoP **cod In order to complete `flepiMoP` installation, you must have [`conda`](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html) installed on your machine. `conda` is a tool that will assist you in managing software environments and code packages on your device, and it will be very helpful in ensuring consistent, reproducible environments across different projects. To install `conda` follow [the directions](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) according to your operating system. We would recommend selecting the `Anaconda Distribution` installer of `conda`. -Once installed, you must set up your `conda` environment. To do this, navigate to your `flepiMoP` directory, and run the following commands: - -```bash -conda env create --name flepimop-env --file environment.yml -``` -This will create a `conda` environment called `flepimop-env`, that you will activate with the command: - -```bash -conda activate flepimop-env -``` - -Installation and activation of `conda` may take a few minutes. +Installation of `conda` may take a few minutes. ## ⬇️ Installing flepiMoP packages and dependencies -While in the `flepiMoP` directory, run the following command: +Navigate to the `flepiMoP` directory and run the following command: **Note: This installation script is currently only designed for Mac/Linux operating systems. Windows installation script coming soon.** ```bash From 8db79232373a89676aa088e9e85ca69b14a4d7d9 Mon Sep 17 00:00:00 2001 From: Emily Przykucki Date: Thu, 26 Dec 2024 10:56:52 -0500 Subject: [PATCH 7/7] Update local_install_or_update --- build/local_install_or_update | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/build/local_install_or_update b/build/local_install_or_update index 0add13f90..77305dbd1 100755 --- a/build/local_install_or_update +++ b/build/local_install_or_update @@ -19,25 +19,16 @@ if [ ! -d "$FLEPI_PATH" ]; then exit 1 fi -# Create the conda environment if it doesn't exist -if ! conda env list | grep -q "$FLEPI_CONDA"; then - conda env create --name flepimop-env --file $FLEPI_PATH/environment.yml -fi - # Ensure that conda environment is named flepimop-env if [ -z "${FLEPI_CONDA}" ]; then export FLEPI_CONDA="flepimop-env" echo "Using '$FLEPI_CONDA' for \$FLEPI_CONDA." fi -# Activate the conda environment -conda activate $FLEPI_CONDA - # Check that the name of the FLEPI_CONDA variable matches the environment that has been set up, exit if not FLEPI_CONDA_ENV_MATCHES=$( conda info --envs | awk '{print $1}' | grep -x "$FLEPI_CONDA" | wc -l ) if [ "$FLEPI_CONDA_ENV_MATCHES" -eq 0 ]; then - echo "Issue with conda environment: ensure you have set up your conda environment and it has the correct name." - exit 1 + conda env create --name flepimop-env --file $FLEPI_PATH/environment.yml fi # Load the conda environment