astropy.tools documentation

The tools package holds general astronomy functions or algorithms that are likely of use to users, but either not related to functionality in an existing package or of general use across multiple packages.

Note

For functions and classes that are more developer-oriented, the correct package is astropy.utils. astropy.tools is intended primarily for functionality that is astronomy-specific and/or of use to users.

Reference/API

Below are the reference documentation for the tools sub-packages. All public functions and classes in these packages will be imported into the astropy.tools package, so the recommended usage is e.g. from astropy.tools import sigma_clip or import astropy.tools instead of from astropy.tools.misc import sigma_clip or similar.

astropy.tools.misc

This module contains simple algorithmic functionality common in astronomy or used in multiple places throughout Astropy, but are not complex enough to necessarily warrant their own module.

This package should generally not be used directly. Everything in __all__ is imported into astropy.tools, and hence that package should be used for access.

astropy.tools.misc.sigma_clip(data, sig=3, iters=1, cenfunc=<function median at 0x46e8c08>, varfunc=<function var at 0x4665c80>, maout=False)

Perform sigma-clipping on the provided data.

This performs the sigma clipping algorithm - i.e. the data will be iterated over, each time rejecting points that are more than a specified number of standard deviations discrepant.

Parameters :

data : array-like

The data to be sigma-clipped (any shape).

sig : float

The number of standard deviations (not variances) to use as the clipping limit.

iters : int or None

The number of iterations to perform clipping for, or None to clip until convergence is achieved (i.e. continue until the last iteration clips nothing).

cenfunc : callable

The technique to compute the center for the clipping. Must be a callable that takes in a 1D data array and outputs the central value. Defaults to the median.

varfunc : callable

The technique to compute the variance about the center. Must be a callable that takes in a 1D data array and outputs the width estimator that will be interpreted as a variance. Defaults to the variance.

maout : bool or ‘copy’

If True, a masked array will be returned. If the special string ‘inplace’, the masked array will contain the same array as data, otherwise the array data will be copied.

Returns :

filtereddata : numpy.ndarray or numpy.masked.MaskedArray

If maout is True, this is a masked array with a shape matching the input that is masked where the algorithm has rejected those values. Otherwise, a 1D array of values including only those that are not clipped.

mask : boolean array

Only present if maout is False. A boolean array with a shape matching the input data that is False for rejected values and True for all others.

Examples

This will generate random variates from a Gaussian distribution and return only the points that are within 2 sample standard deviation from the median:

>>> from astropy.tools.alg import sigma_clip
>>> from numpy.random import randn
>>> randvar = randn(10000)
>>> data,mask = sigma_clip(randvar,2,1)

This will clipping on a similar distribution, but for 3 sigma relative to the sample mean, will clip until converged, and produces a numpy.masked.MaskedArray:

>>> from astropy.tools.alg import sigma_clip
>>> from numpy.random import randn
>>> from numpy import mean
>>> randvar = randn(10000)
>>> maskedarr = sigma_clip(randvar,3,None,mean,maout=True)