facet

Module that holds functions and classes related to faceting.

class lsmtool.facet.Facet(name, ra, dec, vertices, *, wcs=None)

Bases: object

Base Facet class

Parameters:

name (str) – Name of facet
ra (float or str) – RA of reference coordinate in degrees (if float) or as a string in a format supported by astropy.coordinates.Angle
dec (float or str) – Dec of reference coordinate in degrees (if float) or as a string in a format supported by astropy.coordinates.Angle
vertices (list of tuples) – List of (RA, Dec) tuples, one for each vertex of the facet
wcs (astropy.wcs.WCS, optional) – WCS object that defines the world coordinate system to use. If None, a generic WCS is used

download_panstarrs(max_search_cone_radius=0.5)

Returns a Pan-STARRS sky model for the area around the facet

Note: the resulting sky model may contain sources outside the facet’s polygon

Parameters:: max_search_cone_radius (float, optional) – The maximum radius in degrees to use in the cone search. The smaller of this radius and the minimum radius that covers the facet is used
Returns:: skymodel (LSMTool skymodel object) – The Pan-STARRS sky model

find_astrometry_offsets(comparison_skymodel=None, min_number=5)

Finds the astrometry offsets for sources in the facet

The offsets are calculated as (LOFAR model value) - (comparison model value); e.g., a positive Dec offset indicates that the LOFAR sources are on average North of the comparison source positions.

The offsets are stored in self.astrometry_diagnostics, a dict with the following keys (see LSMTool’s compare operation for details of the diagnostics):

‘meanRAOffsetDeg’, ‘stdRAOffsetDeg’, ‘meanClippedRAOffsetDeg’, ‘stdClippedRAOffsetDeg’, ‘meanDecOffsetDeg’, ‘stdDecOffsetDeg’, ‘meanClippedDecOffsetDeg’, ‘stdClippedDecOffsetDeg’

Note: if the comparison is unsuccessful, self.astrometry_diagnostics is an empty dict

Parameters:

comparison_skymodel (LSMTool skymodel object, optional) – Comparison sky model. If not given, the Pan-STARRS catalog is used
min_number (int, optional) – Minimum number of sources required for comparison

get_matplotlib_patch(wcs=None)

Returns a matplotlib patch for the facet polygon

Parameters:: wcs (WCS object, optional) – WCS object defining (RA, Dec) <-> (x, y) transformation. If not given, the facet’s transformation is used
Returns:: patch (matplotlib patch object) – The patch for the facet polygon

set_skymodel(skymodel)

Sets the facet’s sky model

The input sky model is filtered to contain only those sources that lie inside the facet’s polygon. The filtered sky model is stored in self.skymodel

Parameters:: skymodel (LSMTool skymodel object) – Input sky model

class lsmtool.facet.SquareFacet(name, ra, dec, width, *, wcs=None)

Bases: Facet

Wrapper class for a square facet

Parameters:

name (str) – Name of facet
ra (float or str) – RA of reference coordinate in degrees (if float) or as a string in a format supported by astropy.coordinates.Angle
dec (float or str) – Dec of reference coordinate in degrees (if float) or as a string in a format supported by astropy.coordinates.Angle
width (float) – Width in degrees of facet
wcs (astropy.wcs.WCS, optional) – WCS object that defines the world coordinate system to use. If None, a generic WCS is used

lsmtool.facet.filter_skymodel(polygon, skymodel, wcs, invert=False)

Filters input skymodel to select only sources that lie inside the input facet

Parameters:

polygon (Shapely polygon object) – Polygon object to use for filtering
skymodel (LSMTool skymodel object) – Input sky model to be filtered
wcs (WCS object) – WCS object defining image to sky transformations
invert (bool, optional) – If True, invert the selection (so select only sources that lie outside the facet)

Returns:

filtered_skymodel (LSMTool skymodel object) – Filtered sky model

lsmtool.facet.in_box(cal_coords, bounding_box)

Check if coordinates are inside the bounding box.

Parameters:

cal_coords (numpy.ndarray) – Array of x, y coordinates with shape (n, 2).
bounding_box (numpy.ndarray) – Array defining the bounding box as [minx, maxx, miny, maxy].

Returns:

inside (numpy.ndarray) – Boolean array with True for inside and False if not.

lsmtool.facet.is_valid_region(region, vertices, bounding_box)

Check if a Voronoi region is valid by verifying all its vertices are within the bounding box.

Parameters:

region (list of int) – Indices of the vertices forming the region.
vertices (numpy.ndarray) – Array of vertex coordinates with shape (n, 2).
bounding_box (list) – Bounding box defined as [minx, maxx, miny, maxy].

Returns:

bool – True if all vertices are inside the bounding box and the region is not empty, False otherwise.

lsmtool.facet.make_ds9_region_file( facets, outfile, enclose_names=True, associate_names_with_polygons=True, )

Make a ds9 region file for given facet polygons and centers

Parameters:

facets (list of Facet objects) – List of Facet objects to include.
outfile (str) – Name of output region file.
enclose_names (bool, optional) – If True, enclose patch names in curly brackets for full compatibility with ds9. Curly brackets may cause issues with other tools that use the region file, such as DP3, in which case they can be excluded by setting this option to False.
associate_names_with_polygons (optional) – If True, the facet names are associated with the “polygon” entries. This convention matches that used by WSClean (see https://wsclean.readthedocs.io/en/latest/ds9_facet_file.html#adding-a-text-label). If False, the names are associated with the “point” entries instead (required by some DP3 steps).

lsmtool.facet.parse_ds9_facets(region_file)

Parse facet definitions from a ds9 region file.

Each facet in the region file is defined by a polygon line that starts with ‘polygon’ and gives the (RA, Dec) vertices.

Each facet polygon line may be followed by a line giving the reference point that starts with ‘point’ and gives the reference (RA, Dec).

The facet name may be set in the text property of either line (see https://wsclean.readthedocs.io/en/latest/ds9_facet_file.html).

lsmtool.facet.parse_facet_name(lines)

Parse the facet name from the polygon / point definition string.

In the region file, the name is defined using the ‘text’ property. E.g.:: ‘polygon(3.6, 60.9, 3.4, 58.9, 3.1, 59.2) # text = {Patch_1} width = 2’ ‘point(0.1, 1.2) # text = {Patch_1} width = 2’

Note: ds9 format allows strings to be quoted with “ or ‘ or {} (see https://ds9.si.edu/doc/ref/region.html#RegionProperties), so we match everything between “”, ‘’, or {}, if the line contains anything like … # text = …

Note: if a name is defined for both the facet polygon and the facet reference point, the one for the point takes precedence.

lsmtool.facet.prepare_points_for_tessellate(cal_coords, bounding_box)

Select calibration points inside the bounding box and generates mirrored points for Voronoi tessellation.

This function filters the input coordinates to those within the bounding box and creates mirrored points to ensure proper tessellation at the boundaries.

Parameters:

cal_coords (numpy.ndarray) – Array of x, y coordinates with shape (n, 2).
bounding_box (list or numpy.ndarray) – Array defining the bounding box as [minx, maxx, miny, maxy].

Returns:

points_centre (numpy.ndarray) – Calibration points inside the bounding box.
points (numpy.ndarray) – Array of calibration points and their mirrored counterparts for tessellation.

lsmtool.facet.read_ds9_region_file(region_file, wcs=None)

Read a ds9 facet region file and return facets.

Parameters:

region_file (str) – Filename of input ds9 region file.
wcs (astropy.wcs.WCS, optional) – WCS object that defines the world coordinate system to use for the conversion to pixel coordinates. If None, a generic WCS object is created using the reference point of the facet and the default pixel scale from lsmtool.constants.WCS_PIXEL_SCALE.

Returns:

facets (list) – List of Facet objects.

lsmtool.facet.read_from_skymodel(skymodel, ra_mid, dec_mid, width_ra, width_dec, *, wcs=None)

Reads a sky model file and returns facets

Parameters:

skymodel (str) – Filename of the sky model (must have patches), in makesourcedb format
ra_mid (float) – RA in degrees of bounding box center
dec_mid (float) – Dec in degrees of bounding box center
width_ra (float) – Width of bounding box in RA in degrees, corrected to Dec = 0
width_dec (float) – Width of bounding box in Dec in degrees
wcs (astropy.wcs.WCS, optional) – The world coordinate system (WCS) object to use for the conversion between celestial and pixel coordinate systems. If None, a generic WCS object is created using the reference point of the facet and the default pixel scale from lsmtool.constants.WCS_PIXEL_SCALE.

Returns:

facets (list) – List of Facet objects

lsmtool.facet.tessellate(directions, bbox_midpoint, bbox_size, *, wcs=None)

Make a Voronoi tessellation.

This function partitions an image region using Voronoi tessellation seeded with the input calibration directions. It filters points that fall outside the given dimensions of the bounding box and returns the facet centres and polygons that enscribe these points in celestial coordinates.

Parameters:

directions (astropy.coordinates.SkyCoord) – Coordinates of input calibration directions.
bbox_midpoint (astropy.coordinates.SkyCoord) – Coordinates of bounding box centre.
bbox_size (tuple of float) – Size of bounding box (RA, Dec). Should be a 2-tuple of numbers in degrees.
wcs (astropy.wcs.WCS, optional) – WCS object that defines the world coordinate system to use. If None, a generic WCS is used

Returns:

facet_points (numpy.ndarray) – Array of facet points centres with (RA, Dec) in degrees along the columns.
facet_polys (list of numpy.ndarray) – Array of facet polygons (vertices) with (RA, Dec) in degrees along the columns (each array has shape (n, 2), where n is the number of vertices in a given facet).

lsmtool.facet.voronoi(cal_coords, bounding_box, eps=1e-06)

Produce a Voronoi tessellation for the given coordinates and bounding box.

Parameters:

cal_coords (numpy.ndarray) – Array of x, y coordinates with shape (n, 2).
bounding_box (numpy.ndarray) – Array defining the bounding box as [minx, maxx, miny, maxy].
eps (float) – Numerical tolerance value, used to expand the bounding box slightly to avoid issues related to numeric precision.

Returns:

points_centre (numpy.ndarray) – Centre points of the Voronoi cells.
vertices (numpy.ndarray) – Vertices of the Voronoi grid. To obtain the vertices of the polygon that encloses any particular point, use the indices provided in the return value filtered_regions to select the corresponding vertices for a given cell.
filtered_regions (list of list of int) – For each cell in the tesselation, a list of index points for the vertices that enclose the cell. For example vertices[filtered_regions[0]] are the vertices of the first cell. Only points that fall within the bounding_box are retained.