Quickstart

This page provides a brief step-by-step tutorial covering two primary Whole Tale usage scenarios:

Launching a tale

In this example, you’ll launch the LIGO Tutorial tale:

  1. Go to the Browse page and search for “LIGO”. Select the Launch button. This will start your instance of the LIGO tale.
../_images/browse_ligo.png

Searching for and launching a tale

  1. Select the “Ligo Tutorial” in the Launched Tales panel. You should be taken to a Jupyter environment for this tale.
../_images/run_ligo.png

Launched Ligo tale

  1. Browse to work/data/ and open the LOSC_Event_tutorial.ipynb notebook. Follow the notebook narrative.
../_images/ligo_notebook.png

Ligo tale notebook

Congratulations! You’ve successfully run your first tale.

Here’s what happened behind the scenes:

  • When you hit Launch a Docker container was created using a Jupyter image containing all necessary dependencies to run the LIGO tutorial notebook.
  • The Tale Workspace directory contains a notebook and python script required to run the LIGO tutorial
  • The for the Tale, which were registered by the Tale creator, are mounted read-only and available under the data directory.
  • Your Whole Tale home directory was mounted into home. This allows you to access personal files from within the running tale.

In the next example, we create a tale using data published in DataONE.

Composing a new tale

The following steps demonstrate how to create a new tale based on Jupyter and register a dataset from DataONE for analysis.

  1. Select Compose to create a new tale with the name “Water Tale”. Select “Jupyter Notebook” from the Environments panel. Select Launch New Tale to create the tale.
../_images/watertale_compose.png

Composing a tale

  1. From the Manage page select Data and then the + icon to register a new external dataset.
../_images/watertale_manage_dataone.png

Opening the register window

  1. Enter the Digital Object Identifier (DOI) 10.5065/D6862DM8 for the Humans and Hydrology at High Latitudes: Water Use Information dataset published in DataONE. Select Search and then Register.
../_images/watertale_register_dataone.png

Registering a DataONE dataset by DOI

The dataset Humans and Hydrology at High Latitudes: Water Use Information should appear under your Data folder.

  1. From the Run page select the Files tab then the External Data folder and then the “+” button to add the registered dataset to your new Tale.
../_images/watertale_externaldata.png

Adding the registered dataset to your Tale

  1. From the “Select Data” window, higlight the dataset and click “Add Selected” and the “Select” button to save the changes to your Tale.
../_images/watertale_select_dataset.png

Adding the registered dataset to your Tale

  1. Download the example notebook. From the Run page Files tab select the Tale Workspace folder. Select the “+” button and Upload File.
../_images/watertale_upload_notebook.png

Uploading the notebook to your Tale workspace

  1. From the Run page select the Interact tab to display the running Jupyter environment.
../_images/watertale_interact.png

Accessing the interactive environment

  1. Within Jupyter, browse to the workspace directory to open and run the example notebook.
../_images/watertale_run_notebook.png

Running the notebook

Here’s what happended behind the scenes:

  • When you created your Tale, a Docker container was started using the Jupyter environment.
  • When you registered the dataset, a link to the data in DataONE was made in the Whole Tale catalog, available to all users.
  • You added a reference to registered dataset to your new Tale and it appeared in the data directory of your running Jupyter environment.
  • You uploaded the example notebook to the Tale workspace. The notebook references the dataset in the data directory to produce a graphic.