Skip to content

Commit

Permalink
update docker address and include prereqs and outcomes in tutorial no…
Browse files Browse the repository at this point in the history 
…tebooks
  • Loading branch information
@cchu70
cchu70 committed Jun 19, 2024
1 parent 165cc5d commit 1c16d0c
Show file tree
Hide file tree
Showing 4 changed files with 53 additions and 21 deletions.
20 changes: 11 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,15 +38,15 @@ This is _highly_ recommended to manage different dependencies required by differ
When you open a jupyter notebook, you can change the environment the notebook cells are run in to `<your_env>`
### Option 1: Install AnnoMate with pip
#### Option 1: Install AnnoMate with pip
If you are developing a brand new reviewer, you can install from PyPi
```
pip install AnnoMate
```
### Option 2: Install with Git
#### Option 2: Install with Git
AnnoMate and most prebuilt reviewers can be downloaded with git.
Expand All @@ -56,7 +56,7 @@ cd AnnoMate
pip install -e .
```
### Option 3: Install with Conda
#### Option 3: Install with Conda
Assuming you already have a conda environment and it is activated:
```
Expand All @@ -70,26 +70,26 @@ conda activate <your_env>
```
Make sure to add conda environment to ipykernel (see **3. Add conda environment to ipykernel**)
### Option 4: Run with a Docker container
### Run with a Docker container
Below are the commands needed to run the tutorial notebooks in a docker container. You need to open at least 2 ports if you are using Mac or Windows:
1. A port to open jupyter lab (in this case, `<jupyter_port>`)
1. A port to open jupyter lab (in this case, `<jupyter_port>`, i.e. 8890. We recommend to NOT use port 8888, and make sure to not use other ports in use)
2. A port to open the dash app (`<dash_port>`)
```
docker run -it -p <jupyter_port>:<jupyter_port> -p <dash_port>:<dash_port> gcr.io/broad-getzlab-workflows/annomate:dev_branch_v385
docker run -it -p <jupyter_port>:<jupyter_port> -p <dash_port>:<dash_port> ghcr.io/getzlab/annomate:latest
cd AnnoMate/tutorial_notebooks
jupyter lab --ip 0.0.0.0 --port <jupyter_port> --no-browser --allow-root
```
In the notebooks, you can set the port to open the Dash app in `reviewer.run(port=<dash_port>, ...)`.
Copy the provided link to a browser to open and run the jupyter notebooks. In the notebooks, you can set the port to open the Dash app in `reviewer.run(port=<dash_port>, ...)`.
If you are running on Linux, you can open all ports.
```
docker run -it --network host gcr.io/broad-getzlab-workflows/annomate:tests_v381
docker run -it --network host ghcr.io/getzlab/annomate:latest
cd AnnoMate/tutorial_notebooks
jupyter lab --ip 0.0.0.0 --port <jupyter_port> --no-browser --allow-root
```
### Tutorials and Documentation
## Tutorials and Documentation
To run tutorial notebooks, clone the repository if you have not already. If you are running from the docker container, the repo has already been cloned.
Expand Down Expand Up @@ -168,6 +168,8 @@ Github continuous integration: https://docs.github.com/en/actions/automating-bui
rm Miniconda3-latest-Linux-x86_64.sh
source .bashrc
conda install scikit-learn pandas jupyter ipython
```
2. Credit to Nihal Sangeeth from StackOverflow: https://stackoverflow.com/questions/53004311/how-to-add-conda-environment-to-jupyter-lab.
Expand Down
16 changes: 14 additions & 2 deletions tutorial_notebooks/Developer_AnnoMate_Tutorial.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,21 @@
"source": [
"# Developer AnnoMate Tutorial\n",
"\n",
"This tutorial is for developers who want to make a Reviewer object from scratch.\n",
"This tutorial is for developers who want to make a Reviewer object from scratch. \n",
"\n",
"If you are looking to use a pre-made Reviewer, refer to the README.md file.\n"
"- If you just want to get a reviewer running and get familiar with the major built-in features of AnnoMate, see `Quick_Example_AnnoMate_Reviewer.ipynb`\n",
"- If you want to know more details on what AnnoMate reviewers are and extensive documentation of its features, see `Intro_to_AnnoMate_Reviewers.ipynb`\n",
"- We recommend using pre-built reviewers if **one already exists** for a task you want to perform and/or **you consider yourself less technically experienced.** See the [AnnnoMate Reviewer Catalog](https://github.com/getzlab/AnnoMate/blob/master/catalog/README.md) for existing reviewers.\n",
"\n",
"## Prerequistes:\n",
"- User is familiar with executing cells in jupyter notebooks and consider themselves **intermediate - advanced level python**\n",
"- User wants to create a new reviewer from scratch, or make substantion additions (i.e. adding interactive components) to existing pre-built reviewers\n",
"\n",
"## Outcomes:\n",
"- Learn the architecture of pre-built AnnoMate reviewers\n",
"- Learn how to add annotations\n",
"- Learn how to add custom interactive components in a new or pre-built reviewer\n",
"- Learn how to submit a custom reviewer to the catalog"
]
},
{
Expand Down
15 changes: 12 additions & 3 deletions tutorial_notebooks/Intro_to_AnnoMate_Reviewers.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,20 @@
"source": [
"# Intro to AnnoMate Reviewers\n",
"\n",
"All `Reviewer` types in this package follow the same general framework for setting up the dashboard. \n",
"All `Reviewer` types in this package follow the same general framework for setting up the dashboard. This notebook will walk you through how to interact with a basic reviewer, which extends to other `Reviewer` types.\n",
"\n",
"This notebook will walk you through how to interact with a basic reviewer, which extends to other `Reviewer` types.\n",
"- If you want to know how to **create** your own custom reviewer, see `Developer_AnnoMate_Tutorial.ipynb`\n",
"- If you just want to get a reviewer running and get familiar with the major built-in features of AnnoMate, see `Quick_Example_AnnoMate_Reviewer.ipynb`\n",
"- We recommend using pre-built reviewers if **one already exists** for a task you want to perform and/or **you consider yourself less technically experienced.** See the [AnnnoMate Reviewer Catalog](https://github.com/getzlab/AnnoMate/blob/master/catalog/README.md) for existing reviewers.\n",
"\n",
"If you want to know how to **create** your own custom reviewer, see `Developer_AnnoMate_Tutorial`"
"## Prerequistes:\n",
"- User is familiar with executing cells in jupyter notebooks and consider themselves **beginner - intermeidate level python**\n",
"- User wants to learn **all** of the built-in functionality of customizing pre-built Annomate Reviewers and details.\n",
"\n",
"## Outcomes:\n",
"- Get a basic AnnoMate reviewer running\n",
"- Learn how one can reuse previous annotations to create a new reviewer\n",
"- Learn **all** the built in features to update the dashboard in the notebook directly"
]
},
{
Expand Down
23 changes: 16 additions & 7 deletions tutorial_notebooks/Quick_Example_AnnoMate_Reviewer.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,19 @@
"source": [
"# Quick Example AnnoMate Reviewer\n",
"\n",
"This notebook demonstrates how to run an example reviewer built on AnnoMate.\n",
"This notebook demonstrates how to run an example reviewer built on AnnoMate. \n",
"\n",
"- If you want to know more details on what AnnoMate reviewers are and extensive documentation of its features, see `Intro_to_AnnoMate_Reviewers`\n",
"- If you want to know how to **create** your own custom reviewer, see `Developer_AnnoMate_Tutorial`"
"- If you want to know more details on what AnnoMate reviewers are and extensive documentation of its features, see `Intro_to_AnnoMate_Reviewers.ipynb`\n",
"- If you want to know how to **create** your own custom reviewer, see `Developer_AnnoMate_Tutorial.ipynb`\n",
"- We recommend using pre-built reviewers if **one already exists** for a task you want to perform and/or **you consider yourself less technically experienced.** See the [AnnnoMate Reviewer Catalog](https://github.com/getzlab/AnnoMate/blob/master/catalog/README.md) for existing reviewers.\n",
"\n",
"## Prerequistes:\n",
"- User is familiar with executing cells in jupyter notebooks and consider themselves **beginner - intermeidate level python**\n",
"- User wants to learn some of the basic built-in functionality of customizing pre-built Annomate Reviewers\n",
"\n",
"## Outcomes:\n",
"- Get a basic AnnoMate reviewer running\n",
"- Learn some of the features to update the dashboard in the notebook directly"
]
},
{
Expand All @@ -30,7 +39,7 @@
"id": "9e1078a8-0e56-4642-9b6f-3610ddf1377f",
"metadata": {},
"source": [
"Using pypi (recommended)\n",
"Option 1: Using pypi (recommended)\n",
"1. Create an environment: `conda create --name <my-env> --file requirements.txt python==3.8`\n",
"1. Activate environment: `conda activate <my-env>`\n",
"1. Install AnnoMate: `pip install AnnoMate`"
Expand All @@ -41,7 +50,7 @@
"id": "49d4fe42-17fe-4ea6-aaa7-85b7c0718788",
"metadata": {},
"source": [
"Using git:\n",
"Option 2: Using git\n",
"1. Download the repository: `git clone [email protected]:getzlab/AnnoMate.git` \n",
"1. `cd AnnoMate`\n",
"1. Create an environment: `conda create --name <my-env> --file requirements.txt python==3.8`\n",
Expand All @@ -54,11 +63,11 @@
"id": "e637c8ae-2ca2-487a-9522-de96383ae80f",
"metadata": {},
"source": [
"Running from docker container: You need to open at least 2 ports if you are using Mac or Windows:\n",
"Option 3: Running from docker container. You need to open at least 2 ports if you are using Mac or Windows:\n",
"1. A port to open jupyter lab (in this case, `<jupyter_port>`)\n",
"2. A port to open the dash app (`<dash_port>`)\n",
"```\n",
"docker run -it -p <jupyter_port>:<jupyter_port> -p <dash_port>:<dash_port> gcr.io/broad-getzlab-workflows/annomate:dev_branch_v385\n",
"docker run -it -p <jupyter_port>:<jupyter_port> -p <dash_port>:<dash_port> ghcr.io/getzlab/annomate:latest\n",
"cd AnnoMate/tutorial_notebooks\n",
"jupyter lab --ip 0.0.0.0 --port <jupyter_port> --no-browser --allow-root\n",
"```"
Expand Down

0 comments on commit 1c16d0c

Please sign in to comment.