Documentation for `Utils`

Collection of utility functions

`bspline_smooth(y, x=None, degree=3, do_segments=False, breaks=None, n_knots=100)`

Applies a spline smoothing to a curve.

Parameters:

Name	Type	Description	Default
`y`	`numpy.ndarray or list of numpy.ndarray`	Arrays to be smoothen in the last axis	required
`x`	`numpy.ndarray`	Optional. x array, as y = f(x)`` used to find discontinuities inf(x)`. If x is given then splits will be computed, if not`breaks` argument as to be provided.	`None`
`degree`	`int`	Degree of the psline fit, default is 3.	`3`
`do_segments`	`boolean`	Do the splines per segments with splits computed from data `x` or given in `breaks`.	`False`
`breaks`	`list of ints`	List of break indexes in `y`.	`None`
`nknots`	`int`	Number of knots for the B-Spline. If `do_segments` is True, knots will be distributed in each segment.	required

Returns:

Type	Description
`numpy.ndarray`	Smooth array.

`do_tiled_query(ra, dec, ngrid=(5, 5), magnitude_limit=18, epoch=2020, dr=3)`

Find the centers and radius of tiled queries when the sky area is large.

This function divides the data into ngrid tiles and compute the ra, dec coordinates for each tile as well as its radius. This is meant to be used with dense data, e.g. FFI or cluster fields, and it is not optimized for sparse data, e.g. TPF stacks. For the latter use psfmachine.tpf._get_coord_and_query_gaia().

Parameters:

Name	Type	Description	Default
`ra`	`numpy.ndarray`	Data array with values of Right Ascension. Array can be 2D image or flatten.	required
`dec`	`numpy.ndarray`	Data array with values of Declination. Array can be 2D image or flatten.	required
`ngrid`	`tuple`	Tuple with number of bins in each axis. Default is (5, 5).	`(5, 5)`
`magnitude_limit`	`int`	Limiting magnitude for query	`18`
`epoch`	`float`	Year of the observation (Julian year) used for proper motion correction.	`2020`
`dr`	`int`	Gaia Data Release to be used, DR2 or EDR3. Default is EDR3.	`3`

Returns:

Type	Description
`pandas.DatFrame`	Pandas DatFrame with number of result sources (rows) and Gaia columns

`gaussian_smooth(y, x=None, do_segments=False, filter_size=13, mode='mirror', breaks=None)`

Applies a Gaussian smoothing to a curve.

Parameters:

Name	Type	Description	Default
`y`	`numpy.ndarray or list of numpy.ndarray`	Arrays to be smoothen in the last axis	required
`x`	`numpy.ndarray`	Time array of same shape of `y` last axis used to find data discontinuity.	`None`
`filter_size`	`int`	Filter window size	`13`
`mode`	`str`	The `mode` parameter determines how the input array is extended beyond its boundaries. Options are {'reflect', 'constant', 'nearest', 'mirror', 'wrap'}. Default is 'mirror'	`'mirror'`

Returns:

Type	Description
`numpy.ndarray`	Smooth array.

`get_breaks(time, include_ext=False)`

Finds discontinuity in the time array and return the break indexes.

Parameters:

Name	Type	Description	Default
`time`	`numpy.ndarray`	Array with time values	required

Returns:

Type	Description
`numpy.ndarray`	An array of indexes with the break positions

`get_gaia_sources(ras, decs, rads, magnitude_limit=18, epoch=2020, dr=3)`

Will find gaia sources using a TAP query, accounting for proper motions.

Inputs have be hashable, e.g. tuples

Parameters:

Name	Type	Description	Default
`ras`	`tuple`	Tuple with right ascension coordinates to be queried shape nsources	required
`decs`	`tuple`	Tuple with declination coordinates to be queried shape nsources	required
`rads`	`tuple`	Tuple with radius query shape nsources	required
`magnitude_limit`	`int`	Limiting magnitued for query	`18`
`epoch`	`float`	Epoch to be used for propper motion correction during Gaia crossmatch.	`2020`
`dr`	`int or string`	Gaia Data Release version, if Early DR 3 (aka EDR3) is wanted use `"edr3"`.	`3`

`solve_linear_model(A, y, y_err=None, prior_mu=None, prior_sigma=None, k=None, errors=False)`

Solves a linear model with design matrix A and observations y:

Aw = y return the solutions w for the system assuming Gaussian priors. Alternatively the observation errors, priors, and a boolean mask for the observations (row axis) can be provided.

Adapted from Luger, Foreman-Mackey & Hogg, 2017 (https://ui.adsabs.harvard.edu/abs/2017RNAAS...1....7L/abstract)

Parameters:

Name	Type	Description	Default
`A`	`numpy ndarray or scipy sparce csr matrix`	Desging matrix with solution basis shape n_observations x n_basis	required
`y`	`numpy ndarray`	Observations shape n_observations	required
`y_err`	`numpy ndarray`	Observation errors shape n_observations	`None`
`prior_mu`	`float`	Mean of Gaussian prior values for the weights (w)	`None`
`prior_sigma`	`float`	Standard deviation of Gaussian prior values for the weights (w)	`None`
`k`	`boolean, numpy ndarray`	Mask that sets the observations to be used to solve the system shape n_observations	`None`
`errors`	`boolean`	Whether to return error estimates of the best fitting weights	`False`

Returns:

Type	Description
`numpy ndarray`	Array with the estimations for the weights shape n_basis

`sparse_lessthan(arr, limit)`

Compute less than operation on sparse array by evaluating only non-zero values

and reconstructing the sparse array. This function return a sparse array, which is crutial to keep operating large matrices.

Notes: when doing x < a for a sparse array x and a > 0 it effectively compares all zero and non-zero values. Then we get a dense boolean array with True where the condition is met but also True where the sparse array was zero. To avoid this we evaluate the condition only for non-zero values in the sparse array and later reconstruct the sparse array with the right shape and content. When x is a [N * M] matrix and a is [N] array, and we want to evaluate the condition per row, we need to iterate over rows to perform the evaluation and then reconstruct the masked sparse array.

Parameters:

Name	Type	Description	Default
`arr`	`scipy.sparse`	Sparse array to be masked, is a 2D matrix.	required
`limit`	`float, numpy.array`	Upper limit to evaluate less than. If float will do `arr < limit`. If array, shape has to match first dimension of `arr` to do `arr < limi[:, None]`` and evaluate the condition per row.	required

Returns:

Type	Description
`scipy.sparse.csr_matrix`	Sparse array after less than evaluation.

`spline1d(x, knots, degree=3, include_knots=False)`

Make a bspline design matrix (DM) for 1D variable x.

Parameters:

Name	Type	Description	Default
`x`	`np.ndarray`	Array of values to create the DM.	required
`knots`	`np.ndarray`	Array of knots to be used in the DM.	required
`degree`	`int`	Degree of the spline, default is 3.	`3`
`include_knots`	`boolean`	Include or not the knots in the `x` vector, this forces knots in case out of bound values.	`False`

Returns:

Type	Description
`sparse CSR matrix`	A DM with bspline basis for vector `x`.

`threshold_bin(x, y, z, z_err=None, abs_thresh=10, bins=15, statistic=<function nanmedian at 0x1110db790>)`

Function to bin 2D data and compute array statistic based on density.

This function inputs 2D coordinates, e.g. X and Y locations, and a number value Z for each point in the 2D space. It bins the 2D spatial data to then compute a statistic, e.g. median, on the Z value based on bin members. The statistic is computed only for bins with more than abs_thresh members. It preserves data when the number of bin memebers is lower than abs_thresh.

Parameters:

Name	Type	Description	Default
`x`	`numpy.ndarray`	Data array with spatial coordinate 1.	required
`y`	`numpy.ndarray`	Data array with spatial coordinate 2.	required
`z`	`numpy.ndarray`	Data array with the number values for each (X, Y) point.	required
`z_err`	`numpy.ndarray`	Array with errors values for z.	`None`
`abs_thresh`	`int`	Absolute threshold is the number of bib members to compute the statistic, otherwise data will be preserved.	`10`
`bins`	`int or list of ints`	Number of bins. If int, both axis will have same number of bins. If list, number of bins for first (x) and second (y) dimension.	`15`
`statistic`	`callable()`	The statistic as a callable function that will be use in each bin. Default is `numpy.nanmedian`.	`<function nanmedian at 0x1110db790>`

Returns:

Type	Description
`numpy.ndarray`	2D histogram values

`wrapped_spline(input_vector, order=2, nknots=10)`

Creates a vector of folded-spline basis according to the input data. This is meant

to be used to build the basis vectors for periodic data, like the angle in polar coordinates.

Parameters:

Name	Type	Description	Default
`input_vector`	`numpy.ndarray`	Input data to create basis, angle values MUST BE BETWEEN -PI and PI.	required
`order`	`int`	Order of the spline basis	`2`
`nknots`	`int`	Number of knots for the splines	`10`

Returns:

Type	Description
`numpy.ndarray`	Array of folded-spline basis

Documentation for Utils

bspline_smooth(y, x=None, degree=3, do_segments=False, breaks=None, n_knots=100)

do_tiled_query(ra, dec, ngrid=(5, 5), magnitude_limit=18, epoch=2020, dr=3)

gaussian_smooth(y, x=None, do_segments=False, filter_size=13, mode='mirror', breaks=None)

get_breaks(time, include_ext=False)

get_gaia_sources(ras, decs, rads, magnitude_limit=18, epoch=2020, dr=3)

solve_linear_model(A, y, y_err=None, prior_mu=None, prior_sigma=None, k=None, errors=False)

sparse_lessthan(arr, limit)

spline1d(x, knots, degree=3, include_knots=False)

threshold_bin(x, y, z, z_err=None, abs_thresh=10, bins=15, statistic=<function nanmedian at 0x1110db790>)

wrapped_spline(input_vector, order=2, nknots=10)

Documentation for `Utils`

`bspline_smooth(y, x=None, degree=3, do_segments=False, breaks=None, n_knots=100)`

`do_tiled_query(ra, dec, ngrid=(5, 5), magnitude_limit=18, epoch=2020, dr=3)`

`gaussian_smooth(y, x=None, do_segments=False, filter_size=13, mode='mirror', breaks=None)`

`get_breaks(time, include_ext=False)`

`get_gaia_sources(ras, decs, rads, magnitude_limit=18, epoch=2020, dr=3)`

`solve_linear_model(A, y, y_err=None, prior_mu=None, prior_sigma=None, k=None, errors=False)`

`sparse_lessthan(arr, limit)`

`spline1d(x, knots, degree=3, include_knots=False)`

`threshold_bin(x, y, z, z_err=None, abs_thresh=10, bins=15, statistic=<function nanmedian at 0x1110db790>)`

`wrapped_spline(input_vector, order=2, nknots=10)`