GradPak_bin

This module provides useful functions for binning GradPak fibers together to achieve higher Signal to Noise (SNR). Given a desired SNR the algorithm will bin fibers together until either the SNR or the end of a row is reached. The current main limitation with this algorithm is that it will not smartly add a single fiber at the end of a row to the preceeding bin even if that single fiber has a low SNR.

There are many ways to compute the SNR, this module does it simply:

SNR = <signal/noise>

where signal are the values in the datafile and noise are the values in the errfile.

In addition to generating binned spectra this module provides a method for computing the location of each bin, in arcsec or kpc, in a coordinate system defined by the user (usually relative to some galaxy’s center).

Useful Example

For my NGC 891 work I use:

>>> GPB.bin('NGC_891_P3.ms_rfs_lin.fits','NGC_891_P3.mse_rfs_lin.fits',30,'NGC_891_P3_bin30',exclude=[92,93])
>>> GPB.create_locations('NGC_891_P3_bin30.ms.fits',ifucenter=[35.636325,42.37935])

Functions

GradPak_bin.bin(datafile, errfile, SNR, outputfile, waverange=None, exclude=[], logfile=None, logfits=None)

Bin GradPak fibers along a row until the desired SNR is achieved.

The way fibers are grouped together is somewhat simplistic, but the underlying mathematics is correct.

The first bin starts at the smallest non-sky, non-excluded fiber (usually fiber #3) and just keeps adding the next fiber until the desire SNR is reached. Fibers are not binned across rows, which ensures that each bin is made up only of fibers of one size, but also limits the amount of binning that can be done. The major limitation of this method is that the ends of rows can often be left with a single, low SNR fiber. For example, if a bin is constructed containing fibers 14-16 and fiber 17 (at the end of the row) is below the threshold it will not be added to the previous bin and instead will make up a single bin with low a low SNR. This should be easy to fix but in practice it doesn’t cause that much of an issue so I just haven’t done it.

The spectrum for each bin is an average of all the contributing fibers, weighted by each individual’s SNR^2. The corresponding error bin is a sum in quadrature, weighted in the same way.

The history of each bin is recorded in the output FITS header using two keywords:

BINXXXF The fibers that went into bin XXX

BINXXXP The position (in arcsec) of the center of bin XXX. This is

the unweighted average of the centers of the contributing fibers.

Parameters:

datafile : str

The name of a multispec FITS file that you want to bin

errfile : str

The name of a multispec FITS file containing error vectors corresponding to the datafile

SNR : float

The minimum SNR in each bin

outputfile : str

The base name of the binned spectral and error arrays. The results will be called OUTPUTFILE.ms.fits and OUTPUTFILE.me.fits.

waverange : list (default: None)

A 2 element list containing the minimum and maximum wavelengths to consider for the SNR calculations. Regardless of this parameter the final output will span the same wavelength range as the input files.

exclude : list (default: [])

A list containing fibers to exlcude from binning. Sky fibers are automatically excluded and fiber numbers start at 1.

logfile : str

Name of a log file that will contain, for each aperture, a list of the individual fibers and the total S/N.

logfits : str

Name of a FITS file that will contain a separate HDU for each aperture. Each HDU will contain an array with two dimensions that records the fiber numbers and associated weights for that aperture.

Returns:

finalf : numpy.ndarray

Array with shape NBINS x NWAVE containing the binned data

finatle : numpy.ndarray

Array with same shape as finalf containing the errors on the binned data

fibdict : dict

Dictionary of questionable usefulness that contains information about which fibers went into each bin. The keys are ROW_BIN and the entries are a list of the fibers that went into that bin (e.g., ‘1_2’ for the second bin in the first row).

GradPak_bin.compute_SN(signal, noise, idx=None)

Given signal and noise vectors, compute the SNR (possibly over a specific range).

Parameters:

signal : numpy.ndarray

A 1D vector of data values

noise : numpy.ndarray

A 1D vector of error values

idx : numpy.ndarray (default=None)

A 1D vector containing the index values of a sub region used to compute the SNR

Returns:

SNR : float

The signal to noise. Computed simply as <signal/noise>

GradPak_bin.create_bin(fstack, estack, snstack)

Weight and combine data and errors into new bins.

The weights are simply SNR^2.

Parameters:

fstack : numpy.ndarray

A NxM array where of data values N is the number of fibers to add to the bin and M is the number of wavelength channels. Generally the 1st element of this array is the current bin, not an individual fiber.

estack : numpy.ndarray

The errors corresponding to fstack. Should be the same shape as fstack

snstack : numpy.ndarray

Array containing the SNR of each of the N entries in fstack

Returns:

newbin : numpy.ndarray

Array of length M containing the weighted average of fstack

newerr : numpy.ndarray

Array of length M containing the errors on newbin. Errors are combined in weighted quadrature.

GradPak_bin.create_locations(binfile, galcenter=[35.637962, 42.347629], ifucenter=[35.637962, 42.347629], reffiber=105, galpa=293.3, ifupa=295.787, kpc_scale=0.0485)

Given a binned data file, creat a list of bin locations, relative to a galactic center.

The function is designed to give physical meaning to the location of each bin created by bin(). For each bin found in the FITS header it computes physical coordinates in both arcsec and kpc. This method was written with a 2D projection of cylindrical coordinates in mind (r,z), but the user is free to fully define the location and meaning of the coordinate system through keyword options.

The output is a text file containig the location of each bin in the desired coordinate system.

The current defaults are for NGC 891 and WIYN proposal 14B-0456. You should probably change them.

Parameters:

binfile : str

The name of a FITS file produced by bin()

galcenter : list, optional

A list containing the [RA,DEC] coordinates of the center of the coordinate system. The units are decimal degrees.

ifucenter : list, optional

A list containing the center of the fiber specified in reffiber. Units are decimal degrees. This is usually the coordinates of your GradPak pointing.

reffiber : int, optional

The fiber number whoes coordinates are given in ifucenter. This is generally the fiber you used to align GradPak during observations.

galpa : float, optional

The position angle of the desired coordinate system. This angle defines rotation of the horizontal axis relative to the sky.

ifupa : float, optional

The position angle of GradPak. This is defined as an absolute PA, relative to North, not to the defined coordinate system. This is generally the PA you entered during GradPak observations.

kpc_scale : float, optional

kpc/arcsec of the object in question

Returns:

None :

The result is file with the suffix “locations.dat” that contains information about the location in the user defined coordinates of each aperture (bin). Coordinates are given in arcsec and kpc. Note that the reported “size” is the size of the fibers that went into each bin, not the size of the bin itself. This is admittedly confusing.