Features / Functions – Aperture Photometry Tool

Always remember the first rule of data:
Look at the data!
Doing this and using this software will make you an “apt” astronomer.

APT’s Main Graphical User Interface (GUI)

Abstract

APT is software for astronomers interested in manually exploring the photometric qualities of astronomical images. It is a graphical user interface (GUI) designed to allow aperture-photometry calculations to be visualized. The finely tuned layout of the GUI, along with judicious use of color coding and alerting, is intended to give maximal user utility and convenience and minimal chance of blunders. Simply mouse-clicking on a source in the displayed image will instantly compute and print out, for the specified aperture geometry, source intensity and source-intensity uncertainty, along with both conventional and robust measures of the sky background and sky-background scatter. APT is geared toward processing a small number of images, and is not suitable for bulk processing a large number of images (unless a large number of CPU cores are available), unlike other aperture-photometry packages (e.g., SExtractor). However, APT does have a convenient source-list tool that enables aperture-photometry calculations for a large number of detections in a given image, albeit the user is advised that patience is required for the relatively slower computational times expected for software implemented in the Java programming language (although multi-threading can be enabled for faster runtimes). The source-list tool can be run either in the automatic mode to generate a hands-off photometry-results table, or in the manual mode to permit inspection and adjustment of the aperture-photometry calculation for each individual detection. APT displays a variety of useful plots with just the push of a button, including image histogram, aperture slice, source scatter, sky scatter, sky histogram, radial profile, and curve of growth. APT has many functions for customizing aperture-photometry calculations, including outlier rejection, pixel “picking” and “zapping”, and a selection of source and sky models. The radial-profile-interpolation source model, which is accessed via the radial-profile-plot panel, allows extrapolated recovery of flux density in pixels with missing data. Aperture corrections vs. aperture radius can be automatically computed and applied, if activated by the user preferences, so that the aperture size can be reduced for improved signal-to-noise ratio. Many of these software features can be especially beneficial in crowded fields.

Troubleshooting and Bug Reporting

If you experience unexpected behavior from APT, try looking at the output in the terminal window where you are executing the software (or in the console window if APT was installed and run as a double-click application). This may shed some light on the matter.

If you find a bug, please e-mail Russ Laher (laher@ipac.caltech.edu).

Basic Instructions

Choose the primary image to display. The primary image is the first image displayed in the main image-viewing panel (located in the upper right of the main GUI panel, and is overlaid with the label “CLICK ON IMAGE TO OVERLAY APERTURE”), and provides the input data for the aperture-photometry calculations.
Adjust the image stretch for best viewing. As an aid, click on the “Image Histogram” button to see the stretch range, and adjust accordingly.
Select the aperture attributes that are appropriate for the source of interest (integer values only). Similarly, select the centroid, inner-sky. and outer-sky radii. The controls for setting these parameters are located under the Edit menu on the menu bar.
Place the mouse cursor on image over source of interest and click to overlay an aperture.
Show/study the various graphs (instructions are given in the Graphs section below).
Select the desired new radii and/or change other settings as needed.
Redraw/overlay a new aperture by either clicking on “Recompute Photometry” button OR clicking on “Snap” button for nudging the aperture toward the integer pixel coordinates of the source-centroid location OR placing mouse cursor on the image and clicking.
If necessary, increment/decrement the aperture position using the spinner controls for fine tuning the aperture’s position.
Click on the “Recompute Photometry” button to redraw/overlay new aperture.
Show/study the various graphs again.
Optionally save/append the calculational results to a photometry-table file (e.g., APT.tbl) by clicking on the “Save Results” button.
Repeat the above steps for each source of interest!

Input Images

This software reads in only FITS-formatted images. This includes image files with either single or multiple extensions. It also handles FITS files containing data cubes, but not tables (at this time). The software was upgraded in v. 2.6.1 to read in fpack-compressed FITS files directly (which have the .fz filename extension). The software has been tested on FITS images from a variety of projects, including Spitzer, SkyView, IRAS, CFHT, Herschel, LSST ImSim, HST, WISE, and the Palomar Transient Factory (PTF), as well as .fz files from the Las Cumbres Observatory Global Telescope (LCOGT) and Zwicky Transient Facility (ZTF).

Image-data values that are set to NaN (not a number) or Inf (infinity) are displayed with the “blank” color set by the user. Blue is the default blank color, but this can be changed via the available color-picker control. Inf values are handled the same as NaNs and almost no distinction is made between these two special types.

The user can specify the maximum image size that the software will load into memory. This is done via the Preferences menu on the menu bar. The default maximum image size is 10,000 pixels on an image side. For images larger than the assigned maximum, the user will be prompted to specify the desired portion of that image after the filename of the image has been given.

BUNIT is a keyword defined by the FITS Standard for specifying the physical units of the image data. If this keyword is either missing or null in the image FITS header, then the BUNIT setting stored in the user-preferences file will be used. If the stored setting is not available, then, for clarity in various GUI-panel labels, the software will substitute in for BUNIT the setting “D.N.”, which stands for “Data Number”.

Here are some details on the image-display stretch. For purposes of image display only, all pixel intensities outside the interval specified by the stretch extrema are set to the corresponding extreme value; this confines the data set for the histogram plot to within the stretch range. The linear stretch displays intensities that are proportional to the image data values. The logarithmic stretch displays intensities that vary nonlinearly with image data values. Nonlinearity control is provided by a dynamic-range parameter, which must be set to a positive value. Values approaching zero drive the stretch toward linearity, and higher values result in increased nonlinearity that enhances image viewing in the low end of the display range.

The user will quickly learn that the stretch and color-table controls now work only within the visible portion of the image displayed in the upper-right main image-viewing panel. Thus, only this visible portion, plus some hidden margin, is actively updated when image-viewing settings are changed. Moving the scroll bars for large images will reveal the once-active portion of the image inside an obvious bounding box, with possibly a corrupted-looking image display outside of the bounding box. To remove unsightly remnants of the bounding box and refresh the displayed image, two refresh buttons are available. “Refresh 1″ just quickly refreshes the visible portion of the image to save time. “Refresh 2″ refreshes the entire image, which launches multiple threads for refreshing the unseen portion of the image, so that immediate GUI control is returned to the user. For very large images, however, the threads take some time to complete and may still be running even though the user is allowed to continue normal work with the GUI. To avoid queuing up too many threads, do not click on the “Refresh 2″ button repeatedly within the span of a few seconds. The “Refresh 2″ button text will turn to the color yellow to remind the user to click on this button before scrolling about the image. It is not mandatory for the user to click on the “Refresh 2″ button when its text turns red; the user should do this only if/when the scrolls bars are to be moved.

Once the image stretch has been properly set, it is often desirable to save the displayed image in a file for importing into a report document. APT has functionality for exporting a screenshot of the primary image to a file in a choice of the user-selectable formats JPEG, PNG, BMP, or GIF. This tool can be accessed by the “Screenshot” button on the main GUI panel and the “Export Image Data to Image File” option under the File menu-bar category.

Aperture Controls

To perform an aperture-photometry calculation, simply mouse-click on the image in the main image-viewing panel at the location where the aperture is to be centered. An aperture graphic will be overlaid onto the image at that location, consisting of the following: a red circle or ellipse representing the aperture, sized according to the aperture major and minor radii settings; horizontal (cyan) and vertical (pink) crosshairs slicing through the aperture center; and circles or ellipses for the inner (green) and outer (yellow) sky annulus, which is displayed only when sky models B, C, D, E, or F which require sky-background subtraction, are selected via the “More Settings” panel (see below for more details). The above image of the main GUI panel shows an example of the aperture graphic.

The software permits elliptical apertures with arbitrary orientations. Only integer values can be specified for the major and minor aperture radii and rotation angle. The sky annulus for the background-brightness calculation is sized by scaling the inner and outer sky radii off the aperture’s ellipse axes. The centroid major radius for computing the source centroid can be specified separately from the aperture major radius. The controls for setting these parameters are accessed via the “Major Photometry Radii” and “Aperture Size, Shape, and Angle” options located under the Edit menu on the menu bar. There is also a big button on the main GUI panel for more convenient access.

Changes to the centroid, aperture, and sky-annulus radii, as well as other settings, are only instantiated (to give new results) when either a new aperture is overlayed onto the image, or by clicking on the “Recompute Photometry” button.

Changes to the aperture position via the spinner controls are only instantiated by clicking on the “Recompute Photometry” button.

A “Snap” button is available on the main GUI panel to nudge the aperture onto the computed source-centroid location. After moving the aperture, it recomputes the photometric results (just like the “Recompute Photometry” button). The “Snap” button text will turn yellow to remind the user to click on this button to fully center the aperture on the centroid location. This color reminder can and should be ignored if the user wants photometric results for an aperture that is dislocated from the centroid position. The source-centroid calculation does not always give the best aperture position for the source of interest, especially if there are other sources nearby; use visual feedback from the aperture-slice and source-scatter graphs for improved aperture-positioning.

By default, the photometry calculation is performed with the aperture centered on the calculated centroid and using an aperture-position resolution of 0.2 pixels. The “Centroid (X, Y) =” label on the lower-left main GUI panel is displayed in a green color to indicate this. Un-checking the “Use centroid in photometry calculation?” check box on the “More Settings” panel will cause the photometry calculation to revert to centering the aperture on the integer pixel coordinates of the selected aperture position.

To temporarily remove an aperture overlayed onto the image, click on the “Hide/Show Aperture” button. Click on the same button again to show the aperture.

The pick/zap tool enables users to click on enlarged sub-image pixels in the vicinity of the aperture position to pick off pixel positions and pixel values and put them in a text field in which the data can be copied and pasted elsewhere. The zap function allows selected pixels to be omitted from the calculation for purposes of improving the photometric result. More details are given in the Pick/Zap Tool section below.

Menu Bar

APT has a standard menu bar with the following categories: APT, File, Edit, View, Tools, and Help. This is a work in progress, and new functions are under development for addition as menu options, and existing functions will be added to the menu bar as time permits. Some of the functions accessible via the menu bar can also be accessed via buttons on the main GUI panel (such as opening an image). The APT menu-bar category, a.k.a the application menu has About, Preferences, and Quit options. The File menu-bar category has the following options: Open Image; Set Photometry Filename; Clear Photometry File; Export Image Data to Image File; Export Image Data to CSV (comma-separated values) File; and Export Photometry Data to CSV File. The Edit menu-bar category has the following options: Photometry Major Radii; Aperture Size, Shape, and Angle; Preferences (see next section); and More-Settings Panel. The View menu-bar category currently has two options: Color-Table Levels (to display a panel with the currently existing color-table levels); and Image Comparator. The Tools menu-bar category has the following options: Simple Photometric Calibration; Position Locator; and Decimal/Sexagesimal Converter.

A few of the menu options have keyboard shortcuts. For example, to set the output aperture-photometry-table filename using a File-Chooser Dialog, use “Command-s” for Macs and “Control-s” for Windows machines. For non-Mac machines, some of the menus can be accessed via keyboard mnemonics, such as “Alt-p” for the Preferences menu (no keyboard mnemonics have been included for Macs as this practice is frowned upon in the Mac Developers Guide).

Preferences

Upon APT start-up, a set of customizable user preferences are automatically read in from the default preferences file, called “APT.pref”, located in a hidden directory called “.AperturePhotometryTool” in the user’s home directory. If this file does not exist, then the factory default values are loaded into the user’s APT session (but not automatically saved). Various options in the Preferences menu allow the user to change the default settings and then save them in the default preferences file for later automatic pre-loading (or the user can choose to save it somewhere else and load it in manually later when needed). Selecting the “Reset Default Preferences” option in Preferences menu will restore the factory default settings to the user’s session, but will not save them. If “Save Preferences” is selected, then the current settings of the user’s session will be written to a location and filename of choice, and all prior custom settings in any preexisting file specified will be overwritten.

Note that at any time during a user’s session, most of the current settings, as set by the various GUI controls within and without the Preferences menu, are the instantaneous user’s preferences for the session, albeit not necessarily saved. This can be verified by clicking on the “List Preferences” function under the Preferences menu. Therefore, the “Save Preferences” function under the Preferences menu will capture a large portion of the current state of the user’s session.

Whenever a new primary image is read in, the preferences are restored from file APT.pref in the hidden directory called “.AperturePhotometryTool” in the user’s home directory.

Some of the preferences affect the computing speed of the software. Allow several seconds for computations involving small calculational step sizes and very large centroid, aperture and/or sky-annulus radii. The “Set Maximum Number of Threads” function under the Preferences menu can be changed from its default value of 1 to a larger value, and this will enable multithreading for the source-list tool and, consequently, may drastically improve its computational speed.

Aperture-Photometry Settings

The “More-Settings Panel” option under the Edit menu-bar category allows parameters that are more directly associated with aperture photometry to be changed. This panel can also be brought up via the “More Settings” button in the lower left corner of the main GUI panel.

Values for outlier-rejection thresholds on the “More Settings” panel must be given in image data units. It is best to show/study the various graphs and set these thresholds before converting image data units to flux-density units, via the “Perform image-data conversion” checkbox on the “More Settings” panel.

According to Laher et al. (Publications of the Astronomy Society of the Pacific, Vol. 124, No. 917, July 2012, pp. 737-763, PDF),

The source-magnitude uncertainty is given by 1.0857 times the source-intensity uncertainty divided by the source intensity. This can be easily derived by taking derivative of the well-known relationship between source magnitude and source intensity. Note that 2.5 times the natural logarithm of 10 is approximately 1.0857.

The calculation of source-intensity uncertainty requires both the gain (electrons per D.N.) and the conversion factor from image-data units to D.N. The default value for both quantities is 1.0. The default values can be overridden from the “More Settings” panel. When a primary image is loaded, the software attempts to read the GAIN FITS-keyword and, if found, automatically overrides the default gain value. For image data that are already in units of D.N., the value of 1.0 is appropriate for the image-data-to-D.N. conversion factor.

Models B through E are sky algorithms that employ various statistics as sky-background estimators, which are computed over the pixels in a circular or elliptical annulus centered on the source of interest. There is one non-annulus-based sky algorithm called “Model F” that uses a local estimate for the sky background that is computed via bilinear interpolation of the mode statistic computed with a user-specifiable window size on a user-specifiable grid size (the median statistic is used instead if the window is less than 33 pixels). The Model-F input parameters can be changed on the “Local Non-Annulus Sky Background Tool” panel, which can be accessed via the “More Settings” panel and displayed by selecting Model F, clicking on the “Apply Settings”, and clicking the “Yes” button on the pop-up dialog. Model F is potentially more useful than Models B-E in crowded stellar fields.

Here are some other details about Model F, the non-annulus local sky background estimator:

The sky-annulus graphic is displayed even if Model F is selected because I haven’t yet had time to modify the code to display a different graphic. As it stands, the displayed sky annulus merely indicates that background subtraction is enabled, but the Model-F non-annulus local sky background estimate is nevertheless used when Model F is selected.
The aperture-photometry calculation uses the Model-F background estimate at the location of the center of the aperture:localNonAnnulusBkg = localNonAnnulusSkyBkgImage.getImagePixelValue( icenter, jcenter );
The most-recently-computed Model F sky background is stored as a FITS file in the APT hidden directory, and you can copy it to a non-hidden location and use APT to examine it:~/.AperturePhotometryTool/skyBackgroundModelF.fits
When Model F is calculated, you can specify the coarseness/fineness of a grid and a window size. The mode of all image pixels within the square window centered on each grid point is computed (the median is used instead of the mode if the window size < 33 pixels). If you want additional smoothing, you have the further option of median-filtering the grid values, using a limited selection of median filters (i.e., no median-filtering, or 3×3-, 5×5-, or 7×7-pixel subgrid median-filtering), where the value at a grid point is replaced with the median value of the chosen small subgrid of surrounding main-grid-point values. Once the grid has been computed, bilinear interpolation is used to compute the Model-F non-annulus local sky background estimate at any given pixel location (and, again, the location of the aperture center pertains to this in the aperture-photometry calculation).
The Model-F non-annulus local sky background is continuous (and quite robust), but the first derivative is not continuous, and you can see the underlying grid structure in any example, where the image stretch can greatly exaggerate the local background variations seen.

Near the bottom of the “More-Settings” panel are options to convert the image-data units to other data units. This conversion is ex post facto (“after the action”), and, therefore, the specified magnitude zero point must be cast in terms of the original data units.

Graphs

2-D Graphs

APT creates several different kinds of 2-D graphs, thanks to the JFreeChart library from www.jfree.org.

For example, a histogram of the entire image can be plotted by clicking on the “Image Histogram” button on the top-left side of the main GUI panel. The lower and upper limits of this graph’s x-axis are set by the image-display stretch bounds. This histogram is, of course, useful for determining the best stretch. Convenient image statistics are listed on the image-histogram panel, and include mean, standard deviation, median, scale (robust estimator of data-distribution width, given by [84 percentile – 16 percentile]/2), 1 percentile, 99 percentile, number of samples that are not NaNs or Infs (not-a-number or infinity), and number of NaNs and Infs. Except for the number counts, the data units of the image statistics are given by the image’s BUNIT FITS-header keyword, or, if BUNIT is not available, set to “D.N.” (which stands for “Data Number”).

Display the graphs by clicking on main-GUI-panel buttons labeled “Image Histogram”, “Aperture Slice”, “Source Scatter”, “Sky Scatter”, “Sky Histogram”, “Curve of Growth”, and “Radial Profile”, in any order, although the order listed is a good one for adjusting the APT settings systematically. Here is an example of a curve-of-growth plot:

Each time a graph button is clicked on, a new graph is displayed, and previously displayed graphs are not destroyed. This software behavior allows users to create and compare graphs from different APT settings. Users must exercise some discipline in closing graph windows themselves, in order to prevent proliferation of graphs on their computer screens.

APT has capabilities for plotting aperture-photometry results in publication-ready appearance, which is accessed via the “Plot Results” button located in the lower-left corner of the main GUI panel. Pie charts, bar charts, scatter plots, histogram plots, and density (2-D histogram) plots are available. Generally, the pie and bar charts are useful when only a few data points are available for graphical comparision, and, conversely, the histogram and density plots are useful when there is a large number of data points.

Other things to know about the graphs:

The graphing software cannot handle very large or very small numbers, and responds by creating a graph with no numbers on the affected graph axis. If this is encountered, adjust the outlier-rejection range as needed until the problem goes away (click on “More Settings” button on bottom-left side of main GUI panel).
Drag mouse cursor across graph to narrow the range of the plotted data.
Right-click mouse on graph to zoom in/out, save as PNG image, etc. (Mac users will need a “mighty mouse” and, will also have to configure the mouse under “System Preferences” to set up
right-click as a secondary button).

3-D Graphs

There is a relatively new interactive tool under the Tools menu bar, called “Aperture Image-Data 3D Surface Chart”, that displays a projection of a three-dimensional surface of the image data around the aperture location. The 3D chart can be rotated interactively by dragging with the mouse to view the aperture image-data from any angle. Recomputing the photometry with a different aperture radius will accordingly change the subimage size covered by the 3-D chart.

The 3-D surface is computed via bilinear interpolation. In the preferences (save preferences after running the new tool), the keyword

apertureImageSurfaceChart3DGridAxisSamples

controls the number of samples in the interpolation grid along each dimension of the subimage, and the default value is 90. Setting a higher number of interpolation-grid samples will increase the resolution, but make the rotation response slower. ALT-mouse-drag can be used to move the 3D surface chart within the display panel, and the mouse wheel zooms in and out. This capability utilizes the Orson Charts 3-D Java library: http://www.object-refinery.com/orsoncharts. Here is an example:

Output Files

During the operation of this software, several output files are created. Except for the following exceptions, all output files are created in the scratch directory with fixed filenames. The photometry-table path/filename, location of the scratch directory, and user-preferences path/filename can be changed via the Preferences menu. Only the user-preferences file called “APT.pref” in a hidden directory called “.AperturePhotometryTool” in the user’s home directory, if the file exists, is automatically read in upon APT start-up; however, additional user-preferences files can be created with different names and locations, but these must be loaded manually.

Fixed or Default Filename	Definition
APT.pref	Customizable user preferences that are read in upon APT start-up
APT.tbl	Table of photometric results, in plain-text format with space-delimited columns
fitsHdr.txt	FITS header
apertureSliceX.dat	Horizontal image slice across aperture
apertureSliceY.dat	Vertical image slice across aperture
skyScatter.dat	Image data in sky annulus
sourceScatter.dat	Image data in source aperture and sky annulus
curveOfGrowth.dat	Data shown in curve-of-growth graph
radialProfile.dat	Data shown in radial-profile graph
radialProfileDataFitCurve.dat	Data-fit curve shown in radial-profile graph
radialProfileDataFitModel.dat	Data-fit model for radial-profile graph
scatter.dat	Photometry-table results in scatter plot (selected columns by user)
sourceListByAPT.dat	Source list extracted from image

Columns in Photometry Table

APT generates a table of photometric results in a plain-text, space-delimited file, the default filename of which was given in the previous section. The columns that make up this table are listed below. Note: A new column called Flags was added in APT, v. 2.7.8.

Column(s)	Definition
Number	A source counter, which is reset to one each time either 1) a new primary image is loaded; or 2) the source-list tool is executed. In the case of the latter, the ordering of this counter is consistent with the input source list (and the ordering of the output will be generally different if multi-threading is enabled).
ApertureRA, ApertureDec	Sky coordinates of aperture center (decimal degrees or sexagesimal representation, as set by preferences menu).
CentroidRA, CentroidDec	Sky coordinates of source centroid (decimal degrees or sexagesimal representation, as set by preferences menu).
ApertureX, ApertureY	Image coordinates of aperture center (nearest-integer pixel coordinates).
CentroidX, CentroidY	Image coordinates of source centroid (fractional-pixel coordinates).
CentroidFlag	“Centroiding” flag, equal to 1 when the option to perform the photometry calculation with the aperture centered on the calculated centroid has been selected, and zero otherwise. This option is accessible on the control panel via the “More Settings” button on the bottom-left of the main GUI panel.
SourceIntensity	Integrated intensity of the source (in the aperture), in data units given by the “DataUnits” column (see below). Can either include the sky contribution or not, depending upon the setting of the “SkyModel” column.
ApertureCorr	Applied aperture correction, a factor greater than one, to account for the fraction of source intensity outside of the aperture, which is useful when avoiding large aperture to improve the signal-to-noise ratio.
SourceUncertainty	Uncertainty associated with the source intensity, in data units given by the “DataUnits” column (see below). This calculation uses “SkyScale” as a robust estimator of the sky-background sigma (see below).
DataUnits	Data units of “SourceIntensity”, “SourceUncertainty”, “SkyMedian”, “SkyAverage”, “SkyRMS”, “SkyCustom”, “SkySigma” and “SkyScale” columns.
Magnitude	Magnitude representation of “SourceIntensity”.
MagUncertainty	Magnitude uncertainty, given by 1.0857 times “SourceUncertainty” divided by “SourceIntensity”.
SourceModel	“0″ if no radial-profile interpolation has been done; “1″ if radial-profile interpolation has been done only for NaN/Inf pixels in the aperture; or “2″ if radial-profile interpolation has been done for all aperture pixels.
SkyModel	“A” if the background-sky contribution has not been subtracted from the “SourceIntensity” (see above); “B” if the sky median has been subtracted; “C” if the custom sky has been subtracted; “D” if the sky average has been subtracted; “E” if the sky mode has been subtracted; or “F” if the non-annulus-based local sky background has been subtracted (see “SkyLocalNonAnnulusBkg” below).
SkyMedian	The per-pixel median of samples in the sky annulus after the sky outliers have been rejected, in data units given by the “DataUnits” column above. This value, which is a robust estimator of the sky level, times the number of pixels in the aperture form a product that is the sky contribution optionally subtracted from the integrated image data of the source.
SkyMode	The per-pixel mode of samples in the sky annulus after the sky outliers have been rejected, in data units given by the “DataUnits” column above. This value, the most frequent one in the sky histogram, times the number of pixels in the aperture form a product that is the sky contribution optionally subtracted from the integrated image data of the source.
SkyAverage	The per-pixel average of samples in the sky annulus after the sky outliers have been rejected, in data units given by the “DataUnits” column above. The disparity between the average and the median is an indicator of non-uniformity in the distribution of samples.
SkyLocalNonAnnulusBkg	A non-annulus-based, local sky background estimate, in data units given by the “DataUnits” column above, which is computed via bilinear interpolation of the mode statistic in a user-specifiable square window size on a user-specifiable grid size (the median statistic is used instead if the window is less than 33 pixels).
SkyRMS	The per-pixel root-mean-squared (RMS) value of samples in the sky annulus after the sky outliers have been rejected, in data units given by the “DataUnits” column above. This value is slightly larger than the average, and will be equal to the population standard deviation in the special case of zero-mean samples.
SkyCustom	The per-pixel custom-sky value specified by the user, in data units given by the “DataUnits” column above.
SkySigma	The standard deviation of samples in the sky annulus after the sky outliers have been rejected, in data units given by the “DataUnits” column above, calculated using the “unbiased” or “n-1″ method. This result has not been inflated to account for the optional data-clipping of the distribution’s tails (needs to be rectified in a future version of this software).
SkyScale	Robust estimator of the sky-background sigma, in data units given by the “DataUnits” column above. It is given by the difference between the 84 and 16 percentiles of the sky-data distribution (which correspond to +/- one standard deviation in a Gaussian distribution), divided by 2.
RadiusCentroid	Major radius of the ellipse for the source-centroid calculation (pixels).
ApertureMajorRadius	Major radius of the elliptical aperture for the source (pixels).
ApertureMinorRadius	Minor radius of the elliptical aperture for the source (pixels).
ApertureRotationAngle	Rotation angle of the elliptical aperture for the source (degrees). This angle is with respect to the image’s horizontal axis, and a positive angle rotates the ellipse counter-clockwise.
SkyRadiusInner, SkyRadiusOuter	Major radii of the elliptical inner and outer sky annulus (pixels). The corresponding minor radii are derivable by assuming that the sky-annulus inner and outer ellipses are proportional to the aperture ellipse.
ApertureNumPixels	Number of samples in the aperture after the source outliers have been rejected (see “ApertureNumRejected” column below). It is these samples that are summed to yield the integrated image data in the aperture. This quantity has a fractional component because the photometry calculation is now being done with sub-pixel resolution.
ApertureNumRejected	Number of source outliers rejected. These represent losses of integrated image data, for which no accounting has been made in the current version of APT software.
SkyNumPixels	Number of samples in the sky annulus after the sky outliers have been rejected.
RadialProfileFWHM	Full width at half maximum (FWHM) of the radial profile of the source (pixels).
Flags	An integer that contains bit-wise binary flags for various conditions that affect the aperture-photometry calculation. Bit 0, value=1 (=2^0): Aperture contains one or more source pixels (or portions thereof) with non-NaN values that were rejected from the photometry calculation (i.e., outside of range defined by lowerSrcDataLimit and upperSrcDataLimit in APT.pref). Bit 1, value=2 (=2^1): Aperture contains one or more source pixels (or portions thereof) with blanks or NaNs (not a number). Bit 2, value=4 (=2^2): Aperture contains one or more source pixels (or portions thereof) with values at or above the saturation level (caveat emptor: pixels in the original image might have been zapped, in which case, these are not included here). As an example, if an aperture contains all three types of abnormal pixels (rejected, blank, and saturated), then the flags value will be 1+2+4=7. Note: If either of the interpolation source algorithms is selected (Model 1 or 2), then the flags for bits 0-2 will apply to the interpolated values that replace original values.
Image	Path/filename of image.

The photometry-table file can be listed by clicking on the “List Results” button, and a maximum of 100,000 records per file will be listed. User-selected columns in the photometry table can be plotted one against another by clicking on the “Plot Results” button. Both buttons are located in the bottom-left corner of the main GUI panel. The latter button displays the following panel, which has controls for setting up various plots.

Thumbnail Panel

The “Thumbnail” button on the bottom middle of the main GUI panel pops up a separate panel that is capable of displaying the entire primary image, rather than just the image portion displayed in the main image-viewing panel. At the top of the thumbnail panel are “Clear Line/Box”, “Slice”, and “Show Grid” buttons, and a display of the real-time mouse-cursor position in both image and equatorial coordinates, as well as a display of the real-time pixel data value at the cursor position.

The mouse cursor can be dragged across the thumbnail image to overlay a green line between two points of interest in the image, as well as a yellow box. The angular separation between the two points is computed, in angular units if the world coordinate system (WCS) is available, otherwise in pixels. The integrated intensity of the image data and the number of pixels contained in the rectangular box are computed. The box has been dubbed “Laher’s square”! The “Clear Line/Box” button can be utilized to remove the green-line and yellow-box overlay.

Once a Laher’s square has been overlayed onto the image, the “Slice” button will be enabled. The “Slice” button pops up a plot of the image data across the entire image along a line through the mouse-pressed and mouse-released corners of the box. The slice can be horizontal, vertical, or at an arbitrary angle, depending upon the direction the mouse is dragged. When a user clicks on a curve feature in the slice plot, a small circle will be drawn around the corresponding source in the thumbnail image.

The “Show Grid” button will overlay a grid labeled with equatorial coordinates, and then subsequently transform into a “Hide Grid” button. If a WCS is not available in the image’s FITS header, then the coordinates-grid overlay will be disabled.

The thumbnail image can be made to fit on the user’s computer screen using the “Set Maximum Thumbnail Size” option in the Preferences menu. If the thumbnail image is set to larger than the user’s screen, then the panel will be automatically scaled to fit and scroll bars will appear. The maximum size of the thumbnail image has been limited to no less than 500 pixels.

Exporting Images

The software can export a screenshot of the primary image to a file (after the user has adjusted the image stretch for best viewing), and allows a choice of the following popular image formats JPEG, PNG, BMP, or GIF. This functionality can be accessed by the “Screenshot” button on the main GUI panel and the “Export Image Data to Image File” option under the File menu-bar category.

Exporting Data to Excel

The “Export Image Data to CSV File” option under the File menu-bar category allows a portion of the
currently loaded primary image to be exported to a comma-separated-value (CSV) file, which can be directly
imported into Excel for more detailed study. For example, Excel’s three-dimensional plotting capabilities
can be used to visualize the image data for more insight. The user is cautioned that Excel only allows up to 256 columns of data to be imported.

The “Export Photometry Data to CSV File” option under the File menu-bar category writes the data in the output aperture-photometry-table file into a comma-separated-value file, which can be directly imported into Excel for further analysis. Among the available options is a checkbox option for one additional custom column in the output table, based on the FITS-header values associated with the images listed in the photometry-data file for a specified keyword; this is useful for time-domain astrometry, where it is desirable to have an MJD column in the results table.

Radial-Profile Interpolation

Special Notes:

Radial-profile generation and its subsequent use in interpolation should only be done for circular apertures.
The numbers displayed on the radial-profile-tool panel are shown in scientific notation, regardless of whether the user preferences are set to disallow scientific notation (this is an incentive to learn how to read scientific notation).

The radial-profile graph panel has extra controls for fitting the data associated with the currently selected source to a parameterized model radial profile. There is also a function that computes full-width at half-maximum (FWHM) of the radial profile, in pixels.

The radial-profile model is

S(r) = A + B r + C r^2 + D r^3 + E r^4 + F exp( -r^2 / (2 sigma^2) )

where: S(r) is the surface brightness as a function of radial distance from the aperture center, r, in pixels; constants A through F are determined via linear regression; and sigma is a fixed parameter that can be manually adjusted to optimize the data fit. In order to build a model for the image of interest, the user must follow these instructions precisely:

On the “More Settings” panel (accessed via the “More Settings” button on the lower left part of the main GUI panel), select the “Model 0″ source algorithm and the “Model A” sky algorithm. Also, the checkbox labeled “Perform new image-data conversion” on the “More Settings” panel should NOT be checked. A screenshot of the “More Settings” panel is given above. Warnings will be given when the model is saved with these conditions not met.
Fit the radial-profile data by operating the controls on the right-hand side of the radial-profile-plot panel (accessed via the “Radial Profile” button on the main GUI panel). A new fit will be done when the user clicks on either the “Reset Sigma” button, the “Set Slider” button, or the “Recompute Fit” button. Typically, the “best fit” is obtained when Chi^2 is minimized; this, at least, is the goal of the linear regression as implemented in APT. Hint: A not-so-good fit can be made better by reducing the aperture and sky-annulus radii. When a new fit is done, the scale and offset parameters are reset to 1.0 and 0.0, respectively (more details about these model-exogenous parameters are given below).
Once the user has obtained an acceptable fit, the model parameters can be saved by clicking on the “Save” button. The model parameters are written to a file in the scratch directory called “radialProfileDataFitModel.dat”. Only the data-fit model that has been written to this file will be subsequently used in APT calculations involving interpolation.

Once the radial-profile model parameters are saved (as described above), the model can subsequently be used for interpolation with any of the appropriate source algorithms available and any of the available sky algorithms. The algorithms can be selected on the aforementioned “More Settings” panel. The source algorithms that involved interpolation are described as follows.

The “Model 1″ source algorithm is used for interpolating across aperture pixels with NaNs/Infs, in order to fill in missing flux density. It also replaces the missing flux density associated with rejected source outliers in the aperture, provided that the interpolated result falls within the lower and upper limits set for source outlier rejection.

The “Model 2″ source algorithm is used for interpolating flux densities in all aperture pixels, even for those pixels with good data. When this source algorithm is selected, a two-parameter linear regression is automatically performed for each aperture-photometry calculation to scale and offset the radial-profile model (treated as a fixed model here), in order to best fit the model to the data for the sources of interest. Thus, the radial-profile model can be derived from one source and applied to other sources. This model is particularly useful when the image data have an axially symmetrical point spread function (PSF) and the PSF is invariant over the image; in this case, the “Source List Tool” described in a separate section below can perform what is essentially PSF-fitting photometry for a large number of sources. The computed aperture-photometry result from this source algorithm will be less sensitive to the effects of noise in the image data.

Finally, the radial-profile graph panel has also been equipped with controls for manually scaling and offseting the radial-profile model. The current purpose of these controls is mainly to allow the user to experiment with the scale and offset parameters and instantly visualize the effects on the plotted model curve. In a later APT version, it is possible that functionality may be added to allow manual override of the currently built-in automatic scaling and offsetting of the radial-profile model when used for interpolation.

Pick/Zap Tool

The pick/zap tool, which is access via the eponymous button located on the lower middle of the main GUI panel, has a few useful functions for probing and fine-tuning aperture-photometry calculations. After an aperture has been overlayed onto a primary-image source in the upper right of the main GUI panel, an enlarged sub-image centered on the aperture is displayed in the pick/zap tool’s work area. Moving the mouse cursor over the sub-image causes the passed-over pixel positions and associated image-data values to be rapidly displayed.

When the “Pick” radio button is selected (and an aperture-centered sub-image is displayed), the user can mouse-click on the sub-image to pick out specific pixels. Picked pixels are highlighted in the sub-image by an outline around the pixel in the current pick color. The picked image-pixel coordinates and associated image-data values are listed in the adjacent text area. The image-data values can be copied to the clipboard from the text area for analysis by other software programs. The pick color can be changed via the preferences menu.

When the “Zap” radio button is selected, the user can temporarily set specific pixel values to NaN (not a number) by mouse-clicking on the pixels of interest. NaN values are excluded from the aperture-photometry calculations, but this happens only after the “Recompute Photometry” button has been clicked on to update the aperture-photometry calculation. from the color black to the color red as a reminder to the user that the photometry calculation needs to be updated. Pixel-zapping functionality is useful, for example, for eliminating sources from the sky annulus that adversely affect the sky-background calculation. Zapped pixels are displayed in the sub-image with the blank color, and their locations and associated image-data values are listed in the adjacent text area. The blank color can be changed via the preferences menu.

The “Hide/Show Aperture” button is a toggle that hides or shows the overlayed aperture. It is included as a convenience for more clearly showing the sub-image. When the aperture is not hidden, all aperture pixels are outlined in the color red on the sub-image, except for the aperture-center pixel, which is outlined in the color cyan to indicate the aperture center. The sky-annulus pixels are outlined in the color green.

The picks and temporary zaps are kept on the sub-image and in the text areas when the “Hide/Show Aperture” button is pressed. This is also true when any of the image-display controls are adjusted, including stretch, linear/logarithmic scaling, color table, and pick and blank colors.

The centroiding, aperture, and sky-anulus radii can also be changed without clearing the picks and zaps. The same goes for changes made within the “More Settings” panel. After these sorts of changes, in which the aperture may be resized, but is not moved, either the “Recompute Photometry”-button text will change from the color black to the color red to indicate that the photometry calculation needs to be updated, or the photometry will be recalculated in the case of radii changes. Clicking on the “Recompute Photometry” button will nevertheless use the new radii in the updated aperture-photometry calculation.

Finally, any adjustment that changes the aperture’s position will cause the picks and temporary zaps to be cleared, and the image-data values will revert to those in the original image. Note that NaNs in the original image will, of course, be preserved. The aperture can be moved by clicking on either another source in the upper-right main image-viewing window, or the “Snap” button, which will automatically move the aperture to the centroid position. Adjusting the aperture-position spinner controls will also clear the picks and zaps, although the aperture movement itself, in this case, will not be done until the “Recompute Photometry” button has been clicked on. Clicking on the frame around the main image-viewing window when the mouse cursor is shown in the cross-hair style will cause the overlayed aperture and displayed
sub-image to be removed, as well as the picks and zaps.

Source-List Tool

After an image for aperture-photometry calculations has been selected, the user can access the source-list tool via the “Source List” button on the upper-left side of the main GUI panel. The tool does automatic or manual processing of a source list associated with the chosen image. Source lists for this tool can be created by parsing the output of popular source-extraction software, such as SExtractor. It is even possible to create a source list by editing APT’s output photometry-table file (after copying it to another filename).

The source-list tool first requires that the filename of a source list be selected. The format of the source-list file is plain text and consists of one set of source coordinates per line in the file, where the coordinates are delimited by one or more spaces. Either image-pixel coordinates or equatorial coordinates are permitted. Equatorial coordinates can be either in decimal degrees or the sexagesimal representation with “hms dms”
delimeters (e.g., 233.73800 or 15h34m57.12s with no spaces for right ascension, and -23.50319 or -23d30m11.5s with no spaces for declination). An optional header line at the beginning of the source-list file is allowed and auto-detected. Here is an example source-list file:

x       y
723.2   279.0
729.4   145.45
622.195 205.857
595.9   318.4
731.11  195.54
674.84  140.09
643.2   153.1
735.0   161.6
742     237.83
718     301
664     316
715     236

The maximum number of sources allowed is 100,000.

An exception will be raised if the file format is incorrect (e.g., comma-separated values are not allowed).

The user has the option of selecting the button labeled “Automatically Process Source List”, in which case, aperture-photometry calculations will be performed for all sources in the source list for the current aperture-photometry settings. Thus it is important that the user select the desired aperture-photometry settings before pressing this button. Once this option has been selected, identical aperture-photometry calculations will be done for all sources in the source list, and a record will be automatically saved for each source in the photometry-table file. The marker “Automatic Source-List Processing…” will be written to the photometry-table file prior to saving the aperture-photometry records.

The computing can be speeded up by taking advantage the source-list tool’s multi-threading capability. Under the Preferences menu, the option “Set Maximum Number of Threads” can be selected to increase the number of parallel-computing threads from one, the default value, to some larger value usually of the order of the number of available processor cores. Multiple threads, which are scheduled by the operating system, complete in no particular order, and this can result in records in the output photometry-table file that are out of order with respect to the input source list. However, the “Number” column in the photometry-table file allows the user to easily match records to input sources.

Another option available to the user is the “Manually Process Source List” button, in which case, an aperture will be overlayed onto the image for the first source in the source list, and the message “Ready to process source number = 1″, along with the image-pixel coordinates of that source, will be displayed. The user can, at this time, study the image in the vicinity of the aperture and manually adjust any or all of the aperture-photometry settings for that particular source on the main GUI panel and via the “More Settings” button, and then press the “Recompute Photometry” button and view the graphs to make sure that the settings are just right. After the user is satisfied with the settings for that particular source, the “Step Through Source List” button can be pressed, which will redo the aperture-photometry calculation, save a record of the calculational results in the photometry-table file, and then overlay an aperture onto the image for the next source in the source list. The marker “Manual Source-List Processing…” will be written to the photometry-table file prior to saving the aperture-photometry record for the first source. The above steps are repeated for each successive source in the source list. After the source list has be exhausted, the message “Done with source list.” will be displayed. To reset manual processing and start again (perhaps after another selection of aperture-photometry settings has been made), simply press the “Manually Process Source List” button once more.

A function for extracting sources from the image data and creating a source list is available. It utilizes spatially-varying thresholding that is comprised of a local background (normally the mode statistic, or the median if window size is less than 33 pixels) and local data dispersion (“sigma” is given by one half the difference between the 84.1 and 15.9 percentiles), and allows the user to select the grid and window sizes for these local-image statistics. The source detection threshold is an input parameter for the number of “sigmas” above the local sky background to threshold the image data. A source or set of unresolved sources is defined by a contiguous blob of above-threshold image pixels. Input parameters that limit the minimum and maximum number of pixels allowed for a source and that avoid detections near an image edge are available. Sources are deblended using a peak-detection algorithm, which looks for peaks in a source blob that have surrounding pixels with mostly lower data values within a 5×5-pixel region centered on the peak, in accordance with the selected radial-profile sigma, an input parameter on the “Source-List-Creation Tool” panel. Specifically at least 23 out of the 24 neighboring pixels must satisfy

neighborImageDatum <= factor * peakImageDatum

where

distanceFromCentralPixel = sqrt( ( j - jj ) * ( j - jj ) + ( i - ii ) * ( i - ii ) );
factor = exp( -distanceFromCentralPixel * distanceFromCentralPixel /
    ( 2.0 * sourceDetectionRadialProfileSigma * sourceDetectionRadialProfileSigma ) );

The “Source-List-Creation Tool” panel has a check box to allow the user to disable source de-blending, if desired.

Aperture-Correction Tool

As the size of an aperture is increased, the signal from the source becomes more fully contained and the noise encompassed by the aperture is increased, and, therefore, the signal-to-noise ratio (SNR) of the aperture photometry result is decreased. According to Mighell (ASP Conf. Ser., Vol. 172, pp. 317-328, 1999), the optimum SNR for a Gaussian PSF is obtained for a circular aperture radius of ~1.6 times sigma or approximately equal to 0.68 times the full width at half maximum (FWHM). Thus, the optimal aperture will not fully contain the source flux. There are also cases where source-crowding effects warrant using a smaller aperture. In such cases, a multiplier greater than one, called an aperture correction, is needed to correct for source intensity outside of the aperture. In theory, an aperture correction is always needed because of limited bandwidth considerations, but, in practice, no aperture correction is made for sufficiently large apertures. These considerations mainly influence the size of the aperture chosen for a study.

APT’s Radial-Profile Tool can be used to determine the FWHM of a representative source. APT’s Aperture-Correction Tool can be used to determine the aperture-correction value needed as a function of circular-aperture radius. The method involves computing curves of growth for bright, non-saturated, isolated stars in the image of interest. The curves of growth are normalized and averaged. The resulting curve is inverted to give the aperture correction vs. aperture radius. The appropriate aperture-correction value for a given aperture radius is then entered into the text field labeled “Aperture correction:” on the “More Settings” panel. This can be done either manually or automatically. Under the “Preferences menu”, the “Aperture-Correction Mode” can be set to either:

Manually set aperture correction;
Automatically compute aperture correction with input dialog; or
Automatically compute aperture correction using inputs from saved preferences or default values.

The last option causes the Aperture-Correction Tool to be executed automatically each time a new image is loaded, which will increase the loading time somewhat.

Simple Photometric Calibration

This software includes a user-friendly tool to provide the capability of performing simple photometric calibration. The tool matches two source lists and computes a single parameter, the photometric zero point, via sum-of-squared-error minimization. At least one match is required, but no more than 100,000 matches are allowed in the computation. The algorithm makes two passes through the data. The first pass computes robust data statistics, namely, the median and the data dispersion given by one half the difference between the 84.1 and 15.9 percentiles (which is equivalent to 1 standard deviation in the case of Gaussian-distributed data). The second pass applies outlier rejection and faint-source rejection to filter the data. A sufficient variety of data statistics are included in the output to guide the user in setting up repeat calculations to refine the result.

The required inputs are two space-delimited source lists in plain-text files. The software presumes one of the source lists is calibrated and the other is not. The source lists must contain sky coordinates in decimal degrees only (a planned forthcoming upgrade will allow sexagesimal coordinates). The calibrated source list must have only the 3 following columns: right ascension, declination, and absolute magnitude. The uncalibrated source list must have only the 3 following columns: right ascension, declination, and instrumental magnitude. The source lists can contain pairs of sky coordinates in either decimal degrees or sexagesimal representation. Each source-list file may include a header line containing 3 space-separated, single-word column titles (e.g., “RA Dec Mag”). The software will read in up to 100,000 sources from each source list. The source lists are, by default, expected to be located in the source-list directory specified in the APT user preferences, but the user can navigate elsewhere, if necessary.

There are optional inputs to control the computation. The match radius gives the maximum tolerable distance between sources for a match, and its default value is 1 arcsecond. The outlier-rejection threshold, in magnitude, allows outliers to be defined and excluded from the computation, and its default value is 0.3. The faint-source-rejection threshold, in magnitude, assures that only matches of sufficient brightness will be included in the computation, and its default value is 21. The tool will optionally normalize the zero point by an input exposure time, and the default exposure time is 1 second (which is equivalent to not normalizing by the exposure time).

The tool generates and displays a plot of magnitude difference vs. magnitude. There are options to customize the plot on the tool’s main panel. The user can also right mouse click on the plot to expose additional plotting options. One of these options allows the user to save the plot as a PNG image.

PSF Photometry

APT has an optional tool for computing PSF photometry as an ancillary product. It is accessed under the Tools menu bar. The flux (source intensity) is computed by convolving the data with a user-supplied PSF (point spread function). The PSF Photometry tool, on a separate panel, works independently of the aperture-photometry calculations on the main GUI panel, although clicking on the Compute button on the PSF Photometry panel will cause the aperture photometry to be recomputed on the main GUI panel at the position indicated on PSF Photometry panel. No centroiding is done for the PSF photometry, so the results are forced photometry at a single, user-specified source position. The result set comprises the flux and associated uncertainty, along with the alternate representation in terms of magnitude and its uncertainty. The data units of the flux and its uncertainty are given by BUNIT in the FITS header of the data (or set to DN for “data number” if BUNIT is not present). The PSF-photometry results are only displayed on the PSF Photometry panel, and are not written to the photometry file where only aperture-photometry results are stored.

The following is a list of the pertinent configuration parameters that can be changed by the user, via manually editing the APT preferences file (or via widgets on the PSF Photometry panel for some of the parameters). The default preferences file, called “APT.pref”, is located in a hidden directory called “.AperturePhotometryTool” in the user’s home directory.

psfPhotometryCoordX=2234.000000
psfPhotometryCoordY=2746.000000
psfPhotometryCoordinatesType=Pixel coordinates
psfPhotometryMaxBadPixFrac=0.500000
psfPhotometryPsfFitsImageFilename=/Users/laher/ztf_20220810327037_000635_zg_c07_o_q1_diffimgpsf.fits
psfPhotometryPsfType=Read PSF
psfPhotometryRotationAngle=45
psfPhotometrySigmaX=1.000000
psfPhotometrySigmaY=1.000000
psfPhotometrySimcalpsffluxcor=0.898970
psfPhotometrySimcalpsffluxcorApplyFlag=true
psfPhotometryStampSize=25
psfPhotometryUpsampleFactor=5
psfPhotometryZeroPoint=26.200000

These parameters, after any user customizations, are persisted for use in subsequent APT sessions if the user preferences are saved.

The input PSF can be read from a file or computed from a 2-D Gaussian function. If the former, it must be read from a single-extension, FITS-image file. The default PSF image size is 25×25 pixels. The user may modify configuration parameter psfPhotometryStampSize for a different PSF size, which must be a square image with an odd number of pixels on a side. The PSF data units are unimportant because the PSF is renormalized by the tool; only the shape of the PSF matters. A file called psf.fits in the .AperturePhotometryTool hidden directory of the user’s home directory, the contents of which are the original PSF (before upsampling; see explanation below). A file called psfWeightMap.fits is also written containing the upsampled PSF converted to a weight map (which is subsequently convolved with the background-subtracted, upsampled data to obtain the flux).

The coordinates of the source of interest in the data image on the main GUI panel are required inputs. The user may select pixel coordinates or sky equatorial coordinates. The latter can be either decimal or sexagesimal. The user has the option of either manually typing in the coordinates or clicking on the Set Aperture Coordinates button to fill in the coordinates from the aperture position on the main GUI panel. The coordinates will be automatically set on the PSF Photometry panel when it is first opened to the values read from the default preferences file.

The PSF is upsampled by a factor of 5 (by default) for the photometry calculation. The upsampling allows the tool to center the PSF on the desired coordinates more accurately. The user may modify configuration parameter psfPhotometryUpsampleFactor for a different upsampling value. The PSF is upsampled using binlinear interpolation by this tool, which is different from the Gaussian-radial-basis-function interpolation used by the Forced Photometry Service of the Zwicky Transient Factory (ZTF), but the results should be comparable within a percent or so.

There is an option to apply a scale-factor correction to the computed flux. The default scale factor is 0.898970, which is appropriate for ZTF data (as determined from simulations using PSF upsampling based on Gaussian radial-basis functions). The user may modify the scale factor on the tool’s panel (stored in user preferences as configuration parameter psfPhotometrySimcalpsffluxcor), in order to suit individual needs.

There is also an option to input a zero point for the magnitude calculation. The default value of zero gives the instrumental magnitude.

Image Comparator

This software comes with a pop-up tool called the “Image Comparator”, which has up to four magnifier panels that allow simultaneous comparison of a “primary image” with up to three different “comparator images”. Each comparator image can be offset in X and Y using the available spinner adjustments. Separate control over the stretch of each comparator image is currently not implemented, although this is planned for a future release. In the meantime, for comparing images with requiring drastically different stretches, judicious use of the primary-image log-stretch capability can compensate somewhat for this tool’s deficiency. This tool can be accessed via the “Image Comparator” option under the View option on the menu bar.

Batch Mode

APT can be executed in a non-interactive or batch mode. In this mode, the GUI will not be displayed. The following command-line options are available:

APT.csh -i input_FITS-image_filename
        -p user_preferences_filename (default is ~/.AperturePhotometryTool/APT.pref)
        -s input_source_list_filename or "sourceListByAPT" for automatic source-list
           creation
        -o output_aperture-photometry-table_filename (default is
           ~/.AperturePhotometryTool/APT.tbl)
	-b output local_non-annulus_sky_background filename (default is
           ~/.AperturePhotometryTool/skyBackgroundModelF.fits)
        -z zero_point (default value is -999999.99)
        -h (help switch for available command-line options)

To activate batch mode on the command line, the -i and -s options must be invoked together to specify the input FITS image and the source-list file, respectively. Control of the software in the batch mode is done primarily via the saved user preferences in any file specified by the -p option or the default location and filename for automatic loading (which is APT.pref in the .AperturePhotometryTool hidden directory in the user’s home directory). Batch-mode users can also optionally invoke the -o option for the output aperture-photometry-results filename and/or the -z option for the photometric zero point (defaut value is -999999.99). The local non-annulus sky background is always computed, but applied only when Model F (user-preferences noSkyFlag=5) is specified.

In a terminal window, here is an example of how to do it on a Mac or Unix machine:

APT.csh -i myImage1.fits -s mySourceList1.txt
APT.csh -i myImage2.fits -s mySourceList2.txt
APT.csh -i myImage3.fits -s mySourceList3.txt
...

For Windows machines, replace “APT.csh” with “APT.bat” above in a command-prompt window.

Mac users, in addition to the *.dmg file, may want to also install the APT *.tar.gz or *.zip file, which will create a folder where APT.csh is more easily accessible (than in the /Applications folder).

APT’s source-list tool should first be executed in the normal (non-batch) mode in order to set up the source-list option: pixel coordinates or (R.A., Dec.) in decimal degrees. You will also need to consider changing input parameters and options on the “More Settings” panel and elsewhere (e.g., aperture radius). Preferences should be saved after making the desired selections. Saving preferences in the default APT.pref file preserves the settings for subsequent the batch-mode calculations. Preferences, such as specifying the maximum number of allowed threads for the multi-threaded calculations, can make a huge difference with respect to computing time. Test runs in non-batch mode will give you an idea of how long the processing will take (for extremely long source lists and large images, you may want to process them overnight).

Software Limitations

The default maximum image size is 5000×5000 pixels, which has been tested on a computer equipped with 2 GB of RAM. The maximum-image-size setting under the Preferences menu can be increased to accommodate larger images (assuming the user’s machine has sufficient memory) and, in conjunction with this increase, the user may have to start up APT with a larger heap-space setting (currently java -mx1024M APT is executed in APT.csh, the APT C-shell start-up script for UNIX-based platforms). For Mac users running APT as a double-click application, you can similarly edit the -Xmx1024M specification in “/Applications/Aperture\ Photometry\ Tool.app/Contents/Info.plist”.

These items will be addressed in later software versions (your votes count):

No “north is up” button.
No navigation box on thumbnail image.
No capability of handling accompanying data masks and coverage images.
Calculation of source-intensity uncertainty does not include pixel-to-pixel noise correlations.
Limited accuracy for crowded fields and extended objects, although the highest accuracy possible for aperture photometry can be obtained by using APT’s aperture-correction tool in conjunction with the option to estimate the sky background using the non-sky-annulus-based mode statistic (Model F).

Finally, some of the Spitzer SPOT/Leopard Java classes for conversion from pixel to celestial coordinates have been incorporated into APT. The following projections are supported for conversion of equatorial coordinates to pixel coordinates and vice versa (APT does not do galactic coordinates, at least not yet anyway):

Gnomonic or tangent
Orthographic
Cartesian
Aitoff (for FITS-viewing only)

APT handles geometric image distortion only for the gnomonic projection at this time. Two distortion conventions are supported. The SIP convention is applied for images with CTYPE1 = ‘RA—TAN-SIP’ and CTYPE2 = ‘DEC–TAN-SIP’. In the absence of SIP keywords, APT will attempt to read in and apply any PV distortion keywords in the FITS header for images with either CTYPE1 = ‘RA—TAN’ and CTYPE2 = ‘DEC–TAN’ or with CTYPE1 = ‘RA—TPV’ and CTYPE2 = ‘DEC–TPV’. PVi_j distortion keywords are generated by SCAMP and also consumed by SExtractor and SWarp. APT computes SIP distortion up to ninth polynomial order and PVi_j distortion up to seventh polynomial order.

Acknowledgments

Version 2.6.1 utilizes the nom.tam.fits package to read in image data from .fz files directly. I am grateful to Tom McGlynn at NASA/GSFC for his generous help with the integration of this new functionality into APT.

JFreeChart software is harnessed for graph generation and display (www.jfree.org). Also, use in this software is made of the JRegEx package (jregex.sourceforge.net) and the Jama package (math.nist.gov/javanumerics/jama).

Thanks to the beta-testers. In particular, Drs. John Fowler, Seppo Laine, Robert Lupton, Frank Masci, Alberto Crespo-Noriega, Bill Reach, Luisa Rebull, Nancy Silbermann, and Jeonghee Rho made numerous helpful suggestions.

Thanks to Drs. Tom Jarrett and Frank Masci for providing the formula for source-intensity uncertainty.

Thanks to Xiuqin Wu, Trey Roby, Loi Ly, and Booth Hartley for generous expert Java-programming help and the use of their Spitzer SPOT/Leopard Java classes.

A special thanks to Dr. Varoujan Gorgian for suggesting the need for this tool (and thus giving me something to do in my copious spare time!).

Webpage last updated: September 24, 2024 at 7:45 a.m.