The Solar-Stellar Spectrograph

ARTICLE

SSS

The SSS class encapsulates all SSS project data reduction commands. Reducer objects and OIL system objects are created and used by the many methods of this class.

While the other classes in the class library documented here are meant to be fairly general, this class is quite specific to the needs of the Solar-Stellar Spectrograph project. We document it here to ensure transparency of our reduction methods, but the system as documented here depends on the file structure of our system here at Lowell and will not function correctly on other systems unless identically configured. link Look here for a discussion of this configuration.

Data Members

string dbPath

float[512,20] solarRefSpec

Filestream resFile

FITSData data

Bias bias

Ordermap ordermap

ScatteredLight scatteredLight

Flat flat

Spectrum spectrum

WaveCal waveCal

WaveCal waveCalNew

Normalizer normalizer

Method List

make_stellar_hkstack

match_flat( )

ordermap_results( )

preprocess_solar

preprocess_stellar

read_bias_diagnostics

read_ordmap_diagnostics( )

Method Descriptions

FUNCTION bias_results

keyword bool solar

keyword bool countFilesOnly

Calls SSS::read_bias_diagnostics, SSS::read_solar_log, SSS::read_stellar_log, Filestream::get_data

Return int biasEntries

This method displays plots of the mean bias level and its standard deviation for the red and blue frames over the duration of the SSS project (1994 to present). The data are assumed to be in the bias diagnostics file stored in the SSS resource directory. If the solar keyword is set, the solar bias data are displayed; otherwise, the stellar bias data are displayed. The method color codes echelle data with red, yellow, and green points for object, flat field, and ThAr frames, respectively. The HK data are analogously colored as blue, light blue, and green. If the countFilesOnly keyword is set, then the routine just returns the number of entries found in the requested diagnostic file.

This is a utility method intended it give a quick check on the long-term trends in the background ADU level on the SSS CCDs. A scalar offset is applied to the data beginning in 2008, since the new CCDs have significantly different bias levels than the old ones. We subtract 450 from the blue ADU and 3450 from the red ADU beginning in 2008. Additionally, many of the blue frames are adjusted by 8192 ADU to counteract the effects of a stuck bit in the old blue CCD's A/D converter.

Details of the debiasing procedure can be found here.

PRO cleanup

Destructor. Calls Obj_Destroy on all member objects.

PRO debias

argument long frame

keyword bool solar

keyword bool stellar

keyword bool swap

keyword string star

Calls Filelink::set_datafile, Filelink::read, Filelink::write, FITSdata::get_header, FITSdata::get_image, Image:byteswap, BasicFITSHeader::get_card_image, BasicFITSHeader::set_card_image, Image::set_data_type, Image::get_image_ptr, Bias::set_overscan, Bias::go, Bias::get_stats, Tool::attach_data, Tool::detach_data

This method removes the electronic bias from the CCD frames. It will use solar log data and solar data frames if the solar keyword is set, and stellar log data and data frames if the stellar keyword is set. The swap keyword forces data byte swapping if necessary. The frame argument gives the SSS frame number of the frame to be debiased. The star keyword can be set to direct the diagnostic output to a file called [star]_bias_diag.txt rather than the full diagnostic file.

When reducing SSS data, we do not call this method directly. It is used by the reduce_solar, reduce_stellar, and reduce_star methods that automate the complete reduction process.

As with all the principal SSS reduction methods, we use the philosophy that all intermediate data reduction steps should be stored (if only temporarily) and diagnostic information written to a text file. We control whether we work with solar or stellar data via the analogous keywords. We also include the capability to reduce SSS stellar spectra for a given star, rather than by a sequential set of frame numbers, with the star keyword.

This method is hard-wired to the SSS project and is not intended to work with an arbitrary CCD frame. It assumes the data are a 512 x 400 array, with rows 1-32 being the HK order and 33-399 the echelle. "Overscan" regions that define the CCD background are set to spectrum-free areas of the image, and Bias::go is called in its "scalar" mode to remove the mean of the overscan from the blue and red portions of the frame separately.

Details of the debiasing procedure and its results can be found here.

PRO define

Structure definition. Specifies the contents of the IDL structure instantiated by the SSS class. Used by Obj_New; do not invoke directly.

PRO flat

argument long frame

keyword bool solar

keyword bool stellar

keyword bool makeFlat

Calls Filelink::set_datafile, Filelink::read, Filelink::write, FITSdata::get_header, FITSdata::get_image,Image::get_image_ptr, Spectrum::set_order_width, Spectrum::load_order_map, Spectrum::go, Spectrum::store_spectrum, Flat::set_makeflat_mode, Flat::set_order_width, Flat::load_ordermap, Flat::load_flat_spectrum, Flat::load_fit_pts, Flat::go, Flat::get_flat_spectrum, Flat::get_flat_fit, Flat::store_flat_spectrum, Flat::store_flat_fit, Tool::attach_data, Tool::detach_data

This method manages flat fielding of the CCD frames. It will use solar log data and solar data frames if the solar keyword is set, and stellar log data and data frames if the stellar keyword is set. The makeflat keyword is set, the method assumes the frame being reduced is a flat field frame, and will create flat field spectrum information from it. Otherwise, the method assumes the frame is an object frame, and will divide it by the nearest (in time) available flat field spectrum.

When reducing SSS data, we do not call this method directly. It is used by the reduce_solar, reduce_stellar, and reduce_star methods that automate the complete reduction process.

Details of the flat fielding procedure and its results can be found here.

FUNCTION flat_results

keyword bool solar

keyword bool countFilesOnly

Calls SSS::read_ordmap_diagnostics, SSS::read_solar_log, SSS::read_stellar_log, Filestream::get_data

Return int ordmapEntries

This method loads and generates plots of the flat field spectra and blaze functions. It is a utility method intended it give a quick check on the long-term trends of the SSS flat fields.

Details of the flat fielding procedure can be found here.

FUNCTION get_star_obs

keyword bool star

Calls Filestream::get_data

Return struct[] log

Searches the entire stellar observing log and returns all entries for star.

FUNCTION init

Return bool !TRUE

Constructor. Due to the number of tasks performed by this class, init takes several actions.

The constructor first sets up some general quantities needed. It opens IDL windows and sets the output device to use decomposed color. It initializes the system path data member dbPath to the value !DBPATH specified in the startup file. Finally, it loads the high resolution Kurucz solar spectrum, degraded to the resolution of the SSS and selected for the proper wavelength range for each of the 20 orders in an SSS spectrum, into the solarRefSpec data member.

PRO make_fits

argument struct logRec

keyword bool solar

keyword bool stellar

Calls FITSData::get_header, FITSData::get_image, Image::get_image_ptr, Image::get_data_type, BasicFITSHeader::set_card_image

Creates a simple FITS header based on the contents of the observation log record passed in the argument. Set the solar keyword if a solar data frame is being processed, and the stellar keyword if a stellar frame is being processed. In practice, this routine is not called directly, but is used by preprocess_solar and preprocess_stellar.

PRO make_wavecal

argument int ordLen

argument int numOrds

argument string refSpec

argument string refFile

keyword bool solar

This method allows one to fit an extracted Thorium-Argon emission spectrum to a set of laboratory wavelengths to create a wavelength solution for a spectrum or spectra.

The first two arguments specify the order length and number of orders; for SSS data, ordLen is 512, while numOrds is either 20 or 16. The method then needs two other files: refSpec is an extracted ThAr spectrum in the solar or stellar reducing/ directory (i.e., a .spec file), and refFile is the list of rest wavelengths and approximate pixel locations of strong ThAr lines in the SSS spectrum. We have created two such files that live in the main res directory, one for the old camera spectra (wavecal_pts.txt) and one for the new (wavecal_pts_new.txt). As usual, the solar keyword tells the method if we are calibrating a solar or stellar ThAr spectrum (this is only needed so that the method will know in which reducing directory to look for the ThAr spectrum).

A typical calling sequence for this method therefore is:

sssObj->make_wavecal, 512, 16, '06303', 'wavecal_pts_new', /solar, /inspect

The inspect keyword causes the routine to pause after fitting each order and display a plot of the ThAr order, the fits, and the residuals to the fit. If not set, it just plows through without stopping.

The method writes two binary files to the main res directory: [refSpec].cal and refSpec].wave. The .cal file contains the calibration coefficients determined for each order. (There will be three for each order, since a second order polynomial is used to fit the wavelengths.) The .wave file contains the actual wavelengths at each pixel; it therefore has the same dimensions as the solar or stellar spectra.

The method fits line centroids using IDL's gaussfit function with NTERMS = 3. If a fit fails and yields a centroid out of range (less than 0 or greater than 511), the method will print a warning to stdout and set the fitted pixel to the initial value from the refFile.

PRO make_stellar_hkstack

argument string star

argument float bv

keyword long startAt

keyword bool swap

keyword bool inspect

keyword bool saveHK

keyword bool noPlot

Calls SSS::get_star_obs, FITSData::get_header, FITSData::get_header, FITSData::get_image, Image::get_image_ptr

Prepares HK spectra of the star spectified by star for analysis. Normalized (.nrm) spectra are assumed to exist for the star in question. The method reads in all observations for the star and renormalizes the HK order to an absolute intensity scale. This renormalization depends on the star's B-V color, so this must be supplied in the bv argument.

Several keywords are available to customize the routine. startAt allows specification of a starting frame, for inspection of new spectra. swap enables byteswapping of data. Normally the routine puts up a detailed plot of the renormalized spectrum; this can be suppressed with noPlot, and the routine can be halted after each plot with inspect. Ordinarily, the renormalized HK spectrum is not saved, but this can be enabled with saveHK.

FUNCTION match_flat

argument long frame

keyword bool solar

Return string flatID

This method compares a numbered frame to the set of frame numbers in the observing log and returns the flat field frame nearest in time to it. If the solar keyword is set, the solar log is searched; otherwise, the stellar log is searched.

FUNCTION ordermap_results

keyword bool solar

keyword bool countFilesOnly

Calls SSS::read_ordmap_diagnostics, SSS::read_solar_log, SSS::read_stellar_log

Return int ordmapEntries

This method reads the ordermap diagnostic file, which is just a record of the order peak locations at the central pixel along the dispersion axis, and displays the drift in the order locations over time. If the countFilesOnly keyword is set, then the routine just returns the number of entries found in the file.

This is a utility method intended it give a quick check on the long-term trends in the ordermap location on the SSS CCDs. A scalar offset is applied to the data beginning in 2008, since the new CCDs have the orders placed somewhat differently relative to the origin (and have only 16 extractable orders rather than 20).

Details of the order map tracing procedure can be found here.

PRO preprocess_solar

keyword int startAt

Calls SSS::read_solar_log, SSS::make_fits, Filestream::get_data, Filelink::close_datafile, Filelink::write, FITSdata::get_image, FITSdata::write, Image::get_image_ptr, Image::new_data_array, Image::byteswap, Image::rotate, Image::read

Carries out preprocessing of raw solar data frames in the solar/raw directory in the SSS archive. Any frames found are rotated to row-major orientation with wavelength increasing to the right (increasing x) and up (increasing y). Data frames after 2007 are byteswapped. The routine builds a simple FITS header from the information in the log, and writes the file, with a .fits extension, to the solar/raw_fits directory. Set the startAt keyword to specify the first SSS frame number that will be preprocessed.

PRO preprocess_stellar

keyword int startAt

Calls SSS::read_stellar_log, SSS::make_fits, Filestream::get_data, Filelink::set_datafile, Filelink::set_datafile, Filelink::open_datafile, Filelink::stat_datafile, Filelink::write, FITSdata::get_image, FITSdata::write, Image::get_image_ptr, Image::new_data_array, Image::byteswap, Image::rotate, Image::read

Carries out preprocessing of raw stellar data frames in the stellar/raw directory in the SSS archive. Any frames found are rotated to row-major orientation with wavelength increasing to the right (increasing x) and up (increasing y). Data frames after 2007 are byteswapped. The routine builds a simple FITS header from the information in the log, and writes the file, with a .fits extension, to the stellar/raw_fits directory. Set the startAt keyword to specify the first SSS frame number that will be preprocessed.

PRO read_bias_diagnostics

keyword bool solar

Calls Filestream::read, Filestream::reset_all

Reads the file containing the diagnostic output of the debiasing step of data reduction. For each frame in the data set, we store the output of IDL's Moment routine, as well as the minimum ADU level after debiasing, for the red and blue CCDs individually. If the solar keyword is set, the method will get the solar debias data; otherwise, it gets the stellar debias data.

FUNCTION read_ordmap_diagnostics

keyword bool solar

Return float[ ] ordmapLocs

Reads the file containing the diagnostic output of the ordermap creation step of data reduction. For each frame in the data set, we store the location of each order centroid at the central pixel along the dispersion axis. There are 20 centroids for pre-2008 data, and 16 for 2008+ data. If the solar keyword is set, the method will get the solar debias data; otherwise, it gets the stellar debias data. The data are returned as an array of floats, with each row of the array containing the frame number and the ordermap locations. For the 2008+ data, the locations of orders 17-20 are set to 0.0.

PRO read_solar_log

keyword int[ 2 ] frames

Calls Filestream::reset_all, Filestream::read, Filestream::crop_data

Reads the solar log into the SSS object's resFile data member. We maintain the electronic log in an Excel spreadsheet. The log read by this routine is a formatted ASCII file solar_obslog.txt, exported from the Excel spreadsheet, in the res directory in the SSS data archive. It has 12 columns (frame #, frame type [solar or flat], year, day of year, UT hour at the midpoint of the solar exposures, minute at midpoint of solars, exposure duration in seconds, four temperatures [room, coffin, red CCD, blue CCD], and observer number0. The columns are formatted per the following IDL code:

format = '( I5.5, X, I1, X, I4.4, X, I3.3, X, 3( I2.2, X ), 4( F5.1, X ), I2.2 )'.

The structure associated with the Filestream object is created with the appropriate tags and types, and the data read in.

If the frames keyword is set, the data structure is cropped to contain only those data frames between frames[0] and frames[1] inclusive.

PRO read_stellar_log

keyword int[ 2 ] frames

Calls Filestream::set_format, Filestream::crop_data, Filestream::reset_data, Filestream::read, Filestream::set_data, Filelink::set_datafile

Reads the stellar log into the SSS object's resFile data member. We maintain the electronic log in an Excel spreadsheet. The log read by this routine is a .CSV file solar_obslog.txt, exported from the Excel spreadsheet, in the res directory in the SSS data archive.

The log is read in two passes. First, the entire .CSV file is read into the Filestream object as a big array of strings (with approximately 21,200 elements as of July 2008). Second, the strings are parsed based on the locations of the commas and the various values loaded into an array of structures, with each structure holding the observational parameters for one frame. The format of the structure can be seen in the following IDL code fragments, which show the values of the format, tagTypes, and tagNames data members placed in the Filestream object.

format = '( I4.4, X, I5.5, X, A8, X, I4.4, X, 2( I2.2, X ), I3.3, $

X, A5, X, I4.4, X, 4( F5.1, X ), A8, X, A80 )'

tagTypes = [ 3, 3, 7, 2, 2, 2, 2, 7, 2, 4, 4, 4, 4, 7, 7 ]

tagNames = [ 'Night', 'Frame', 'Observation', ' Year', 'Month', $

'Day', 'DOY', 'UT Start', 'Expdur', $

'Tred', 'Tblue', 'Troom', 'Tcoffin', 'Observer', 'Comment' ]

If the frames keyword is set, the data structure is cropped to contain only those data frames between frames[0] and frames[1] inclusive.

PRO reduce_solar

argument long startFrame

argument long endFrame

keyword bool swap

keyword bool skipDB

keyword bool skipFlats

keyword bool flatsOnly

keyword bool normOnly

Calls SSS::read_solar_log, Filestream::get_data, Normalizer::set_norm_types, Normalizer::set_deblaze, Normalizer::init_continuum_pts, SSS::match_flat, SSS::debias, SSS::ordermap, SSS::flat, SSS::scatteredlight, SSS::spectrum, SSS::normalizer

Reduces solar data frames from startFrame to endFrame inclusive, via the following procedure.

1. Debias all frames. 2. Use flats to create ordermaps and extract flat field spectra and echelle blaze information. 3. Divide debias object frames by flat field spectra. 4. Remove scattered light from object frames. 5. Extract spectra. 6. Normalize the continua to unity.

The keywords allow the user to control which parts of the reduction occur. For example, one can reduce only the flat field frames or only the target frames by setting the flatsOnly or skipFlats keywords. In case of an error in normalization (failure of a fit point, or testing a new set of fit points), the routine can be contrained to normalization only by setting skipDB and normOnly. The swap keyword forced byte swapping of the data should it be needed.

The routine also initializes the SSS object's normalizer data member in the following way. 1. The echelle orders are set to be fit with a cubic spline, and the HK order with a straight line. 2. All orders will be divided by the blaze. 3. The fit point file solar_norm_pts (old cameras) or solar_norm_pts_new (new cameras) is loaded for use in curve fitting.

This is the principal method we call in reducing solar spectra. Examples:

sss->reduce_solar, 6309, 6313

sss->reduce_solar, 6309, 6313, /skipDB, /skipFlats

The first example will completely reduce a typical 5-frame day of solar data (flat, 3 solars, Th-Ar). The second example will reduce only the solars and Th-Ar, using a previously reduced flat.

PRO reduce_star

argument long star

argument string normType

keyword bool normOnly

Calls SSS::read_stellar_log, Filestream::get_data, Normalizer::set_norm_types, Normalizer::set_deblaze, Normalizer::init_continuum_pts, SSS::match_flat, SSS::debias, SSS::ordermap, SSS::flat, SSS::scatteredlight, SSS::spectrum, SSS::normalizer

This method reduces all the observation for a requested star. It requires the normalization file explicitly via the argument normType. If the normOnly keyword is set, extracted spectra are assumed to exist and the method goes straight to normalization. As usual, it expects to find two versions of the normalization file: [normType].txt for old camera data and [normType]_new.txt for new camera data.

Example:

sss->reduce_star, 146233, 'G2'

PRO reduce_stellar

argument long startFrame

argument long endFrame

keyword bool swap

keyword bool skipDB

keyword bool skipFlats

keyword bool flatsOnly

keyword bool normOnly

keyword bool noNorm

Reduces stellar data frames from startFrame to endFrame inclusive, via the following procedure.

A complication occurs during normalization, since the fit points need to differ from star to star due to differences in spectral type and line strength. We maintain a set of these files in the resource directory for a variety of spectral types; for 18 Sco, for example, we use the file "G2" or "G2_new" for old or new camera data. We also maintain a separate text file containing an index of which normalization point files are used for which star. The reduce_stellar method loads this file, and then checks the entries against the object for each frame being normalized. It then initializes the Normalizer object with the right fit points before doing the normalization. If a star is missing from the index file, reduce_stellar will use the solar fit point file rather than unceremoniously crash.

The routine also initializes the SSS object's normalizer data member in the following way. 1. The echelle orders are set to be fit with a cubic spline, and the HK order with a straight line. 2. All orders will be divided by the blaze. 3. The fit point file [normPts] (old cameras) or [normPts]_new (new cameras) is loaded for use in curve fitting.

This is the principal method we call in reducing solar spectra. Examples:

sss->reduce_stellar, 1, 23600

sss->reduce_stellar, 21000, 21071, /noNorm

The first example will reduce the entire stellar data set from 1994 on. (We recommend The Brothers Karamazov to pass the time while this command executes.) The second example will reduce a night of data through spectrum extraction, skipping normalization. This is mainly useful during code testing.

PRO scattered_light

argument long frame

argument long flatref

keyword bool solar

keyword bool stellar

Calls Filelink::set_datafile, Filelink::read, Filelink::write, FITSdata::get_header, FITSdata::get_image, Image::get_image_ptr, ScatteredLight::set_order_width, ScatteredLight::set_order_start, ScatteredLight::load_ordermap, ScatteredLight::go, ScatteredLight::get_lightsurf, ScatteredLight::store_lightsurf, Tool::attach_data, Tool::detach_data

This method manages removal of scattered light from the CCD frames. It will use solar log data and solar data frames if the solar keyword is set, and stellar log data and data frames if the stellar keyword is set. The flatRef argument specifies which ordermap is to be used to trace aperture locations.

When reducing SSS data, we do not call this method directly. It is used by the reduce_solar, reduce_stellar, and reduce_star methods that automate the complete reduction process.

Details of the scattered light removal procedure and its results can be found here.

PRO spectrum

argument long frame

argument long flatRef

argument bool isFlat

keyword bool solar

keyword bool stellar

Calls Filelink::set_datafile, Filelink::read, Filelink::write, FITSdata::get_header, FITSdata::get_image, Image::get_image_ptr, ScatteredLight::set_order_width, ScatteredLight::load_ordermap, Spectrum::go, Spectrum::get_spectrum, Spectrum::store_spectrum, Tool::attach_data, Tool::detach_data

This method extracts spectra from CCD frames, using the frames output by the scattered light removal (".dsc" frames). It will use solar log data and solar data frames if the solar keyword is set, and stellar log data and data frames if the stellar keyword is set. The swap keyword forces data byte swapping if necessary. The frame argument gives the SSS frame number of the frame to be debiased. The isFlat argument is used to tell the method if the incoming frame is a flat field, in which case the spectrum will be stored to the res directory rather than the reducing directory.

When reducing SSS data, we do not call this method directly. It is used by the reduce_solar, reduce_stellar, and reduce_star methods that automate the complete reduction process.

Details of the spectrum extraction procedure and its results can be found here.

PRO solar_hkseries

Calls SSS::read_solar_log, FileStream::get_data, WaveCal::get_calibration

This method creates the solar H and K time series.

The method loads every observation of the Sun and calculates daily mean valuesof the HK index, R', excess magnetic flux, and S. The methods writes the solar HK data to output files for subsequent use, and it generates plots of the HK spectrum stacks and the solar time series.

PRO stellar_hkseries

argument string star

argument float bv

argument float by

argument int endYear

argument float seasStart

keyword int wingFitOrd

keyword float slideCal

keyword float slideH

keyword float sigClip

keyword float noPlot

Calls SSS::get_star_obs, WaveCal::get_calibration

This method creates stellar H and K time series using the spectrum stack files created by SSS::make_stellar_hk_stack. This is a monstrously long method, because it does a number of different calculations, produces a variety of graphical output products, and generates several different data products.

The method loads every observation of star, and uses its B-V color (bv) and b-y (by) to calculate continuum fluxes and S. The time series is plotted through endYear.

The keywords allow one to control a number of aspects of the time series creation. The slideCal and slideH keywords will move either the wavelength calibration scale or the H stack to ensure the line centers are perfectly lined up with the extraction bandpass (a 1Ã rectangle). The wingFitOrd keyword specifies the order of the polynomial that will be used to fit a time series of the average value of the K line wings on either side of (and well away from) the core; this is to track and remove any secular systematic drifts in the spectra over the years. Spurious or improperly normalized spectra in the time series can be identified by their systematic intensity deviations in the line wings; this keyword allows control of the number of standard deviations above which a spectrum will be rejected. Finally, noPlot suppresses generation of plots.

Sample Usage

obj = Obj_New( 'SSS' )

Obj_Destroy( obj )

[Back to contents]

Supported by grants from the National Science Foundation.
[ Back to my home page | Email me: jch [at] lowell [dot] edu ]
The SSS is publicly funded. Unless explicitly noted otherwise, everything on this site is in the public domain.
If you use or quote our results or images, we appreciate an acknowledgment.
This site is best viewed with Mozilla Firefox.