Introduction

The Kapteyn Package is a collection of Python modules and applications developed by the computer group of the Kapteyn Astronomical Institute, University of Groningen, The Netherlands. The purpose of the package is to provide tools for the development of astronomical applications with Python.

The package is suitable for both inexperienced and experienced users and developers and documentation is provided for both groups. The documentation also provides in-depth chapters about celestial transformations and spectral translations.

Some of the package’s features:

  • The handling of spatial and spectral coordinates, WCS projections and transformations between different sky systems. Spectral translations (e.g., between frequencies and velocities) are supported and also mixed coordinates. (Modules wcs and celestial)

  • Versatile tools for writing small and dedicated applications for the inspection of FITS headers, the extraction and display of (FITS) data, interactive inspection of this data (color editing) and for the creation of plots with world coordinate information. (Module maputils) As one example, a gallery of all-sky plots is provided.

  • A class for the efficient reading, writing and manipulating simple table-like structures in text files. (Module tabarray)

  • Utilities for use with Matplotlib such as obtaining coordinate information from plots, interactively modifiable colormaps and timer events (module mplutil); tools for parsing and interpreting coordinate information entered by the user (module positions).

Overview

The following modules are included:

  • wcs, a binary module which handles spatial and spectral coordinates and provides WCS projections and transformations between different sky systems. Spectral translations (e.g., between frequencies and velocities) are supported and also mixed coordinates.

  • celestial, containing NumPy-based functions for creating matrices for transformation between different celestial systems. Also a number of other utility functions are included.

  • wcsgrat, for calculating parameters for WCS graticules. It does not require a plot package.

  • maputils. Provides methods for reading FITS files. It can extract 2-dim image data from data sets with three or more axes. A class is added which prepares FITS data to plot itself as an image with Matplotlib.

  • positions, enabling a user/programmer to specify positions in either pixel- or world coordinates.

  • rulers, defining a class for drawing rulers.

  • shapes, defining a class for interactively drawing shapes that define an area in an image. For each area a number of properties of the data is calculated. This module can duplicate a shape in different images using transformations to world coordinates. This enables one for instance to compare flux in two images with different WCS systems.

  • mplutil, utilities for use with Matplotlib. Classes AxesCallback, providing a more powerful mechanism for handling events from LocationEvent and derived classes than Matplotlib provides itself; TimeCallback for handling timer events and VariableColormap which implements a Matplotlib Colormap subclass with special methods that allow the colormap to be modified.

  • kmpfit, providing a class and a function for non-linear least-squares fitting, using the Levenberg-Marquardt technique. It is based on the implementation in C of Craig Markwardt’s MPFIT.

  • tabarray, providing a class for the efficient reading, writing and manipulating simple table-like structures in text files.

Prerequisites

To install the Kapteyn Package, at least Python [1] 3.5 Version 3.4 has been built for Python 3.10. Further it depends on NumPy [2], SciPy [3] and Matplotlib [6]. To process FITS files, we used PyFITS [4] but nowadays it is part of AstroPy [5] and NumPy [2] (both with header files) are required.

Windows users may also need to install Readline [7] or an equivalent package.

Mark Calabretta’s WCSLIB [8] does not need to be installed separately. Its code is now included in the Kapteyn Package under the GNU Lesser General Public License.

Download

The package can be downloaded as https://www.astro.rug.nl/software/kapteyn/kapteyn-3.4.tar.gz. This is not necessary if you install the package with pip, see next section.

An archive with all the examples and data used in the tutorials can downloaded from examples.tar.gz.

Installing

With pip

You can install the Kapteyn Package 3.4 for Python with:

pip install https://www.astro.rug.nl/software/kapteyn/kapteyn-3.4.tar.gz

If you don’t have permission to install it because you don’t have enough privileges, then try to install it as a user with:

pip install --user https://www.astro.rug.nl/software/kapteyn/kapteyn-3.4.tar.gz

It will then be installed in a folder in your home directory called .local. The location will be inserted in your Python path which can be inspected with:

In [1]: import sys

In [2]: print(sys.path)

You can uninstall the Kapteyn Package in both cases with:

pip uninstall kapteyn

Manually

The recipes below we written for the older versions of the Kapteyn Package. For the current version you should use the pip command as described in the previous section.

First unpack the downloaded .tar.gz or .zip file and go to the unpack directory. Then one of the following options can be followed:

  1. Install into your Python system (you could need root permission for this):

    python setup.py install

  2. If you prefer not to modify your Python installation, you can create a directory under which to install the module e.g., mydir. Then install as follows:

    python setup.py install --install-lib mydir

    To use the package you need to include mydir in your PYTHONPATH.

  3. GIPSY is the Groningen Image Processing System. It leans heavily on the kapteyn Package If you want to use and modify this package in the context of GIPSY, then download the tar file and untar it with tar -xvf kapteyn-3.4.tar.gz. With a proper setup of your GIPSY environment, you can install it as follows:

    pip install ./kapteyn-3.4 --upgrade --target=$gip_exe

    The GIPSY installation procedure normally does this automatically, so you will only need this if the GIPSY installation failed to install the Kapteyn Package.

Windows installer

The most convenient way to go here is to install Anaconda3 from https://www.anaconda.com/distribution/.

To build the C files, you need to install a compiler. We tried Visual studio, see: https://visualstudio.microsoft.com/vs/features/cplusplus/

It is important to at least install Windows 10 SDK (10.0.16299.0) for Desktop C++ form the visual studio build tools.

Open a so called Anaconda prompt (a terminal) and type the pip command from above to install the package:

pip install https://www.astro.rug.nl/software/kapteyn/kapteyn-3.4.tar.gz

Mac OS X Compiler problem

There is a known problem with Apple’s llvm-gcc-4.2 compiler. This compiler is known to crash with an internal compiler error (Segmentation fault: 11) when WCSLIB routine wcserr.c is compiled. For this reason, setup.py tries to detect this compiler and use the clang compiler instead. If compilation still fails, one could try to prefix a shell variable definition to the install command like this:

export CC=CLANG; python setup.py install ...

Contact

The authors can be reached at:

Kapteyn Astronomical Institute
Postbus 800
NL-9700 AV Groningen
The Netherlands
Telephone: +31 50 363 4073
E-mail: gipsy@astro.rug.nl