Representations of and computations with ellipses (pwkit.ellipses)

pwkit.ellipses - utilities for manipulating 2D Gaussians and ellipses

XXXXXXX XXX this code is in an incomplete state of being vectorized!!! XXXXXXX

Useful for sources and bivariate error distributions. We can express the shape of the function in several ways, which have different strengths and weaknesses:

• “biv”, as in Gaussian bivariate: sigma x, sigma y, cov(x,y)

• “ell”, as in ellipse: major, minor, PA [*]

• “abc”: coefficients such that z = exp (ax² + bxy + cy²)

[*] Any slice through a 2D Gaussian is an ellipse. Ours is defined such it is the same as a Gaussian bivariate when major = minor.

Note that when considering astronomical position angles, conventionally defined as East from North, the Dec/lat axis should be considered the X axis and the RA/long axis should be considered the Y axis.

pwkit.ellipses.abcd2(x0, y0, a, b, c, x, y)

Given an 2D Gaussian expressed as the ABC polynomial coefficients, compute a “squared distance parameter” such that

z = exp (-0.5 * d2)

Inputs:

• x0: position of Gaussian center on x axis

• y0: position of Gaussian center on y axis

• a: such that z = exp (ax² + bxy + cy²)

• b: see above

• c: see above

• x: x coordinates of the locations for which to evaluate d2

• y: y coordinates of the locations for which to evaluate d2

Returns: d2, distance parameter defined as above.

This is pretty trivial.

pwkit.ellipses.abcell(a, b, c)

Given the nontrivial parameters for evaluation a 2D Gaussian as a polynomial, compute the equivalent ellipse parameters (major, minor, pa)

Inputs: (a, b, c), where z = exp (ax² + bxy + cy²)

Returns:

• mjr: major axis (sigma not FWHM) of the Gaussian

• mnr: minor axis (sigma not FWHM) of the Gaussian

• pa: position angle (from +x to +y) of the Gaussian, radians

pwkit.ellipses.bivabc(sx, sy, cxy)

Compute nontrivial parameters for evaluating a bivariate distribution as a 2D Gaussian. Inputs:

• sx: standard deviation (not variance) of x var

• sy: standard deviation (not variance) of y var

• cxy: covariance (not correlation coefficient) of x and y

Returns: (a, b, c), where z = k exp (ax² + bxy + cy²)

The proper value for k can be obtained from bivnorm().

pwkit.ellipses.bivell(sx, sy, cxy)

Given the parameters of a Gaussian bivariate distribution, compute the parameters for the equivalent 2D Gaussian in ellipse form (major, minor, pa).

Inputs:

• sx: standard deviation (not variance) of x var

• sy: standard deviation (not variance) of y var

• cxy: covariance (not correlation coefficient) of x and y

Outputs:

• mjr: major axis of equivalent 2D Gaussian (sigma, not FWHM)

• mnr: minor axis

• pa: position angle, rotating from +x to +y

Lots of sanity-checking because it’s obnoxiously easy to have numerics that just barely blow up on you.

pwkit.ellipses.bivnorm(sx, sy, cxy)

Given the parameters of a Gaussian bivariate distribution, compute the correct normalization for the equivalent 2D Gaussian. It’s 1 / (2 pi sqrt (sx**2 sy**2 - cxy**2). This function adds a lot of sanity checking.

Inputs:

• sx: standard deviation (not variance) of x var

• sy: standard deviation (not variance) of y var

• cxy: covariance (not correlation coefficient) of x and y

Returns: the scalar normalization

pwkit.ellipses.bivrandom(x0, y0, sx, sy, cxy, size=None)

Compute random values distributed according to the specified bivariate distribution.

Inputs:

• x0: the center of the x distribution (i.e. its intended mean)

• y0: the center of the y distribution

• sx: standard deviation (not variance) of x var

• sy: standard deviation (not variance) of y var

• cxy: covariance (not correlation coefficient) of x and y

• size (optional): the number of values to compute

Returns: array of shape (size, 2); or just (2, ), if size was not

specified.

The bivariate parameters of the generated data are approximately recoverable by calling ‘databiv(retval)’.

pwkit.ellipses.clscale(cl)

Say we take a Gaussian bivariate and convert the parameters of the distribution to an ellipse (major, minor, PA). By what factor should we scale those axes to make the area of the ellipse correspond to the confidence interval CL? (I.e. 0 < CL < 1)

pwkit.ellipses.databiv(xy, coordouter=False, **kwargs)

Compute the main parameters of a bivariate distribution from data. The parameters are returned in the same format as used in the rest of this module.

• xy: a 2D data array of shape (2, nsamp) or (nsamp, 2)

• coordouter: if True, the coordinate axis is the outer axis; i.e. the shape is (2, nsamp). Otherwise, the coordinate axis is the inner axis; i.e. shape is (nsamp, 2).

Returns: (sx, sy, cxy)

In both cases, the first slice along the coordinate axis gives the X data (i.e., xy[0] or xy[:,0]) and the second slice gives the Y data (xy[1] or xy[:,1]).

pwkit.ellipses.ellabc(mjr, mnr, pa)

Given a 2D Gaussian expressed as an ellipse (major, minor, pa), compute the nontrivial parameters for its evaluation.

• mjr: major axis (sigma not FWHM) of the Gaussian

• mnr: minor axis (sigma not FWHM) of the Gaussian

• pa: position angle (from +x to +y) of the Gaussian, radians

Returns: (a, b, c), where z = exp (ax² + bxy + cy²)

pwkit.ellipses.ellbiv(mjr, mnr, pa)

Given a 2D Gaussian expressed as an ellipse (major, minor, pa), compute the equivalent parameters for a Gaussian bivariate distribution. We assume that the ellipse is normalized so that the functions evaluate identicall for major = minor.

Inputs:

• mjr: major axis (sigma not FWHM) of the Gaussian

• mnr: minor axis (sigma not FWHM) of the Gaussian

• pa: position angle (from +x to +y) of the Gaussian, radians

Returns:

• sx: standard deviation (not variance) of x var

• sy: standard deviation (not variance) of y var

• cxy: covariance (not correlation coefficient) of x and y

pwkit.ellipses.elld2(x0, y0, mjr, mnr, pa, x, y)

Given an 2D Gaussian expressed as an ellipse (major, minor, pa), compute a “squared distance parameter” such that

z = exp (-0.5 * d2)

Inputs:

• x0: position of Gaussian center on x axis

• y0: position of Gaussian center on y axis

• mjr: major axis (sigma not FWHM) of the Gaussian

• mnr: minor axis (sigma not FWHM) of the Gaussian

• pa: position angle (from +x to +y) of the Gaussian, radians

• x: x coordinates of the locations for which to evaluate d2

• y: y coordinates of the locations for which to evaluate d2

Returns: d2, distance parameter defined as above.

x0, y0, mjr, and mnr may be in any units so long as they’re consistent. x and y may be arrays (of the same shape), in which case d2 will be an array as well.

pwkit.ellipses.ellplot(mjr, mnr, pa)

Utility for debugging.

pwkit.ellipses.ellpoint(mjr, mnr, pa, th)

Compute a point on an ellipse parametrically. Inputs:

• mjr: major axis (sigma not FWHM) of the ellipse

• mnr: minor axis (sigma not FWHM) of the ellipse

• pa: position angle (from +x to +y) of the ellipse, radians

• th: the parameter, 0 <= th < 2pi: the eccentric anomaly

Returns: (x, y)

th may be a vector, in which case x and y will be as well.

pwkit.ellipses.sigmascale(nsigma)

Say we take a Gaussian bivariate and convert the parameters of the distribution to an ellipse (major, minor, PA). By what factor should we scale those axes to make the area of the ellipse correspond to the n-sigma confidence interval?

Negative or zero values result in NaN.