gcfit.util.Field

class gcfit.util.Field(coords, cen=(0, 0), unit=None, preprep=False)

Representation of an observational photometric field.

Constructed based on imaged field coordinate boundaries, in RA and DEC, this class exists to facilitate the analysis of all mass function data.

Polygons representing the observed fields are constructed, corrected, merged and prepped in order to best handle the extraction of radial slices and the monte carlo integration of any function within it’s bounds.

Parameters:

coordsnumpy.ndarray or shapely.geometry.Polygon

Input polygon descriptor, either in the form of a already created polygon (or multi-polygon) or as an array of ordered coordinates.

cen2-tuple of float, optional

The central coordinate of the relevant globular cluster, in RA and DEC. If cen does not have any associated units, one must be supplied to the unit parameter. This is only used for initialization, all coordinates will be centred around (0, 0). Defaults to assuming this centring has already happened.

unitstr or astropy.units.Unit, optional

Unit associated with all coordinates. Only angular units (deg, rad, arcmin, etc.) are currently supported. Must be provided if coords has no units. All input coordinates will be assumed to be in these units if they do not have their own, and otherwise they will be converted to this unit. This unit cannot be changed afterwards and all other class functionality (e.g. sampling) will be based on it.

preprepbool, optional

Whether to run Field.prep upon initialization. Defaults to False.

Attributes:

polygonshapely.geometry.Polygon

The shapely Polygon or MultiPolygon object representing the field.

areaastropy.Quantity

The total area contained by the fields, in arcmin^2.

See also

shapely

Source for all geometry operations.

Notes

preprep will construct the prepared polygons immediately, however this geometry cannot be pickled, and thus the Field will not be passable using something like mpi. If that is desired, prep will have to be called manually at a later time, before any calls to __contains__.

Methods

MC_integrate(func[, sample, M])	Monte Carlo integration of func over this field.
MC_sample(M[, return_points])	Randomly sample M points from this field.
__init__(coords[, cen, unit, preprep])
from_dataset(dataset, cen)	Create this field from a corresponding gcfit.core.data.Dataset.
plot(ax[, prev_sample, adjust_view, unit, ...])	Plot this field onto a given ax as a polygonal patch.
prep()	Prepare the polygons for quicker containment searches.
slice_radially(r1, r2)	Return a new field representing a radial "slice" of this field.

MC_integrate(func, sample=None, M=None)

Monte Carlo integration of func over this field.

Using a random sample of points within this field, either generated beforehand or using Field.MC_sample, computes the integral of the given func over the entire field by simply evaluating and summing the function over all samples, and normalizing to the field area.

Will support units, if supported by the given function.

Parameters:

funccallable

The (vectorized) function to integrate over. Must accept an array of points represented by their radial distances from the origin.

samplenumpy.ndarray, optional

The sample of points to be used in the integration, represented by their radial distances from the origin. If None (default), a new sample will be generated using Field.MC_sample and M.

Mint, optional

The number of points to be sampled from Field.MC_sample, if sample is None.

Returns:

u.Quantity

The (definite) integral result. A single float value with units corresponding to the func and field units.

MC_sample(M, return_points=False)

Randomly sample M points from this field.

Random points are generated (using random.uniform) between the minimum and maximum bounds of each polygon, and simple rejection sampling is used to determine the points within each polygon. The number of points per polygon (in fields with multiple seperate polygons) is in proportion to their respective areas.

Parameters:

Mint

The number of points to sample.

return_pointsbool, optional

If True, returns a shapely.geometry.MultiPoint object containing all the points, otherwise simply returns the radial position of each (in arcmin). Defaults to False.

Returns:

astropy.Quantity or shapely.geometry.MultiPoint

Array of M sampled points, either in radial positions or coordinates, based on return_points.

classmethod from_dataset(dataset, cen)

Create this field from a corresponding gcfit.core.data.Dataset.

plot(ax, prev_sample=False, adjust_view=True, *, unit='arcmin', sample_kw=None, **kwargs)

Plot this field onto a given ax as a polygonal patch.

Given an already-initialized matplotlib axes, add a patch representing all polygons in this field, using a PathPatch constructed from each polygons boundary lines.

This method only adds a patch to existing plots, all other plotting logic must be handled seperately.

Parameters:

axmatplotlib.axes.Axes

The matplotlib axes object to add this plot to.

prev_samplebool, optional

If True, also attempt to add a scatterplot of the last sampled points. Field.MC_sample must have been recently run, with return_points=True for this to function. Defaults to False.

adjust_viewbool, optional

If True (default), also calls the autoscale_view method of ax. Simply adding a patch to a plot will not move the view to match, and patches could end up outside of the window limits. This parameter corrects that.

unitstr or astropy.units.Unit, optional

Unit to convert all coordinates to before plotting. The default is “arcmin”, not the current unit, to ensure easier consistent plotting between multiple fields, as astropy.visualization is not enough to convert Patch coordinates correctly.

sample_kwdict, optional

Kwargs to be passed to the scatter plot of the sample plot, if prev_sample=True.

**kwargs

All other arguments passed to the PathPatch object directly.

Returns:

matplotlib.patches.Patch

The patch which corresponds to this field and was added to the given ax.

prep()

Prepare the polygons for quicker containment searches.

slice_radially(r1, r2)

Return a new field representing a radial “slice” of this field.