synospec.etc.aperture module

Define apertures to use for on-sky integrations.

License

Copyright © 2020, Kyle B. Westfall

class synospec.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

property area

The area of the aperture.

property 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.

See also: Aperture.map_integral_over_source().

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 synospec.etc.aperture.CircularAperture(*args, **kwargs)[source]

Bases: synospec.etc.aperture.FiberAperture

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

Bases: synospec.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 synospec.etc.aperture.HexagonalAperture(cx, cy, d, incircle=False, orientation='horizontal')[source]

Bases: synospec.etc.aperture.Aperture

Define a hexagonal 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 (float) – The diameter of circumscribed circle.

  • incircle (bool, optional) – Use the provided diameter to set the incircle of the hexagon instead of its circumscribed circle.

  • orientation (str, float, optional) – Sets the orientation of the hexagon, must be either ‘horizontal’, ‘vertical’, or a rotation angle in degrees relative to the horizontal orientation. The horizontal and vertical orientations set the long axis of the hexagon along the Cartesian x and y axis, respectively. The horizontal orientation is equivalent to a rotation angle of 0 and a vertical orientation is equivalent to a rotation angle of 30 degrees. While the polar-coordinate ordering of the vertices in the output array will change, note the shape is degenerate with a periodicity of 60 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

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

Bases: synospec.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

synospec.etc.aperture.hexagon_vertices(d=1.0, incircle=False)[source]

Construct the vertices of a hexagon.

The long axis of the hexagon is always oriented along the Cartesian \(x\) axis.

Parameters

  • d (float, optional) – The diameter of circumscribed circle.

  • incircle (bool, optional) – Use the provided diameter to set the incircle of the hexagon instead of its circumscribed circle.

Returns

An array with shape \((6,2)\), providing the x and y Cartesian vertices of the hexagon.

Return type

numpy.ndarray

synospec.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

synospec.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.