Quickstart

Once installed, jdaviz can be run either in a Jupyter notebook or as a standalone web application. Detailed workflows are given within the documentation, but some quick-start tips are given below.

As a Standalone Application

Note

This feature is currently in development for the new generalized version of jdaviz, so the following may change in an upcoming release.

jdaviz provides a command-line tool to start the standalone desktop application in a browser. To see the syntax and usage, from a terminal, type:

jdaviz --help

usage: jdaviz [-h]
              [--layout {cubeviz,specviz,specviz2d,mosviz,imviz,flexible}]
              [-fp [FILEPATH ...]] [-ff [FILE_FORMAT ...]]
              [--instrument INSTRUMENT] [--browser BROWSER]
              [--theme {light,dark}] [--verbosity {debug,info,warning,error}]
              [--history-verbosity {debug,info,warning,error}] [--host HOST]
              [--port PORT] [--hotreload | --no-hotreload] [--version]

Start a Jdaviz application instance with data loaded from FILENAME.

options:
  -h, --help            show this help message and exit
  --layout {cubeviz,specviz,specviz2d,mosviz,imviz,flexible}
                        Configuration to use. Deprecated as of 5.0.
  -fp, --filepath [FILEPATH ...]
                        The path to a file to be loaded into the Jdaviz
                        application. May be repeated to load multiple files.
  -ff, --file_format [FILE_FORMAT ...]
                        The format of a file to be loaded into the Jdaviz
                        application.The same number of filepath and
                        file_format arguments must be specified, and will be
                        associated based on input order.
  --instrument INSTRUMENT
                        Manually specifies which instrument parser to use, for
                        Mosviz
  --browser BROWSER     Browser to use for application (use qt for embedded Qt
                        browser).
  --theme {light,dark}  Theme to use for application.
  --verbosity {debug,info,warning,error}
                        Verbosity of the application for popup snackbars.
  --history-verbosity {debug,info,warning,error}
                        Verbosity of the logger history.
  --host HOST           Host to bind the server to, defaults to localhost.
  --port PORT           Port to bind the server to, defaults to 0 (finds an
                        empty port).
  --hotreload, --no-hotreload
                        Whether to enable hot-reloading of the UI (for
                        development).
  --version             show program's version number and exit

Jdaviz is now intended to be used in a flexible, generalized layout rather than the older “configs”, but these deprecated configurations are still available from the command line. For compatibility with the older configurations during their deprecation period, you can specify --layout=flexible to launch the new generalized Jdaviz from the command line. To load a file into a configuration:

jdaviz --layout=[imviz|specviz|cubeviz|mosviz|specviz2d|flexible] --filepath="/path/to/data/file" --file_format="FileFormat"

This will warn that the --layout argument is deprecated. In the future, running the jdaviz command will simply launch the generalized Jdaviz application without going through a launcher page. You can also specify filepath and file format using the shorter -fp and -ff, respectively, which may be useful if loading multiple files. Note that the file format is generally required because many files can be read by multiple loaders. See Data Formats for the current list of available data formats. Note that you will need to enclose multi-word formats in quotation marks, for example --file_format='1D Spectrum'.

Currently, running the command jdaviz without any additional input will still run a launcher. To launch the modern generalized jdaviz from here, click the Jdaviz logo in the top right. Alternatively, you can still use the deprecated legacy functionality to select a file from the file picker, which will identify the best configuration according to the file type. You can also select the desired deprecated configuration by clicking one of the bottom buttons without specifying a file. A blank configuration will open and the IMPORT button will be available to select a file from the file picker.

In a Jupyter Notebook

The power of Jdaviz is that it can integrated into your Jupyter notebook workflow:

import jdaviz as jd

jd.show()
jd.load('filename.fits', format='Image', data_label='MyData')

Jdaviz also provides a directory of sample notebooks to test the application, located in the notebooks sub-directory of the Git repository.

Customizing Notebook Display Layout

By default, calling show() will display your visualization tool inline in your notebook, that is the tool will show underneath the notebook cell it was called from:

import jdaviz as jd

jd.show()
jd.load('filename.fits', format='Image')

The height of the application in the notebook can be changed by passing an integer specifying the height in pixels to the height argument of show, for example:

jd.show(height=800)

You can additionally specify the location with the loc argument. For example, inline can be specified manually with:

jd.show(loc='inline')

Detached Popout

Jdaviz can also be displayed in a detached window, separate from your working Jupyter interface.

Note

Popups must be allowed in your browser to display properly.

The following shows jdaviz in a new popout window:

jd.show(loc='popout')

To manually specify the anchor location, append the anchor to popout, separated by a colon:

jd.show(loc='popout:window')

You can also popout to a new browser tab by specifying a tab anchor:

jd.show(loc='popout:tab')

Sidecar (Jupyter Lab)

In Jupyter Lab, sidecar provides additional methods to customize where to show the viewer in your workspace. The following shows jdaviz in the default sidecar location, to the right of the notebook:

jd.show(loc='sidecar')

To manually specify the anchor location, append the anchor to sidecar, separated by a colon:

jd.show(loc='sidecar:right')

Other anchors include: split-right, split-left, split-top, split-bottom, tab-before, tab-after, right. An up-to-date list can be found at jupyterlab-sidecar.

Multiple Jdaviz Instances

By default, any commands sent to jdaviz will be sent to the current default application. For example:

import jdaviz as jd

jd.show()  # shows the default application
jd.load('filename.fits', format='Image')  # loads into the default application

However, multiple independent instances of Jdaviz can be created and displayed in the same notebook. To do so, create a new Jdaviz app instance and store it in a custom variable:

import jdaviz as jd

app1 = jd.new_app()
app2 = jd.new_app()

app1.show(loc='sidecar:right')
app2.show(loc='sidecar:left')

app1.load('filename1.fits', format='Image')
app2.load('filename2.fits', format='Image')

You can also access the current default application with jdaviz.gca() (get current application), and pass arguments to jdaviz.new_app() or jdaviz.gca() to manage which is considered the current application.

Keyboard Shortcuts

The following keyboard shortcuts are available when your cursor is over an image viewer. Some shortcuts require a specific plugin to be open.

Key	Action	Requirements
b	Blink to next image	2+ images loaded
B	Blink to previous image	2+ images loaded
l	Plot line profiles at cursor position	Line Profile (XY) plugin open
m	Add marker at cursor position	Markers plugin open
d	Set distance measurement point (press twice to complete)	Markers plugin open
Alt+d (Option+d)	Set distance point with snap to nearest marker	Markers plugin open
r	Clear all markers and distance lines	Markers plugin open