enyo.etc.aperture module¶

Define apertures to use for on-sky integrations.

#.. _pypi https://pypi.org/project/sdss-mangadap/

class enyo.etc.aperture.Aperture(shape)[source]¶

Bases: object

Abstract class for a general aperture shape.

Parameters:	shape (shapely.geometry.base.BaseGeometry) – A shape object from the Shapely python package.

_overlapping_grid_polygons(x, y)[source]¶

Construct a list of grid-cell polygons (rectangles) that are expected to overlap the aperture.

The list of polygons follows array index order. I.e., polygon \(k\) is the cell at location \((j,i)\), where:

.. math::

j = k//nx i = k - j*nx

Parameters:

x (array-like) – The list of x coordinates for the grid. Must be linearly spaced.
y (array-like) – The list of y coordinates for the grid. Must be linearly spaced.

Returns:

Five objects are returned:

A list of shapely.geometry.polygon.Polygon objects, one per grid cell. Only those grid cells that are expected to overlap the shape’s bounding box are included.

The starting and ending x index and the starting and ending y index for the returned list of cell polygons.

Return type:

tuple

_overlapping_region(x, y)[source]¶

Return the starting and ending indices of the grid cells that overlap with the shape bounds.

Parameters:	x (array-like) – The list of x coordinates for the grid. Must be linearly spaced. y (array-like) – The list of y coordinates for the grid. Must be linearly spaced.
Returns:	Returns six scalars: the starting and ending x index, the grid step in x, the starting and ending y index, and the grid step in y for the region of the grid that overlaps the shape boundary.
Return type:	`tuple`

area¶: The area of the aperture.

bounds¶: The bounding box of the aperture.

integrate_over_source(source, response_method='fractional', sampling=None, size=None)[source]¶

Integrate the flux of a source over the aperture.

This is done by generating an image of the aperture over the map of the source surface-brightness distribution, using Aperture.response(). The source is expected to already have been mapped using its make_map function, or one should provide sampling and size values to construct the map inside this function.

Todo

No type checking is done to require that source is a Source object, but the code will barf if it isn’t.

Parameters:	source (`Source`) – Source surface-brightness distribution response_method (`str`, optional) – See `method` argument for `Aperture.response()`. sampling (`float`, optional) – Sampling of the square map in arcsec/pixel. If not None, the source map is (re)constructed. size (`float`, optional) – Size of the square map in arcsec. If not None, the source map is (re)constructed.
Returns:	The integral of the source over the aperture.
Return type:	`float`
Raises:	`ValueError` – Raised if the source map has not been constructed and `sampling` and `size` are both None.

map_integral_over_source(source, response_method='fractional', sampling=None, size=None)[source]¶

Construct a continuous map of the source integrated over the aperture.

This is done by generating an image of the aperture over the map of the source surface-brightness distribution, using Aperture.response(). The integral of the source over the aperture at any offset position within the map is calculated by convolving the the source distribution and the aperture image.

See also Aperture.integrate_over_source(). A single call to this function or Aperture.integrate_over_source() to get the integral with no offset of the aperture are marginally different. However, use of this function is much more efficient if you want to calculate the integral of the source over many positional offsets of the aperture.

Todo

No type checking is done to require that source is a Source object, but the code will barf if it isn’t.

Parameters:

source (Source) – Source surface-brightness distribution
response_method (str, optional) – See method argument for Aperture.response().
sampling (float, optional) – Sampling of the square map in arcsec/pixel. If not None, the source map is (re)constructed.
size (float, optional) – Size of the square map in arcsec. If not None, the source map is (re)constructed.

Returns:

The integral of the source over the aperture with the aperture centered at any position in the map. The integral with no offset between the image of the aperture and the image of the source is:

cy = source.data.shape[0]//2
cx = source.data.shape[1]//2
integral = Aperture.map_integral_over_source(source)[cy,cx]

which should be identical to:

integral = Aperture.integrate_over_source(source)

Return type:

numpy.ndarray

response(x, y, method='fractional')[source]¶

Compute the response function of the aperture to the sky over a regular grid. This is the same as rendering an “image” of the aperture.

The integral of the returned map is normalized to the aperture area.

Parameters:	x (array-like) – The list of x coordinates for the grid. Must be linearly spaced. y (array-like) – The list of y coordinates for the grid. Must be linearly spaced. method (`str`, optional) – Method used to construct the overlap grid. Options are: ’whole’: Any grid cell with its center inside the aperture is set to the area of the grid cell. All others set to 0. ’fractional’: Perform the detailed calculation of the fraction of each grid-cell within the aperture.
Returns:	An array with shape \((N_x, N_y)\) with the fraction of each grid cell covered by the aperture.
Return type:	numpy.ndarray
Raises:	`ValueError` – Raised if the provided arguments are not regularly spaced, or if there aren’t at least 2 grid points in each dimension.

vertices(wrap=False)[source]¶

class enyo.etc.aperture.FiberAperture(cx, cy, d, resolution=None)[source]¶

Bases: enyo.etc.aperture.Aperture

Define a fiber aperture.

Note that the units for the center and diameter are only relevant in the application of the aperture to a source. They should typically be in arcseconds, with the center being relative to the source to observe.

Parameters:

cx (scalar-like) – Center X coordinate, typically 0.
cy (scalar-like) – Center Y coordinate, typically 0.
d (scalar-like) – Fiber diameter. Aperture is assumed to be a circle resolved by a set of line segments.
resolution (int, optional) – Set the “resolution” of the circle. Higher numbers mean more line segments are used to define the circle, but there isn’t a 1-1 correspondence. See shapely.buffer. Default is to use the shapely default.

center¶

Center x and y coordinate.

Type:	`list`

diameter¶

Fiber diameter

Type:	`float`

class enyo.etc.aperture.SlitAperture(cx, cy, width, length, rotation=0.0)[source]¶

Bases: enyo.etc.aperture.Aperture

Define a slit aperture.

The orientation of the slit is expected to have the length along the y axis and the width along the x axis. The rotation is counter-clockwise in a right-handed Cartesian frame.

Note that the units for the center, width, and length are only relevant in the application of the aperture to a source. They should typically be in arcseconds, with the center being relative to the source to observe.

Exactly the same aperture is obtained in the following two calls:

s = SlitAperture(0., 0., 1, 10)
ss = SlitAperture(0., 0., 10, 1, rotation=90)

Parameters:	cx (scalar-like) – Center X coordinate, typically 0. cy (scalar-like) – Center Y coordinate, typically 0. width (scalar-like) – Slit width along the unrotated x axis. length (scalar-like) – Slit length along the unrotated y axis. rotation (scalar-like) – Cartesian rotation of the slit in degrees.

center¶

Center x and y coordinate.

Type:	`list`

width¶

Slit width

Type:	`float`

length¶

Slit length

Type:	`float`

rotation¶

Slit rotation (deg)

Type:	`float`

enyo.etc.aperture.point_inside_polygon(polygon, point)[source]¶

Determine if one or more points is inside the provided polygon.

Primarily a wrapper for polygon_winding_number(), that returns True for each poing that is inside the polygon.

Parameters:	polygon (numpy.ndarray) – An Nx2 array containing the x,y coordinates of a polygon. The points should be ordered either counter-clockwise or clockwise. point (numpy.ndarray) – One or more points for the winding number calculation. Must be either a 2-element array for a single (x,y) pair, or an Nx2 array with N (x,y) points.
Returns:	Boolean indicating whether or not each point is within the polygon.
Return type:	bool or numpy.ndarray

enyo.etc.aperture.polygon_winding_number(polygon, point)[source]¶

Determine the winding number of a 2D polygon about a point. The code does not check if the polygon is simple (no interesecting line segments). Algorithm taken from Numerical Recipies Section 21.4.

Parameters:	polygon (numpy.ndarray) – An Nx2 array containing the x,y coordinates of a polygon. The points should be ordered either counter-clockwise or clockwise. point (numpy.ndarray) – One or more points for the winding number calculation. Must be either a 2-element array for a single (x,y) pair, or an Nx2 array with N (x,y) points.
Returns:	The winding number of each point with respect to the provided polygon. Points inside the polygon have winding numbers of 1 or -1; see `point_inside_polygon()`.
Return type:	int or numpy.ndarray
Raises:	`ValueError` – Raised if polygon is not 2D, if polygon does not have two columns, or if the last axis of point does not have 2 and only 2 elements.