radiopadre-client 1.0rc8

Overview

Radiopadre is a Jupyter notebook framework for quick and easy visualization of [radio astronomy, primarily] data products and pipelines.

Radiopadre includes integration with JS9 and CARTA for live FITS viewing of [remote] FITS files straight from your browser. (In boldface, because this is a pretty neat capability to have!)

Radiopadre is a custom Jupyter kernel, so in principle you could install it and create radiopadre notebooks directly from a Jupyter session. Some of the tight integration with JS9 and CARTA, however, works smoother if you start your sessions via run-radiopadre, which takes care of starting up and stopping appropriate helper processes and such.

run-radiopadre can also take care of starting radiopadre inside remote Jupyter sessions using virtualenv, Docker or Singularity. It will manage port forwarding for you, so that your local browser can talk to the remote Jupyter server (and CARTA/JS9 backends).

Installation notes

Radiopadre strives to be admin-free. That is, you should not need to bother your friendly local sysadmin for most (or all) of the below.

Radiopadre itself (plus the attendant Jupyter etc. dependencies) must be installed inside a Python 3.6+ virtual environment. The Jupyter notebook server then runs inside this environment.

run-radiopadre does not have (but can) live in the same virtualenv. Since it has almost no dependencies (and is backwards-compatible down to Python 2.7), you can install it directly with pip install --user, for example. (Or clone the repository and jury-rig an install via PATH and PYTHONPATH settings.)

Examples

$ run-radiopadre -V .

Uses the virtualenv backend (-V). Activates the virtual environment, runs the Jupyter notebook server inside with “.” as the working directory, and drives a browser to it (see --browser option). If no notebooks are present, creates a minimalistic starter notebook called radiopadre-default.ipynb. If a notebook called radiopadre-auto.ipynb is present, opens it automatically (see --auto-load option.) Also opens the CARTA browser in a separate tab.

$ run-radiopadre -V remote_box:project

Uses SSH to connect to remote_box. Uses the virtualenv backend (-V). Activates the virtual environment, runs the Jupyter notebook server inside with ~/project as the working directory. Sets up port forwarding so that a local browser can talk to Jupyter on the remote end. Drives a local browser to the appropriate URL. If no notebooks are present in project, creates a minimalistic starter notebook called radiopadre-default.ipynb. Opens radiopadre-auto.ipynb automatically.

$ run-radiopadre -D remote_box:project --auto-init -u

Uses SSH to connect to remote_box. If run-radiopadre is not found on the remote, tries to bootstrap an installation. If successful, uses the Docker backend (-D). Checks for an updated version of the Docker image (-u) and downloads it if needed. Runs the container with a Jupyter notebook server inside, with ~/project as the working directory. Sets up port forwarding so that a local browser can talk to Jupyter inside the remote container. Drives a local browser to the appropriate URL. If no notebooks are present in project, creates a minimalistic starter notebook called radiopadre-default.ipynb. Opens radiopadre-auto.ipynb automatically.

Persistent configuration

Combinations of command-line settings can be made into persistent defaults by saving them to a config file called ~/.config/radiopadre-client. This is useful when you work with different remote hosts with different setups. The -s option saves the current combination of command-line options to a config section called [host]. The -e option saves them to a section called [host:path]. For example, the result of the following three runs of run-radiopadre:

$ run-radiopadre -D box1:project1 -s
$ run-radiopadre -V box1:project2 -e
$ run-radiopadre -S box2:project2 -s

is the following config file:

[box1]
backend = docker

[box1:project1]
backend = venv

[box2:project2]
backend = singularity

The contents of the config file modify the relevant default settings. If run-radiopadre is then run without an explicit -V, -D, or -S option for a matching host (and possibly path), the default backend setting is taken from the config file.

In case of confusion, look at messages at the start of run-radiopadre. These tell you which settings come from the config file, and which from the command line.

Note also that some options (e.g. --update and --auto-init) are considered one-off settings, and are not saved to the config file.

Recent sessions

Invoking run-radiopadre without arguments gives you a list of the five most recent sessions, and lets you invoke one of them again by entering its number.

Updates and bleeding-edge installs

The --client-install-pip and --server-install-pip determine what package names are passed to pip install when --auto-init is invoked. The default values are simply radiopadre-client and radiopadre. Whenever --update is given, pip --upgrade is invoked to upgrade these packages. You can pin a particular release by including a pip version specifier, e.g. --radiopadre-client radiopadre-client==1.0.

~Maso~ advanced users may want to track the git repository versions rather than pip releases. This can be done by setting the following options, adjusting their values as appropriate:

--client-install-path ~/radiopadre-client
--client-install-repo https://github.com/ratt-ru/radiopadre-client.git
--client-install-branch master
--server-install-path ~/radiopadre
--server-install-repo https://github.com/ratt-ru/radiopadre.git
--server-install-branch master

These options override the pip settings. Rather than installing from PyPI, the packages are then cloned from the specified repositories into the specified directories, and installed into the virtual environment with pip install -e. When --update is given, git pull is invoked to update the sources.

If using Docker or Singularity, you will probably want to combine this with the --container-dev option. If set, this will mount the client/server install paths inside the container, thus overriding the potentially older versions installed inside the image.