AstroVista Lite

Reference

Command reference

Every command the terminal knows, with how it is written, what it does, its keywords and an example; the examples run as written, in order, on the example image. The terminal explains how a line is written. In the syntax, [ ] marks what is optional and | a choice; N and M are buffer numbers. Commands marked MONSTA name share their name with a command of MONSTA, John Tonry's image analysis and plotting system; their options are AstroVista Lite's own, as given here.

Groups
  1. Images and buffers
  2. Arithmetic
  3. Statistics
  4. Changing the geometry
  5. Smoothing and cleaning
  6. Making images
  7. The FITS header
  8. Variables
  9. Isophotes and sources
  10. Masks
  11. Files, folders and the session

Images and buffers

An image lives in a numbered buffer: 1, 2, 3, … The list on the left of the window shows them, each with the command that made it.

rd MONSTA name

rd N file[ext]

Read a FITS image into buffer N. The file may be gzip-compressed and may have any name: FITS is recognised by its contents. Without [ext], the first image in the file is read.

[n]the HDU with that number, 0 being the primary: rd 1 frame.fits[1]
[NAME]the image extension called NAME (its EXTNAME): [sci]
[NAME,v]NAME with version v (EXTVER): [sci,2]
rd 1 galaxy.fits
rd 2 frame.fits[sci]
rd 3 frame.fits[sci,2]

fitsinfo

fitsinfo file

List what a FITS file holds: each HDU by number and name, with the size of its image or the rows and columns of its table.

fitsinfo frame.fits

wd MONSTA name

wd N file

Write buffer N as a FITS file (32-bit floating point), with its header. The commands that made the buffer are kept as HISTORY cards.

wd 1 copy_of_galaxy.fits

tv MONSTA name

tv N

Show buffer N in the image window.

tv 1

copy

copy N M

Copy buffer N, pixels and header, into buffer M.

copy 1 5

close MONSTA name

close N

Remove buffer N.

close 5

buffers buf

buffers (or buf)

List the buffers: number, name, size, and the line that made each.

buffers

tag

tag N "name"

Give buffer N a name of your own, shown in the buffer list. Any command or formula that makes a buffer also takes tag="name" at the end of its line.

tag 1 "UGC 12517, F110W"
[6] = [1] * 2 tag="twice"

Arithmetic

Formulas over whole images, worked out pixel by pixel. Help ▸ Documentation ▸ Image arithmetic explains them in detail.

[M] = BM =

[M] = expression (or BM = expression)

Put the result of a formula into buffer M: [3] = [1] - [2] subtracts buffer 2 from buffer 1, pixel by pixel. A formula holds buffers ([n] or Bn), numbers, variables, mask layers by name (1 where good, NaN where masked), + - * / % and ^ or ** for powers, comparisons (1 or 0), and functions. Dividing by 0 gives NaN, never infinity.

mean median sum min max stdof several values: pixel by pixel; of one buffer: one number over the whole image
div(a, b, fill)a / b, with fill where b is 0
where(c, a, b)a where c is true (not 0), b elsewhere
clip(a, lo, hi)the values limited to lo … hi
good(m), masked(m)1 where the mask layer m is good / masks
abs sqrt exp log log10 …functions of each pixel (help calc lists them all)
[2] = [1] - median([1])
[3] = median([1], [2], [6])
[4] = div([1], [2], 0)
[7] = where([1] > 1000, [1], nan)

calc

calc M EXPR='expression'

The same as [M] = expression, written as a command with a keyword.

calc 8 EXPR='[1] * 2.5'

ac sc mc dc MONSTA name

ac N value (sc, mc, dc)

Add (ac), subtract (sc), multiply by (mc) or divide by (dc) a number, in place. The value may be a variable or an expression of variables.

ac 8 100
sc 8 100
mc 8 2
dc 8 2

ai si mi di MONSTA name

ai N M (si, mi, di)

Add (ai), subtract (si), multiply (mi) or divide (di) buffer N by buffer M, pixel by pixel, in place in N. The buffers must have the same size; dividing by 0 gives NaN.

ai 8 1
si 8 1

log ln sqrt inverse round MONSTA name

log N (ln, sqrt, inverse, round)

Replace each pixel of buffer N by its base-10 logarithm (log), natural logarithm (ln), square root (sqrt), 1/x (inverse) or nearest whole number (round). Where the function has no value (log of 0 or less, square root of a negative number, 1/0) the pixel becomes NaN.

copy 1 9
log 9
round 9

Statistics

Numbers about a buffer. Columns and rows are counted from 0. mn, max and min also keep their results as variables, for the commands that follow.

stats

stats N [MASK=a,b]

The mean, median, standard deviation, minimum, maximum and number of pixels of buffer N, leaving out NaN pixels and those of the mask layers named.

MASK=mask layers to leave out, separated by commas
stats 1
stats 1 MASK=mymask

sky MONSTA name

sky N [MASK=a,b]

The sky level of buffer N: the median of the pixels the masks leave, clipped at 3 standard deviations until it settles. Also gives the clipped mean and the standard deviation.

MASK=mask layers to leave out
sky 1 MASK=mymask

mn MONSTA name

mn N

The mean, median, standard deviation (sigma) and number of the finite pixels of buffer N. Sets the variables mean, median and sigma.

mn 1

max min MONSTA name

max N (min N)

The largest (smallest) pixel and its column and row. Sets the variables max, maxc, maxr (min, minc, minr).

max 1
min 1

abx MONSTA name

abx N

The sum, mean and number of the finite pixels, and the maximum and minimum with their columns and rows.

abx 1

print MONSTA name

print N C R [SIZE=5]

The pixel values in a SIZE × SIZE square around column C, row R, as a table with the rows from top to bottom.

SIZE=the side of the square, in pixels (default 5)
print 1 567 562 SIZE=3

Changing the geometry

Results go into the buffer itself unless OUT=M asks for another one.

shift MONSTA name

shift N DX= DY= [ORDER=3] [OUT=M]

Move the image by DX columns and DY rows, fractions of a pixel too. Pixels that come in from outside are NaN.

DX=, DY=the shift in pixels (default 0)
ORDER=the order of the spline interpolation, 0 to 5 (default 3)
OUT=the buffer for the result
shift 9 DX=1.5 DY=-0.25

rotate MONSTA name

rotate N ANGLE= [ORDER=3] [OUT=M]

Rotate the image about its centre by ANGLE degrees, counter-clockwise. Multiples of 90° are exact (no interpolation); other angles keep the image's size, with NaN in the corners.

ANGLE=degrees, counter-clockwise (rotate N 90 works too)
ORDER=the spline order (default 3)
OUT=the buffer for the result
rotate 9 ANGLE=90
rotate 9 ANGLE=12.5 OUT=10

flip

flip N X|Y [OUT=M]

Mirror the image left to right (X) or top to bottom (Y).

flip 9 X

bin

bin N k [MEAN] [OUT=M]

Add up the pixels in blocks of k × k, making an image k times smaller; with MEAN, average them instead. NaN pixels are left out.

MEANaverage the blocks instead of adding them
bin 9 2 MEAN OUT=10

mash MONSTA name

mash N ROWS|COLS [OUT=M]

Add up all the rows into one row (ROWS), or all the columns into one column (COLS). The result goes into a free buffer unless OUT= names one.

mash 1 ROWS OUT=10

Smoothing and cleaning

Results go into the buffer itself unless OUT=M asks for another one.

smooth MONSTA name

smooth N FWHM= or smooth N BOXCAR=k [OUT=M]

Smooth with a Gaussian of the full width at half maximum given, or with a k × k boxcar. NaN pixels neither spread nor count.

FWHM=pixels (default 2)
BOXCAR=the side of the box, in pixels
smooth 9 FWHM=3 OUT=10
smooth 9 BOXCAR=5 OUT=10

filt MONSTA name

filt N MEDIAN=k [OUT=M]

Replace each pixel by the median of the k × k pixels around it.

MEDIAN=the side of the box (default 5)
bin 1 4 MEAN OUT=10
filt 10 MEDIAN=3

zap MONSTA name

zap N [SIG=5] [SIZE=5] [OUT=M]

Replace the pixels more than SIG standard deviations above the median of the SIZE × SIZE around them by that median: cosmic rays and hot pixels. The standard deviation is measured locally, from the median absolute deviation.

SIG=how many standard deviations above the local median (default 5)
SIZE=the side of the box (default 5)
zap 1 SIG=5 OUT=10

clip MONSTA name

clip N [MIN=] [MAX=] [VALUE=] [OUT=M]

Pixels below MIN become MIN and pixels above MAX become MAX, or VALUE when it is given (VALUE=nan makes them NaN).

MIN=, MAX=the limits
VALUE=what clipped pixels become instead of the limit
clip 10 MIN=0 MAX=60000
clip 10 MAX=60000 VALUE=nan

skysub MONSTA name

skysub N [VALUE=]

Subtract the sky from buffer N: the value given, or the median of the image clipped at 3 standard deviations.

VALUE=the sky to subtract
skysub 10
skysub 10 VALUE=3246

Making images

For practice and tests: add a star or noise to an image, or look at its power spectrum.

gauss MONSTA name

gauss N X= Y= FWHM= PEAK=

Add a Gaussian star at X, Y (ELLIPROF's coordinates: the first pixel spans 0 to 1) with the full width at half maximum and the peak given.

gauss 10 X=200 Y=200 FWHM=2.5 PEAK=5000

noise MONSTA name

noise N SIGMA= [SEED=]

Add Gaussian noise of standard deviation SIGMA. SEED= makes it the same every time.

noise 10 SIGMA=10 SEED=1

fft MONSTA name

fft N OUT=M

The power spectrum of buffer N, with the zero frequency at the centre, into buffer M. The mean is subtracted first and NaN pixels count as 0.

fft 1 OUT=11

The FITS header

ch MONSTA name

ch N KEY=value ...

Set FITS header keywords of buffer N. Numbers are kept as numbers; quote text with spaces.

ch 1 OBJECT='UGC 12517' GAIN=2.4

chead

chead N [WORD]

Print the header of buffer N, or only the cards containing WORD.

chead 1 NAXIS

Variables

Numbers kept by name. Variable names are not case-sensitive (set keeps them in lower case). A variable, or an expression of variables, can be used as any keyword's value (X0=xc, R1=2*re), as a number in a command (ac 1 sky, print 1 maxc maxr) and in formulas ([2] = [1] - sky).

set MONSTA name

set NAME=expression ...

Set variables. An expression may use numbers, other variables, + - * / ** and sqrt log10 log exp abs sin cos tan, and pi.

set xc=567 yc=562 re=126.5
set r1=2.75*re

typ MONSTA name

typ [NAME ...]

Print variables: those named, or all of them.

typ
typ xc yc

Isophotes and sources

The two measurements of AstroVista Lite. The tools on the right of the window type these commands for you.

elliprof MONSTA name

elliprof N X0= Y0= R0= R1= NR= [NITER=10] [SKY=] [RMSTAR] [MASK=a,b] [MASKBUF=M,...] [MASKFILE=file] [TOMODEL=M] [TORESID=M]

Fit elliptical isophotes to buffer N with ELLIPROF, John Tonry's isophote fitting from MONSTA (through the elliprof package): NR ellipses from R0 to R1 around X0, Y0. The profile goes to Results ▸ Profile and the ellipses onto the image.

X0=, Y0=the centre, in ELLIPROF's coordinates (required)
R0=, R1=the first and last semi-major axis, in pixels (required)
NR=the number of ellipses (required)
NITER=iterations of the fit (default 10)
SKY=a constant sky subtracted before the fit
RMSTARreject star-like bright samples along each ellipse
MASK=mask layers whose pixels are left out
MASKBUF=buffers used as masks: masked where 0 or NaN
MASKFILE=a mask file (FITS or .dmask, 0 = masked)
TOMODEL=, TORESID=the buffers for the model and the residual
elliprof 1 X0=567 Y0=562 R0=9 R1=347 NR=23 SKY=3246 RMSTAR MASK=u12517j TOMODEL=3 TORESID=4

sources

sources N [KEYWORD=value ...] [MASK=a,b] [TOSEG=M]

Find the sources (stars and galaxies) in buffer N and measure them, with SEP (the algorithms of SExtractor). Each run is numbered; the catalogue is in Results ▸ Sources. Keywords not given take the values of the Source finder panel's defaults.

THRESH_TYPE=RELATIVE (in standard deviations of the background, default) or ABSOLUTE
DETECT_THRESH=the detection threshold (default 3)
DETECT_MINAREA=connected pixels above it (default 5)
FILTER=, FILTER_FWHM=, FILTER_TYPE=smoothing before detection: Y/N, FWHM in pixels (0: a 3 × 3 kernel), matched or conv
DEBLEND_NTHRESH=, DEBLEND_MINCONT=deblending (32, 0.005)
CLEAN=, CLEAN_PARAM=cleaning of spurious detections (Y, 1)
BACK_TYPE=, BACK_VALUE=, BACK_SIZE=, BACK_FILTERSIZE=, BACK_FILTTHRESH=the background: AUTO (a map in cells of BACK_SIZE = 64 pixels) or MANUAL (the constant BACK_VALUE)
PHOT_APERTURES=, PHOT_AUTOPARAMS=, PHOT_FLUXFRAC=aperture diameters (5), MAG_AUTO's Kron factor and smallest radius (2.5,3.5), FLUX_RADIUS's fraction (0.5)
MAG_ZEROPOINT=, GAIN=the magnitude of one count (0), e-/ADU (0)
MASK=mask layers whose pixels are left out
TOSEG=the buffer for the segmentation image
sources 1
sources 1 DETECT_THRESH=2.5 DETECT_MINAREA=8 TOSEG=12

runs

runs

List the source-finder runs: number, image, how many sources, and the settings that differ from the defaults.

runs

centre

centre N SOURCE=number [RUN=k]

Take ELLIPROF's centre from a found source (by its NUMBER), of the last run on buffer N or of run k.

centre 1 SOURCE=1

Masks

A mask layer marks the pixels to leave out of a measurement. In files, 0 means masked and 1 good. Coordinates are ELLIPROF's: the first pixel spans 0 to 1. The drawing actions take ERASE to unmask instead. help mask lists them all.

mask new MONSTA name

mask new NAME [N]

An empty mask layer the size of buffer N (without N: of the lowest-numbered buffer).

mask new edges 1

mask load MONSTA name

mask load NAME file [N]

Read a mask from a FITS file or a legacy .dmask bitmap (0 = masked). The mask also appears as a buffer (1 good, 0 masked) kept up to date with the layer.

mask load published u12517j.dmask 1

mask save MONSTA name

mask save NAME file

Write a mask layer: a .dmask name writes a legacy bitmap, any other name a FITS image (1 good, 0 masked).

mask save edges edges_mask.fits

mask frombuf tobuf MONSTA name

mask frombuf NAME N · mask tobuf NAME M|new

A mask layer from buffer N (masked where it is 0 or NaN), or a mask layer as buffer M (or a new buffer).

mask frombuf frombuffer 1
mask tobuf edges new

mask copy rename delete MONSTA name

mask copy NAME FROM · mask rename NAME NEW · mask delete NAME

Copy, rename or delete a mask layer.

mask copy spare edges
mask rename spare spare2
mask delete spare2

mask union intersect MONSTA name

mask union|intersect NAME A B ...

A new layer with the pixels masked by any (union) or all (intersect) of the layers A, B, …

mask union both edges published

mask circle ellipse box polygon brush MONSTA name

mask circle NAME X Y R · mask ellipse NAME X Y A B ANGLE · mask box NAME X0 Y0 X1 Y1 · mask polygon NAME X1 Y1 X2 Y2 X3 Y3 ... · mask brush NAME R X1 Y1 X2 Y2 ... [ERASE]

Draw a shape on a layer: a circle of radius R, an ellipse with semi-axes A, B turned by ANGLE degrees, a box between two corners, a polygon through its corners, or circles of radius R along a path. The mask tools of the window type these commands.

ERASEunmask the shape instead of masking it
mask circle edges 812 440 12
mask ellipse edges 300 300 70 22 35
mask box edges 10 10 60 40
mask polygon edges 100 100 150 100 125 140
mask brush edges 3 400 400 420 410 440 400
mask circle edges 812 440 12 ERASE

mask unpatch MONSTA name

mask unpatch NAME X Y

Unmask the whole connected masked area under X, Y.

mask circle edges 812 440 12
mask unpatch edges 812 440

mask nan range MONSTA name

mask nan NAME N · mask range NAME N LO HI

Mask the pixels of buffer N that are not finite (NaN or infinite), or whose values lie from LO to HI.

mask nan edges 1
mask range edges 1 60000 1e9

mask sources segments MONSTA name

mask sources NAME [RUN=k] [SCALE=1.5] [KEEP=centre|none|number] [X0= Y0=] [IDS=1,5,9] [WHERE='condition'] · mask segments NAME [RUN=k] [GROW=0] [KEEP=...] [X0= Y0=]

Mask the found sources: their Kron ellipses enlarged by SCALE (sources), or their own pixels from the segmentation grown by GROW pixels (segments). The galaxy at ELLIPROF's centre is kept unmasked unless KEEP= says otherwise.

RUN=the source-finder run (default: the last on that image)
SCALE=the Kron ellipses × SCALE (default 1.5)
KEEP=centre (the source at X0, Y0, default; before any fit, the largest source), none, or a source NUMBER
X0=, Y0=the centre to keep (default: the last ELLIPROF centre)
IDS=only these source numbers
WHERE=only the sources meeting a condition: catalogue columns compared with numbers, joined by and / or, read from left to right: WHERE='MAG_AUTO < 22 and FWHM_IMAGE < 3'
GROW=pixels added around each segment (segments)
mask new found 1
mask sources found SCALE=1.5
mask sources found WHERE='FLUX_RADIUS < 2.5'
mask segments found GROW=2

mask grow shrink invert clear fill show hide MONSTA name

mask grow|shrink NAME R · mask invert|clear|fill NAME · mask show|hide NAME

Grow or shrink the masked areas by R pixels; swap masked and good; unmask or mask everything; show or hide the layer on the image.

mask grow edges 2
mask shrink edges 1
mask hide edges
mask show edges

masks

masks

List the mask layers: size and number of masked pixels.

masks

undo redo

undo · redo

Undo the last mask edit, or redo the edit undone last (the last 30 are kept). Ctrl+Z and Ctrl+Shift+Z do the same.

undo
redo

Files, folders and the session

cd pwd

cd [folder] · pwd

Change the folder that file names are relative to (cd alone: your home folder), or print it. Programs run from the terminal start there too.

pwd

run

run file

Run the commands in a file, one per line (# starts a comment). File names in it are relative to the file's own folder. The run stops at the first error, naming the file and the line.

run session.txt

help MONSTA name

help [command]

List the commands, or explain one. help mask lists the mask actions and help calc the arithmetic.

help shift
help mask

export

export NAME=value ...

Set environment variables for the programs run from the terminal.

export CATALOGUES=catalogues