Some conventions for structuring your code#

How to use libraries or modules in Python#

In Python, a library (or module) offers a set of definitions (constants, variables, functions, classes) that can be used from your code. The definitions are available as soon as an import statement is inserted into your code:

import some_module

where some_module is the name of a module implemented inside the python file named some_module.py available either in the current directory or in a directory specified in the PYTHONPATH environment variable.

Once the import statement is provided in your code, all definitions of this module are available and can be referenced and used using the following syntax:

import some_module
...
x = some_module.some_function()
...
y = some_module.some_variable
...

For more details of the Python modules, have a look at this notebook.

Utility modules provided for the course#

Some functions or features are considered either too complex to be mastered during the duration of this course, out of scope for the course, or offer no pedagogical value. For this reason, a few modules are provided in your base environment that you will use to develop your applications. These modules are put in npac directory; they are described below.

args.py#

When running the applications you will develop for this course, you are generally expected to provide the image file name on the command line, or to type it interactively at the beginning of the execution. The module args.py do this for you. Its only function get_file_name() check the command line for a file name, and if it founds none it will ask it interactively:

from npac import args
...
file_name = args.get_file_name()

This has to be inserted at the very begining of your application. The file name suffix must be .fits if specified explicitly, but can be ommited. If no directory is specified, the file is looked for in the ../data directory. When the argument is ommitted, it defaults to ../data/specific.fits in batch mode or the file name to use is prompted in interactive mode.

coordinates.py ++++++++++****

This module provides the way to convert image (x, y) coordinates to/from space coordinates (RA, DEC). The transformation matrix is obtained from the FITS header of the analyzed file. Two specialized classes PixelXY and RaDec allow to declare variables in either coordinate systems.

from npac import coordinates
...
wcs = coordinates.get_wcs(header)

The coordinates.get_wcs() function returns the transformation matrix from the header block of a FITS file previously read (see next conversion functions to get usage of the wcs returned value)

x, y = coordinates.PixelXY(1.0, 2.0)
ra, dec = coordinates.RaDec(1.0, 2.0)

Those two classes permits to construct specialized objects (actually they are namedtuples). Be careful that those classes have only non-mutable attributes. Therefore, (x, y) or (ra, dec) attributes can only be entered at creation time. Attributes can be read (using the ``object.x`` notation)

ra, dec = coordinates.xy_to_radec(wcs, coordinates.PixelXY(1.0, 2.0))
x, y = coordinates.radec_to_xy(wcs, coordinates.RaDec(1.0, 2.0))

Those 2 functions convert coordinates expressed as PixelXY or RaDec objects using the wcs matrix transformation.

stars.py#

This module queries the Simbad web-service against one region of the sky, centered at a given (ra, dec) coordinates, and inside a circular extension of a given radius (given in degree)

from npac import coordinates
from npac import stars

radec = coordinates.RaDec(1.0, 2.0)

objects, out, req = stars.get_celestial_objects(radec, radius)

  • objects is a dictionary of celestial objects found, if any, found in standard catalogues at this position within the acceptance extension.

  • out is the raw answer from Simbad (only for debugging purposes)

  • req is the raw request sent to Simbad (only for debugging purposes)

The objects dictionary is keyed with the object names, and entries contain the object types.

Conventions for your own modules#

While you develop code for the various exercises (and for projects) it’s useful to follow general naming conventions. Although those conventions are not mandatory, we recommend to follow them for two reasons:

  • for us, to ease comparison of the various solutions provided by different students

  • for students, to ease the evolution from exercise to exercise, enforcing the possibility to reuse the code.

The 5 exercises form a coherent set of features, based on a progression in the complexity and the concepts, where the resolution of each exercise is needed for the next one.

Therefore it’s largely recommended to define at least one function per exercise, and to move this function into a dedicated module. In the documentation, we suggest some naming conventions for those functions or definitions (eg. classes) that you might have to implement for the 5 exercises.

For the projects, instead, you are responsible both for the design and the implementation. Therefore, we don’t suggest any naming convention. However, the modules implemented for the exercises will be a natural use for the projects.