A collection of tutorials on methodologies involving the tools of the Institute
True README in construction
| Minimum | Python version 3.10. Later version, or version 3.9, might work. Earlier versions, we don't want to know. |
| Best | A working Conda install. |
Before you can run through and play with the tutorial notebooks, you must put together their computing environment. Please open an issue if you encounter any issue that is not documented below, or if you get stuck during setup.
In a terminal window, type
python -m venv venv
. venv/bin/activate
pip install -r requirements.txtOn Windows, the sequence is almost the same, but the environment is activated slightly differently:
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txtAlternatively, if you have Conda, you can benefit from a better assurance of a clean virtual environment with a suitable version of Python:
conda create -p venv "python=3.10" "pip"
conda activate ./venv
pip install -r requirements.txtIf you do not already have a Jupyter Lab instance running, then you can start it now, from the tutorial venv you just built.
jupyter labIf you are running it on the same computer as your desktop,
then this will open up a web browser window automatically.
Otherwise, arrange port forwarding, and browse to the http://localhost:8xxx/lab?token=... URL printed by Jupyter Lab.
However...
You have to ensure that your running instance of Jupyter Lab matches versions with this environment for the three following packages:
bokehpanelpyviz-comms
For that, locate the Conda environment or venv your Jupyter Lab instance (or instance of jupyter-labhub, or jupyterhub-singleuser) runs from.
If it runs from an environment at path /conda/env, then run
conda list -p /conda/envIf it runs off of a regular Python venv at path /regular/venv, try instead
pip list --path /regular/venv/lib/python3.10/site-packages(The version number on the right of python can be different.)
This latter form will also work if your Jupyter Lab runs from some cursed systemwide or user account deployment, such as
pip list --path /usr/lib/python3.10/site-packages
pip list --path $HOME/.local/lib/python3.9/site-packagesIn the list you get from any of these commands, look for the names of the packages above. The version deployed in this environment is displayed on the right of the name. You can get creative:
| Platform | Command |
|---|---|
| Linux / macOS | conda list -p /opt/conda/envs/jupyterhub | grep bokeh |
| Windows | conda list -p "C:\Users\johndoe\miniconda3\envs\jupyter" | findstr bokeh |
After a reasonable effort, you will either find the version of each package as it was deployed in that foreign Jupyter environment, or not. On the one hand, if version information can be found for any of the three packages above, then force the installation of the same version of that package in your own environment. For instance, if you've discovered that the Jupyterhub environment has Bokeh version 3.0.1, then run
pip install --upgrade --ignore-installed --no-deps "bokeh==3.0.1"You can further run pip list or conda list in your own Conda environment or venv to double-check that versions match.
On the other hand, for one of these packages, you might not have found any version information.
This is likely because the package is not yet deployed in the Jupyter Lab or JupyterHub environment.
As the case may be, you may have the privileges to add packages to that environment.
If this is so, use pip list once again to look up the version of that package that got installed in your own environment,
and use pip install <package>==<same version> to deploy it in the foreign environment wherefrom Jupyter Lab runs.
However, if you don't have that privilege, then it will not be possible for you to run these tutorials in that Jupyter Lab or JupyterHub instance.
If you can access the computer differently (say, through SSH),
or if you can just simply start another Jupyter Lab instance on the box,
then you can run Jupyter Lab from the tutorial venv you built, as shown above.
Otherwise, you will have to restart the setup on a computer you can access and configure suitably.
In your Jupyter Lab instance, open a terminal, and activate your venv.
| Tool / Platform | Activating the venv... |
|---|---|
| Conda / Any | conda activate ./venv |
| Pure Python / Linux or macOS | . venv/bin/activate |
| Pure Python / Windows | venv\Scripts\activate |
Then punch in the following command:
python -m ipykernel install --user --name tutte-tutorials --display-name "Tutte Institute Tutorials"If you open another launcher and wait a few seconds, you should see a new blue-and-yellow icon show up under Notebooks, with the label Tutte Institute Tutorials. You can now close the terminal.
From here, we are ready to start!
The existing tutorials, in a suggested order of reading, are: