| Contents |
|---|
| Prerequisites |
| Set up the Notebooks Starter Kit |
| Run GBDXTools in Jupyter Lab |
| Working with Notebooks |
| Additional Help Topics |
The Starter Kit is a template repository for users who want a quick start guide to running Jupyter with GBDXtools. Example notebooks are included in the repository.
It is assumed that users of this starter kit will have a basic knowledge of Git and Github.
Before using the Notebooks starter kit, set up the following prerequisites:
All the commands in this document are for use in your systems shell. If you are on a system with MacOS, Windows, or Linux, the commands will be the same. Any references to terminal is meant to be interchangable with Windows Powershell, MacOS terminal, Linux terminal, or any other.
This file provides access to GBDX from your Notebooks starter kit. If you are a GBDXtools user, you may already have this file configured.
Create this file in your root directory:
~/.gbdx-configExample:
C:\Users\{username}\.gbdx-configAdd your GBDX credentials to the file in the following format:
[gbdx]
user_name = [yourusername@yourdomain.com]
user_password = [yourgbdxpassword]The following is a recommended way of getting up and running with standard Python. If you already have a Python development environment using Conda, or you would prefer to use a docker container, see these alternate instructions. Once your dev environment is configured, jump to the Run GBDXTools in Jupyter Lab section.
To check which version of Python you have installed, open a terminal window. At the command prompt, type:
python --versionIf you need to install or update your Python version, download from python.org. The Hitch Hiker's Guide to Python has good instructions for various platforms on how to install python.
Pipenv is a simple dependency manager for Python projects. You will need pipenv to install dependencies needed for the Notebooks starter kit.
To check which version of Pipenv you have installed, open a terminal window. At the command prompt, type:
pipenv --versionIf you need to install or update Pipenv, follow these instructions for installing pipenv or the pipenv documentation
To create a personal repository from this template, select the "Use this template" button from the top of the starter kit directory.
Enter the following information:
- Owner (required): Choose your github name or your organization's github location from the dropdown menu. Do not select Maxar Analytics from the dropdown.
- Repository name (required): Choose a name that's easy to remember your starter kit repository.
- Description (optional): Add a few words that describe this repository.
- Public or private: Choose private
- Include all branches: Do not select this option. Leave the box blank.
Once you've completed these steps, select the "create repository from template" button.
Select the green Code button at the top of the directory. This opens a menu with several options for cloning the repository to your local machine.
Github Desktop is a user interface for interacting with GItHub. Choosing "Open with Github Desktop" is a simple way to see way to view or select the local path the starter kit will be copied to.
Note: Keep track of the location the repo is shared to. You'll need it for the next step.
Installing the virtual environment will add required dependencies such as Jupyter Labs and GBDX Notebooks. You can find a list of the dependencies in the Pipfile.
Open a terminal window and change directories (cd) into the folder for the cloned repo. To learn about using the cd command to change directories, see "Additional Help Topics" at the bottom of this page.
To setup the environment, run:
pipenv installThis repository uses Jupyter Lab, documentation can be found here: https://jupyterlab.readthedocs.io/en/stable/
Before starting the server, we will add a kernel for use in the Jupyuter notebooks:
pipenv run python -m ipykernel install --user --name=python3-notebooksIf Jupyter Lab is not already running, run the following to start it. The command must be run from the root of your repository for your files to show up in the sidebar.
Note: if you are using Conda or Docker, see those docs for how to start the server.
pipenv run jupyter labUse this command to open Jupyter Lab every time. This will open Jupyter Lab in your default browser showing all the files from the directory you started the server in. When you are done, you can close the browser and in the shell press <Ctrl+C> to stop the server.
Note: If you can't open Jupyter in your browser because it is asking for a password, try copying the url from the shell with the token, and open it in your browser. If that doesn't work, you can disable auth by running:
jupyter lab --NotebookApp.token='' --NotebookApp.password=''. Note that this removes authentication from the running server, and anyone with access to your computer can access the server.
To keep all the dependencies isolated in the pipenv environment, you will need to make sure you use the correct kernel in your notebook. You will only need to select the kernel once for each notebook, and Jupyter will remember it.
To open a new notebook with your new kernel:
When opening an existing notebook, you will have to select the new kernel. To do this, select the label in the top right and a popup will give you a list of kernels to choose from:
If you are using notebooks locally, any existing notebooks can be moved to the directory of your new repository, and they will show up in the Jupyter tree immediately. To push those notebooks to your repository, you need to run the git push ... command. An example would be as follows:
git commit --all --message "Adding more notebooks"
git pushNote: The structure of this directory is not important, so organize to suit your needs.
To open a new notebook, with the new kernel you created before, select the kernel from the Launcher:
Alternately, you can create a new notebook file from the file menu:
When you run Jupyter from the root of your repository, all the files in that location will be in the Jupyter file browser in the left sidebar.
To run an example notebook, double click the examples directory in the file browser, and double click on any of the notebooks.
To run the cells in a notebook, select the cell and type shift + enter. We recommend running the cells within a notebook in order so that no dependencies are missed. Running a cell without running the cells before it may result in an error.
To share a notebook with another Github user, the notebook needs to be committed and pushed to Github. More information can be found in the sharing document here.
In Jupyter, each notebook has dedicated resources tied to a kernel session. When opening a bunch of notebooks, your computers resources will be consumed. It is good practice to check the running kernel sessions periodically and shutdown the sessions that are not required. You won't lose any data, but your system resources will be released. To find the running sessions, click on the sidebar as shown below:
Clicking SHUT DOWN will close the session.
When cloning your new notebooks repository, pick a location under your user directory. On MacOS and Linux your user directory will be ~/<username>/, and on Windows it will be C:\Users\{username}\. The following are examples of cloning and navigating.
From terminal:
cd ~/<username>/
git clone https://github.com/<github_username>/<my_notebook_repo_name>.git
cd my_notebook_repo_nameFrom a command prompt or power shell:
cd C:\Users\{username}\
git clone https://github.com/<github_username>/<my_notebook_repo_name>.git
cd my_notebook_repo_nameExample notebooks can be found in the examples directory.