Module pynifs

Loads a NIFS FITS file into computer memory.

Inputs:
filename -  The FITS file to be loaded into memory. May be a single- or
            multi-extenstion FITS file.
pxoff -     X-pixel offset to be used for plotting purposes. Defaults to 0.0.
pyoff -     Y-pixel offset to be used for plotting purposes. Defaults to 0.0.
scihead -   The header name of the science data extentsion. Defaults to
            'SCI' for multi-extenstion FITS files, and will be automatically
            be set to 'PRIMARY' for a single-extension file.
varhead -   The header name of the variance data extenstion. Defaults to
            'VAR'.
dqhead -    The header name of the pixel quality flag array. Defaults to
            'DQ'.
xu, yu -    Strings defining the units of the x and y axes. Defaults to
            'arcsec' for both.
zu -        String defining the units of the x and y axes. Defaults to 'A'
            (angstrom). This module currently only recognises two options:
            'A' - angstrom
            'um'- micron
scalefact - Float giving the value to scale the data and variances by. This
            is useful for pulling data values into something close to
            reasonable human numbers. Defaults to 1.0 (no scaling).
flipx -     Boolean value, specifying whether to invert the x-axis (i.e.
            flip the sign on the x pixel increment.) Designed for use with
            files coming out of IRAF that have had their CDELT1 value sign
            flipped for some reason. Defaults to False.


Outputs:
data -      A fitscube instance containing the data cube.

Adds a variance array to a pre-existing fitscube instance. The mask from
fitscube.scidata will be applied to the variance array after loading.

Inputs:
fitscube -  The fitscube instance the variance array is to be added to
vars -      The variance array to be added to the fitscube instance. It must
            have the same shape as fitscube.scidata. Can be a nested list,
            a numpy array, etc etc.
            
Returns:
data -      A fitscube instance identical to the original fitscube, but
            with the new variance array

Applies mask to the scidata and variance arrays in the fitscube.

Inputs:
fitscube -  The fitscube instance the mask is to be added to
mask -      The mask to be applied. The mask should take the same form as
            the initial DQ pixel quality array - that is, a True/1 value
            denotes a pixel that is bad, False/0 denotes good.
            
Returns:
data -      A fitscube instance identical to the original fitscube, but with
            the new mask applied.

Function to load a DQ pixel quality mask onto data that has already been
loaded into a fitscube() class instance.

Inputs:
fitscube -  The pre-existing fitscube instance. If the fitscube already has
            a mask applied to the scidata and/or variance arrays, that mask
            will be overwritten.
dqfile -    The FITS file (possibly multi-extension) which containts the DQ
            pixel quality array.
dqhead -    The header of dqfile containing the DQ pixel quality array.
            Defaults to 'DQ', however, if dqfile is detected to be single-
            extension, it will automatically be set to 'PRIMARY'.
            
Returns:
data -      A fitscube instance which is identical to the input fitscube,
            but with the new masking applied to the scidata and vars arrays.

Function to load a variance array into a fitscube() instance that has
already been loaded into memory. The mask from fitscube.scidata will then
be applied to the new variance array.

Inputs:
fitscube -  The pre-existing fitscube instance. If this fitscube already has
            a variance array in it, this array will be overwritten.
varfile -   The FITS file (possibly multi-extension) which contains the
            variance array.
varhead -   The header of the FITS file extension containing the variance
            array. Defaults to 'VAR'; however, if varfile is detected to be
            single-extension, it will automatically be set to 'PRIMARY'.
zu -        Units the sigmas are represented in (i.e. the variances will be
            in units of zu**2.) Options are angstrom 'A' or micron 'um'.
            Defaults to 'A'.
            
Returns:
data -      A fitscube instance identical to the input fitscube, but with
            the new variance data.

Function to simultaneously load a variance array and a pixel quality mask
into a pre-existing fitscube instance. This function simply calls
loadFITSvars, and then applyMask, and is provided for convenience.

Inputs:
fitscube -  The pre-existing fitscube instance. If this instance already
            contains a variance array and/or a pixel quality mask, these
            will both be replaced.
filename -  the multi-extenstion FITS file containing the variance array and
            pixel quality array.
varhead -   The header of the extension containing the variance array.
            Defaults to 'VAR'.
dqhead -    The header of the FITS extension containing the pixel quality
            array. Defaults to 'DQ'.
            
Returns:
data -      A fitscube instance identical to the initial instance, but with
            the new variance array and pixel quality mask.

Open a saved nifscube or velfit instance, and load it into Python memory.

Inputs: filename - The name of the saved nifscube/velfit file to be opened.

Returns: velfit - The nifscube/velfit instance read out of the file.

Integreates the raw data in the nifcscube instance over the spectral
dimension between the defined wavelength limits. Only unmasked pixels
will be used. Integral is calculated histogram-style - that is, each data
points represents a vertical column of height (data valae) and width
(delta lambda).

Inputs:
nifscube -      The nifscube instance to be summed over.
startw, stopw - The beginning and end wavelengths of the wavelength range to
                be integrated over. Given in units of m.

Returns:
intdata -       A two-dimensional masked array containing the integrated
                values. The integral will only be of those pixels which are
                unmasked in the full three-dimensional data cube.
                The mask will only suppress spaxels which have no unmasked
                value in the full three-dimensional data cube.
interr -        A two-dimensional masked array, containing the error on
                intdata related to the summation/integration process. Note
                that this error won't account for systematics introduced by,
                e.g., masked pixels within the integration range.
nopoints -      A two-dimensional array, containing the number of points
                used to compute the integrated flux density in that spaxel.

Integrates the raw data in the nifscube instance over the spectral dimension
between the defined velocity limits. Only unmasked pixels will be used.
Integral is calculated histogram-style - that is, each data point represents
a vertical column of height (data value) and width (delta lambda).

Inputs:
nifscube -      The nifscube instance to be summed over.
restwavl -      The rest wavelength, given in units of m.
startv, stopv - The beginning and end velocities of the velocity range to
                be integrated over. Given in units of km/s.
                
Returns:
intdata -       A two-dimensional masked array containing the integrated
                values. The integral will only be of those pixels which are
                unmasked in the full three-dimensional data cube.
                The mask will only suppress spaxels which have no unmasked
                value in the full three-dimensional data cube.
interr -        A two-dimensional masked array, containing the error on
                intdata related to the summation/integration process. Note
                that this error won't account for systematics introduced by,
                e.g., masked pixels within the integration range.
nopoints -      A two-dimensional array, containing the number of points
                used to compute the integrated flux density in that spaxel.

Sums the data in the nifscube instance over the spectral dimension between
the defined velocity limits. Only unmasked pixels will be summed.

Inputs:
nifscube -      The nifscube instance to be summed over.
restwavl -      The rest wavelength, given in units of m.
startv, stopv - The beginning and end velocities of the velocity range to
                be summed over. Given in units of km/s.
                
Returns:
sumdata -       A two-dimensional masked array containing the summed values.
                The sum will only be of those pixels which are unmasked in
                the full three-dimensional data cube.
                The mask will only suppress spaxels which have no unmasked
                value in the full three-dimensional data cube.
vardata -       A two-dimensional masked array containing the variances of
                the summed data. The variance of each spaxel is computed
                by adding the sqrt(variance) of each pixel, and then taking
                the square of the result. The same mask applied to sumdata
                will be applied to vardata. If there is no variance
                information in the input nifscube, a two-dimensional masked
                array of zeros in the correct shape will be returned.

Forms an averaged, integrated continuum image over two specified velocity
ranges. The ranges share a single width, to allow for simple averaging.

Inputs:
nifscube -  The nifscube instance to be acted upon.
restwavl -  The rest wavelength of the line being investigated (in m).
vlower -    The start velocity of the first wavelength range.
vupper -    The start velocity of the second wavelength range.
deltav -    The width of the velocity ranges.

Returns:
contimage - An integrated flux density (i.e. flux) image, averaged from
            the two velocity ranges above. Takes the form of a masked array.
            Will have the same shape as the spatial dimensions of the
            passed nifscube instance.

Fits a multi-component Gaussian to every spaxel in the given NIFS data cube.

Inputs:
nifscube -      The nifscube instance to be acted uopn
restwavl -      The rest wavelength of interest (in m).
vmin -          The lowest velocity data value to be included in the
                fitting (in km/s). Defaults to -1000 km/s.
vmax -          The highest velocity data value to be included in the
                fitting (in km/s). Defaults to 1000 km/s.
ftestlim -      The upper limit allowed for the F-test, to determine whether
                extra Gaussian components are required or not. Defaults to
                1.4.
ftestp -        The limiting P-value for the F-test, to determine whether
                extra Gaussian components are required or not. Defaults to
                0.05.
fitmax -        The maximum number of Gaussian components that can be fit
                to any one spaxel. Defaults to 1.
xlim -          Either none, OR a tuple denoting the start and end x-coords
                of the region of interest. Defaults to None.
ylim -          As for xlim, but with respect to the y coordinates.
vlim -          A two-element list, containing min and max values for
                ALL fit component centroid values, in units km/s. Defaults
                to None (in which case, the centroid values will be forced
                to lie within the velocity range of interest.)
wmin -          Minimum allowed fitted line width. Defaults to 10.0 km/s.
wpercent -      Percentage of total line intensity permitted to be on the
                opposite side of 0 km/s to the line peak. Used to calculate
                maximum permitted fitted line width for each feature. Must
                be a float between 0.0 and 1.0. Defaults to 0.10.
wperspace -     Expected percentage error on initial guess line velocities.
                Used for calculating maximum allowed fitted line widths.
                Must be a float between 0.0 and 1.0. Defaults to 0.25.
wmaxcut -       Lower limit on maximum allowed fitted line width. Defaults
                to 50.0.
fixbg -         Boolean value, denoting whether to fix the background
                height of the fit 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. S/N is calculated as the peak flux
                value in the spaxel, divided by the average noise across
                the entire region of interest (generally speaking, the
                errors in any one spaxel are roughly the same in adjacent
                pixels.) Must be expressed as a positive number. Defaults
                to 5.
noisepts -      The number of points to be used just outside the velocity
                region of interest to compute an uncertainty estimate for
                each spaxel (to be used with signal-to-noise rejection).
                Points will be taken from the side of the region of interest
                furthest from v = 0 km/s.
            
Returns:
velfit -        A new velfit instance containing the fit information.

Converts a wavelength to a radial velocity.

Inputs: wavl - Wavelength to be converted (units m). restwavl - Rest wavelength (units m). wavs - Wave speed (units m s^-1). Defaults to speed of light c = 2.9979e8 m s^-1.

Returns: radvel - Corresponding radial velocity (units km s^-1).

Converts a radial velocity to a wavelength.

Inputs: radvel - Radial velocity (units km s^-1). restwavl - Rest wavelength (units m). wavs - Wave speed (units m s^-1). Defaults to speed of light c = 2.9979e8 m s^-1.

Returns: wavl - Corresponding wavelength (units m).

Masks all pixels in the cube with the specified x- and y-index.

Inputs: cube - Cube to be acted upon xind - The x-index of pixels to be masked yind - The y-index of pixels to be masked

Returns: Nil.

Converts the arrays of pixel centroids xpts and ypts in the passed fitscube
into arrays of pixel corner values. Either returns the two arrays, or a
meshgrid of them. Uses the offset position arrays

Inputs:
fitscube -  The fitscube instance to be acted upn.
mesh -      Denotes whether to return lists of pixel corner x- and y-
            coordinates (False), or a meshgrid of the two for plotting
            purposes (True).

Returns:
EITHER
xcors, ycors -  The lists of pixel corner x- and y-coordinates,
                respectively.
OR
XX, YY -        The result of meshgrid(xcors, ycors)

Re-grids a two-dimensional data array (with coordinates given in x- and y-
space) into a one-dimensional data array with coordinates given in radius.
The radius is computed from the given x and y center coordinates.

Inputs:
data -  The two-dimensional (potentially masked) data array to be
        re-gridded. Must have shape(len(ypts), len(xpts)).
xpts -  The list of x-coordinates corresponding to the data.
ypts -  The list of y-coordinates corresponding to the data.
vars -  The array of data variances corresponding to the data. Defaults to
        None. Must be the same shape as data.
xcen -  The center x-coordinate to be used for computing the radius.
        Defaults to 0.0.
ycen -  The center x-coordinate to be used for computing the radius.
        Defaults to 0.0.
        
Returns:
datarad -   A one-dimensional array (potentially masked), of length
            len(xpts)*len(ypts), containing the input data re-gridded into
            radius space.
varsrad -   A one-dimensional array (potentially masked) containing the
            variance information of the input data re-gridded to radius
            space. If no variances were passed when the function was called,
            an array of zeros of the appropriate size will be returned.
rads -      A one-dimensional array containing the radius coordinates of the
            re-gridded data. Specified such that rads[i] is the radial
            coordinates of datarad[i]. Points in rad will almost certainly
            NOT be sorted in any particular order.

Function that trims a two-dimensional data array so that it only retains
points that are within the ranges [xmin,xmax] and [ymin,max].

Inputs:
data -          The two-dimensional data array to be acted upon
xpts, ypts -    The list of x- and y-coordinates corresponding to the data
                array
xmin, xmax -    The minimum and maximum x-values to be left in the array
ymin, ymax -    The minimum and maximum y-values to be left in the array
incall -        Boolean value describing whether points are included based
                on their centroid coordinate (False), or whether any point
                in the pixel is within the specified ranges (True). Defaults
                to False.
dx, dy -        The pixel sizes of the data array.

Returns:
trimdata -      The trimmed down data array
trimxpts -      The pixel centroid x-coordinates corresponding to trimdata
trimypts -      The pixel centroid y-coordinates corresponding to trimdata

Function that trims a three-dimensional data array so that it only retains
points that are within the ranges [xmin,xmax] and [ymin,max].

Inputs:
data -          The two-dimensional data array to be acted upon
xpts, ypts -    The list of x- and y-coordinates corresponding to the data
                array
xmin, xmax -    The minimum and maximum x-values to be left in the array
ymin, ymax -    The minimum and maximum y-values to be left in the array
incall -        Boolean value describing whether points are included based
                on their centroid coordinate (False), or whether any point
                in the pixel is within the specified ranges (True). Defaults
                to False.
dx, dy -        The pixel sizes of the data array.

Returns:
trimdata -      The trimmed down data array
trimxpts -      The pixel centroid x-coordinates corresponding to trimdata
trimypts -      The pixel centroid y-coordinates corresponding to trimdata

Function flattens the input list. Input list can have arbitrary, changing depth throughout.

Inputs: x - The list to be flattened.

Returns: The flattened version of x

Computes the total flux incident from a Gaussian line profile, which has
base units of km/s. Assumes the line profile has a background height of zero
(otherwise, the integral over +-infinity would result in infinity).

Note that it has not been necessary to fully transform the Gaussian function
for integration over wavelength space. The distribution is actually already
*in* wavelength space, being expressed in units of, say, erg/cm^2/s/lambda.
However, given that its defined over velocity space (i.e. line velocity
is the x-unit), we simply have to convert the width of the Gaussian into
wavelength via sigma_lambda = sigma*restwavl / c.

Inputs:
amp -       The amplitude of the line profile. Can be passed in any units
            desired - however, the 'spectral unit' must match the unit which
            restwavl is expressed in. For example, if the line peak is
            expressedin units of erg/cm^2/s/A, the rest wavelength MUST be
            expressed in A to get the correct result.
width -     Line profile width, in km/s.
restwavl -  Rest wavelength of the line being investigated. Must be
            expressed in similar units to the line profile amplitude (see
            above).
amperr -    The uncertainty in the amplitude of the line profile, in the
            same units as amp. Defaults to 0.0.
widerr -    The uncertainty in the width of the line profile, in units km/s.
            Defaults to 0.0.
            
Returns:
lineflux -  The computed line flux. The units will mirror those used for
            the line profile amplitude, less the 'spectral unit' - e.g.
            if amplitude is passed as erg/cm^2/s/A, the flux returned will
            be in units of erg/cm^2/s.
lineferr -  The error in the computed line flux, in the same units as
            lineflux. Will come back as zero if amperr = widerr = 0.0.

Recomputes the fluxes and fluxerrs arrays of the designated velfit interest.
Designed for use when the velfit instance has been modified/damaged,
or on velfit instances made before the sqrt(2) discrepancy in the original
calculation was identified (26 Sep 12).

Inputs:
velfits -   The velfit instance to be updated. Fluxes are re-calculated
            based on the velfit.fits array.
wavlu -     The wavelength units in the flux density values. Accepted values
            are 'A' and 'um'. Defaults to 'A'.
            
Returns:
Nil. The flux and fluxerr arrays of the velfit instance are updated in-situ.

Computes the maximum allowed width for a Gaussian centered on centroid, such
that at most intpercent of the total Gaussian intensity is beyond x=0
(relative to which side of x=0 the line centroid is on). Assumes a
Gaussian of the form A.exp(-(x-x0)^2/s^2) (note no factor of 2 in the
exponent denominator).

Inputs:
centroid -      The value of the line centroid.
intpercent -    The maximum allowable percentage of the Gaussian function
                intensity (i.e. the area under the Gaussian) can be on the
                opposite side of x=0 relative to the centroid position. Must
                be a float between 0 and 1.
errfact -       The percentage error expected in the position of the line
                centroid position, which will allow for some 'wiggle room'
                in the returned width limit. Must be a float between 0 (no
                error) and 1 (error is comparable to the centroid value
                itself).
                
Returns:
widlimit -      Upper limit on Gaussian sigma (NOT FWHM). Will be returned
                in the same units as centroid.

Find the spaxel index corresponding to the given z (wavelength) value.

Inputs:
instance -      The nifscube/velfit instance to be used.
z -             The wavelength value that we wish to find the spaxel index
                for. Specified in m.
                
Returns:
j -             The spaxel y-index corresponding to the passed y-coordinate.

Find the spaxel index corresponding to the given y value.

Inputs:
instance -      The nifscube/velfit instance to be used.
y -             The y-coordinate that we wish to find the spaxel index for
useoffsets -    Specifies whether to use the raw ypts array in the instance,
                or the offset values (fitscube instance only). Defaults to
                False. An error will be thrown if useoffsets=True is passed
                in concert with a velfit instance.
                
Returns:
j -             The spaxel y-index corresponding to the passed y-coordinate.

Find the spaxel index corresponding to the given x value.

Inputs:
instance -      The nifscube/velfit instance to be used.
x -             The x-coordinate that we wish to find the spaxel index for
useoffsets -    Specifies whether to use the raw ypts array in the instance,
                or the offset values (fitscube instance only). Defaults to
                False. An error will be thrown if useoffsets=True is passed
                in concert with a velfit instance.
                
Returns:
i -             The spaxel x-index corresponding to the passed x-coordinate.

Find the spaxel index corresponding to the given x & y values.

Inputs:
instance -      The nifscube/velfit instance to be used.
x -             The x-coordinate that we wish to find the spaxel index for
y -             The xycoordinate that we wish to find the spaxel index for
useoffsets -    Specifies whether to use the raw ypts array in the instance,
                or the offset values (fitscube instance only). Defaults to
                False. An error will be thrown if useoffsets=True is passed
                in concert with a velfit instance.
                
Returns:
i -             The spaxel x-index corresponding to the passed x-coordinate.
j -             The spaxel y-index corresponding to the passed y-coordinate.

Computes the distance between two points.

Inputs: x1, y1 - First point x2, y2 - Second point

Returns: dist - The distance between the two points.

Compute the electron density equivalent to the 1.553/1.644 um [Fe II] flux ratio, as described by Pesenti et al. 2003. Result corresponds to a gas temperature of 10,000 K. Formula taken from Agra-Amboage et al. 2011.

Inputs: R - The 1.533/1.644 um [Fe II] line flux ratio.

Returns: ne - The computed electron number density. Returns units of cm^{-3}.

Returns the footprint radius (and associated uncertainty, if required) of
an MHD wind, as per Anderson et al. 2004.

Inputs:
winf -      The radius (i.e. distance from the outflow center) at which the
            poloidal and rotational velocity measurements are made, in units
            of AU.
vp -        The poloidal (i.e. downstream) outflow velocity at the point
            specified, in units of km s^-1.
vphi -      The rotational outflow velocity at the point specified, in units
            of km s^-1.
Mstar -     The mass of the central star, in units of M_sun.
doerrs -    A Boolean value, specifying whether to compute and return the
            uncertainty on the footprint radius (True) or not (False).
            Defaults to False.
winferr -   The uncertainty of the radius winf, in units of AU. Defaults to
            0.0.
vperr -     The uncertainty of poloidal velocity vp, in units km s^-1.
            Defaults to 0.0.
vphierr -   The uncertainty on the rotational velocity vphi, in units
            km s^-1. Defaults to 0.0.
Mstar -     The uncertainty on the stellar mass Mstar, in units M_Sun.
            Defaults to 0.0.

Generates a colormap based on an underlying cubic function (i.e. plotting
the variation in color as a function of x from 0 to 1 would appear to be
cubic). Note this function is designed to deal with smoothly varying
colormaps (i.e. those for which every (x,y0,y1) colormap tuple has y0 = y1)
- I have no idea what will happen if a segmented colormap is passed.

Inputs:
startcolor, -   The start and stop colours of the colormap. Should be given
stopcolor       as RGB 3-tuples.
interval -      The number of segments to break the colormap into.
                More segments will make a more 'accurate' conversion away
                from the linear colormap, but will slow down computation of
                the new colormap and make it take up more memory. It is
                recommended that trial-and-error may be useful for
                determining an adequate value for interval. Defaults to 10.

Returns:
cmap_cubic -    The cubic-based colormap. This will be a smoothly varying
                colormap, regardless of the colormap that's put in.

Generates a colormap based on an underlying quintic function (i.e. plotting
the variation in color as a function of x from 0 to 1 would appear to be
cubic). Note this function is designed to deal with smoothly varying
colormaps (i.e. those for which every (x,y0,y1) colormap tuple has y0 = y1)
- I have no idea what will happen if a segmented colormap is passed.

Inputs:
startcolor, -   The start and stop colours of the colormap. Should be given
stopcolor       as RGB 3-tuples.
interval -      The number of segments to break the colormap into.
                More segments will make a more 'accurate' conversion away
                from the linear colormap, but will slow down computation of
                the new colormap and make it take up more memory. It is
                recommended that trial-and-error may be useful for
                determining an adequate value for interval. Defaults to 10.

Returns:
cmap_cubic -    The cubic-based colormap. This will be a smoothly varying
                colormap, regardless of the colormap that's put in.

Generates a colormap based on an underlying heptic function (i.e. plotting
the variation in color as a function of x from 0 to 1 would appear to be
cubic). Note this function is designed to deal with smoothly varying
colormaps (i.e. those for which every (x,y0,y1) colormap tuple has y0 = y1)
- I have no idea what will happen if a segmented colormap is passed.

Inputs:
startcolor, -   The start and stop colours of the colormap. Should be given
stopcolor       as RGB 3-tuples.
interval -      The number of segments to break the colormap into.
                More segments will make a more 'accurate' conversion away
                from the linear colormap, but will slow down computation of
                the new colormap and make it take up more memory. It is
                recommended that trial-and-error may be useful for
                determining an adequate value for interval. Defaults to 10.

Returns:
cmap_cubic -    The cubic-based colormap. This will be a smoothly varying
                colormap, regardless of the colormap that's put in.

Generates a linearly interpolated colormap, with a 'break' in the linear
profile. The break occurs breakpc along the colormap, at a height
of breakheight.

Inputs:
startcolor -    The starting color of the colormap. Should be an RGB
                3-tuple.
stopcolor -     The end color of the colormap. Should be an RGB 3-tuple.
breakpc -       The percentage along the x-axis that the linear break
                occurs. Must be between 0 and 1.
breakheight -   The 'height' along the color axis where the break occurs.
                Must be between 0 and 1.
                
Returns:
break_cmap -    The colormap instance.

Returns a modified version of the RdYlBu colormap, where the center of the
'yellow' appears at xpt.

Inputs:
xpt -   The position in the colormap where yellow appears. Must be between
        0 and 1.
        
Returns:
modRdYlBu - The modified colormap.

Returns a RdOrYlBu (red-orange-yellow-blue) colormap.

Inputs:
orpt -      The point between 0 and 1 where the colormap returns orange.
ylpt -      The point between 0 and 1 where the colormap returns yellow.
            Must be greater than orpt.
        
Returns:
RdOrYlBu -  The modified colormap.

Returns a three-color colormap.

Inputs:
color1, color2, color3 -    The three colors to be used in the colormap.
                            Should be passed as 3-tuples.
colorpt -                   The point on the x-scale where color2 is used.
                            Must be between 0 and 1. Defaults to 0.5.
                            
Returns:
colormap -                  The requested three-color colormap.

Define a colormap with an arbitrary number of colors.

Inputs:
colors -    A list of RGB 3-tuples to be used a colors.
turnpts -   A list of turning points where colors are to be used on the
            x (0 to 1) scale. The length of this list must be two less
            than the length of the colors list (as the first and last
            colors are automatically placed at 0.0 and 1.0). If no
            turning points are passed, they are automatically generated
            in an evenly spaced fashion. Defaults to None.
            
Returns:
colormap -  The requested colormap.

Returns a three-color yellow-orange-red colormap.

Inputs:
colorpt -   The point on the color axis (0 to 1) where orange is used.
            Defaults to 0.5.
            
Returns:
colormap -  The colormap.

Returns a rainbow color map desgined by Peter McGregor.

Inputs:
Nil.

Returns:
RainbowPJM - A rainbow-style colormap, with only bright colors, and
             black and white removed.

Returns data for an PV diagram in the x-direction of a data cube.

Inputs:
nifscube    - The data cube to be operated on
y           - The y-position along which to make the cut
restwavl    - Rest wavelength used to determine line velocities. Must be
              specified in units of m.
vstart      - The start velocity of the PV diagram
vstop       - The end velocity of the PV diagram
x0          - Optional. The x-position to treat as the origin of the
              position axis. Defaults to 0.
xstart      - Optional. The x-position to treat as the start of the position
              axis, or None to use to start of the coordinates in the
              nifscube. Defaults to None.
xstop       - Optional. The x-position to treat as the end of the position
              axis, or None to use to end of the coordinates in the
              nifscube. Defaults to None.
useoffsets  - Optional. Boolean value specifying whether to use offset
              spatial coordinates or original coordinates. Defaults to
              True (offset coordinates).

Returns:
pos         - The array of positions for plotting
vel         - The array of velocities for plotting
PVdata      - The data the be plotted onto the PV diagram. Conforms to
              the Python standard for having point (x,y) located in the
              array at PVdata[y,x].

Returns data for an PV diagram in the x-direction of a data cube.

Inputs:
nifscube    - The data cube to be operated on
xpos        - The y-position along which to make the cut
restwavl    - Rest wavelength used to determine line velocities. Must be
              specified in units of m.
vstart      - The start velocity of the PV diagram
vstop       - The end velocity of the PV diagram
y0          - Optional. The x-position to treat as the origin of the
              position axis. Defaults to 0.
ystart      - Optional. The x-position to treat as the start of the position
              axis, or None to use to start of the coordinates in the
              nifscube. Defaults to None.
ystop       - Optional. The x-position to treat as the end of the position
              axis, or None to use to end of the coordinates in the
              nifscube. Defaults to None.
useoffsets  - Optional. Boolean value specifying whether to use offset
              spatial coordinates or original coordinates. Defaults to
              True (offset coordinates).

Returns:
pos         - The array of positions for plotting
vel         - The array of velocities for plotting
PVdata      - The data the be plotted onto the PV diagram. Conforms to
              the Python standard for having point (x,y) located in the
              array at PVdata[y,x].

Returns data for an PV diagram in the x-direction of a data cube.

Inputs:
velfit      - The velocity fit to be operated on
comp        - The component of the velocity fit to be displayed
y           - The y-position along which to make the cut
vstart      - The start velocity of the PV diagram
vstop       - The end velocity of the PV diagram
x0          - Optional. The x-position to treat as the origin of the
              position axis. Defaults to 0.
xstart      - Optional. The x-position to treat as the start of the position
              axis, or None to use to start of the coordinates in the
              velfit. Defaults to None.
xstop       - Optional. The x-position to treat as the end of the position
              axis, or None to use to end of the coordinates in the
              velfit. Defaults to None.

Returns:
pos         - The array of positions for plotting
vel         - The array of velocities for plotting
PVdata      - The data the be plotted onto the PV diagram. Conforms to
              the Python standard for having point (x,y) located in the
              array at PVdata[y,x].

Returns data for an PV diagram in the y-direction of a data cube.

Inputs:
velfit      - The velocity fit to be operated on
comp        - The component of the velocity fit to be displayed
x           - The x-position along which to make the cut
vstart      - The start velocity of the PV diagram
vstop       - The end velocity of the PV diagram
x0          - Optional. The y-position to treat as the origin of the
              position axis. Defaults to 0.
ystart      - Optional. The y-position to treat as the start of the position
              axis, or None to use to start of the coordinates in the
              velfit. Defaults to None.
ystop       - Optional. The y-position to treat as the end of the position
              axis, or None to use to end of the coordinates in the
              velfit. Defaults to None.

Returns:
pos         - The array of positions for plotting
vel         - The array of velocities for plotting
PVdata      - The data the be plotted onto the PV diagram. Conforms to
              the Python standard for having point (x,y) located in the
              array at PVdata[y,x].