COR1 User's Guide

The main site for documentation about the SECCHI software is the data analysis section of the SECCHI website. Users are encouraged to visit that site to learn about the SECCHI software library. Here we outline a few of the basic routines important for COR1 data analysis, to help people get started using COR1 data.

Table of contents

Setup

The environment variable $SECCHI_LZ points to the top of the SECCHI data tree. Beneath this top directory is a series of directories containing the FITS images, separated by spacecraft, telescope, type of image, and date. For example, a COR1 file could be found in the directory $SECCHI_LZ/L0/a/seq/cor1/20070710/, where the pathname parts have the following meanings:

Pathname Parts Meanings
L0 Level 0.5 data. Currently, this is the only option
a: Either a or b for Ahead and Behind respectively
seq: Stands for image sequence data. Up until July 2011, the normal mode of operation for COR1 consisted of a sequence of images at three polarization angles, and all such COR1 science data will be in this subdirectory. The other options are img for single images (e.g. EUVI, or some COR1 after July 2011), or cal for calibration images.
20070710: The date, in year-month-day format, i.e. July 10th, 2007

A complete description of the organization of the data archive can be found here.

Some sites, such as NRL, may instead use the environment variable $secchi, which will point to a directory containing a subdirectory called "lz", which will in turn contain the directory tree described above.

Another useful environment variable is $SECCHI_BKG, which points to background images.
(See below.) The SECCHI background images are now distributed through SSWDB, and this environment variable is now defined automatically within SolarSoft.

SECCHI File Names

SECCHI data files have names such 20070710_010518_s4c1A.fts where the filename parts have the following meanings:

Pathname Parts Meanings
20070710: The date, in year-month-day format, i.e. July 10th, 2007
010518: The (commanded) time, in hour-minute-second format, i.e. 01:05:18 UT. Although the Ahead and Behind images are taken at slightly different times to account for the difference in light travel time from the Sun to each spacecraft, the time encoded in the filename will be the same for both spacecraft.
s: A code representing the type of image, where n=normal, m=multiple exposures, d=double exposure, k=dark image, e=LED image, c=continuous image, s=sequence, l=photometrically calibrated, and v=vignetting.
4: A code representing the data source, where C=calibration, 2=realtime, 3=realtime+SSR1, 4=SSR1 (synoptic buffer), 5=SSR2 (special event buffer), and 7=space weather.
c1: The telescope, where c1=COR1, c2=COR2, eu=EUVI, h1=HI1, and h2=HI2.
A: Either A or B for Ahead and Behind respectively.

Simultaneous images from the Ahead and Behind spacecraft will have identical filenames except for the "A" or "B" at the end of the name.

Finding COR1 Data

There are several routines available to users for finding SECCHI FITS files. The links below will take you to copies of these routines and their embedded documentation on the SolarSoft website, or you can use the XDOC routine in IDL.

SCCLISTER is a widget-based routine for browsing the SECCHI summary files.

The command

IDL> list = scclister()

will return the structure variable "list" with the tags "list.sc_a" and/or "list.sc_b", each of which is a string array containing a list of filenames for the Ahead and Behind spacecraft respectively. For COR1, be sure to select "polarized" for the data type.

COR1_PBSERIES returns a list of the COR1 files for a given day or time range, organized into polarization sequences of 0, 120, and 240 degrees. For example, the call

IDL> series = cor1_pbseries('2007-07-10', 'a')

returns a structure with dimensions 3xN where the first dimension represents the 3 polarization angles, and the second dimension represents the total number of sequences. (One can also use this routine to find matching Ahead and Behind observations, in which case the dimensions will be 3xNx2.) The filenames can be retrieved as "series.filename". Additional information from the summary files, such as the observation date, is also encoded in the output structure.

Reading and Preparing Data for Analysis

The primary routine for reading and preparing SECCHI data for analysis is SECCHI_PREP. This routine is extensively documented on the SECCHI website. Information about the calibration status of COR1 can be found on the SECCHI Coronagraph Intercalibration wiki site.

For example, to read in and calibrate a FITS file found using SCCLISTER, one could use the commands

IDL> list = scclister()
IDL> secchi_prep, list.sc_a[0], header, image

or to read in the three files making up a polarization sequence, one could use

IDL> series = cor1_pbseries(date, 'Ahead')
IDL> secchi_prep, series[*,0].filename, headers, images

There is also a widget front-end routine called XSECCHI_PREP.

Subtracting Backgrounds

Background images are derived from a complete solar rotation (one month), and are recalculated every 10 days. These images are available from the COR1 website at cor1.gsfc.nasa.gov/data/. The routine SCC_GETBKGIMG returns the appropriate background image closest in time to the image that it is being applied to. It uses the environment variable $SECCHI_BKG to point to the top directory containing the backgrounds. There are separate background images for the 0, 120, and 240 degree polarizer positions.

There are also backgrounds available based on regular calibration roll maneuvers--see SCC_GETBKGIMG for more details.

The background images are now distributed through the SolarSoft Data Base, and the background subtraction is automatically implemented within SECCHI_PREP. Alternatively, one can apply the backgrounds by hand by calling SECCHI_PREP with the keywords /CALFAC_OFF, /CALIMG_OFF, and /BKGIMG_OFF, e.g.

IDL> secchi_prep,filename,hdr,img,/calfac_off,/calimg_off,/bkgimg_off
IDL> bkg = scc_getbkgimg(hdr)
IDL> img = img - bkg

One would do the same (except for the /BKGIMG_OFF) keyword) for COR2 or HI images, where the background subtraction is not automatic.

Calculating Polarized Brightness

There are three routines for calculating the total and polarized brightness from a COR1 polarization sequence triplet. The routine COR_POLARIZ calculates the total brightness from three images and their corresponding headers, as shown in the following example:

IDL> list = cor1_pbseries('2007-07-01', 'ahead')
IDL> secchi_prep, list[*,0].filename, header, image
IDL> totb = cor_polariz(image, header)

Alternatively, one can accomplish the same thing with the /POLARIZ_ON keyword to SECCHI_PREP. Adding the keyword /PB calculates the polarized brightness.

An alternate routine for calculating total and polarized brightness is COR1_QUICKPOL. This routine produces the same results as COR_POLARIZ, but is significantly faster, and can calculate total and polarized brightness in a single call. The calling sequence is

IDL> cor1_quickpol, image, totb, pb

The third routine for calculating polarized brightness, COR1_FITPOL, differs from the other two in that it adds an additional constraint on the direction of polarization. This has the effect of suppressing most of the noise-induced apparent polarization signal. The calling sequence is

IDL> cor1_fitpol, header, image, totb, pb

Calculating Total Brightness

Because of the lower telemetry rate as the spacecraft get farther from Earth, the default COR1 mode of operation changed starting in July 2011. Instead of always sending down a sequence of three images at polarization angles of 0, 120, and 240 degrees, some of the sequences are combined onboard and sent down as a single total brightness image. Both polarization sequence and total brightness data can be separately processed using SECCHI_PREP, but there are three routines which can be used to combine both kinds of observations into a single total brightness product.

COR1_TOTBSERIES works like COR1_PBSERIES, but returns a time-ordered list of both polarization sequences and total brightness images. The result has the dimensions 3xN (or 3xNx2), with total brightness images simply being replicated across the first dimension.

COR1_TOTBPREP is a front-end to SECCHI_PREP to be used with the output of COR1_TOTBSERIES. The polarization sequences and total brightness images are processed separately to derive total brightness. All SECCHI_PREP keywords are supported except /POLARIZ_ON (which is applied automatically for the polarization sequences) and the related keywords /PB, /MU, and /PERCENT. One should also not use the /CALFAC_OFF keyword, because this will cause the two different kinds of observations to end up at different brightnesses. The following is an example of using COR1_TOTBSERIES and COR1_TOTBPREP together:

IDL> series = cor1_totbseries('2011-07-09', 'Ahead')
IDL> cor1_totbprep, series.filename, headers, images

COR1_TOTALB combines COR1_TOTBSERIES and COR1_TOTBPREP into a single routine. Thus, the above example could be simplified to

IDL> cor1_totalb, '2011-07-09', 'Ahead', headers, images

Extracting coordinates

The World Coordinate System (WCS) set of routines can be used to extract solar coordinates from a SECCHI image. First one converts the SECCHI header into a WCS structure via FITSHEAD2WCS, e.g. 

IDL> wcs = fitshead2wcs(header)

Then, one can convert pixel positions into solar coordinates via WCS_GET_COORD, or invert the process using WCS_GET_PIXEL. For example, the call

IDL> suncenter = wcs_get_pixel(wcs, [0,0])

returns the pixel position of Sun center.

Deriving electron density

Tongjiang Wang has made available some IDL software for deriving coronal electron density from COR1 pB data. These routines are available as a tar file, and are described in the paper "Validation of Spherically Symmetric Inversion by Use of a Tomographically Reconstructed Three-Dimensional Electron Density of the Solar Corona".