starlink-pywrapper: Quick Start Guide

Easily script Starlink commands with Python.

This package requires a separate working Starlink installation to be available and the path to be passed to the package. See https://starlink.eao.hawaii.edu to download Starlink. It allows easy pythonic calling of Starlink commands from python, where you can use normal Python arguments and keywords and have access to the call signatures and help strings through the normal Python help.

There are auto-generated wrapper modules providing easy access to the Starlink packages KAPPA, CONVERT, ATOOLS, CCDPACK, CUPID, FIGARO, POLPACK, and SMURF. There are also commands to allow access to the pipelines ORAC-DR and Picard.

Installation

You should normally install this package via pip with:

pip install starlink-pywrapper

This will also install the necessary python dependencies.

You must also have a working Starlink installation, which can be downloaded from https://starlink.eao.hawaii.edu.

Running commands

To run e.g. the KAPPA stats command command on a file myndf.sdf, you would use the starlink.kappa.stats() function, after first importing the package and telling it where your Starlink installation was

>>> from starlink import kappa
>>> kappa.wrapper.change_starpath('/path/to/my/starlink/installation')
>>> statsinfo = kappa.stats('myndf.sdf')
>>> print(statsinfo.mean)
18.3

As you can see in this example, the returned object from the command will include all output values that you would previously have either accessed with KAPPA’s parget, or just read from the screen output.

Many other commands will produce a new output NDF file on disk. For example, the makesnr command in KAPPA:

>>> snrinfo = kappa.makesnr(in_='myndf.sdf', out='snr.sdf', minvar=0.0)
>>> print(snrinfo.out)
snr.sdf

The returned object is less useful for these commands, although may contain useful information. The documentation should indicate what values are returned and what they mean, and can be accessed as normal in Python:

>>> help(kappa.makesnr)

Differences from standalone Starlink

• When using the command line starlink programs, each command will often remember certain important variables you set previously, and use those as the default for the next repeat of that command, or the next command you run. This behaviour has been deliberately not included in this package, as when writing scripts this behaviour can produce suprising results. Instead, the documented defaults should always be the default seen by your programs.
• You do not have to add shell escapes to your strings when passing them to Starlink commands.
• You do not need to use KAPPA’s parget to read the return values of a command; instead every return value is included in the returned object (a ‘namedtuple’ type) as a field.
• Interactive usage of commands where you are prompted to enter values is not supported; the full command must be specified when running the command.
• You should not use KAPPA’s fitslist to access FITS header values programatically as it will only print values to the terminal (if logging is set to DEBUG), and does not provide access to them in an Python object. Instead, either use starlink.kappa.fitsval() to read single values, or use the starlink.utilities.get_ndf_fitshdr() to read in the entire FITS header of an NDF file and return it as an Astropy Header object (requires Astropy to be installed).

Guide to this software

• Overview of this package
  • Installation
  • Running Starlink commands from Python
    • Setting up Starlink
    • Running commands
    • Getting help.
    • Directly running a command (without using the specific package).
    • Logging and seeing the full output.
    • Scripting ORAC-DR and PICARD
  • How this package runs Starlink
    • ADAM directory
  • Commands that should be avoided
    • parget
    • fitslist
    • Interactive usage
  • Known Issues

There are also some worked examples using this software.

(These examples are also available as Jupyter notebooks, viewable at XXXXX, XXXX and XXXX)

Module references:

starlink.wrapper	starlink.wrapper: A module for running Starlink commands from python.
starlink.utilities	Convenience utilities when using Starlink in python.
starlink.atools	Runs commands from the Starlink ATOOLS package.
starlink.ccdpack	Runs commands from the Starlink CCDPACK package.
starlink.convert	Runs commands from the Starlink CONVERT package.
starlink.cupid	Runs commands from the Starlink CUPID package.
starlink.figaro	Runs commands from the Starlink Figaro package.
starlink.fluxes	Module to run the Starlink FLUXES package.
starlink.kappa	Runs commands from the Starlink KAPPA package.
starlink.polpack	Runs commands from the Starlink POLPACK package.
starlink.smurf	Runs commands from the Starlink SMURF package.
starlink.picard	Module for running PICARD recipes from python.

Indices and tables

• Index
• Module Index
• Search Page