How to use Pan3D in a Jupyter Notebook

Running Pan3D in a Jupyter notebook allows data scientists to incorporate the tool into their existing workflows and can facilitate greater collaboration between teammates. This tutorial assumes you have a running Jupyter notebook. You can find examples at notebook examples in the Pan3D code repository. You can run these examples on Binder here.

In your current kernel, install Pan3D:
```
pip install pan3d[viewer]
```

In the first cell of your notebook, initialize Pan3D’s DatasetBuilder and viewer.

from pan3d import DatasetBuilder
builder = DatasetBuilder()
viewer = builder.viewer

Prepare a configuration for the builder to import. This can come from a previously exported configuration file from Pan3D. An example of this is shown in example_config_xarray.json:
```
from pan3d import DatasetBuilder
config_path = '../example_config_xarray.json'
builder = DatasetBuilder()
builder.import_config(config_path)
```

You can alternatively create a configuration dictionary. See pangeo_forge.ipynb for an example of this:

from pan3d import DatasetBuilder
config = {
    'data_origin': 'https://ncsa.osn.xsede.org/Pangeo/pangeo-forge/noaa-coastwatch-geopolar-sst-feedstock/noaa-coastwatch-geopolar-sst.zarr',
    'data_array': {
        'name': 'analysed_sst',
        'x': 'lon',
        'y': 'lat',
        't': 'time',
    },
    'data_slices': {
        'lat': [-90, 90, 50],
        'lon': [-180, 180, 50]
    },
}
builder = DatasetBuilder()
builder.import_config(config)

If you’d like finer control of the configuration process, you can call individual state setters on the builder by referring to the API documentation for the DatasetBuilder class. Refer to manual_config.ipynb for an example using these API methods:
```
builder = DatasetBuilder()
builder.dataset_path = '../example_dataset.nc'
builder.data_array_name = 'density'
builder.x = 'length'
builder.y = 'width'
builder.z = 'height'
builder.t = 'second'
builder.t_index = 2
```
After configuring the builder instance, you can show the Pan3D viewer as cell output.
```
viewer = builder.viewer
await viewer.ready
viewer.ui
```
If you’d like to do more advanced rendering than the Pan3D viewer allows, you can still use the DatasetBuilder class for mesh preparation. You can access the mesh with builder.mesh and use it in a PyVista rendering pipeline. Refer to advanced_pyvista_rendering.ipynb for an example of this technique, which leverages PyVista plotting to generate an animated GIF of timesteps in the dataset.