Core API

This page documents the reusable core table classes.

BaseTable

Bases: object

A simple wrapper around ~astropy.table.QTable.

Parameters:

Name	Type	Description	Default
table	`~astropy.table.QTable`	Core table	None

Methods:

format

format(colnames=None, units=None, formats=None, descriptions=None, ignore_missing=False)

Format table content.

Parameters:

Name	Type	Description	Default
colnames	sequence of str	Names of the columns to keep. Columns in the new table will be ordered according to this parameter.	None
units	sequence	Units to which each kept column should be converted. Items can be either ~astropy.units.Unit objects or their string representations.	None
formats	sequence of str	Format specifiers for each kept column.	None
descriptions	sequence of str	Descriptions of each kept column.	None
ignore_missing	bool	Whether to ignore the error when any key in colnames is missing from the original table (default: False). If True, a column will be added with all NaNs.	False

write

write(filename, keep_metadata=True, add_timestamp=True, **kwargs)

Write table to file.

Parameters:

Name	Type	Description	Default
filename	str	Name of the file to write to.	required
keep_metadata	bool	Whether to keep existing metadata (Default: True)	True
add_timestamp	bool	Whether to add a time stamp in the metadata (Default: True)	True
**kwargs	Any	Additional keyword arguments passed to ~astropy.table.Table.write.	{}

StatsTable

Bases: BaseTable

Table class offering tools for calculating catalog/image stats.

Methods:

find_coords_in_regions

find_coords_in_regions(ra, dec)

Find region membership for input sky coordinates.

Parameters:

Name	Type	Description	Default
ra	array_like	R.A. of the coordinates in question	required
dec	array_like	Declination of the coordinates in question	required

Returns:

Type	Description
ndarray	A boolean array indicating whether each region contains each input coordinate. The shape of this array is: (n_coordinate, n_region).

calc_catalog_stats

calc_catalog_stats(entry, ra, dec, stat_func=None, weight=None, colname='new_col', unit='', **kwargs)

Calculate statistics of a catalog entry within each region.

"Catalog" in this context means a table recording both the (ra, dec) coordinates and other properties of a list of identified objects on the sky. Typical examples: molecular cloud catalogs, HII region catalogs, stellar cluster catalogs.

An example catalog entry: the "molecular cloud size" column in a cloud catalog.

Parameters:

Name	Type	Description	Default
entry	array_like	The catalog entry in question.	required
ra	array_like	RA coordinates of the listed objects.	required
dec	array_like	Dec coordinates of the listed objects.	required
stat_func	callable	A function that accepts an array of values and returns a scalar value (which is the calculated statistics). If 'weight' is not None, this function should also accept a keyword named 'weights', which specifies the statistical weight of each value in the array.	None
weight	array_like	If not None, this keyword should be an ndarray specifying the statistical weight of each row in the catalog. Note that in this case, the broadcasted weight array will be passed to 'stat_func' in a keyword named 'weights'.	None
colname	str	Name of a column in the table to save the output values. Default: 'new_col'	'new_col'
unit	str or `~astropy.units.UnitBase`	Physical unit of the output values (default='').	''
**kwargs	Any	Additional keyword arguments passed to stat_func.	{}

calc_image_stats

calc_image_stats(image, ihdu=0, header=None, stat_func=None, weight=None, colname='new_col', unit='', suppress_error=False, **kwargs)

Calculate statistics of an image within each region.

Parameters:

Name	Type	Description	Default
image	str, bytes, path-like, `~astropy.io.fits.HDUList`,	FITS HDU, or ndarray The image to calculate statistics for.	required
ihdu	int	If 'image' is a str or an HDUList, this keyword should specify which HDU (extension) to use (default=0)	0
header	`~astropy.io.fits.Header`	If 'image' is an ndarray, this keyword should be a FITS header providing the WCS information.	None
stat_func	callable	A function that accepts an array of values, and return a scalar value (which is the calculated statistics). If 'weight' is not None, this function should also accept a keyword named 'weights', which specifies the statistical weight of each value in the array.	None
weight	array_like	If not None, this keyword should be an ndarray specifying the statistical weight of each pixel in the input image. Note that in this case, the broadcasted weight array will be passed to 'stat_func' in a keyword named 'weights'.	None
colname	str	Name of a column in the table to save the output values. Default: 'new_col'	'new_col'
unit	str or `~astropy.units.UnitBase`	Physical unit of the output values (default=''). If unit='header', the 'BUNIT' entry in the header is used.	''
suppress_error	bool	Whether to suppress the error message if 'image' looks like a file but is not found on disk (default=False)	False
**kwargs	Any	Additional keyword arguments passed to stat_func.	{}

create_maps_from_columns

create_maps_from_columns(colnames, header, allow_region_overlap=False)

Create 2D maps from data in columns based on a FITS header.

Parameters:

Name	Type	Description	Default
colnames	sequence of str	Name of the columns to create 2D maps for.	required
header	`~astropy.fits.Header`	FITS header defining the WCS of the output 2D maps.	required
allow_region_overlap	bool	If False (default), an error will be raised when regions overlap (i.e., if any pixel belongs in multiple regions). If True, overlapping regions will be allowed, in which case later rows (regions) will overwrite earlier rows.	False

Returns:

Type	Description
list	List of two-dimensional arrays or quantity arrays built from the requested columns.

format

format(colnames=None, units=None, formats=None, descriptions=None, ignore_missing=False)

Format table content.

Parameters:

Name	Type	Description	Default
colnames	sequence of str	Names of the columns to keep. Columns in the new table will be ordered according to this parameter.	None
units	sequence	Units to which each kept column should be converted. Items can be either ~astropy.units.Unit objects or their string representations.	None
formats	sequence of str	Format specifiers for each kept column.	None
descriptions	sequence of str	Descriptions of each kept column.	None
ignore_missing	bool	Whether to ignore the error when any key in colnames is missing from the original table (default: False). If True, a column will be added with all NaNs.	False

write

write(filename, keep_metadata=True, add_timestamp=True, **kwargs)

Write table to file.

Parameters:

Name	Type	Description	Default
filename	str	Name of the file to write to.	required
keep_metadata	bool	Whether to keep existing metadata (Default: True)	True
add_timestamp	bool	Whether to add a time stamp in the metadata (Default: True)	True
**kwargs	Any	Additional keyword arguments passed to ~astropy.table.Table.write.	{}

GeneralRegionTable

Bases: StatsTable

Table build from a set of user-defined regions on the sky.

Each region corresponds to a row in the table. Once a table is constructed, additional columns can be added by calculating statistics of images within each region.

Note that the regions can overlap with each other.

Parameters:

Name	Type	Description	Default
region_defs	a list of FITS HDU objects and/or functions	This parameter defines the sky regions that comprise the table, with each element in the list corresponds to a region. - If that element is an HDU object, it should contain a bitmap that defines the corresponding region (1=in, 0=out). - If that element is a function object, it should take an RA array and a DEC array as the only input parameters, and return a boolean array specifying whether these coordinates are in the region.	required
names	list of str	A list of names to be included as the 1st column in the table (should be concise and suffice to identify the regions).	None

Methods:

find_coords_in_regions

find_coords_in_regions(ra, dec)

Evaluate region membership for each input coordinate.

Parameters:

Name	Type	Description	Default
ra	array_like	R.A. of the coordinates in question	required
dec	array_like	Declination of the coordinates in question	required

Returns:

Type	Description
ndarray	A boolean array indicating whether each region contains each input coordinate. The shape of this array is: (n_coordinate, n_region).

format

format(colnames=None, units=None, formats=None, descriptions=None, ignore_missing=False)

Format table content.

Parameters:

Name	Type	Description	Default
colnames	sequence of str	Names of the columns to keep. Columns in the new table will be ordered according to this parameter.	None
units	sequence	Units to which each kept column should be converted. Items can be either ~astropy.units.Unit objects or their string representations.	None
formats	sequence of str	Format specifiers for each kept column.	None
descriptions	sequence of str	Descriptions of each kept column.	None
ignore_missing	bool	Whether to ignore the error when any key in colnames is missing from the original table (default: False). If True, a column will be added with all NaNs.	False

write

write(filename, keep_metadata=True, add_timestamp=True, **kwargs)

Write table to file.

Parameters:

Name	Type	Description	Default
filename	str	Name of the file to write to.	required
keep_metadata	bool	Whether to keep existing metadata (Default: True)	True
add_timestamp	bool	Whether to add a time stamp in the metadata (Default: True)	True
**kwargs	Any	Additional keyword arguments passed to ~astropy.table.Table.write.	{}

calc_catalog_stats

calc_catalog_stats(entry, ra, dec, stat_func=None, weight=None, colname='new_col', unit='', **kwargs)

Calculate statistics of a catalog entry within each region.

"Catalog" in this context means a table recording both the (ra, dec) coordinates and other properties of a list of identified objects on the sky. Typical examples: molecular cloud catalogs, HII region catalogs, stellar cluster catalogs.

An example catalog entry: the "molecular cloud size" column in a cloud catalog.

Parameters:

Name	Type	Description	Default
entry	array_like	The catalog entry in question.	required
ra	array_like	RA coordinates of the listed objects.	required
dec	array_like	Dec coordinates of the listed objects.	required
stat_func	callable	A function that accepts an array of values and returns a scalar value (which is the calculated statistics). If 'weight' is not None, this function should also accept a keyword named 'weights', which specifies the statistical weight of each value in the array.	None
weight	array_like	If not None, this keyword should be an ndarray specifying the statistical weight of each row in the catalog. Note that in this case, the broadcasted weight array will be passed to 'stat_func' in a keyword named 'weights'.	None
colname	str	Name of a column in the table to save the output values. Default: 'new_col'	'new_col'
unit	str or `~astropy.units.UnitBase`	Physical unit of the output values (default='').	''
**kwargs	Any	Additional keyword arguments passed to stat_func.	{}

calc_image_stats

calc_image_stats(image, ihdu=0, header=None, stat_func=None, weight=None, colname='new_col', unit='', suppress_error=False, **kwargs)

Calculate statistics of an image within each region.

Parameters:

Name	Type	Description	Default
image	str, bytes, path-like, `~astropy.io.fits.HDUList`,	FITS HDU, or ndarray The image to calculate statistics for.	required
ihdu	int	If 'image' is a str or an HDUList, this keyword should specify which HDU (extension) to use (default=0)	0
header	`~astropy.io.fits.Header`	If 'image' is an ndarray, this keyword should be a FITS header providing the WCS information.	None
stat_func	callable	A function that accepts an array of values, and return a scalar value (which is the calculated statistics). If 'weight' is not None, this function should also accept a keyword named 'weights', which specifies the statistical weight of each value in the array.	None
weight	array_like	If not None, this keyword should be an ndarray specifying the statistical weight of each pixel in the input image. Note that in this case, the broadcasted weight array will be passed to 'stat_func' in a keyword named 'weights'.	None
colname	str	Name of a column in the table to save the output values. Default: 'new_col'	'new_col'
unit	str or `~astropy.units.UnitBase`	Physical unit of the output values (default=''). If unit='header', the 'BUNIT' entry in the header is used.	''
suppress_error	bool	Whether to suppress the error message if 'image' looks like a file but is not found on disk (default=False)	False
**kwargs	Any	Additional keyword arguments passed to stat_func.	{}

create_maps_from_columns

create_maps_from_columns(colnames, header, allow_region_overlap=False)

Create 2D maps from data in columns based on a FITS header.

Parameters:

Name	Type	Description	Default
colnames	sequence of str	Name of the columns to create 2D maps for.	required
header	`~astropy.fits.Header`	FITS header defining the WCS of the output 2D maps.	required
allow_region_overlap	bool	If False (default), an error will be raised when regions overlap (i.e., if any pixel belongs in multiple regions). If True, overlapping regions will be allowed, in which case later rows (regions) will overwrite earlier rows.	False

Returns:

Type	Description
list	List of two-dimensional arrays or quantity arrays built from the requested columns.

VoronoiTessTable

Bases: StatsTable

Table built from a Voronoi tessellation of (a part of) the sky.

Each seed/tile in the Voronoi diagram maps to a row in the table. Once a table is constructed, additional columns can be added by calculating statistics of images within each Voronoi tile, or by resampling images at the location of each seed.

Angular separations are calculated with small angle approximation.

Parameters:

Name	Type	Description	Default
center_ra	float	Right Ascension of the FoV center (in degrees)	required
center_dec	float	Declination of the FoV center (in degrees)	required
fov_radius	float	Radius of the FoV to cover with the tessellation (in degrees)	required
seeds_ra	array_like	Right Ascension of user-defined seed locations (in degrees)	None
seeds_dec	array_like	Declination of user-defined seed locations (in degrees)	None
seed_spacing	float	If the seed locations are to be automatically generated, this keyword specifies the spacing between adjacent seeds (in degrees).	None
tile_shape	(square, hexagon)	If the seed locations are to be automatically generated, this keyword specifies the shape of the Voronoi tile. Default: 'square', in which case the Voronoi diagram comprises regularly spaced square tiles.	'square'

Methods:

find_coords_in_regions

find_coords_in_regions(ra, dec, fill_value=-1)

Match coordinates to the nearest Voronoi tile.

Parameters:

Name	Type	Description	Default
ra	array_like	R.A. of the coordinates in question	required
dec	array_like	Declination of the coordinates in question	required
fill_value	int	The index value to return for input coordinates that have no matched regions (default: -1).	-1

Returns:

Type	Description
ndarray	An index array indicating which tile each input coordinate belongs to. The length of this array equals the number of input coordinates.

resample_image

resample_image(image, ihdu=0, header=None, colname='new_col', unit='', suppress_error=False, fill_outside='nearest')

Resample an image at the location of the Voronoi seeds.

The resampling is done by finding the nearest pixel to the location of each seed in the image.

Parameters:

Name	Type	Description	Default
image	str, bytes, path-like, `~astropy.io.fits.HDUList`,	FITS HDU, or ndarray The image to be resampled.	required
ihdu	int	If 'image' is a str or an HDUList, this keyword should specify which HDU (extension) to use (default=0)	0
header	`~astropy.io.fits.Header`	If 'image' is an ndarray, this keyword should be a FITS header providing the WCS information.	None
colname	str	Name of a column in the table to save the output values. Default: 'new_col'	'new_col'
unit	str or `~astropy.units.UnitBase`	Physical unit of the output values (default=''). If unit='header', the 'BUNIT' entry in the header is used.	''
fill_outside	(nearest, float)	The behavior outside the footprint of the input image. If fill_outside='nearest', all seeds outside the footprint are assigned the value of the nearest pixel in the image. Otherwise, all seeds outside the image footprint are assigned the value of this keyword.	'nearest'
suppress_error	bool	Whether to suppress the error message if 'image' looks like a file but is not found on disk (default=False)	False

format

format(colnames=None, units=None, formats=None, descriptions=None, ignore_missing=False)

Format table content.

Parameters:

Name	Type	Description	Default
colnames	sequence of str	Names of the columns to keep. Columns in the new table will be ordered according to this parameter.	None
units	sequence	Units to which each kept column should be converted. Items can be either ~astropy.units.Unit objects or their string representations.	None
formats	sequence of str	Format specifiers for each kept column.	None
descriptions	sequence of str	Descriptions of each kept column.	None
ignore_missing	bool	Whether to ignore the error when any key in colnames is missing from the original table (default: False). If True, a column will be added with all NaNs.	False

write

write(filename, keep_metadata=True, add_timestamp=True, **kwargs)

Write table to file.

Parameters:

Name	Type	Description	Default
filename	str	Name of the file to write to.	required
keep_metadata	bool	Whether to keep existing metadata (Default: True)	True
add_timestamp	bool	Whether to add a time stamp in the metadata (Default: True)	True
**kwargs	Any	Additional keyword arguments passed to ~astropy.table.Table.write.	{}

calc_catalog_stats

calc_catalog_stats(entry, ra, dec, stat_func=None, weight=None, colname='new_col', unit='', **kwargs)

Calculate statistics of a catalog entry within each region.

"Catalog" in this context means a table recording both the (ra, dec) coordinates and other properties of a list of identified objects on the sky. Typical examples: molecular cloud catalogs, HII region catalogs, stellar cluster catalogs.

An example catalog entry: the "molecular cloud size" column in a cloud catalog.

Parameters:

Name	Type	Description	Default
entry	array_like	The catalog entry in question.	required
ra	array_like	RA coordinates of the listed objects.	required
dec	array_like	Dec coordinates of the listed objects.	required
stat_func	callable	A function that accepts an array of values and returns a scalar value (which is the calculated statistics). If 'weight' is not None, this function should also accept a keyword named 'weights', which specifies the statistical weight of each value in the array.	None
weight	array_like	If not None, this keyword should be an ndarray specifying the statistical weight of each row in the catalog. Note that in this case, the broadcasted weight array will be passed to 'stat_func' in a keyword named 'weights'.	None
colname	str	Name of a column in the table to save the output values. Default: 'new_col'	'new_col'
unit	str or `~astropy.units.UnitBase`	Physical unit of the output values (default='').	''
**kwargs	Any	Additional keyword arguments passed to stat_func.	{}

calc_image_stats

calc_image_stats(image, ihdu=0, header=None, stat_func=None, weight=None, colname='new_col', unit='', suppress_error=False, **kwargs)

Calculate statistics of an image within each region.

Parameters:

Name	Type	Description	Default
image	str, bytes, path-like, `~astropy.io.fits.HDUList`,	FITS HDU, or ndarray The image to calculate statistics for.	required
ihdu	int	If 'image' is a str or an HDUList, this keyword should specify which HDU (extension) to use (default=0)	0
header	`~astropy.io.fits.Header`	If 'image' is an ndarray, this keyword should be a FITS header providing the WCS information.	None
stat_func	callable	A function that accepts an array of values, and return a scalar value (which is the calculated statistics). If 'weight' is not None, this function should also accept a keyword named 'weights', which specifies the statistical weight of each value in the array.	None
weight	array_like	If not None, this keyword should be an ndarray specifying the statistical weight of each pixel in the input image. Note that in this case, the broadcasted weight array will be passed to 'stat_func' in a keyword named 'weights'.	None
colname	str	Name of a column in the table to save the output values. Default: 'new_col'	'new_col'
unit	str or `~astropy.units.UnitBase`	Physical unit of the output values (default=''). If unit='header', the 'BUNIT' entry in the header is used.	''
suppress_error	bool	Whether to suppress the error message if 'image' looks like a file but is not found on disk (default=False)	False
**kwargs	Any	Additional keyword arguments passed to stat_func.	{}

create_maps_from_columns

create_maps_from_columns(colnames, header, allow_region_overlap=False)

Create 2D maps from data in columns based on a FITS header.

Parameters:

Name	Type	Description	Default
colnames	sequence of str	Name of the columns to create 2D maps for.	required
header	`~astropy.fits.Header`	FITS header defining the WCS of the output 2D maps.	required
allow_region_overlap	bool	If False (default), an error will be raised when regions overlap (i.e., if any pixel belongs in multiple regions). If True, overlapping regions will be allowed, in which case later rows (regions) will overwrite earlier rows.	False

Returns:

Type	Description
list	List of two-dimensional arrays or quantity arrays built from the requested columns.