From 1c16d0c652acc32675b33e23ca4661a81f6c45c2 Mon Sep 17 00:00:00 2001 From: Claudia Chu Date: Wed, 19 Jun 2024 17:45:22 -0400 Subject: [PATCH] update docker address and include prereqs and outcomes in tutorial notebooks --- README.md | 20 ++++++++-------- .../Developer_AnnoMate_Tutorial.ipynb | 16 +++++++++++-- .../Intro_to_AnnoMate_Reviewers.ipynb | 15 +++++++++--- .../Quick_Example_AnnoMate_Reviewer.ipynb | 23 +++++++++++++------ 4 files changed, 53 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 7e52c20..d13f2ed 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ 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 `` -### 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 @@ -46,7 +46,7 @@ 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. @@ -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: ``` @@ -70,26 +70,26 @@ conda activate ``` 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, ``) +1. A port to open jupyter lab (in this case, ``, 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 (``) ``` -docker run -it -p : -p : gcr.io/broad-getzlab-workflows/annomate:dev_branch_v385 +docker run -it -p : -p : ghcr.io/getzlab/annomate:latest cd AnnoMate/tutorial_notebooks jupyter lab --ip 0.0.0.0 --port --no-browser --allow-root ``` -In the notebooks, you can set the port to open the Dash app in `reviewer.run(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=, ...)`. 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 --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. @@ -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. diff --git a/tutorial_notebooks/Developer_AnnoMate_Tutorial.ipynb b/tutorial_notebooks/Developer_AnnoMate_Tutorial.ipynb index d0e305f..c1a72e2 100644 --- a/tutorial_notebooks/Developer_AnnoMate_Tutorial.ipynb +++ b/tutorial_notebooks/Developer_AnnoMate_Tutorial.ipynb @@ -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" ] }, { diff --git a/tutorial_notebooks/Intro_to_AnnoMate_Reviewers.ipynb b/tutorial_notebooks/Intro_to_AnnoMate_Reviewers.ipynb index 558963b..4cf8dd9 100644 --- a/tutorial_notebooks/Intro_to_AnnoMate_Reviewers.ipynb +++ b/tutorial_notebooks/Intro_to_AnnoMate_Reviewers.ipynb @@ -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" ] }, { diff --git a/tutorial_notebooks/Quick_Example_AnnoMate_Reviewer.ipynb b/tutorial_notebooks/Quick_Example_AnnoMate_Reviewer.ipynb index 29e645a..324e044 100644 --- a/tutorial_notebooks/Quick_Example_AnnoMate_Reviewer.ipynb +++ b/tutorial_notebooks/Quick_Example_AnnoMate_Reviewer.ipynb @@ -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" ] }, { @@ -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 --file requirements.txt python==3.8`\n", "1. Activate environment: `conda activate `\n", "1. Install AnnoMate: `pip install AnnoMate`" @@ -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 git@github.com:getzlab/AnnoMate.git` \n", "1. `cd AnnoMate`\n", "1. Create an environment: `conda create --name --file requirements.txt python==3.8`\n", @@ -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, ``)\n", "2. A port to open the dash app (``)\n", "```\n", - "docker run -it -p : -p : gcr.io/broad-getzlab-workflows/annomate:dev_branch_v385\n", + "docker run -it -p : -p : ghcr.io/getzlab/annomate:latest\n", "cd AnnoMate/tutorial_notebooks\n", "jupyter lab --ip 0.0.0.0 --port --no-browser --allow-root\n", "```"