A Photo Primer (Not for Dummies)

What is this document?

The goal of this web page is to help new users examine the results of the Photometric Pipeline ("photo" hereafter). After reading this document and trying the commands you should know how to display images of frames and individual objects and how to list parameters and flags measured by photo. Included below are brief descriptions of what photo does and links to more complete documentation by the authors of the software. This document is meant to be read on the WWW; it includes lots of links to other documents that will not be visible if you print it.

To just start typing commands and see some images, skip down to Jump Starting Photo.

Disclaimer: As the title suggests, this is not "Photo for Dummies." The author of this page is responsible for any errors herein. If the instructions below don't work, it is not necessarily because photo is broken. File a bug report only when you're fairly certain that the problem is in photo rather than in this documentation. The commands below have been verified to work at both Fermilab and Princeton using the current version (v???) of photo.

Background
Data
Jump Starting Photo
More About Using Photo
Plotting Using PGPLOT in Photo
Other Ways of Looking at Photo Outputs
Where to Get Help
Bug Reporting

Background
To learn about the SDSS project as a whole, see the Black Book (declassified).

What Does Photo Do?
Photo reduces the continuous scans of the sky from the imaging camera into images and measured parameters of detected objects.
From the Sky to Binary Tables: Runs, Columns, Frames, and Pixels
The photometric CCDs are 2048x2048 pixel devices and are arranged in the camera in 6 columns of 5 CCDs each. The focal plane scale is approximately 0.4 arcseconds/pixel. Adjacent columns are separated by roughly 1800 pixels. Thus we must interlace two strips (a "strip" is the result of a single scan) to form a stripe 2.5 degrees in width. A quick look at the imaging camera (see Figure 8.2) will make this clear.
Driftscanning at sidereal rate yields an exposure time in each filter of approximately 54 seconds. During a scan, an object traverses a single column from top to bottom and thus is registered in each of the 5 filters nearly simultaneously.
For each run (a continuous readout of the camera), the data stream from each CCD is cut into frames of 2048 columns and 1361 rows. Before processing by photo, the 128 rows from the next frame are added to the top of each frame, so that photo actually works on a 2048x1489 image at one time. The resulting overlap between reduced frames (128 rows) is roughly the same as the number of columns that overlap with the other strip of a stripe. Remember this overlap when you look at photo's outputs; some objects will be detected in multiple frames!
Photo analyzes the data one frame at a time. Because information about each object is contained in five separate frames, one for each filter, the five frames for each field are processed together.
Description of the Photometric Pipeline
An overview of the photometric pipeline is on-line. Look there if want to get more detailed information about how the pipeline works. Also see the data systems chapter of the Black Book.
Basic operation of the photometric pipeline is also described in The Photometric Pipeline document (very large Postscript file), which is a status report as of 2/98; much of this information is also contained in the Black Book.
Photo is coded in ANSI-C and Tcl (Tool command language) and uses a framework called Dervish, which was developed at Fermilab. Image display from photo is done in FSAOimage , which is Fermilab's version of the SAOimage display familiar to most astronomers.

Outputs of Photo
The outputs of the photometric pipeline consist of both atlas images and measured parameters for each object. An atlas image is an areas of a reduced frame that includes all pixels that belong to a detected object, plus some extra pixels around the edge. Some atlas images are cut where no object was found; these may be either "sky" patches or locations of known objects (e.g., X-ray or radio sources). The measured object parameters document describes the properties of each object that photo estimates.
In short, photo's outputs are FITS binary tables of the parameters and Atlas Images that are stored in compressed form in a binary heap structure of a FITS file. As we describe below, the parameter files may be unpacked and examined within photo itself (which this document describes), through macros run within SM (parameters only),or by any program (see the FITS/IO library) that can read FITS binary tables. The atlas image files may be examined in photo (again, described in this document) or by using a standalone reader. Don't even think of trying to get an atlas image out of an fpAtlas file without this code.
Data Structures and Types
It will be easier to work with the photo outputs if you understand the fundamental data types used by photo and the underlying dervish environment.
The Science Archive
Eventually, all of the outputs of photo will be archived in the Science Archive (SX) that is being designed and written at Johns Hopkins. The SX will provide an efficient query mechanism for selecting objects with particular properties and for viewing and manipulating these data.
We anticipate that the SX will be available for use in Summer 1999. In the near term we will use photo to directly access these data. Even when the SX is on-line, we will continue to use photo to directly examine and test its outputs.
Back to the Table of Contents

The Data

What Data Have Been Taken, What's their Status and Where Do They Live?

Status of "good" imaging runs is summarized on the Run Database page at Fermilab. For each month, there is a link, e.g., March 1999 Dark Run, to a table that lists all of the imaging runs for that month, notes which were of "science" quality, and details their position on the sky. For each "science" run, for example < a href="http://www-sdss.fnal.gov:8000/~sdssdp/schedule/sch_745.html"> Run 745, there is a graphical table that depicts the processing status (hope for lots of smiley faces) followed by links to lots of plots. The release notes link for each run points to Brian Yanny's overview, as posted to sdss-obs. The latter is actually a good place to start if you want to learn about a particular run.
To check for yourself what data are currently spinning on disk, look in the SDSS data directories and see if the necessary files are there. (For sites other than Fermilab, consult your local data guru!) Directories at Fermilab look like /data/dp3.b/data/(run number)/*. The necessary files have names like (these for run 745, camera column 1) calibChunks/tsObj-000745-1-0-0011.fit, objcs/1/fpObjc-000745-1-0200.fit, and objcs/1/fpAtlas-000745-1-0200.fit More in a moment about what these file types mean and why you should care.
Note that the commands in photo automatically configure the pathnames, so you don't need to remember these or the file names. The directory structure and file name might change but the code will (hopefully) take this into account.
What Do the File Names Mean?
fpObjc files are binary FITS tables of the measured object parameters. tsObj files are similar to the fpObjc files; they differ from the latter in that (1) astrometric calibration has been applied, thus row and column in pixels are replaced with ra and dec (J2000), (2) photometric calibration has been applied, thus counts are replaced with magnitudes (really, asinh - see this technical publication, and (3) outputs for multiple fields have been combined into one very large FITS file (with multiple HDU's). fpAtlas files are FITS files with all the compressed atlas images from a frame stored in binary heap.
The Data Model describes all the files that are used in taking and processing the data. Dig down in the imaging stuff to see what the FITS headers for the files look like.
Back to the Table of Contents

Jump Starting Photo
The following set of instructions should allow anyone with an account at Fermilab to start photo and examine images from the reduced SDSS photometric data. Examples of command line text are given below in typewriter-like font, such as set table [openit $frame].
Log on, Set Up, and Start Photo
All of this assumes that whatever machine you're working on has a complete SDSS environment installed.
Logon (if you're not using ssh, your password is transmitted as cleartext) to an appropriate machine (e.g., sdssdp2.fnal.gov) and prepare to run photo by invoking
```
setup photo
```
If you're not sitting at the console, you also need to set the display variable, as in (for csh or tcsh)
```
setenv DISPLAY myworkstation:0
```
or, for bash,
```
export DISPLAY="myworkstation:0"
```
Now start photo with the cryptic command
```
photo
```
You will see the names of the TCl startup scripts echoed, e.g.,
```
Executing commands in /p/OSF1/dervish/v7_4/etc/dervishStartup.tcl: 
Executing commands in /p/OSF1/astrotools/v4_6/etc/astrotoolsStartup.tcl
Executing commands in /p/OSF1/photo/v4_8_6b/etc/photoStartup.tcl: 
```
In this example, you are using version 7_4 of dervish, version 4_6 of astrotools, and version 4_8_6b of photo. If you've done this right, you'll now see the photo> prompt. Congratulations, you're in!

Choose Which Data to Use
You must specify the run, column, and frame that you want to examine. A run is a continuous scan with the camera. The column number refers to the column of CCDs in the camera, numbered 1 through 6. A frame is a roughly 10' by 13' piece of a scan. To select run 745 and column 1 (these are data from the March dark run), which live under directory /data/dp3.b/data at Fermilab (see the release notes, as described above, to check where various data should live), invoke
```
set_run -r /data/dp3.b/data 745 1
```
Obviously, if you or someone else has moved/hidden the data elsewhere, you need specify the appropriate root directory.
By default, set_run will try to use the fpObjc files (remember, these are the uncalibrated ones). To use the tsObj files, add the argument -ts, as in
```
set_run -rootdir /data/dp3.b/data 745 1 -ts
```
In some cases, the fpObjc are no longer on disk, thus use of the tsObj files is mandatory. For descriptions of this and other options, see
```
set_run -help
```
Open a Display and Show a Frame
Image display from photo uses a Fermilab-modified version of SAOImage, called FSAOimage ("fsaoimage" hereafter). See below for links to help on using fsaoimage. Note that the origin (pix [1,1]) is at the lower left of the display. To open two fsaoimage windows (don't ask why the g r arguments) type
```
set_mtv g r
```
Now set the current frame number to one less than the one you want to examine, e.g.,
```
set frame 100
```
if you want to see frame 101. To display all of the detected objects in this frame in the r' band, along with their id numbers, type
```
next_frame
```
(Patience...this may take a moment.) The left-hand fsaoimage display now shows all detected objects in frame 101. What next_frame has done is to reconstruct an image of the sky from the individual atlas images (but without putting the sky values in between them). This uses the procedure recon, which is not identical to reconstruct_frame. See More About Using Photo below to learn how to use next_frame to insert binned sky in between the atlas images or to show only certain objects (e.g., only galaxies).
By default, next_frame shows the atlas images, id numbers of the objects, and properties of the mask. Note the variation in the color of the id numbers. Most id's are in yellow; these are objects that photo has classified as stars. The objects whose id's are in red within a white box are "not stars," thus most of these are galaxies. Note that the meaning of these colors is different from what is used by, e.g., mtv_blend below. To toggle these id's on and off, click Cursor -> region -> view on the fsaoimage display buttons.
The most common mask features are green vertical lines that indicate interpolated columns and red objects. The meaning of all the mask colors is as follows:
```
    INTERP		green
    SATUR		purple
    NOTCHECKED		yellow
    BRIGHTOBJECT	blue
    OBJECT		red
    BINOBJECT		magenta
    CATOBJECT		cyan
    SUBTRACTED		orange
    GHOST		orange
    CR			green
```
To toggle the mask display on and off, click on "Scale" in the fsaoimage window and right-click the display.
To step through a sequence of frames just keeping typing
```
next_frame
```
Reconstruct an Image of The Sky
To show an image of the sky that includes the "sky" in between the atlas images, use
```
next_frame binned
```
Note that the sky that is used in binned down 4x4 and so looks smoother than the atlas images themselves. Because the object finder was run on the original pixel data (1x1), a 2x2 binned image, and a 4x4 binned image, most of the statistically significant information about the sky is contained in this binned data. Let us know if you find any LSB objects lurking in the sky!
Examine the Atlas Image of One Object
To proceed further (most of the commands below require that you have done the following), you need to load lots of other information about this frame using
```
set table [openit $frame]
```
Note that $frame is a variable that was already set by set frame and then incremented along by next_frame. You can issue more than one command at a time in Tcl by separating the commands with a semi-colon. A useful combination is, for example,
```
next_frame; set table [openit $frame]
```
To look at an atlas image of one object in all five colors and see its deblended children (if any), read its id number from the display that next_frame created and type, e.g.,
```
 mtv_blend table 123
```
which displays object 123 in the right-hand fsaoimage display window. If more than one set of images appears, that means that this "parent" object was deblended into several "children." To include display of the mask bits, use
```
mtv_blend table 123 1
```
The meaning of the mask colors and procedure for toggling the mask on/off are as described above for next_frame.
To examine the atlas image of any object without children (if any), type
```
mtv_objc table 123
```
Decoding the Blended Atlas Image Display
The images within each panel show the object in different filters. From left to right, upper to lower (or maybe the reverse), the colors are u', g', r', i', and z', respectively.
Note the label in the upper right-hand corner: red type indicates that this is a deblended child, yellow that this is a parent.
The children always have id numbers sequentially higher than their parent, so you can find the parent by using mtv_blend to step back and examine objects with smaller id numbers. If it's a parent, then the parent object is shown in the lower left panel and the children are in separate rectangles on the display. For objects that were first detected as "BRIGHT," or that are children of such an object, stepping back through the sequence of object numbers will lead you back to a display of the parent with all children, but this mosaic also has a red id number; the object before this one is the true parent and this "mosaic" has the peculiar property of having one display region blank.
The center of each child is marked with a yellow symbol. Other centers are marked in red. A cross "X" indicates that photo thinks it's a PSF, otherwise the center is marked with a plus "+" symbol.
The ID number of a child's parent may be found using
```
set objcIo [objcIoRead table childsID]
puts [exprGet $objcIo.parent]
```
where you just substitute for childsID.
Object Parameters and Flags (VERY USEFUL)
To see a list of measured parameters for an object, say, object 123
```
p_objc table 123
```
The columns of this list, from left to right, are the name of the parameter and then the parameter value in u'g'r'i'z'. If you leave off the arguments table and id number, p_objc will list parameters of the last object that you examined. To see specific parameters of a specific object, say, the exponential scale size and fiber surface brightness in all five colors of object 123,
```
p_objc table 123 all {r_exp fiberSB} 
```
See the measured outputs document for an explanation of the meaning of the parameters. Related Tcl procedures (see the list below) include read_objc and show_objc.
Among the possible outputs of p_objc are the calibrated magnitudes and the (roughly) calibrated RA and DEC (J2000) of the object,
```
p_objc table 123 all {ra dec psfMag} filename.dat
```
Subtle point: if you're looking at fpObjc files, then the magnitudes are computed here on the fly by referencing the calibration files to get the zero points to convert PSF counts to a PSF magnitude. In the tsObj files, magnitudes have already been computed and entered in the table, but are nevertheless listed as, e.g., psfCounts.
In the previous example, the argument "filename.dat" specifies that the output should be sent to this file rather than the screen. Prepending a plus sign to the filename, as in "+filename.dat" will append this output to an existing file.
After using p_objc, the ID number of a child's parent may be found by typing
```
puts [exprGet $objcIo.parent]
```
A list of all the flags that photo set for this object may be seen by typing
```
pflags
```
In this case, the flags for each color are on a separate line, beginning with OBJC (flags for the blended object, comprised of all five colors), followed by 0-4 (u' through z' bands). The measured outputs document also contains an explanation of these flags.
Back to the Table of Contents

More About Using Photo

Existing Tcl Procedures
Now that you've seen a glimpse of what you can do within the photo environment, we can try more complex operations. Before we do, look at the list of all procedures related to photo's outputs. This list is printed by typing
```
help -facil=phOutputs
```
which yields the list
```
apertures_objc            classify_obj1             classify_objc              
close_mytables            display_mask              display_mtv_objc_blend     
dump_test_info_list       flags                     get_mask                   
mosaic_id                 mtv_blend                 mtv_mosaic_blend           
mtv_objc                  mtv_objc_blend            mtv_objc_list              
mtv_objc_mosaic           objcIoRead                objcVersion                
objc_intro                objfileClose              objfileOpen                
objtable2chain            offsetsRead               open_mytables              
p_objc                    p_profs                   pflags                     
pflags2                   read_objc                 reconstruct_frame          
refresh_ids               regUnbin                  select                     
show_annuli               show_ids                  show_obj1                  
show_objc                 show_peaks                show_petro                 
write_atlas_images_as_fits write_mytables          
```
Using help with the procedure name will extract more detail (but not much) about a specific procedure, for example
```
help mtv_objc_mosaic
```
Optional parameters are delimited with brackets [ optional args ].
Pre-loaded Tcl Procedures
To see the Tcl files that photo reads when it starts up, note the directories of the startup scripts that are listed on the screen when you first start photo, e.g., /p/OSF1/photo/v4_8_6b/etc/ Look in this directory for the read_objc.tcl file that defines the procedures listed above. Lots of other TCL goodies are also in this directory.
Adding Your Own Tcl Procedures
To add your own Tcl procedures, it may be helpful to start by looking at the structure of the existing procedures in the files listed above. And look at a good book on Tcl!
To load your own definitions, enter
```
source mydefinitions.tcl
```
In the future, you can load these by adding them to your own dervish.tcl file and setting the PHOTO_USER environment variable (see above) to point to this file.
View Only Selected Objects
This is a case where writing your own Tcl procedure will help immensely, because it will allow you to select objects based on your choice of cuts on the parameters. In the commands below, you must specify a Tcl selection procedure that selects objects on the basis of their measured parameters and flags. For example, here's a Tcl procedure that selects only galaxies by throwing out stars, "sky" objects, and objects that are near the edge, deblended, or saturated:
```
proc sel_gal {objcIo {band 2}} {
   global OBJECT1

   set flgs [exprGet $objcIo.flags<$band>]

# reject edge, blended, saturated
   if {[expr $flgs&($OBJECT1(EDGE)|$OBJECT1(BLENDED)|$OBJECT1(SATUR))]} {
      return 0;
   }

# reject sky objects
   if {[eval lindex [exprGet $objcIo.objc_type] 1]=="OBJ_SKY"} {
      return 0
   }
# reject stars
   if {[eval lindex [exprGet $objcIo.objc_type] 1]=="OBJ_STAR"} {
      return 0
   }
   return 1
}
```
Another example is at the comments at the beginning of the read_objc.tcl file. This procedure is not loaded automatically. Some other crude examples live in Vogeley's select.tcl file. The latter includes examples of how to select on magnitude and color. You should write your own (copy and modify the one above) in a file called, say, select.tcl and load it into photo by saying
```
source select.tcl
```
Earlier we showed how to display all the detected objects in a frame using next_frame. You may also display only a subset of the objects, also positioned in the display where they were found, by invoking, e.g..,
```
next_frame "" 1 r sel_gal
```
which displays all the objects that survived sel_gal in r' band. Replace "" with binned to get the binned sky. Replace 1 with 0 to not show the mask colors.
To display a mosaic of detected objects in one or all of the filters, use mtv_blend_mosaic. This procedure takes several arguments, for example
```
mtv_blend_mosaic table 200 300 sel_gal all 1 300
```
displays a mosaic in all (one could also specify only 'r' to get the r band) filters of the objects 1 through 300 that passed the sel_gal procedure. Each sub-image is 200x300 pixels in size. The argument 'table' refers to the binary table loaded for this frame. In the following example, 50x50 pixel i-band images are shown of the objects 1 through 1000 that met the sel_gal criteria:
```
mtv_blend_mosaic table 50 50 sel_gal i 1 1000
```
Display/Removing Object ID Numbers
The command
```
mosaic_id sao#
```
will add object ID numbers to the objects displayed in a mosaic in fsaoimage window number sao#. Clicking on Cursor->region -> view will toggle the id's and peak symbols on/off.
Radial Profiles
After invoking p_objc, mtv_objc, or any other procedure that specifes a specific object, you can print out the values of its radial profile using
```
p_profs
```
...How to get nicer format for this output?
Printing a Color Image
Warning: The following will only work if the corrected frames, i.e. fpC files, are on disk, which is not usually true.
The command make_ppm_file, which is defined in wallpaper.tcl, makes a nice color PPM (this format can be converted later to TIFF, GIF or whatever) files from a specified series of frames in one column. You can choose which filters are used to form the color image and what stretch is applied. In addition, you can indicate that xv should be launched to display the result. For example,
```
make_ppm_file r745-c1 100 100
```
will make a large (c. 9MByte) PPM file from frame 100 of the current run and column (set by set_run) using (by default) the full frame and the g', r', and i' filters. The argument 'r745-c1' provides the base name for the file, not the run and column numbers themselves. Thus, the name of this file is r745-c1-100.ppm and it will live in the current directory.
```
make_ppm_file r745-c1 100 100 i r g 1 0:10s 500 500 0 0 1
```
makes a smaller image of frame 100, using i', r', and g', binning 1x1, stretching from 0 to 10 sigma, and using only a 500x500 pixel region. The ending '1' indicates that xv should automatically display the image.
Printing an Image of the Display
The print button in fsaoimage doesn't seem to work, but you can save and/or print the display by starting up xv and using it to grab and fsaoimage window.
Dervish has a built in command called "regPrint" that saves a region to a postscript file. After displaying a frame with next_frame, try
```
regPrint $frame_reg junk.ps
```
to save the frame to filename junk.ps in the current directory. There are lots of parameters to play with to determine how it translates into postscript (use help regPrint to see these options).
Saving an Atlas Image in FITS Format
If you would like to examine the atlas images outside of photo, using code that can read FITS images, you can save the atlas images to a file using, e.g.,
```
write_atlas_images_as_fits table "" "" 1 100
```
which writes the atlas images of objects 1-100. The last four arguments are optional; by default it will write atlas images of all the objects to FITS files in the current directory with names that begin "AI."
Photometric and Astrometric Calibration
Calibrated outputs of photo are in the tsObjc files, but not in the fpObjc files because photometric and astrometric calibration is performed downstream after photo has done its work. However, As described above, one can use p_objc to get calibrated magnitudes and (roughly, not taking into account chromatic effects) calibrated positions of one object at a time from the fpObjc files if necessary. Exercise for the reader: Look at read_objc.tcl to see how this procedure gets the calibrated quantities. You'll see that measured counts may be converted to AB magnitudes by using the flux20 values - the number of counts in a 20th magnitude object - from the CB files.
Making a Corrected Frame (Complete Reduced Sky Image
Photo constructs a "corrected frame," which is what one usually thinks of as a reduced image including bias, dark, and flatfield corrections and saves this as a file with a name like fpC-.... These are FITS images. However, these are quite large and are not always saved on disk, because (in principle) they can be easily reconstructed from their predecessor files. A command to build these if necessary is called make_corrected_frames, which lives in wallpaper.tcl
Back to the Table of Contents

Plotting using PGPLOT

Object Parameters: Quick and Easy X vs. Y Plots
You can use PGPLOT to plot object parameters from within photo. You can see a simple demonstration of PGPLOT by typing
```
demo_plot1
```
This command displays a simple x vs. y plot and writes the displayed vectors to a file in the current directory called plot_xy.dat. Type RETURN on the command line to clear the PGPLOT display window. The source code for this demonstration lives in sanityCheck.tcl.
To plot photo outputs, you must first invoke some commands that create the appropriate data structure. Assuming that you have already opened a binary table using set table [openit $frame], type
```
set chain [objtable2chain $table]
```
To make a simple plot of one object parameter versus another, enter
```
plot_chains /XWINDOW $chain fiberCounts<1> $chain fiberCounts<2>
```
which plots the counts within a 3 arcsecond aperture in g' vs. r' bands.
See the measured objects document for the names of the parameters that you could substitute for fiberCounts. Here and throughout, the filters u', g', r', i', z' correspond to the the ordinal values 0, 1, 2, 3, and 4, respectively. Thus, the z' Petrosian radius is petroRad<4>.
Replacing /XWINDOW with /PS will produce a postscript file in the current directory with the name plot_xy.ps.
Object Parameters: More Detail
Now we'll describe step by step how a plot is made. After reading this section and looking at the Tcl procedure plot_chains you should be able to write your own procedure to make plots. Look at the Tcl procedures in sanityCheck.tcl to learn more. The command
```
set table [openit $frame]
```
reads the files from disk for this frame and creates a binary table in memory. Then the command
```
set chain [objtable2chain $table]
```
makes a "linked list" in memory of all the object parameters for this frame. The plotting routines work on vectors, so the next step is to load the parameter values that you want into a pair of vectors. For example,
```
set fc1 [vFromChain $chain fiberCounts<1>]
set fc2 [vFromChain $chain fiberCounts<2>]
```
loads the 3 arcsecond fiber counts in g' and r' into the vectors fc1 and fc2.
To make a plot, first start up a new PGPLOT process,
```
set pgs [pgstateNew]
pgstateOpen $pgs
```
To plot the vectors defined above, type
```
vPlot $pgs $fc1 $fc2
```
A (very slight) shortcut to this plot is
```
vPlot $pgs [vFromChain $chain fiberCounts<1>] [vFromChain $chain fiberCounts<2>]
```
If you ask for another plot, it will appear in the same window after hitting RETURN on the command line.
To plot a restricted range of the parameters, give vPlot more parameters, e.g.,
```
vPlot $pgs $fc1 $fc2 -xmin 0 -xmax 1e4 -ymin 0 -ymax 1e4
```
If you associate a name with each vector, then that name will appear as the axis label. For example,
```
vNameSet $fc1 "g' fiber counts"
vNameSet $fc2 "r' fiber counts"
vPlot $pgs $fc1 $fc2
```
will appropriately label the axes in the example above. Add a title to this plot with
```
titlePlot "Fiber Counts g' vs. r'" 40
```
To annotate a plot,
```
pgText 1000 1000 "HERE"
```
will place the text "HERE" at parameter location x=1000, y=1000.
Several additional properties of the PGPLOT may be controlled by pgstateSet. Use help pgstateSet to see all the options. (Also look in this Dervish documentation ) For example,
```
pgstateSet $pgs -nxwindow 2 -nywindow 2
```
will cause the the PGPLOT window to have four available windows. If you execute four successive plot calls, each will be sent to a different window. In this example, the fifth plot will appear on the next "page" in the PGPLOT window.
To close a PGPLOT without producing a postscrip file,
```
endplot $pgs ""
```
To get postscript output of a plot, set
```
pgstateSet -device /PS
```
(the default is device=/XWINDOW) before creating the plot, and use
```
endplot $pgs "mynewplotname.ps"
```
when you're all done. If you leave off the filename, the plot will appear in pgplot.ps. Among other things, endplot executes a pgstateClose and pgstateDel.

Saving Vectors to a File
You might want to save the vectors of parameters to a file to examine later or to plot with, for example, SM. The command (also in sanityCheck.tcl)
```
vectorsWriteToFile $x $y plot_xy.dat
```
will write the vectors x and y to an ascii file called plot_xy.dat in the current directory.
Filtering What Gets Plotted
In progress... Clearly, it will be most useful to plot the parameters of a selected sample of objects in a frame.
Use a select procedure to make a mask vector, so only good data get plotted. Need to call vPlot including a vector passed with -vectorMask
Or make a chain out of only selected objects. Need a new objtable2chain command. See sanityCheck.tcl for examples of how to make a chain.
Operations on Vectors: Magnitudes and Colors
In addition to plotting values of the object parameters, one can plot derived quantities by first performing vector operations on them. For example, instead of plotting the observed counts, one can plot magnitudes by using the zeropoint values to calibrate the measurements. For example, to load the r' band psf magnitudes into a vector, one must get the psf counts into a vector (remember that 2 means r' here)
```
set psf2 [vFromChain $chain psfCounts<2>]
```
next get the zeropoint for the current frame
```
set zero2 [exprGet $fieldparams.frame<2>.flux20]
```
and, finally, calibrate the counts
```
set psf2 [vectorExprEval 20-2.5*lg($psf2/$zero2)]
```
Note that the logarithm operation fails for counts less than or equal to zero, so you'll get lots of 20th mag objects this way. This is an example of why we use inverse hyperbolic sine instead of magnitude. (ref for this?).
Similarly, one can make vector g'-r' and r'-i' colors after creating the appropriate magnitude vectors by using
```
set gr [vectorExprEval $f1-$f2]
set ri [vectorExprEval $f2-$f3]
```
Plotting Cross-sections Through an Image
To plot the values of pixels in a region that runs either horizontally or vertically through an image, use vectorGetFromRegion to make a vector of the the mean (or, if you choose, the median) of the pixels in the orthogonal direction. For example, after using next_frame to display a frame in an fsaoimage window, typing
```
set x [vectorExprEval (1,100)]
set y [vectorGetFromRegion $frame_reg 1 100 15 20 1]
```
puts the row number values 1 through 100 in the x vector and puts the mean of the pixels in columns 15 through 20 in each row into the y vector. The final argument of vectorGetFromRegion specifies the direction of the cut, 1 for vertical, 0 for horizontal (the averaging is done in the orthogonal direction). As usual see help vectorGetFromRegion for all options.
Histograms
An example of a procedure to plot a histogram of values in a vector is in sanityCheck.tcl. For example,
```
plot_histogram /XWINDOW $y
```
will make a simple histogram of values in the current y vector.
Plotting Frames Diagnostics
To produce plots of many useful statistical properties of the data, type (for frames 100 through 110)
```
fpstats 100 110
```
which makes a plot for each color (notes in upper right corner of the PGPLOT window). Step through the series of plots by hitting RETURN on the command line.
Many other useful plots to look at are referenced by the Run Database pages. Back to the Table of Contents

Putting it All Together: A Mosaic and Color-Magnitude Diagram of Selected Galaxies
TBD
For the grand finale of this primer, we'll use fsaoimage and pgplot to display a mosaic and a color-magnitude diagram of galaxies selected by a Tcl procedure.
Back to the Table of Contents

Other Ways of Looking at Photo Outputs
The following are brief notes on looking at the data with SM, a standalone FITS reader, and IDL.
Plotting with SM
To plot the distribution of object parameters, e.g. a color-magnitude diagram, you may use SM to read measured parameters and flags from the binary files and plot these quantities. A primer for doing is in Michael Strauss's phototest notes.
You must have SM v2.4.1 or later to do this. At Princeton, please note that only certain machines can see the SDSS data directories on stribor (the LINUX box that has the disks). Try from another machine if you have trouble.
Stand-alone Code to Use FITS Format
The object parameters are stored as binary FITS tables in the fpObjc files and may be read by a C or Fortrash program by calling routines in the FITS/IO library.
Extracting the atlas images from the fpAtlas files is trickier, because they are stored in heap, not as FITS images. As an alternative to using photo to examine Atlas Images, there are a couple of utilities in photo/readAtlasImages which can be built independently of photo or dervish; alternatively or additionally they could be built into e.g. astrotools. They are not especially friendly, but they are supposed to be easily modifiable when you decide to write your own special purpose code. The code lives in the directory /u/rhl/photo/readAtlasImages
To read an atlas image, say the r' band image from object 12, say
```
   read_atlas_image fpAtlas.fit -c 2 12 outfile.fit
```
To read a set of masks, say the SATUR mask, say
```
   read_mask fpM.fit 1 outfile.fit
```
In each case the output is a FITS file, in the former with BITPIX==16, in the latter with BITPIX==8. In the respective main programs, the atlas image is returned as the type ATLAS_IMAGE, and the different "objects" making up the mask are returned as OBJMASKs.
The mask planes in successive HDUs of the fpM files are:
```
1  S_MASK_INTERP,               /* pixel's value has been interpolated */
2  S_MASK_SATUR,                /* pixel is/was saturated  */
3  S_MASK_NOTCHECKED,           /* pixel was NOT examined for an object */
4  S_MASK_OBJECT,               /* pixel is part of some object */
5  S_MASK_BRIGHTOBJECT,         /* pixel is part of bright object */
6  S_MASK_BINOBJECT,            /* pixel is part of binned object */
7  S_MASK_CATOBJECT,            /* pixel is part of a catalogued object */
8  S_MASK_SUBTRACTED,           /* model has been subtracted from pixel */
9  S_MASK_GHOST,                /* pixel is part of a ghost */
10 S_MASK_CR,                   /* pixel is part of a cosmic ray */
(See photo/include/phSpanUtil.h)
```
You can get a reminder of the arguments with the -h flag

Using IDL
TBD
Thanks to David Schlegel.
Back to the Table of Contents

Where to Get Help

Source Code
To understand exactly what photo does you may need to look at the code. The C and Tcl source code resides in /u/rhl/photo/src and /u/rhl/photo/etc.
One can most easily navigate among the source code files by using the TAGS feature of emacs. To learn more about TAGS, read emacs info. Primer: 'M-.' (that's a period while holding down the Meta key) with the point (cursor) on the tag takes you to the file that defines the tag. 'C-x 4.' will open the file with the tag definition in another emacs window. Watch the mini-buffer to see what tag emacs is looking for and check that it is referencing the /u/rhl/photo/TAGS for this information. Use 'C-h a tag' (apropos command) to see info on other tags-related commands.
Photo command line
Help for many of the Tcl commands and procedures may be obtained by simply typing
```
help some_command
```
Help with supporting software
The Dervish home page has some useful links that describe the underpinnings of photo.
Good books from which to learn Tcl include
- Welch, B.B., Practical Programming in Tcl and Tk (Prentice-Hall, 1997)
- Ousterhout, J., Tcl and the Tk Toolkit (Addison-Wesley, 1994)
A few chapters of Practical Programming are on the webl. The TCL Resources homepage has links to other info. Tcl/Tk runs on almost every available platform - including most flavors of UNIX, Win95, and MacOS - so it's worth learning to use. You can get binaries or source off the web (see, e.g., the Scriptics software page).
Look at the SAOimage home page for documentation about the original software product.
People

Back to the Table of Contents

Bug Reporting
In the unlikely event that you find a problem in photo, you may file a bug report in the SDSS Bug Database. The reporting form will automatically enter your name and email address if you use the link in the form http://www.astro.princeton.edu:81/gnats-SOFTWARE/YOUR_NAME/username/, which keeps you from repeatedly having to enter this info. In your report, please include information about the version of photo that you are running, by quoting the result of typing
```
photoVersion
```
and the version of photo that was used to reduce the data, obtained by
```
objcVersion
```
after opening some data with, e.g., set table [openit $frame]; p_objc table 1
Note that bugs may be reported for both the software and its documentation. THIS document is not part of photo, so please report all errors herein to the author.
Back to the Table of Contents

Please send any comments or suggestions to Michael Vogeley

MSV, May 7, 1999

A Photo Primer (Not for Dummies)

What is this document?

Table of Contents

Background

What Does Photo Do?

From the Sky to Binary Tables: Runs, Columns, Frames, and Pixels

Description of the Photometric Pipeline

Outputs of Photo

Data Structures and Types

The Science Archive

The Data

What Data Have Been Taken, What's their Status and Where Do They Live?

What Do the File Names Mean?

Jump Starting Photo

Log on, Set Up, and Start Photo

Choose Which Data to Use

Open a Display and Show a Frame

Reconstruct an Image of The Sky

Examine the Atlas Image of One Object

Decoding the Blended Atlas Image Display

Object Parameters and Flags (VERY USEFUL)

More About Using Photo

Existing Tcl Procedures

Pre-loaded Tcl Procedures

Adding Your Own Tcl Procedures

View Only Selected Objects

Display/Removing Object ID Numbers

Radial Profiles

Printing a Color Image

Printing an Image of the Display

Saving an Atlas Image in FITS Format

Photometric and Astrometric Calibration

Making a Corrected Frame (Complete Reduced Sky Image

Plotting using PGPLOT

Object Parameters: Quick and Easy X vs. Y Plots

Object Parameters: More Detail

Saving Vectors to a File

Filtering What Gets Plotted

Operations on Vectors: Magnitudes and Colors

Plotting Cross-sections Through an Image

Histograms

Plotting Frames Diagnostics

Putting it All Together: A Mosaic and Color-Magnitude Diagram of Selected Galaxies

Other Ways of Looking at Photo Outputs

Plotting with SM

Stand-alone Code to Use FITS Format

Using IDL

Where to Get Help

Source Code

Photo command line

Help with supporting software

People

Bug Reporting