Reading in Files¶

Input handlers govern how the observational data is read in. This includes both images and catalogs. The class InputFiles is the default, so if you are using that (which is typical), you can omit the :type: specification.

class piff.Input[source]¶

The base class for handling inputs for building a Piff model.

This is essentially an abstract base class intended to define the methods that should be implemented by any derived class.

getPointing(logger=None)[source]¶

Get the pointing coordinate of the (noinal) center of the field of view.

Parameters: logger – A logger object for logging debug info. [default: None]
Returns: a galsim.CelestialCoord of the pointing direction.

getWCS(logger=None)[source]¶

Get the WCS solutions for all the chips in the field of view.

Parameters: logger – A logger object for logging debug info. [default: None]
Returns: a dict of WCS solutions (galsim.BaseWCS instances) indexed by chipnum

makeStars(logger=None)[source]¶

Process the input images and star data, cutting out stamps for each star along with other relevant information.

The base class implementation expects the derived class to have appropriately set the following attributes:

stamp_size

The size of the postage stamp to use for the cutouts

x_col

The name of the column in the catalogs to use for the x position.

y_col

The name of the column in the catalogs to use for the y position.

Parameters: logger – A logger object for logging debug info. [default: None]
Returns: a list of Star instances

classmethod process(config_input, logger=None)[source]¶

Parse the input field of the config dict.

Parameters

config_input – The configuration dict.
logger – A logger object for logging debug info. [default: None]

Returns

stars, wcs, pointing

stars is a list of Star instances with the initial data. wcs is a dict of WCS solutions indexed by chipnum. pointing is either a galsim.CelestialCoord or None.

class piff.InputFiles(config, logger=None)[source]¶

An Input handler that just takes a list of image files and catalog files.

Parse the input config dict (Normally the ‘input’ field in the overall configuration dict).

The two required fields in the input dict are:

image_file_name

The file name(s) of the input image(s).

cat_file_name

The file name(s) of the input catalog(s).

There are a number of ways to specify these file names.

A string giving a single file name. e.g.:

image_file_name: image.fits
cat_file_name: input_cat.fits

A list of several file names. e.g.:

image_file_name: [image_00.fits, image_01.fits, image_02.fits]
cat_file_name: [input_cat_00.fits, input_cat_01.fits, input_cat_02.fits]

A string that glob can recognize to list several file names. e.g.:
```
image_file_name: image_*.fits
cat_file_name: input_cat_*.fits
```

A dict parseable as a string value according to the GalSim configuration parsing types. In this case, you also must specify nimages to say how many file names to generate in this way. e.g.:

    nimages: 20
    image_file_name:
        type: FormattedStr
        format: image_%03d_%02d.fits.fz
        items:
            - { type : Sequence, first: 0, repeat: 4 }  # Exposure number
            - { type : Sequence, first: 1, last: 4 }    # Chip number
    cat_file_name:
        type: Eval
        str: "image_file_name.replace('image','input_cat')"
        simage_file_name: '@input.image_file_name'

See the description of the GalSim config parser for more details about the various
types that are valid here.

    `https://github.com/GalSim-developers/GalSim/wiki/Config-Values`_

There are many other optional parameters, which help govern how the input files are read or interpreted:

chipnum

The id number of this chip used to reference this image [default: image_num]

image_hdu

The hdu to use in the image files. [default: None, which means use either 0 or 1 as typical given the compression sceme of the file]

weight_hdu

The hdu to use for weight images. [default: None, which means a weight image with all 1’s will be automatically created]

badpix_hdu

The hdu to use for badpix images. Pixels with badpix != 0 will be given weight == 0. [default: None]

noise

Rather than a weight image, provide the noise variance in the image. (Useful for simulations where this is a known value.) [default: None]

cat_hdu

The hdu to use in the catalog files. [default: 1]

x_col

The name of the X column in the input catalogs. [default: ‘x’]

y_col

The name of the Y column in the input catalogs. [default: ‘y’]

ra_col

(Alternative to x_col, y_col) The name of a right ascension column in the input catalogs. Will use the WCS to find (x,y) [default: None]

dec_col

(Alternative to x_col, y_col) The name of a declination column in the input catalogs. Will use the WCS to find (x,y) [default: None]

flag_col

The name of a flag column in the input catalogs. [default: None] By default, this will skip any objects with flag != 0, but see skip_flag and use_flag for other possible meanings for how the flag column can be used to select stars.

skip_flag

The flag indicating which items to not use. [default: -1] Items with flag & skip_flag != 0 will be skipped.

use_flag

The flag indicating which items to use. [default: None] Items with flag & use_flag == 0 will be skipped.

property_cols

A list of column names of star properties (e.g. star colors). [default: None]

sky_col

The name of a column with sky values. [default: None]

gain_col

The name of a column with gain values. [default: None]

sky

The sky level to subtract from the image values. [default: None] Note: It is an error to specify both sky and sky_col. If both are None, no sky level will be subtracted off.

gain

The gain to use for adding Poisson noise to the weight map. [default: None] It is an error for both gain and gain_col to be specified. If both are None, then no additional noise will be added to account for the Poisson noise from the galaxy flux.

satur

The staturation level. If any pixels for a star exceed this, then the star is skipped. [default: None]

use_partial

Whether to use stars whose postage stamps are only partially on the full image. [default: False]

nstars

Stop reading the input file at this many stars. (This is applied separately to each input catalog.) [default: None]

nproc

How many multiprocessing processes to use for reading in data from multiple files at once. [default: 1]

wcs

Normally, the wcs is automatically read in when reading the image. However, this parameter allows you to optionally provide a different WCS. It should be defined using the same style as a wcs object in GalSim config files. [defulat: None]

The above values are parsed separately for each input image/catalog. In addition, there are a couple other parameters that are just parsed once:

stamp_size

The size of the postage stamps to use for the cutouts. Note: some stamps may be smaller than this if the star is near a chip boundary. [default: 32]

ra, dec

The RA, Dec of the telescope pointing. [default: None; See setPointing for details about how this can be specified]

Parameters

config – The configuration dict used to define the above parameters.
logger – A logger object for logging debug info. [default: None]

load_images(stars, logger=None)[source]¶

Load the image data into a list of Stars.

We don’t store the image data for Stars when we write them to a file, since that would take up a lot of space and is usually not desired. However, we do store the bounds in the original image where the star was cutout, so if you want to load back in the original data from the image file(s), you can do so with this function.

Parameters

stars – A list of Star instances.
logger – A logger object for logging debug info. [default: None]

Returns

a new list of Stars with the images information loaded.

static readImage(image_file_name, image_hdu, weight_hdu, badpix_hdu, sky_file_name, sky_hdu, noise, logger)[source]¶

Read in the image and weight map (or make one if no weight information is given

Parameters

image_file_name – The name of the file to read.
image_hdu – The hdu of the main image.
weight_hdu – The hdu of the weight image (if any).
badpix_hdu – The hdu of the bad pixel mask (if any).
sky_file_name – A file to use for a sky background to subtract from the image (if any).
sky_hdu – The hdu to use in the sky_file_name (if any).
noise – A constant noise value to use in lieu of a weight map.
logger – A logger object for logging debug info.

Returns

image, weight

static readStarCatalog(cat_file_name, cat_hdu, x_col, y_col, ra_col, dec_col, ra_units, dec_units, image, flag_col, skip_flag, use_flag, property_cols, sky_col, gain_col, sky, gain, satur, nstars, image_file_name, stamp_size, logger)[source]¶

Read in the star catalogs and return lists of positions for each star in each image.

Parameters

cat_file_name – The name of the catalog file to read in.
cat_hdu – The hdu to use.
x_col – The name of the column with x values.
y_col – The name of the column with y values.
ra_col – The name of a column with RA values.
dec_col – The name of a column with Dec values.
ra_units – The units of the ra column.
dec_units – The units of the dec column.
image – The image that was already read in (mostly for the wcs).
flag_col – The name of a column with flag values.
skip_flag – The flag indicating which items to not use. [default: -1] Items with flag & skip_flag != 0 will be skipped.
use_flag – The flag indicating which items to use. [default: None] Items with flag & use_flag == 0 will be skipped.
property_cols – A list of column names with star properties (e.g. star colors).
sky_col – A column with sky (background) levels.
gain_col – A column with gain values.
sky – Either a float value for the sky to use for all objects or a str keyword to read a value from the FITS header.
gain – Either a float value for the gain to use for all objects or a str keyword to read a value from the FITS header.
satur – Either a float value for the saturation level to use or a str keyword to read a value from the FITS header.
nstars – Optionally a maximum number of stars to use.
image_file_name – The image file name in case needed for header values.
stamp_size – The stamp size being used for the star stamps.
logger – A logger object for logging debug info. [default: None]

Returns

lists image_pos, extra_props

setPointing(ra, dec, logger=None)[source]¶

Set the pointing attribute based on the input ra, dec (given in the initializer)

There are a number of ways the pointing can be specified. Even this is probably not sufficiently generic for all applications, but it’s a start.

numerical values (in Hours, Degrees respective) for ra, dec
hh:mm:ss.ssss, dd:mm:ss.ssss strings giving hours/degrees, minutes, seconds for each
FITS header key words to read to get the ra, dec values
None, which will attempt to find the spatial center of all the input images using the midpoint of the min/max ra and dec values of the image corners according to their individual WCS functions. [Not implemented currently.]