Overview

The programmable titling capability allows the user to programmatically retrieve plot titling information from:
  1. stack window titles (i.e. the stack title at the very top of the image stack display).
  2. fits header values and comments,
  3. measurements table values, text, or column statistics, and
  4. AIJ preferences.

In addition to retrieving the titling information, substrings can be extracted from text strings based on any defined separator character (or string), or more complex extraction of substrings can be achieved using regular expressions (regex). Also, numeric values can be formatted.

To use the programmable titling capability, select the "Programmable" option in either or both of the Multi-Plot Main Title and Subtitle subpanels. Start typing fixed text that should be included as would be done in the "Custom" title mode. Insert the syntax described below to automatically extract the variable information that is desired from the various available information sources.

A simple example is as follows: With a stack display title name "TIC144193715-01_20230825_LCO-SSO-1m0_zs_33s", and the following syntax in the plot title box in programmable mode: @split _ $1 @ title from Telescope @split _ $3 @ title the following plot title is created: TIC144193715-01 from Telescope LCO-SSO-1m0.

If a function (including formatting, splitting, and regex expressions) is to be followed by text or another function, the function must be followed by a space. If a space is desired after a function, two consecutive spaces must be added in the source window. Each required delimiting space will be highlighted in green in the source window.

Any function parameter that contains whitespace or multiple single or double quotes must be wrapped in quotes.

The @ symbol starts all functions, and must precede each function name. If the @ character is required in the fixed text of a plot title, it must be escaped (preceded) with a backslash (eg. \@).

The text in the source window can be wrapped for clarity by adding a backslash to the end of a line and then pressing the <Enter> key. A backslash may otherwise be used in the title text, but if the text must end with the backslash character, the backslash must be escaped using a double backslash (e.g. \\).

Extracting Strings and Numeric Values

String and numeric values can be extracted from different sources using the following functions:

Name Function name Description Parameters Example
Preferences pref, prf, p Read values for AIJ preferences by name.
Key Description
key The preferences entry.
Some special values are provided for ease of use.
Macro Output
MA: @ pref APMODE, Radius: @p APRADIUS px MA: FIXED, Radius: 15px
@pref LASTMA FApRadPAll(0.01): 12.0-0.0-31.0
Header header, hdr, h Read values from the FITS header. Requires the stack to be open.
Key Description
key The header key to read.
slice The slice to pull the header from.
Available Data Macro Output
CCDTEMP = 23.5 Hello @header CCDTEMP C Hello 23.5C
Comment comment, cmt, c Read comments from the FITS header. Requires the stack to be open.
Key Description
key The header key to read.
slice The slice to pull the header from.
Available Data Macro Output
CCDTEMP = 23.5 // C Hello @h CCDTEMP @ comment CCDTEMP Hello 23.5C
Datetime now datetimenow, dtn Get today's date, time, or datetime
Key Description
zoneId The timezone to use. Use _ for the user's timezone.
type
Key Description
date, d The date
time, t The time
datetime, dt, _ The datetime
Available Data Macro Output
Today: 2023/09/21 @dtn UTC-5 date 2023-09-21
Stack title title, ttl Get the stack title. Stack must be open. N/A
Available Data Macro Output
Stack title = observation2 @ttl observation2
Table table, tbl, t Get values and statistics from the table.
Key Description
column The column to use
row The row to use.
Some special values are provided for ease of use and extracting of statistics.
Available Data Macro Output
Table: (Label, 1) = test.fits @tbl Label 1 test.fits

Processing Extracted Data

Extracting Strings and Substrings

The extracted strings can be further broken down by prefixing the above syntax with any of the following:

Name Function name Description Parameters Example
Split split, spt, s Split a string using a deliminator.
Key Description
splitter The deliminator
out The output text, containing group references such as $1.
$0 refers to the entire input text.
in The input text, may be another function.
Macro Output
@split _ "$2 of $1" test_fits fits of test
@s _ $1 @ s - $2 lco-star_5-6 star
Regular Expression regex, rgx, r Process a string using regex.
Key Description
exp The regualr expression to use
out The output text, containing group references such as $1.
$0 refers to the entire input text.
Named groups are supported.
in The input text, may be another function.
Available Data Macro Output
Header: CCDTEMP = 23.5; Column Label, first value processed_altair_21.fits Regex with @rgx _(\w+)_ $1 @t Label 1 and @ rgx ([0-9]+) $1C @ h CCDTEMP Regex with altair and 23C
Header: DATE-OBS = 1996-10-14T10:14:36.123 @regex (.+)T $1 @hdr DATE-OBS 1996-10-14

Formatting Numeric Values

Extracted numeric values can be formatted by prefixing any of the above, including a split or regex of any source, by prefixing them with:

Name Function name Description Parameters Example
Number Format format, fmt, f Format numeric values
Key Description
exp The formatting expression, generally use # to designate digits that should be output if non-zero, and 0 to designate digits that should always by output. See here for more information
in The input text to format, must be a number
Available Data Macro Output
Header: CCDTEMP = 23.5 @fmt ##0.0 @ h CCDTEMP 23.5
Header: CCDTEMP = 23.0 @fmt ##0.# @ h CCDTEMP 23
Date-Time Format datetimeformat, dtf Format dates and times.
Key Description
inFormat The format of the input datetime. May use _ to use yyyy-MM-dd'T'HH:mm:ss[.S].
Some special values are supported:
Key Description
date, d A date
time, t A time
mjd, jd A (Modified) Julian Date
datetime, dt A datetime

See here for more information.
inLocale The locale of the input datetime. May use _ to use user's locale. See all locales here.
outFormat The format of the output datetime. May use _ to use yyyy-MM-dd HH:mm:ss.
Some special values are supported:
Key Example Output
date, d 2023-09-19
weekdaydate, wd Mon, Sep. 21 2023
time, t 13:15:06
@ datetimeformat yyyy-MM-dd en-US "E, MMM dd yyyy" en-US @ today UTC Mon, Sep. 21 2023

See here for more information.
outLocale The locale of the output datetime. May use _ to use user's locale. See all locales here.
datetime The datetime to format
Macro Output
@ datetimeformat yyyy-MM-dd en-US "E, MMM dd yyyy" en-US @ today UTC Mon, Sep. 21 2023

Special Preferences Keys

Key Description
LASTMA A short summary of the last MA run
APVARFLUXCUT The flux cutoff for auto. var. ap.
APVARFWHM The flux FWHM for auto. var. ap.
APMODE How aperture radii were selected for MA
APSKYOUTER The outer sky annulus for apertures
APSKYINNER The inner sky annulus for apertures
APRADIUS The radius for apertures
APLOADING How apertures were loaded in MA

Special Table Row Keys

Key Description
F The first row (same as entering 1)
L The last row
AVG The average of the column
MED The median of the column
MIN The minimum of the column
MAX The maximum of the column