Class velfit

Compute a multi-component Gaussian fit to spaxel x=i, y=j in the velfits
instance. Modifies the velfits instance in place.

If params are not provided, the function uses the following algorithm
to produce initial guesses:
-   Make a copy of the spaxel data
-   Find the highest data value within the range defined by vlim, use to
    give guess velocity shift and amplitude
-   Compute estimate for line width
    -   Find nearest point to peak <= half the guess amplitude, compute
        where the line between the that point, and the next point
        towards the peak, is = half the guess amplitude
    -   If the next point towards the peak is masked, use the line
        between the peak and the half-amplitude point instead
-   Compute the maximum allowed width for this fitted line, based on the
    guess velocity centroid
    -   If guess width is above this value, adjust guess to 5.0 km/s
        below max allowed value
    -   If guess width is below wmin, adjust guess to 5.0 km/s above max
        allowed value
-   Subtract the guessed Gaussian profile from copy of spaxel data
-   Repeat the procedure until there are enough guess parameters to fit
    comps components

Inputs:
velfits -   The velfits instance to be acted upon.
i -         The x-index of the spaxel to be fitted.
j -         The y-index of the spaxel to be fitted.
comps -     The number of Gaussian components to fit to the spaxel
            spectrum. Defaults to 1.
fixno -     Boolean value denoting whether to force the spectrum to be
            fit with comps components (True), or to incrementally try a
            number of components from 1 to comps, stopping when the
            limiting reduced chi-squared is acheived (False). Defaults
            to False.
ignoreamp - Boolean value specifying whether to consider the nifscube's
            stated amplitude limit when fitting. Defaults to False (any
            fits not conforming to the limit will be considered bad).
quiet -     Boolean value denoting whether or not the MPFIT fitting
            routine should be quiet or not. Defaults to False.
params -    Fitting parameters to be passed to the fitting routine.
            Intended for use when the automatic paramter finder produces
            unacceptable results. Requires fixno = True.
            Takes the form of a list composed of
            [background, amplitude, shift, width, amplitude....].
            Defaults to None (at which point the
            automatic first-guess finding will be used.)
vlim -      A two-element list giving the minimum and maximum values
            allowed for ALL component centroids in the fits, in units
            of km/s. Defaults to None (where the minimum and maximum
            velocities present in the fitvels instance will be used as
            the limits.
wmin -      The minimum allowed line sigma to be fit. Note this does NOT
            represent a FWHM value. Defaults to 10.0
wpercent -  The percentage of total line intensity allowed to be on the
            opposite side of v=0 to the line peak. Used to calculate an
            upper limit on the fitted line width. Must be a float
            between 0.0 and 1.0. Defaults to 0.10.
wperspace - Expected percentage error on the initial guess for the line
            centroid velocity. Used in the calculation of maximum
            allowed fitted line width. Must be a float between 0.0 and
            1.0. Defaults to 0.25.
wmaxcut -   Lower limit on maximum allowed fitted line width. Avoids the
            initial guess routine from trying to fit peaks of noise.
            Defaults to 50.0 km/s.
alim -      A two-element list giving the minimum and maximum values
            allowed for the amplitude of ALL fit components, in units
            km/s. Defaults to None (at which point, the amplitudes
            will only be limited to be positive).
fixbg -     Boolean value, specifying if the background height of the
            fits should be forced to 0.0 (True) or not. Defaults to
            False.
snthresh -  Signal-to-noise threshold - if spaxel is below this
            threshold, fits will still be made, but fitno[j,i] will then
            be set to 0 afterwards. Masking calculated by the
            maskFits function.
            
Returns:
Nil. The velfits instance is updated in place. The fit information for
the i-th, j-th pixel will be updated as follows:
    If fixno = False, the fit information for the first multi-component
    fit that satisfies the rchisqlim for this velfits instance will be
    recorded. If all fits, up to and including the comps-component fit,
    do not satisfy this limit, no fit info (and empty list) will be
    recorded.
    If fixno = True, then the fit will be made blindly and recorded,
    with no regard to the reduced chi-squared limit.

'Mask' spaxel if signal-to-noise is under the specified value. By
'mask', the no. of fits recorded for that spaxel will be set to 0.
Signal-to-noise is determined as the ratio of the peak flux value
recorded in the spaxel to the corresponding error of that data point.

Inputs:
i, j     -  Spaxel x- and y- indices, respectively.
snthresh -  The S/N threshold value. Any spaxels with an S/N less than this
            value will be 'masked'. Defaults to 7.5.
            
Returns:
Nil. fitvels instance is updated in-situ.

Mask a particular pixel in the velfit instance.

Inputs: i, j, k - The pixel's x-, y- and spectral indices respectively.

Returns: Nil. The velfit instance is updated in-situ.

Apply maskFits to every spaxel in the velfit instances.

Inputs: snthresh - The S/N threshold for masking. Defaults to 5.

Returns: Nil. fitvels instance updated in-situ.

Plot the spectrum of a given spaxel, along with any fits made.

Inputs:
i -         x-index of the spaxel in the fitvel instance
j -         y-index of the spaxel in the fitvel instance
linewidth - Line widths of the plot components. Defaults to 2.
plotpeak -  Boolean value, denoting whether to plot the peak position
            (with errorbars) for each fit component. Defaults to True.
highres -   Boolean value, denoting whether to plot the fits at high
            velocity resolution (True), or a with the same sampling as
            the data (False). Defaults to False.
plotresid - Boolean value, denoting whether to plot the fitting
            residual or not. Defaults to True. If plotted, residuals
            will be scaled such that they sit between -rsf times the
            maximum data value, and 0.0.
rsf -       Float value, indicating the scaling that should be applied
            to the residuals data. Residuals will then be scaled to
            be plotted between -rsf*data.max() and 0.0. Defaults to 0.2.
ms -        Float value, denoting the size of the markers used to plot
            the data. Defaults to 5.
arcsecs -   Boolean value, denoting whether to convert the data values
            into flux density per arcsec^2 (True), or leave them as
            flux density per pixel (False). Defaults to False.

Outputs:
Nil. The plot is made to the plotting region specified before the
function is called (i.e. a whole figure, a subplot, etc.)

Plots a pseudocolor image of the specified parameter in the velfit
instance.

Inputs:
z -         An integer code, corresponding to the parameter from the
            velfit that we wish to plot. Defaults to 0 (corresponds to
            plotting the total flux per spaxel, i.e. self.summed. The
            codes are:
            0 - Number of fit components
            1 - Spaxel chi-squared
            2 - Spaxel degrees of freedom
            3 - Spaxel reduced chi-squared
            100 - Spaxel total flux
            101 - Fit background height
            102 - Spaxel peak flux
            103 - Spaxel summed error
            104 - Ratio of spaxel peak flux/spaxel average error
            105 - Ratio of spaxel summed flux/spaxel summed error
            106 - Ratio of spaxel peak flux/corresponding pixel error
            111 - First component total flux
            112 - Second component total flux
                  ...and so on
            121 - Spaxel fitted total flux
            122 - Spaxel fitted total flux error
            123 - Spaxel fitted total flux / total flux error
            11 - First component peak flux
            12 - First component line velocity
            13 - First component line width
            21 - Second component peak flux
            22 - Second component line velocity
            23 - Second component line width
               - ....and so on. Codes are currently included for up to
               three components.
colorbar -  A boolean value, denoting whether or not to include a
            colorbar. Defaults to True.
colormap -  A colormap instance, to be used as the colormap for the
            pseudocolor diagram. Must be passed as matplotlib.cm.*.
            Defaults to matplotlib.cm.jet.
log -       A boolean value, specifying whether to plot the data as is
            (False), or the base-10 log of the data (True). If True,
            the data parameter to be plotted will be masked wherever
            it is less than or equal to zero. Defaults to False.
edged -     Boolean vale, denoting whether to draw edges around each
            spaxel in the returned image. Defaults to False.
        
Returns:
plotted -   The colorbar instance which has been plotted. This is
            required in order to add to the diagram later on, e.g.
            colorbar(plotted).
Will plot a pseudocolor diagram of the requested parameter to the
current figure/axes when called. If the requested parameter does not
exist (i.e. asked to plot the third component amplitude on a two-
component velfit), a message will be returned to the terminal, and
nothing else will occur.

Sums over the velocity range of the cube, and save the result to the summed array.

Inputs: Nil.

Returns: Nil. The summed attribute of the velfit instance is updated.

Collapse the fluxes and fluxerr arrays to represent total flux, summed over all components that have been fit.

Inputs: Nil.

Returns: fluxsum - The array holding the summed flux values. fluxsumerr - The array holding the summex flux values.

Returns the F-test information for all fits made to spaxel (i,j).

Inputs:
i, j -  The x- and y-indices of the spaxel to be inspected.

Returns:
ftest - A list of list containing the F test information. Each element
        of the master list will be a three-element list, containing:
        - The number of components in the more complex fit
        - The F-ratio of this complex fit to the simpler fit before
        - The F-test P-ratio for the same comparison.

Returns fit information (e.g. chi-sq, degrees of freedom) for
the comps-component fit of the given spaxel.

Inputs:
i -     The spaxel x-index
j -     The spaxel y-index
comps - The parameter will be extracted from the fit information with
        this number of components.
info -  An integer code corresponding to the information wanted. Options
        are:
        0 - number of fit components
        1 - spaxel chi-squared
        2 - spaxel degrees of freedom
        3 - spaxel reduced chi-squared
        4 - spaxel F-test information
        
Returns:
value -  The requested information for this spaxel

Returns a particular fit parameter for a given spaxel.

Inputs:
i -     The spaxel x-index
j -     The spaxel y-index
comps - The parameter will be extracted from the fit information with
        this number of components.
info -  An integer code corresponding to the information wanted. Options
        are:
        0 - background amplitude
        1 - fit amplitude, component A
        2 - fit displacement (i.e. line velocity), component A
        3 - fit FWHM (i.e. line width), component A
        4 - fit amplitude, component B
        5 - fit displacement (i.e. line velocity), component B
        ...and so on.

Returns:
parameter - The requested parameter from the relevant fit for this
            spaxel.
perror -    The formal covariance matrix error associated with this
            parameter for this spaxel. Note that this is NOT the
            formal error - the relevant chi-squared value and
            degrees of freedom will still need to be taken into account.

Generates a masked array of fit information, as returned by returnInfo.
The information returned will correspond to the best fit for each
spaxel (as denoted in self.fitno).

Inputs:
info -  An integer code denoting what information we want returned.
        These codes correspond to those found in returnInfo().
        
Returns:
infoarr -   A two-dimensional masked array, containing the requested
            information for each spaxel. Will take the same shape as the
            spatial dimension of the fitvels instance (i.e. the same
            shape as, say, fitno).

Generates a masked array of fit parameters, as returned by
returnFitInfo. The fit parameter returned will correspond to the best
fit for each spaxel (as denoted in self.fitno).

Inputs:
info -  An integer code denoting what information we want returned.
        These codes correspond to those found in returnFitInfo().
        
Returns:
paramarr -  A two-dimensional masked array, containing the requested
            information for each spaxel. Will take the same shape as the
            spatial dimension of the fitvels instance (i.e. the same
            shape as, say, fitno).
paramperr - A two-dimensional masked array, containing the formal
            1-sigma errors for the requested information.

Save the current velfit to file.

Inputs:
filename -  Filename to be saved to. Defaults to None, in which case
            a datetime stamp will be used to generate a file name.

Returns:
Nil. A file is saved to the current working directory containing this
velfit instance.

Find the spaxel index corresponding to the given velocity value.

Inputs: z - The x-coordinate that we wish to find the spaxel index for

Returns: k - The spaxel index corresponding to the passed velocity.