Package: radiopadre-client
Your one-stop client-side script to runradiopadrenotebooks
locally and on remote machines.Quick start:$ pip install radiopadre-client
$ run-radiopadre interesting_local_directory --auto-initOr for a remote session, assuming you have ssh access to the host:$ run-radiopadre remote_host:interesting_remote_directory --auto-init(With any luck, the –auto-init option will cause an automatic installation on the remote end.)OverviewRadiopadreis a Jupyter
notebook framework for quick and easy visualization of [radio astronomy, primarily]
data products and pipelines.Radiopadre includes integration withJS9andCARTAfor  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
viarun-radiopadre, which takes care of starting up and stopping appropriate
helper processes and such.run-radiopadrecan 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 notesRadiopadre 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-radiopadredoes 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 withpip install--user,
for example. (Or clone the repository and jury-rig an install viaPATHandPYTHONPATHsettings.)Automatic virtualenv installIf started outside a virtualenv,run-radiopadre-Vwill look for a virtualenv
called~/.radiopadre/venv, activate it, and run the Jupyter
notebook server within.If~/.radiopadre/venvdoes not exist, specify the--auto-initoption so thatrun-radiopadrecan try to create it for you, and install
radiopadre inside. This is normally the easiest way to bootstrap a new
installation. (Python 3.6+ required.)Manual virtualenv installIf, for whatever reason, you want to install radiopadre in a custom
virtualenv, then create [a Python 3.6+] one yourself and install radiopadre inside it
followingthe instructions.
This follows normal pip practice. You can usepip install, or elsepip install-efor an “editable” install from a local directory. Sinceradiopadredepends onradiopadre-client, it will automatically install the latter as well
(though you may well want to pre-install a local version withpip install-e).Ifrun-radiopadreis then run inside that virtual environment, it will
look for radiopadre in the same environment. Alternatively, you can still
runrun-radiopadre-Voutside the environment, but specify its location
with--radiopadre-venv.The Docker/Singularity backendsIf you don’t want to or can’t use virtual environments (don’t have Python 3.6,
for example), you can run radiopadre notebooks inside a Docker or Singularity
container. Images are provided on dockerhub.To use containers, invokerun-singularity-Dorrun-singularity-S.
This will automatically download the required image from dockerhub, if not
already available on the system.Remote installationTo run remote radiopadre sessions, the remote end must have either:(a) have a full radiopadre install inside.radiopadre/venv(or
another custom environment);(b) have radiopadre-client alone installed inside.radiopadre/venv,
and support Docker or Singularity;(c) or haverun-radiopadresomewhere in the default path (i.e. apip install-e, or a jury-rigged install), and support Docker
or Singularity.Case (a) requires Python 3.6+, and allowsrun-radiopadre-V, while (b) or
(c) can make do with Python as low as 2.7, but require usingrun-radiopadre-Dorrun-radiopadre-S.If you’ve got nothing at all installed on the remote, you can try--auto-initto bootstrap an installation. At present, this will try to set up case (a), so
Python 3.6+ and virtualenv is required. For funky/older systems without,
you’ll have to set up (b) or (c) by hand.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--browseroption).
If no notebooks are present, creates a minimalistic starter notebook
calledradiopadre-default.ipynb. If a notebook calledradiopadre-auto.ipynbis present, opens it automatically (see--auto-loadoption.) Also opens the CARTA browser in a separate tab.$ run-radiopadre -V remote_box:projectUses SSH to connect toremote_box. Uses the virtualenv backend
(-V). Activates the virtual environment, runs the Jupyter notebook
server inside with~/projectas 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 inproject, creates a minimalistic starter notebook
calledradiopadre-default.ipynb. Opensradiopadre-auto.ipynbautomatically.$ run-radiopadre -D remote_box:project --auto-init -uUses SSH to connect toremote_box. Ifrun-radiopadreis 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~/projectas 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 inproject, creates a minimalistic starter notebook
calledradiopadre-default.ipynb. Opensradiopadre-auto.ipynbautomatically.Persistent configurationCombinations 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-soption saves the current combination of command-line
options to a config section called[host]. The-eoption
saves them to a section called[host:path]. For
example, the result of the following
three runs ofrun-radiopadre:$ run-radiopadre -D box1:project1 -s
$ run-radiopadre -V box1:project2 -e
$ run-radiopadre -S box2:project2 -sis the following config file:[box1]
backend = docker

[box1:project1]
backend = venv

[box2:project2]
backend = singularityThe contents of the config filemodifythe relevant default
settings. Ifrun-radiopadreis 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 ofrun-radiopadre. These tell you which settings come from
the config file, and which from the command line.Note also that some options (e.g.--updateand--auto-init) are considered one-off settings, and are
not saved to the config file.Recent sessionsInvokingrun-radiopadrewithout 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 installsThe--client-install-pipand--server-install-pipdetermine
what package names are passed to pip install when--auto-initis invoked. The default values are simplyradiopadre-clientandradiopadre. Whenever--updateis given,pip--upgradeis invoked to upgrade
these packages. You can pin a particular release by including
a pip version specifier, e.g.--radiopadre-clientradiopadre-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 masterThese 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
withpip install-e. When--updateis given,git pullis invoked to update the sources.If using Docker or Singularity, you will probably want to combine this
with the--container-devoption. If set, this will mount the
client/server install paths inside the container, thus overriding
the potentially older versions installed inside the image.