API/Reference

ADI.ADIAlgorithm

This abstract type is used for defining ADI algorithms. Algorithms are stateful objects that define the options for a given algorithm (e.g. the number of components used in PCA decomposition). The most direct usage of an algorithm is to use it to fit HCI data; that is, given a sample of pixels, apply the algorithm using the given options and return an object containing all the necessary information to reconstruct the input data.

See the extended help (??ADIAlgorithm) for interface details.

Extended help

Interface

To extend ADIAlgorithm you may implement the following

ADI.fit(::Alg, data::AbstractMatrix; kwargs...)

Fit the data (flattened into a matrix). To support RDI, ensure the ref keyword argument is usable (ref is also a flattened matrix). This is the only method you need to implement for a new ADIAlgorithm, along with a suitable ADIDesign.

ADI.jl automatically coaxes the cube input into a matrix for use with fit, appropriately handling the various geometries. When available, this input is a view, so if the algorithm requires dense arrays, make sure to call collect when appropriate. If a given algorithm doesn't support the default operations, all that needs to be done is override the default behavior (for an example, see the GreeDS implementation).

reconstruct(::Alg, cube; kwargs...)

Fit the data using the algorithm and return a cube with the estimate of the PSF. By default uses the reconstruction from the ADIDesign fit to the data.

subtract(::Alg, cube; kwargs...)

Fit the data using the algorithm and return a cube that has had the PSF estimate subtracted. By default, calls reconstruct and subtracts it from cube.

process(::ADIAlgorithm, cube; kwargs...)
(::ADIAlgorithm)(cube; kwargs...)

Fully process the data (estimate, subtract, collapse). By default, derotates and collapses output from subtract. You only need to define process, since the functor version is supplied automatically.

reconstruct(alg, cube; [ref], kwargs...)

Reconstruct the PSF approximation for the given algorithm, using ref as the reference cube if given and supported by the algorithm.

Examples

julia> cube, angles = # load data

julia> S = reconstruct(PCA(10), cube);

julia> size(S) == size(cube)
true

julia> flat_res = collapse(cube .- S, angles); # form resid, derotate, and combine

subtract(alg, cube; [ref], kwargs...)

Reconstruct the PSF approximation for the given algorithm and subtract it from cube, using ref as the reference cube if given and supported by the algorithm.

Examples

julia> cube, angles = # load data

julia> R = subtract(PCA(10), cube);

julia> size(R) == size(cube)
true

julia> flat_res = collapse(R, angles); # derotate, and combine

process(alg, cube, angles; [ref], kwargs...)

Fully process an ADI data cube using subtract and collapsing the residuals. Keyword arguments will be passed to ADI.fit.

ADI.fit(::ADIAlgorithm, cube; [ref], kwargs...)

Given the description of an algorithm and the appropriate options, take the pixels from cube and fit them, returning an (ADIDesign) containing the necessary information from the fit (e.g. the principal components from PCA decomposition).

If the algorithm supports reference differential imaging (RDI), the reference cube can be passed by the keyword argument ref.

ADI.design(::ADIDesign)

Return the pertinent data required to form the PSF approximation. For example, weights and components for PCA/NMF or the median frame for classic ADI.

ADI.ADIDesign

An abstract type used for holding the output of ADI.fit. The purpose of these types is to hold the minimum information required to reconstruct the PSF estimate (e.g. weights and principal components from PCA). ADI.jl includes two designs- ADI.ClassicDesign and ADI.LinearDesign.

Interface

When implementing a new algorithm, if your outputs do not fit into either of those designs, you will have to create your own ADIDesign with the following methods-

ADI.design(::Design)

accessor for the pertinent data to approximate the PSF

reconstruct(::Design)

return the approximate PSF estimate as a matrix

ADI.LinearDesign(coeffs, basis)

A "linear" design implies the use of some linear basis for reconstructing data along with a set of coefficients or weights. The reconstruction will be the matrix product of the basis and the weights, Z * w.

ADI.design will return (basis, ceoffs), and you can also extract them via iteration, like Z, w = design.