cutout-fits 0.1.1

A package to produce cutouts of (remote) FITS files.

cutout-fits

A utility to produce cutouts of FITS images using astropy. Remotely-hosted FITS images are fully supported using ffspec and s3fs.

Installation

From PyPI (stable):

pip install cutout-fits

From git (latest):

pip install git+https://github.com/AlecThomson/cutout-fits.git

Usage

Universal cutouts

The command-line tool can be invoked using cutout-fits entry point. Currently, spatial cutouts are specified using a centre right ascension and declination along with a cutout radius. Spectral cutouts are specified with a start and end frequency range.

Any additional cube dimensions, such as time or Stokes, will simply be included in the cutout. Further, any non-image HDUs present in the FITS file will also be simply included in the output file.

$ cutout-fits -h
usage: cutout-fits [-h] [-o] [-v] [--freq-start FREQ_START] [--freq-end FREQ_END] infile outfile ra_deg dec_deg radius_arcmin

Make a cutout of a FITS file

options:
  -h, --help            show this help message and exit

File options:
  infile                Path to input FITS file - can be a remote URL
  outfile               Path to output FITS file
  -o, --overwrite       Overwrite output file if it exists
  -v, --verbosity       Increase output verbosity

Cutout options:
  ra_deg                Centre RA in degrees
  dec_deg               Centre Dec in degrees
  radius_arcmin         Cutout radius in arcminutes
  --freq-start FREQ_START
                        Start frequency in Hz
  --freq-end FREQ_END   End frequency in Hz

CASDA Access

Cutouts from the CSIRO ASKAP Science Data Archive (CASDA) can be made by invoking the cutout-casda entry point. The same set of cutout arguments as cutout-fits are supported

$ cutout-casda -h
usage: cutout-casda [-h] [--freq-start FREQ_START] [--freq-end FREQ_END] [--username USERNAME] [--store-password] [--reenter-password] [-v]
                    ra_deg dec_deg radius_arcmin filename [filename ...]

Make a cutout of a FITS file on CASDA

options:
  -h, --help            show this help message and exit

Cutout options:
  ra_deg                Centre RA in degrees
  dec_deg               Centre Dec in degrees
  radius_arcmin         Cutout radius in arcminutes
  --freq-start FREQ_START
                        Start frequency in Hz
  --freq-end FREQ_END   End frequency in Hz

CASDA options:
  filename              FITS file name(s)
  --username USERNAME   CASDA username
  --store-password      Store password in keyring
  --reenter-password    Re-enter password
  -v, --verbosity       Increase output verbosity

The CASDA Astroquery API requires an OPAL username and password to login. You can supply your username via the CLI or as the CASDA_USERNAME environment variable. Astroquery supports caching your password, which you will need if running non-interactively. To cache your password you can interactively run the helper script casda-login:

$ casda-login -h
usage: casda-login [-h] username

Login to CASDA and save credentials

positional arguments:
  username    Username for CASDA

options:
  -h, --help  show this help message and exit

Python API

Further API documentation is provided on read the docs.

Remote files

If accessing a remote file on S3, you'll need to set your access keys. To do this, fsspec looks for the following environment variables:

FSSPEC_S3_ENDPOINT_URL='https://...'
FSSPEC_S3_KEY='...'
FSSPEC_S3_SECRET='...'

This project support using a .env file to store these variables, if needed. Simply set these variables in a .env files in your current working directory or set them in your environment if you wish. Be careful not to commit them to VCS.