GradPak_plot

This module contains an API for plotting data taken with GradPak. At it’s heart it contains hardcoded information about the location of all the GradPak fibers on the sky, which can then be used to make nice plots with pyplot’s Patch Collection object.

User interaction should be limited to the plot*() functions, all of which, at their most basic level, take in an array of length 109 (the number of GradPak fibers) and return an pyplot Axes object containing a plot that can be further modified by the user. Specific details about the plot*() functions and their copious advanced options can be found below.

Useful Example

An extremely basic example can be used to plot the GradPak fibers color coded by fiber number:

>>> ax = GradPak_plot.plot(np.arange(109))
>>> ax.figure.show()

More options, including synergy with GradPak_bin, FITS image overplotting, rotations, and more can be found in plot(), which is really the only function you should ever use.

Functions

GradPak_plot.GradPak_patches()

Produce the “data” of where the GradPack fibers live. Because we’re all about plotting, these data are stored as pyplot Patches. Fiber locations are given in arcsec relative to the central, bottom row fiber (fiber 10).

Returns a tuple of fiber number and the corresponding Patch

GradPak_plot.exclude_bins(header, exclude)

Convert an exclusion vector using binned apertures to an exclusion vector using raw GradPak fibers.

When using a binheader the user will specify excluded data by aperture number. This function converts these numbers to the range of underlying GradPak fiber numbers, which is what prep_patches() and its ilk expect.

GradPak_plot.fill_fibers_with_bins(header, values)

Given a FITS header containing information about the fibers in each bin return a list of values where each individual GradPak fiber is assigned the value of its corresponding bin.

This function is useful if you want to plot every GradPak fiber, but fill them with binned data values.

GradPak_plot.format_tpl(tpl)

Take in a ds9 .tpl file and print out corresponding pyplot Patch definitions.

WARNING: It is almost certainly the case that ds9 template files are NOT listed in fiber order. It is therefore NOT SAFE to assume that the output of this function can be used to produce something like GradPak_patches(). Manual confirmation of fiber order is crucial.

GradPak_plot.get_bin_boxes(header, patches, pval)

Given a FITS header containing binning information return a list of pyplot Polygon objects that can be used to plot boxes around all the fibers in a given bin.

GradPak_plot.get_binned_patches(header)

Produce patches from the header of a GradPak multispec data file produced by GradPak_bin.

The output is interchangeable with the output of GradPak_patches()

GradPak_plot.plot(values, binheader=None, plotbins=False, ax=None, figsize=(8, 8), figure=None, geometry=(1, 1, 1), fitsfile=None, imrot=False, wcsax=True, invert=True, pa=0, center=[0, 0], reffiber=105, alpha=1.0, clabel='', cmap='gnuplot2', minval=None, maxval=None, labelfibers=True, sky=False, exclude=[])

Generate a spatial plot of the GradPack IFU fibers with each fiber colored based on user-supplied values. This is one of the main user-level functions in this module, and returns an Axes object for integration into whatever higher-level plotting the user is doing.

It is of the utmost importance that the values input variable is of length 109 and is ordered by fiber number.

A quick example of how to use this function:

>>> GradPak_plot.plot(np.arange(109)).figure.show()

This will show you a simple plot with the fibers colored by their fiber number and presented on a relative arcsec scale. More advanced usage can be achieved with the following options:

Parameters:

values : numpy.ndarray

The data values associated with each fiber. The length of this array should be equal to either 109 or the number of bins specified in binheader.

binheader : pyfits.header.Header

A FITS header that contains keywords BINFXXX and BINPXXX. This header will be used to group fibers together during plotting.

plotbins : bool

An extremely poorly named parameter. If True, plot every fiber (not aperture) with a value given by the value of its aperture assignment as specified by binheader. If False the apertures specified by binheader will be plotted as contiguous regions.

alpha : float

The desired opacity of the plotted patches.

ax : matplotlib.axes.Axes

If supplied, the GradPack patches will be plotted in this axis. This is very useful for plotting multiple pointings on the same plot. Setting this option causes fitsfile, imrot, invert, and wcsax to be ignored.

figure : matplotlib.pyplot.Figure instance

If not None, the axis object created by plot() will be placed into this figure with the geometry specified by geometry.

figsize : tup

The size of the figure, in inches. Passed directly to plt.figure(). This option is ignored if figure is not None

geometry : int or tup

A pyplot-style geometry argument for placing the axis in its parent figure. Can be a 3 digit integer (e.g., 111) or a tuple (e.g., (1,1,1)

fitsfile : str -

The name of a FITS image to draw on the plot. The FITS header must contain WCS parameters in the CDELT, CRVAL, CRPIX format.

imrot : float

Rotation of fits image in relation to the axes. This is useful for, e.g., aligning a galaxy’s major axis along the x axis. This option is ignored if fitsfile = None or ax != None

wcsax : bool

If True the axis labels will be in Fk5 WCS coordinates. This option is ignored if fitsfile = None or ax != None

invert : bool

If True, the colormap of the fits image will be inverted. This option is ignored if fitsfile = None or ax != None

pa : float

Position angle of GradPak in decimal degrees. This angle is measured East of North and should be whatever you told the telescope operator.

center : tup or list

Length 2 tuple or list containing the coordinates of the GradPak array. The units should be decimal Ra and Dec. This is probably the coordinates you had listed in your cache.

reffiber : int

The IFU fiber placed at the coordinate given in center. Default is fiber 105.

clabel : str

The label of the colorbar. This is typically a description of the values being plotted.

cmap : str

The name of a matplotlib colormap that will be applied to the data values. This is passed directly to plt.get_cmap() Don’t use ‘jet’.

minval/maxval : float

The lower and upper limits of the colorbar, respectively. These are passed directly to matplotlib.colors.Normalize()

labelfibers : bool

If True, each fiber will be labeled with its fiber number.

sky : bool

If True, sky fibers will be plotted and the axes limits expanded to view the sky fibers.

exclude : list

A list of fiber numbers to be excluded from plotting. These patches are simply deleted.

Returns:

ax : matplotlib.axes.Axes

The Axes containing all the plotting requested.

GradPak_plot.plot_img(values, ax=None, figsize=(8, 8), fitsfile=None, imrot=False, invert=True, pa=0, center=[0, 0], reffiber=105, clabel='', cmap='gnuplot2', minval=None, maxval=None, numpoints=500, method='nearest', sky=False, exclude=[])

Generate an interplotaed image of the GradPak IFU using user supplied values. This is one of the main user-level functions in this module, and returns an Axes object for integration into whatever higher-level plotting the user is doing.

It is of the utmost importance that the values input variable is of length 109 and is ordered by fiber number.

A quick example of how to use this function:

>>> GradPak_plot.plot_img(np.arange(109)).figure.show()

This will show you a simple image of GradPack colored by fiber number and presented on a relative arcsec scale. More advanced usage can be achieved with the following options:

Input Options:

o ax (pyplot.Axes) - If supplied, the GradPack image will be plotted

in this axis. This is very useful for plotting multiple pointings on the same plot. Setting this option causes fitsfile, imrot, invert, and wcsax to be ignored.

o figsize (tup) - The size of the figure, in inches. Passed directly

to plt.figure()

o fitsfile (str) - The name of a FITS image to draw on the plot. The

FITS header must contain WCS parameters in the CDELT, CRVAL, CRPIX format.

o imrot (float) - Rotation of fits image in relation to the axes. This

is useful for, e.g., aligning a galaxy’s major axis along the x axis. This option is ignored if fitsfile = None or ax != None

o wcsax (bool) - If True the axis labels will be in Fk5 WCS

coordinates. This option is ignored if fitsfile = None or ax != None

o invert (bool) - If True, the colormap of the fits image will be

inverted. This option is ignored if fitsfile = None or ax != None

o pa (float) - Position angle of GradPak in decimal degrees. This

angle is measured East of North and should be whatever you told the telescope operator.

o center (tup or list) - Length 2 tuple or list containing the

coordinates of the GradPak array. The units should be decimal Ra and Dec. This is probably the coordinates you had listed in your cache.

o reffiber (int) - The IFU fiber placed at the coordinate given in

center. Default is the lower left fiber (viewed on Wifoe), which is fiber 105.

o clabel (str) - The label of the colorbar. This is typically a

description of the values being plotted.

o cmap (str) - The name of a matplotlib colormap that will be applied

to the data values. This is passed directly to plt.get_cmap()

o minval/maxval (float) - The lower and upper limits of the colorbar,

respectively. These are passed directly to matplotlib.colors.Normalize()

o numpoints (int) - The number of points to use when interpolating the

GradPak IFU. This is actually the number of points to interpolate over in each dimension, so the total number of points will be numpoints**2

o method (str) - The interpolation method used. This is passed

directly to spi.griddata(). The available options are:

‘nearest’, ‘linear’, ‘cubic’

o sky (bool) - If True, sky fibers will be plotted and the axes limits

expanded to view the sky fibers.

o exclude (list) - A list of fiber numbers to be excluded from

plotting. These patches are simply deleted

Output:

ax (pyplot.Axes) - The Axes containing all the plotting requested.

GradPak_plot.plot_rows(values, binheader=None, ylabel='', label='', ax=None, fullout=False, weights=None, err=False, kpc_scale=None, zcorr=0, **plot_kwargs)

Bin values by GradPak row and produce a plot of the results. Each row’s value is the weighted average of the fibers in that row. This is one of the main user-level functions in this module, and returns an Axes object for integration into whatever higher-level plotting the user is doing.

It is of the utmost importance that the values input variable is of length 109 and is ordered by fiber number.

A quick example of how to use this function:

>>> GradPak_plot.plot_img(np.arange(109)).figure.show()

This will show you a simple image of GradPack colored by fiber number and presented on a relative arcsec scale. More advanced usage can be achieved with the following options:

Input Options:

o ylabel (str) - Y axis labels. If ax != None this option is ignored.

o label (str) - Label applied to plotted lines. Useful for any future

calls to ax.legend()

o ax (pyplot.Axes) - If supplied, the GradPack patches will be plotted

in this axis. This is very useful for plotting multiple pointings on the same plot. Setting this option causes fitsfile, imrot, invert, and wcsax to be ignored.

o weights (length 109 numpy array) - Weights to be applied to

individual fibers when averaging rows together. If None then all fibers are assumed to have equal weight.

o err (bool) - If True the standard error is used for error bars. If

False then the weighted standard deviation is used for plot error bars.

o kpc_scale (float) - Kpc/arcsec scale used to convert height (x axis)

to something meaningful.

o fullout (bool) - If True the binned values and associated errors are

returned along with the Axes.

o **plot_kwargs (dict) - Plotting keywords passed directly to

ax.errorbar

Outputs:

o ax (pyplot.Axes) - The Axes containing all the plotting requested.

o abcissa (ndarray) - The height of each binned row. If kpc_scale was

set then the units of abcissa are kpc, otherwise they are arcsec.

o binned_vals (ndarray) - The binned (weighted avg.) values of each

GradPak row.

o binned_errs (ndarray) - The standard error of each row

o binned_stds (ndarray) - The weighted standard deviation of each row

GradPak_plot.prep_axis(fitsfile=None, invert=True, sky=False, imrot=False, wcsax=True, figure=None, figsize=(8, 8), geometry=(1, 1, 1))

Create a pyplot Axes object and get it ready to receive some GradPack patches. This includes the creation of a colorbar and setting reasonable limits on the plot. It is also possible to provide a FITS image that will be displayed on the axes with WCS axis labels.

Parameters:

fitsfile : str

The name of a fits file to plot. This file MUST have a well formed, useful header.

invert : bool

If a fitsfile is provided, do you want to invert the colormap?

sky : bool

Do you want to show sky fibers in the plot?

imrot : float

The angle (in degrees, E of N) to rotate the fitsfile by

wcsax : bool

Display axis labels in WCS coordinates?

figsize : list or tuple

Width x height of figure, in inches

figure : matplotlib.pyplot.Figure instance

If not None, the axis object created by will be placed into this figure with the geometry specified by geometry.

geometry : int or tup

A pyplot-style geometry argument for placing the axis in its parent figure. Can be a 3 digit integer (e.g., 111) or a tuple (e.g., (1,1,1)

Returns:

ax : matplotlib.axes.Axes

The requested axis, all setup and ready for plotting

hdu : None or pyfits.PrimaryHDU

The HDU used to create the WCS axis

GradPak_plot.prep_patches(values, binheader=None, plotbins=False, hdu=None, pa=0, center=[0, 0], reffiber=105, sky=False, exclude=[])

Generate GradPak patches and prepare them for plotting. This function is used to transform the patches and remove any unwanted fibers (sky or user defined).

Parameters:

values : numpy.ndarray

Should be length 109 and contain the data value of each fiber, in order.

binheader : pyfits.header.Header

A header (probably produced by GradPak_bin) containing information on what fibers went into what apertures

plotbins : bool

Somewhat strangely named; if True plot the raw GradPak fibers, regardless of aperture assignment (the actual fiber values will still be taken on an aperture-by-aperture basis).

hdu : pyfits.PrimaryHDU

Contains a header with a WCS solution that is used to transform the patches.

pa, center, reffiber : float

Parameters that describe how to transform the patches. See transform_patches() for more info.

sky : bool

If True, plot sky fibers

exclude : list

List of fiber numbers to be excluded from the plot. If a binheader is provided this list should contain aperture numbers, not fiber numbers.

Returns:

patches : list of matplotlib.patches.Circle

Transformed and culled list of pyplot Patch objects

pvals : numpy.ndarray

Culled list of values so that pval[i] is the value of patch[i]

refcenter : list of float

The pixel center of the reference fiber

GradPak_plot.transform_patches(patches, pa=0, center=[0, 0], reffiber=105, scale=1.0, refpatches=None)

Rotate and shift the centers of the GradPak Patches.

Parameters:

patches : list of matplotlib.patches.Circle

GradPak patches produced by GradPak_patches()

pa : float

Position angle, in degrees, of GradPak on sky.

center : list

Tuple or length 2 list containing the position, in decimal degrees, of the fiber specified in reffiber

reffiber : int

The fiber to place at center

scale : float

Radial scale factor, in px/arcsec. This is needed because Patches are plotted in pixel space.

refpatches : None or list of matplotlib.patches.Circle

A full set of all GradPak patches that are used to compute the transformed locations of binned patches.

Returns:

patches : list of pyplot.Patches

The shifted, rotated, and scaled patches

GradPak_plot.wcs2pix(patches, header)

Given a pyfits header object, convert the centers of the GradPak patches from WCS coordinates (decimal degrees) to pixel coordinates on the corresponding FITs file. Radial scaling is done as part of transform_patches().