rtplots plots files from server.

rtplot plots ultracam data files as they come in. This is useful during focus runs, positioning objects etc. It is probably the most useful program for observing with ULTRACAM. rtplot has many arguments (48 in all!) but many will not be prompted for by default and depending upon what options are selected.

Among the options are the possibilities of plotting a file of defects, useful for ensuring that a target does not fall on any of them, and also a file of test windows for setting up the readout format on a target. Fitting options, especially the Moffat profile are useful for focussing. See below for more details of this.

An irritating feature is that if you switch between prompted and unprompted input, you may have to alter the order of the command line arguments unless you explicitly name them. This is a feature I'm afraid.

Program call

rtplot [device source] ((url)/(file) first trim [(ncol nrow) twait tmax])/(flist) [pause] nccd [def] (defect transform) [setup] setwin bias (biasframe) (threshold (photon) naccum) (lowlevel highlevel) ([stack]) xleft xright yleft yright iset (i1 i2)/(p1 p2) (profit) ([method symm (beta) fwhm hwidth readout gain sigrej onedsrch (fwhm1d hwidth1d) (fdevice)])

Arguments

device --- Plot device. e.g. "/xs" or "1/xs"

source --- Data source, either 'l' for local, 's' for server or 'u' for a list of ucm files. 'Local' means the usual .xml and .dat files accessed directly. Do not add either .xml or .dat to the file name; these are assumed.

url/file --- If source='S', this should be the complete URL of the file, e.g. 'http://127.0.0.1:8007/run00000012', or just the file part in which case the program will try to find a default part to add from the environment variable ULTRACAM_DEFAULT_URL. Failing this it will add http://127.0.0.1:8007/, i.e. the local host. If source='L', this should just be a plain file name.

first --- If source='L' or 'S, 'first' sets which exposure to start with (starts at 1). Set = 0 to always try to get the last file, useful if the program does not keep up with the data and for positioning stars.

trim --- If source='L' or 'S', set trim=true to enable trimming of potential junk rows and columns of each window

ncol --- If trim, then this specifies the number of columns nearest the readouts of each window to be snipped off as these can be corrupted.

nrow --- If trim, then this specifies the number of rows to snip off the bottom of each window as these can be corrupted.

twait --- Time to wait between attempts to find a new exposure. (Only for data from a server)

tmax --- Maximum time to wait before giving up, set = 0 to give up immediately. (Only for data from a server).

flist --- If source = 'U', this is the name of a list of ULTRACAM files to reduce. These should be arranged in temporal order to help the reduction move from one exposure to the next successfully.

pause --- Seconds to pause between frames.

nccd --- CCD number to plot, 0 for all

stack --- Stacking direcion when plotting more than on CCD. Either in 'X' or 'Y'

bias --- true/false according to whether you want to subtract a bias frame. You can specify a full-frame bias because it will be cropped to match whatever your format is. This is useful for ultracam because of the different bias levels of the 6 readouts.

biasframe --- If bias, then you need to specify the name of the bias frame.

threshold --- If you are applying a bias to ULTRASPEC L3CCD data, you have the option of converting to photon counts (0 or 1 whether above or below a certain threshold).

photon --- The threshold level if threshold = true

naccum --- Accumulate data into the sum of naccum frames before plotting.

def --- true/false according to whether you want to plot a list of CCD defects (see setdefect). This is supposed to be useful when trying to acquire targets.

defect --- The name of the defect file if def=true. Bad ones are plotted as stars; moderate ones as circles. Moderate line defects are dashed cf solid lines for disastrous ones.

transform --- The name of a transformation file generated by the script transform. This allows the defects of one CCD to be over-plotted on another, accounting for their relative orientations. For each CCD this file has a line listing the scale factor, rotation (anti-clockwise degrees) and translation in x and y to get from a reference CCD to the CCD in question. Lines starting with '#' or a blank are skipped.

setup --- True if you want to try setting up windows in which a file of test windows (next argument) is continually re-read for each image plotted.

setwin --- The file of test windows that will be read each image, allowing you to keep changing it while new images come in (e.g. with 'emacs', remembering to save it). This should start with the binning factors as a line 'XBIN YBIN' and then a series of lines of the form 'XSTART YSTART NX NY', which define each window in the following manner: XSTART is the X value of left-most column in the window (in terms of unbinned pixels), YSTART is the Y value of the bottom row, and NX and NY are the X and Y dimensions. All of these are in unbinned pixels. This file will be read once per image and the windows overplotted as dashed boxes. They will be in yellow if judged valid, red if not, and the reason for their not being valid will be printed to the terminal. Lines starting with '#' or a blank or a tab are treated as comments. setwin may either be a disk file name or an http URL on which a server is waiting which will dispatch the values. The Java clients udriver and usdriver can act as servers for rtplot. If these are running on the same machine as rtplot, then 'http://localhost' should work.

lowlevel --- A warning will be printed if the median level of the left-hand window of the CCD 1 falls BELOW this value. Sometimes this happens after a power on and adds noise to all the CCDs. 2000 seems to be about the right value. Set = 0 to ignore. (ULTRACAM only)

highlevel --- A warning will be printed if the median value of the right-hand window of CCD 1 is ABOVE this value. 3500 seems about the right value, but remember sky counts will trigger it. Set = 0. to ignore. (ULTRACAM only)

flatlevel --- To reduce false high bias warnings, this is a level above which no warning will be printed. It is a level WITHOUT bias-subtraction so 6000 is reasonable.

stack --- Stacking direcion when plotting more than on CCD. Either in 'X' or 'Y'

xleft xright --- X range to plot

yleft yright --- Y range to plot

iset --- 'A', 'D' or 'P' according to whether you want to set the intensity limits automatically (= min to max), directly or with percentiles.

ilow ihigh --- If iset='d', ilow and ihigh specify the intensity range to plot

plow phigh --- If iset='p', plow and phigh are percentiles to set the intensity range, e.g. 10, 99

profit --- If a single CCD is plotted, this option allows profile fitting. If you type 'y', you will be asked to select objects with a cursor for fitting on each frame. If you select two stars then the angle of the line joining them with respect to the chip rows will be reported, which is useful during drift mode setups.

method --- There are two options for profile fitting: 2D Gaussian or a Moffat profile. The latter is a much better representation of seeing broadened profiles. The Gaussian can be symmetric or elliptical. The Moffat profile is of the form h/(1+(r/R)**2)**beta where r is the distance from the centre of the profile, R is a scale length and beta is a parameter that you will be prompted for an intial value. As beta gets large, the Moffat profile tends to Gaussian. The intial value of R is computed from a FWHM value. The routine plots a line at 2 times the measured FWHM on the image (not yet for the asymmetric gaussian).

symm --- Yes/no for symmetric versus elliptical gaussians in the case of gaussian fits. I have not fully tested this option.

fwhm --- fwhm is the initial FWHM to use for the profile fits.

hwidth --- The half-width of the region to be used when fitting a target. Should be larger than the fwhm, but not so large as to include multiple targets if possible. This is also the region used to compute the maximum value that the program will report.

readout --- Readout noise, RMS ADU in order for the program to come back with an uncertainty. NB It is important in this case to carry out bias subtraction if you want half-way decent error estimates.

gain --- Gain, electrons/ADU, again for uncertainty estimates

sigrej --- The fits can include rejection of poor pixels. This is the threshold, measured in sigma. Should not be too small as this may cause rejection of many points which can slow the routine down a fair bit as well as leading to calamity in some cases.

onedsrch --- Yes if you want a 1D search to be made before each profile fit. This is tolerant of poor positioning of the start point, but potentially vulnerable to problems with multiple targets. What happens is that a box around the cursor position is collapsed in X and Y and then the peak in each direction is located using cross-correlation with a gaussian of FWHM=fwhm1D. This new position is then used to define the fitting region and initial position for the 2D gaussian fit. For an isolated target, this should probably be enabled.

fwhm1d --- This is the FWHM used in the 1D search. It does not have to match the FWHM of the target necessarily, and you may want to err on the large side to ensure that a taget is picked up..

hwidth1d --- The half-width of the region to be used for searching for a target by collapsing to 1D. The wider this is, the more chance of finding a target from a sloppy start position, but also the more chance of peaking up on a spurious target.

fdevice --- Plot device for showing Moffat & symmetrical gaussian fits. Should be different from the image plot device. e.g. "/xs" or "2/xs" if image plot device = "1/xs" otherwise program goes belly up for reasons that I can't quite track down.

Fitting

Two fit options are available: 2D gaussian or a Moffat profile. The Moffat profile can be thought of as a genaralised gaussian since it tends towards it in extreme cases. It is therefore usually a better one to use. The only caveat is that at the moment the implementation of the Moffat assumes that it is symmetrical whereas the gaussian can be elliptical as well as symmetrical. Most of all the Moffat is better usually because it allows for more extended wings than the gaussian and tghe real profiles seem to have these. You have the option during fits of plotting a 1D representation of the fit where the data is plotted versus radius from the fitted position.

The radii of the green circle plotted is set equal to the fitted FWHM (at least in the Moffat case)

Classes

This command is a member of the classes: Display, Observing.

Author: T.R. Marsh
Created: 09 May 2002
Revised: 06 July 2007

Page generated Fri Jul 5 12:23:42 2013

device	---	Plot device. e.g. "/xs" or "1/xs"
source	---	Data source, either 'l' for local, 's' for server or 'u' for a list of ucm files. 'Local' means the usual .xml and .dat files accessed directly. Do not add either .xml or .dat to the file name; these are assumed.
url/file	---	If source='S', this should be the complete URL of the file, e.g. 'http://127.0.0.1:8007/run00000012', or just the file part in which case the program will try to find a default part to add from the environment variable ULTRACAM_DEFAULT_URL. Failing this it will add http://127.0.0.1:8007/, i.e. the local host. If source='L', this should just be a plain file name.
first	---	If source='L' or 'S, 'first' sets which exposure to start with (starts at 1). Set = 0 to always try to get the last file, useful if the program does not keep up with the data and for positioning stars.
trim	---	If source='L' or 'S', set trim=true to enable trimming of potential junk rows and columns of each window
ncol	---	If trim, then this specifies the number of columns nearest the readouts of each window to be snipped off as these can be corrupted.
nrow	---	If trim, then this specifies the number of rows to snip off the bottom of each window as these can be corrupted.
twait	---	Time to wait between attempts to find a new exposure. (Only for data from a server)
tmax	---	Maximum time to wait before giving up, set = 0 to give up immediately. (Only for data from a server).
flist	---	If source = 'U', this is the name of a list of ULTRACAM files to reduce. These should be arranged in temporal order to help the reduction move from one exposure to the next successfully.
pause	---	Seconds to pause between frames.
nccd	---	CCD number to plot, 0 for all
stack	---	Stacking direcion when plotting more than on CCD. Either in 'X' or 'Y'
bias	---	true/false according to whether you want to subtract a bias frame. You can specify a full-frame bias because it will be cropped to match whatever your format is. This is useful for ultracam because of the different bias levels of the 6 readouts.
biasframe	---	If bias, then you need to specify the name of the bias frame.
threshold	---	If you are applying a bias to ULTRASPEC L3CCD data, you have the option of converting to photon counts (0 or 1 whether above or below a certain threshold).
photon	---	The threshold level if threshold = true
naccum	---	Accumulate data into the sum of naccum frames before plotting.
def	---	true/false according to whether you want to plot a list of CCD defects (see setdefect). This is supposed to be useful when trying to acquire targets.
defect	---	The name of the defect file if def=true. Bad ones are plotted as stars; moderate ones as circles. Moderate line defects are dashed cf solid lines for disastrous ones.
transform	---	The name of a transformation file generated by the script transform. This allows the defects of one CCD to be over-plotted on another, accounting for their relative orientations. For each CCD this file has a line listing the scale factor, rotation (anti-clockwise degrees) and translation in x and y to get from a reference CCD to the CCD in question. Lines starting with '#' or a blank are skipped.
setup	---	True if you want to try setting up windows in which a file of test windows (next argument) is continually re-read for each image plotted.
setwin	---	The file of test windows that will be read each image, allowing you to keep changing it while new images come in (e.g. with 'emacs', remembering to save it). This should start with the binning factors as a line 'XBIN YBIN' and then a series of lines of the form 'XSTART YSTART NX NY', which define each window in the following manner: XSTART is the X value of left-most column in the window (in terms of unbinned pixels), YSTART is the Y value of the bottom row, and NX and NY are the X and Y dimensions. All of these are in unbinned pixels. This file will be read once per image and the windows overplotted as dashed boxes. They will be in yellow if judged valid, red if not, and the reason for their not being valid will be printed to the terminal. Lines starting with '#' or a blank or a tab are treated as comments. setwin may either be a disk file name or an http URL on which a server is waiting which will dispatch the values. The Java clients udriver and usdriver can act as servers for rtplot. If these are running on the same machine as rtplot, then 'http://localhost' should work.
lowlevel	---	A warning will be printed if the median level of the left-hand window of the CCD 1 falls BELOW this value. Sometimes this happens after a power on and adds noise to all the CCDs. 2000 seems to be about the right value. Set = 0 to ignore. (ULTRACAM only)
highlevel	---	A warning will be printed if the median value of the right-hand window of CCD 1 is ABOVE this value. 3500 seems about the right value, but remember sky counts will trigger it. Set = 0. to ignore. (ULTRACAM only)
flatlevel	---	To reduce false high bias warnings, this is a level above which no warning will be printed. It is a level WITHOUT bias-subtraction so 6000 is reasonable.
stack	---	Stacking direcion when plotting more than on CCD. Either in 'X' or 'Y'
xleft xright	---	X range to plot
yleft yright	---	Y range to plot
iset	---	'A', 'D' or 'P' according to whether you want to set the intensity limits automatically (= min to max), directly or with percentiles.
ilow ihigh	---	If iset='d', ilow and ihigh specify the intensity range to plot
plow phigh	---	If iset='p', plow and phigh are percentiles to set the intensity range, e.g. 10, 99
profit	---	If a single CCD is plotted, this option allows profile fitting. If you type 'y', you will be asked to select objects with a cursor for fitting on each frame. If you select two stars then the angle of the line joining them with respect to the chip rows will be reported, which is useful during drift mode setups.
method	---	There are two options for profile fitting: 2D Gaussian or a Moffat profile. The latter is a much better representation of seeing broadened profiles. The Gaussian can be symmetric or elliptical. The Moffat profile is of the form h/(1+(r/R)2)beta where r is the distance from the centre of the profile, R is a scale length and beta is a parameter that you will be prompted for an intial value. As beta gets large, the Moffat profile tends to Gaussian. The intial value of R is computed from a FWHM value. The routine plots a line at 2 times the measured FWHM on the image (not yet for the asymmetric gaussian).
symm	---	Yes/no for symmetric versus elliptical gaussians in the case of gaussian fits. I have not fully tested this option.
fwhm	---	fwhm is the initial FWHM to use for the profile fits.
hwidth	---	The half-width of the region to be used when fitting a target. Should be larger than the fwhm, but not so large as to include multiple targets if possible. This is also the region used to compute the maximum value that the program will report.
readout	---	Readout noise, RMS ADU in order for the program to come back with an uncertainty. NB It is important in this case to carry out bias subtraction if you want half-way decent error estimates.
gain	---	Gain, electrons/ADU, again for uncertainty estimates
sigrej	---	The fits can include rejection of poor pixels. This is the threshold, measured in sigma. Should not be too small as this may cause rejection of many points which can slow the routine down a fair bit as well as leading to calamity in some cases.
onedsrch	---	Yes if you want a 1D search to be made before each profile fit. This is tolerant of poor positioning of the start point, but potentially vulnerable to problems with multiple targets. What happens is that a box around the cursor position is collapsed in X and Y and then the peak in each direction is located using cross-correlation with a gaussian of FWHM=fwhm1D. This new position is then used to define the fitting region and initial position for the 2D gaussian fit. For an isolated target, this should probably be enabled.
fwhm1d	---	This is the FWHM used in the 1D search. It does not have to match the FWHM of the target necessarily, and you may want to err on the large side to ensure that a taget is picked up..
hwidth1d	---	The half-width of the region to be used for searching for a target by collapsing to 1D. The wider this is, the more chance of finding a target from a sloppy start position, but also the more chance of peaking up on a spurious target.
fdevice	---	Plot device for showing Moffat & symmetrical gaussian fits. Should be different from the image plot device. e.g. "/xs" or "2/xs" if image plot device = "1/xs" otherwise program goes belly up for reasons that I can't quite track down.