ianhellstrom / zoose

JupyterLab Docker images for Python with separate flavours for Neo4j and quantum computing libraries

What is Zoose?

Jupyter is to Jupiter as Zoose is to Zeus.

Zoose is a Docker container image for Jupyter notebooks pre-loaded with common Python packages as well as a Neo4j web server for graph analytics with Cypher. Containerized notebooks with a standard set of packages make sharing and reproducing notebooks easier: no need for virtual environments and brittle configurations that break on Python upgrades.

Flavours

Zoose comes in a few flavours: base, neo4j, pytorch, quantum, and geo. What is included in base is always included in the rest, too.

You can run these flavours directly in VSCode from your browser with GitHub Codespaces. Only two clicks to spin up an IDE or notebook with all packages installed and ready!

Special flavours

There are also several special flavours suitable for use with Gitpod, an alternative to GitHub Codespaces.

• base-gitpod
• pytorch-gitpod
• quantum-gitpod
• geo-gitpod

To get started with these special flavours for Gitpod, please use the template to create a repository that you use to spin up a workspace from that repo.

In Gitpod, you have two options for Zoose notebooks:

1. A VSCode experience
2. JupyterLab, which you can start from the Gitpod workspace terminal with /jupyter.sh.

Zoose Base

• Python 3.10
• JupyterLab 3.6 with extensions

Python packages:

• Beautiful Soup 4.12
• Gower 0.1
• Keras 2.12
• LIME 0.2
• Matplotlib 3.7
• NLTK 3.8
• Numpy 1.24
• Pandas 2.0
• Prince 0.10
• Requests 2.31
• Scikit-learn 1.2
• SciPy 1.10
• Scrapy 2.9
• Seaborn 0.12
• SHAP 0.41
• spaCy 3.5
• StatsModels 0.14
• thefuzz 0.20

Zoose Neo4j

Zoose Neo4j includes everything from Zoose Base as well as:

• Neo4j Community Edition 4.4
• py2neo 2021.2.4

Zoose PyTorch

Zoose PyTorch includes everything from Zoose Base as well as:

• Captum 0.6
• PyTorch 2.0
• PyTorch Audio 2.0 (CPU)
• PyTorch Text 0.15 (CPU)
• PyTorch Vision 0.15 (CPU)
• Transformers 4.29

Zoose Quantum

Zoose Quantum includes everything from Zoose Base as well as:

• Amazon Braket SDK 1.41
• Cirq 1.1
• cuQuantum 23.3
• OpenFermion 1.5
• PennyLane 0.30 with plugins for Cirq, Stawberry Fields, Qiskit
• pytket 1.15
• Qiskit 0.43
• QuTiP 4.7
• Strawberry Fields 0.23

Zoose Geo

Zoose Geo includes everything from Zoose Base as well as:

• Geopandas 0.13
• Geoplot 0.5
• h3 3.7
• h5py 3.8
• netCDF4 1.6
• shapely 2.0
• xarray 2023.5
• zarr 2.14

How to use?

Execute ./zoose.sh, which launches a Jupyter notebooks session. By default it launches Zoose Base. If you want Neo4j, Geo, or Quantum, just use ./zoose.sh neo4j, ./zoose.sh geo, or ./zoose.sh quantum instead.

Please use the link from the command line to access it, as it requires a token.

If you do not want to git clone the repo, you can use the public Docker image:

docker run --rm -it \
  -v $(pwd):$(pwd) -w $(pwd) \
  -p 8888:8888 \ 
  "databaseline/zoose-base"

Please ensure that the Docker container has sufficient resources. Go to Docker Desktop > Preferences > Resources and set the number of CPUs to at least half of the total number available. Assign at least 4 GB of RAM to the container. Note that the Jupyter kernel may crash when loading large data sets (into memory). These settings apply to all local containers.

BigQuery credentials

BigQuery support has been dropped from the base image in 3.1. You can install pandas_gbq and google.auth easily from within a notebook with pip: ! pip install pandas_gbq.

If you use Zoose with BigQuery often, you may want to preserve credentials. You can do so by adding -v $(pwd)/.config:/root/.config/pandas_gbq/ to the command above.

Just make sure you ignore .config and do not share your personal credentials in a git repository!

IBMQ credentials

If you use Zoose Quantum with Qiskit often, you may want to preserve IBMQ credentials. You can do so by adding -v $(pwd)/.qiskit:/root/.qiskit to the command above. You need to execute IBMQ.save_account(...) from Zoose Quantum once to save the credentials. Afterwards, you can execute IBMQ.load_account(), provided you have mounted the .qiskit volume prior to launching Zoose Quantum.

Just make sure you ignore .qiskit and do not share your API token in a git repository!

Neo4j

Zoose also kicks off a Neo4j web server. The UI is available at localhost:7474. Please check out this value stream example to learn more about Neo4j and Cypher.

If you use Neo4j, please ensure that your Docker container has at least 6 GB of RAM allocated. This can be configured in the Docker client under 'Resources'.

zoose's Issues

Migrate to Qiskit 1.0

I'm making this issue because this project is part of the Qiskit ecosystem.

As of June 2024, we're introducing a requirement that all projects are compatible with Qiskit 1.0. New users will be using Qiskit 1.0 and we want to make sure any projects we guide them to work straight away.

See our migration guide. and let me know if you need any support (such as answering questions about Qiskit or code review). With Qiskit's new stability policy, this should be the last change needed for a while.

In June, we will test out your project and remove it if it doesn't work with Qiskit 1.0. This includes cases in which we can't get the project working because the documentation is lacking. We do value your project so let me know if you need any help migrating or have any other concerns.

`/jupyter.sh` launched window that needed token - expected?

I'm not exactly sure what the "traditional Jupyterlab experience" is, but perhaps it means that when the browser is launched via /jupyter.sh you still have to find and copy/paste the token in to the auth screen? (I did that, and it worked, copying the token from one of the given urls.)

None of the three suggested ways to access the server actually worked, BTW:

[C 2022-10-17 20:40:28.682 ServerApp] 
    
    To access the server, open this file in a browser:
        file:///home/gitpod/.local/share/jupyter/runtime/jpserver-2207-open.html
    Or copy and paste one of these URLs:
        http://davidbakin-zooseplaypen-lv7b3xp10i4:8888/lab?token=6db29cd2ba64eb918fff6bf1b3d8dd12eae38015d0145f1f
     or http://127.0.0.1:8888/lab?token=6db29cd2ba64eb918fff6bf1b3d8dd12eae38015d0145f1f

They all gave some sort of 404.

I guess the issue here is that ... I've got no Jupyter experience. It was easy to figure out the token from the given urls so I could cut/paste it. But the three urls didn't work.

(BTW, good job on this repo! It really is a seamless way to get going. Only thing I could suggest at this point as a feature request would be an "import" that took a URL to a notebook - cloning it, I suppose - not just a local filesystem name.)

Create Zoose-Geo flavour

A Zoose Geo flavour must be derived from Zoose Base and contain and there very least:

• h5py
• zarr
• xarray
• netCDF4
• geopandas