Skip to content

CDAT/jupyter-vcdat

Repository files navigation

DOI

Jupyter-vcdat

A Jupyter Lab extension that integrates vCDAT features directly in a notebook.

Prerequisites

For installing locally with conda you'll need:

  • Installation of conda via Anaconda or Miniconda conda >=4.7.12 (the script will try to update your base installation anyway)

If you didn't let Anaconda or Miniconda prepend the Anaconda(2 or 3) install location to PATH, make sure conda is in your PATH (for more information see the Anaconda Documentation). Assuming Ananconda is installed in ${HOME}/anaconda:

  • export PATH=${HOME}/anaconda/bin:${PATH} # for bash
  • setenv PATH ${HOME}/anaconda/bin:${PATH} # for tcsh

For running docker container, you'll need docker installed:

User Installation

You can run jupyter-vcdat via a local installation, an anaconda environment or through a docker container.

New conda environment

This example will create and run a new conda environment 'jupyter-vcdat', containing JupyterLab and jupyter-vcdat

conda create -n jupyter-vcdat -c cdat/label/v82 -c conda-forge jupyter-vcdat #Create conda environment
conda activate jupyter-vcdat #Start environment
jupyter lab build #Build jupyter lab to include jupyter-vcdat extension (only for first time installation)

jupyter lab #Start Jupyter Lab

The browser should open automatically, if not, point your browser to: localhost:8888/lab

Existing conda environment

This example will install jupyter-vcdat to an existing conda environment.

  • Note: python3 is required and will be installed.
conda install -c cdat/label/v82 -c conda-forge jupyter-vcdat #Install jupyter-vcdat
jupyter lab build #Build jupyter lab to include jupyter-vcdat extension (only for first time installation)

jupyter lab #Start Jupyter Lab

The browser should open automatically, if not, point your browser to: localhost:8888/lab

Jupyter-vcdat docker container

This example runs a jupyter-vcdat docker container at localhost:9000/lab, with mounted volume 'my_data':

docker run -p 9000:8888 -v /Path/To/my_data/:/home/jovyan/my_data/ -it cdat/vcdat:latest jupyter lab #Run the image

After the container is running, obtain the token (if needed) from the output shown in the console:

The Jupyter Notebook is running at:
http://(d8a71c79a232 or 127.0.0.1):8888/?token=<Copy the token value from here>

Open a browser and use this URL:

localhost:8888/lab?token=<Paste token value here>

You should then be able to access the jupyter lab instance on your local browser.

Obtaining sample data

To download sample data, enter the code below within a Jupyter notebook cell and run the cell:

import vcs
import cdms2
import cdat_info
import pkg_resources
vcs_egg_path = pkg_resources.resource_filename(pkg_resources.Requirement.parse("vcs"), "share/vcs")
path = vcs_egg_path+'/sample_files.txt'
cdat_info.download_sample_data_files(path,"sample_data")

Local installation (for developers)

Make sure you have met all pre-requisits noted at the top. Clone the jupyter-vcdat github repo:

git clone https://github.com/CDAT/jupyter-vcdat.git

Change into the directory containing the repo and type in the following commands:

    #Create the environment
    ./install_script.sh #Note: You can use -h to get help and options for installation script.

    # The following two lines of code install tslint if developers want to use it (optional):
      # For VSCode:
      code --install-extension tslint

      # For Atom:
      apm install linter-tslint

    # For all users, activate the jupyter-vcdat environment and launch the JupyterLab interface
    conda activate jupyter-vcdat
    jupyter lab

To rebuild the package and the JupyterLab app:

npm run build
jupyter lab build