AstroImageJ version 5 installation and overview of new feature operation

[karenacollins]

AIJ version 5 has now been released. It is a a major new release, and requires a fresh install of AIJ. For Mac users that have had to deal with complex installation workarounds, AIJ v5 now installs on a Mac with no special workarounds. The new Windows, Mac, and Linux AIJ v5 installation packages are available on the AIJ website. After installation, start AIJ v5 and go to AIJ_Toolbar > Edit > Options > "Memory and Threads" and update the "Maximum memory" value from the default of 640 or 3000 MB to your preferred AIJ memory upper limit. It is recommended to set the value to ~75% of your computer's physical memory. For example, if you have 8 GB of memory, set the maximum memory value to 6000 MB. If you have a large amount of memory, you can set the limit higher, leaving something like 4 GB of memory for OS and other program use. For example, if you have a 64 GB system, you can probably set the limit to 60,000 MB. Note that all of the memory is not used, unless it is needed by AIJ, so a high setting does not otherwise affect system operation.

You may either delete your current AstroImageJ folder (or app in the case of Mac), or keep both versions installed by renaming the folder or app to something like AstroImageJv3, and then installing AIJ v5 as AstroImageJ. Both versions will use the same preference settings, and previous preferences will be maintained in v5.

Windows and Linux users, you must install AstroImageJ into a directory where you have write access. For Windows, it's fine to install AstroImageJ into your documents folder.

A brief introduction to the major new features is provided here:

-- All previous features and AIJ workflow continue to be supported, so you can adopt the new features at your own pace

-- AIJ now directly opens TESScut files, TESS postage stamp sequences, TICA FFIs, and SPOC FFIs from MAST (drag and drop on AIJ toolbar)

-- AIJ now directly opens zipped fits.fz files as downloaded from the LCOGT archive (no unzipping or FUNPack decompression required, just drag and drop the single zip file on the AIJ toolbar)

-- AIJ now offers automatic aperture size extraction

-- AIJ now offers automatic comp star selection

-- AIJ now offers bulk removal of outlier data points

-- AIJ now offers automatic comp ensemble optimization through model residual RMS minimization

-- AIJ now offers automatic detrend parameter selection according to BIC

-- AIJ now offers automatic operation of the "Add Data" function at the end of the Multi-Aperture run to add new data columns such as BJD_TDB, airmass, etc

-- Save plots in Publication Quality (vectorized) PDF file format

-- Plus, many other detailed enhancements and improvements are included

The new Multi-Aperture set-up panel looks like the first image below. The Auto Radius option will extract a radial profile of the T1 target star and adopt the AIJ suggested aperture radii. You can see the radii that have been selected by looking at the seeing plot that will pop up. Note that the automatic radius is extracted only from the first image, so if the seeing or focus vary dramatically throughout the image sequence, you may need to disable the Auto settings and set the manual radii as needed. Note that the manual radii shown in the Multi-Aperture setup panel are used to perform the Radial Profile, so they still need to be set to reasonable values for your images.

The Auto Comparison Star option, will search the image for stars with similar brightness to the target star, and optionally closer to the target star. The main thing you will need to set up are the Max Comp Brightness % and Min Comp Brightness % that you want to allow, relative to the target star brightness. The useful range will depend on the quality of your detector, so some trial and error may be needed to find values that work well for your setup. Settings of Min = 50% and Max = 150% should be a good starting point for most set-ups, unless of course the target star is nearly saturated. High quality detectors such as the LCOGT SINISTRO cameras seem to tolerate a larger range, even as wide as 10% to 500%, if needed, and if the 500% is not too close to saturation. The Weight of brightness vs. distance (relative to the target star) lets you specify how much you want to emphasize proximity to the target star vs. closeness in brightness to the target star. It seems that 50% works pretty good for most purposes. I think you will find that using a Max Comps setting of 12 to 13 works well, since the comp star ensemble optimizer works through that number of comp stars in just a few seconds to a few 10s of seconds, depending on the number of cores in your computer (parallel processing is implemented to make use multiple processor cores). If a max number of comp stars are not found within the specified brightness range, fewer than the max comp stars will be placed. After the auto comps are placed, you can delete any that you don't want with a left click inside the aperture, or you can add to the comp stars manually.

The Smoothing Filter Radius is the radius used to Gaussian smooth the image before searching for peaks. If too many peaks are being found, then the filter radius should be increased. Generally, the default 3.5 pixels works fine for most image sequences I have tried. To be clear, the smoothing and peak finding happens on an image copy that is not displayed, and most importantly doesn't affect the version of the image that is used for photometry.

The Base Aperture, is the aperture number that is used when comparing brightness for comp star selection. Normally this would be set to "1" for T1, but if you are using more than one Target aperture, as in the case of an NEB check, then you may want to change the setting so that comps are selected based on the brightness in a different selected aperture.

If Auto Thresholds (corresponding to peak values of maxima found) does not produce the expected comp stars, you may need to manually set the Max Peak and Min Peak values. Max should be set below saturation, but above the peak pixel value of the brightest star you might want considered as a comp star. For a typical 16 bit CCD, a max setting of 50,000 to 60,000 probably works well, unless your calibrated data are modified significantly by calibration (i.e. as is done by LCOGT, which multiplies the raw pixel values by the CCD gain). The Min value should be above the sky background, but below the faintest star peak pixel value you might want to consider as a comp star. Unless the images have very high sky background, a Min settings of 1000 - 3000 or so will probably work for bright star photometry.



The New Data Auto Run function can be enabled by opening the New Data panel from the Multi-Aperture Main panel, set it up as desired, and then enable the "Auto" checkbox at the bottom of the panel. The specified values will then be updated at the end of every Multi-Aperture run. The New Data panel needs to remain open and the Auto option must be selected for the Auto operation to work.

The other three major features are in the Data Fitting panels (as shown in the first image below). To use these, you'll need to set up an approximate transit model fit and include any fixed model parameters that you want from prior knowledge, such as from SPOC or QLP reports for TESS transits. Note that the fit can now be locked to an impact factor b, instead of inclination, if you prefer.

1a) Click Clean to remove any data points more than X-sigma from the transit model, where X can be set by the user in the box below the Clean button. A value of 4-5σ seems to work reasonably well for many cases. If the clean operation removed unexpected data points, the original data values can be restored by clicking the undo icon to the left of clean. The top box to the right of "Clean" shows the total number of data points that have been removed since the first clean. The bottom box shows the number of data points that have been removed (-), or restored with an undo (+) during the last clean or undo operation (successive clean and undo operations are allowed).

1b) Hold Shift and click Clean to remove any data points more than X times the RMS of the transit model residuals, where X can be set by the user in the box below the Clean button. A value of 3-4 times RMS seems to work reasonably well for many cases. The operation may need to be repeated a few times to iteratively remove more data points, since the RMS value will decrease each time an outlier is removed. RMS is the value reported in the corresponding fit panel's RMS box, and is the RMS value of the transit model data residuals (i.e. is calculated based on the difference between the fitted and detrended data points and the current transit model curve).

2) In the Comp Star Optimization sub-panel, click "Start" to find the comp star ensemble with the minimum RMS relative to the transit model. The comp stars that are considered are the apertures that are set as "C" apertures in the Reference Star Settings panel. Note the new "Save" option in the Ref Star panel. This option allows you to save a set of "C" stars that you may want to start the optimization over with several times. If you need to run optimization again, just select "Recall" to restore the desired master set of comp stars before starting optimize again. This allows multiple T stars to be set, and to disable specific "C" apertures, if they are known to be "bad", before starting optimization.

3) In the Detrend Parameter Optimization section, click start to automatically select the best detrending parameter(s) according to BIC. I recommend using a Max Detrend Pars setting of 1 detrend parameter for a partial or full transit light curve (or maybe two parameters if you have a full transit with good amount of out-of-transit baseline). I recommend leaving Min BIC Threshold set to the default value of 2 (which means a delta-BIC improvement of more than 2 is required per accepted detrend parameter). If fewer than the max detrend parameters are justified according to delta-BIC, fewer (or no) detrend parameters will be suggested. If you want to ensure very strong correlation before the optimizer accepts a detrend parameter, try setting the Min BIC Threshold to something like 10. The detrend parameters that will be considered are the ones that are displayed in the detrending section above the optimize subpanel (whether the parameter checkbox is selected or not). I recommend optimizing against the 7 detrend parameters shown in the second image below, but you can identify more or less potential detrending parameters according to your needs by changing the "Detrend Vars" setting near the top-middle of the Multi-Plot Main panel, and then selecting a parameter in the new detrend boxes that now show in the Fit Settings panel. If you no longer want to have a detrend parameter considered as part of an optimization, set the parameter selection to blank and/or reduce the number of max detrend parameters set on the Multi-plot Main panel.

You may want to iterate between cleaning, comp star optimization, and detrend parameter optimization a couple of times to find the best combination. Be sure to "Recall" the full comp star set that you want to optimize against on each comp star optimization iteration. All detrend parameters that are shown will be used for repeated optimizations, even if the check box is not enabled.