Academic attribution

Please acknowledge this project and its contributors when using the work in research, and cite the associated publications and software release where applicable. This is a scholarly request, not an additional licence condition. Citation information can be found in CITATION.cff.

Origins

fitstoolz is a partial rewrite of Owlcat’s Owlcat/FitsTool.py. Sphesihle Makhathini, a contributor to Owlcat, developed it into a standalone package to modernise and expand those FITS tools. Credit goes to the Owlcat contributors for the original work; see NOTICE for attribution.

Features

• Image and coordinate data indexing is consistent

• Simple API for adding, transposing and expanding axes (or dimensions)

• Celestial, spectral and Stokes axes evaluated through the WCS rather than approximated by stepping CDELT

• Xarray support

• Zarr support

• A native fitstoolz command line; install fitstoolz[ninja] to use its subcommands as stimela-ninja pipeline steps

Installation

$ pip install fitstoolz

Requires Python 3.11–3.13. See the installation docs for the development setup.

Example Usage

In[1]: from fitstoolz.reader import FitsData

In[2]: myfits = FitsData("example-image.fits")
       myfits.coord_names

Out[2]: ['STOKES', 'FREQ', 'DEC', 'RA']

In[3]: myfits.dshape
Out[3]: (1, 504, 100, 100) # these dimensions match the labels above

In[4]: myfits.coords

Out[4]:
Coordinates:
STOKES   (stokes) int32 4B dask.array<chunksize=(1,), meta=np.ndarray>
FREQ     (spectral) float64 4kB 8.803e+08 8.804e+08 ... 9.328e+08 9.329e+08
RA       (celestial.ra) float64 800B 53.16 53.16 53.16 ... 53.1 53.1 53.1
DEC      (celestial.dec) float64 800B -28.16 -28.16 ... -28.11 -28.11

From the command line:

$ fitstoolz header image.fits --show
$ fitstoolz stats image.fits --show
$ fitstoolz slice image.fits --axis FREQ,0,64 --outfile cube-sub.fits

Documentation

Full documentation is at fitstoolz.readthedocs.io — including a quickstart and the generated command-line reference.

Contributing

Bug reports, fixes, tests and documentation are all welcome. See CONTRIBUTING.md for the development setup, and AGENTS.md for the design conventions — particularly if your change touches axis ordering or adds a new app. By participating you agree to the Code of Conduct.

Security

A FITS file is untrusted input. SECURITY.md describes what fitstoolz does and does not guarantee about hostile or malformed ones, and how to report a vulnerability privately — please don’t open a public issue for security problems.

License

Apache License 2.0 — see LICENSE and NOTICE.