Overview
The programmable titling capability allows the user to programmatically retrieve plot titling information from:
- stack window titles (i.e. the stack title at the very top of the image stack display).
- fits header values and comments,
- measurements table values, text, or column statistics, and
- 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. |
|
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. |
|
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 |
|
Performing Mathematical Operations
The extracted strings can be further processed with math.
Binary operators take a function and 2 parameters, such as for addition.
Unary operators take a function and 1 parameter, such as for sin().
Name |
Function name |
Description |
Parameters |
Binary Operator |
math2, m2, m |
Math functions with 2 parameters |
Function(s) |
Operation |
add, + |
a + b |
sub, - |
a - b |
div, / |
a / b |
mul, * |
a * b |
mod, % |
a % b |
exp, ^ |
ab |
log |
logba |
root |
b√a |
atan2 |
atan(b, a) |
min |
min(a, b) |
max |
max(a,b) |
qsum |
√ a2 + b2 |
scalb |
a * 2b |
|
Unary Operator |
math1, m1 |
Math functions using only 1 parameter. |
Function(s) |
Operation |
exp |
ea |
log |
log10(a) |
ln |
ln(a) |
deg |
Convert radians to degrees |
rad |
Convert degrees to radians |
round |
round(a) |
truncate, trunc |
truncate(a) |
fact, ! |
a! |
abs |
|a| |
ceil |
ceil(a) |
floor |
floor(a) |
signum |
1 if a > 0, 0 if a is 0, or -1 if a < 0 |
sin |
sin(a) |
cos |
cos(a) |
tan |
tan(a) |
asin |
asin(a) |
acos |
acos(a) |
atan |
atan(a) |
sinh |
sinh(a) |
cosh |
cosh(a) |
tanh |
tanh(a) |
asinh |
asinh(a) |
acosh |
acosh(a) |
atanh |
atanh(a) |
|
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 |