NAME:
occprof
PURPOSE: (one line only)
Plot an occultation profile based on a set of chords
DESCRIPTION:
CATEGORY:
Occultation
CALLING SEQUENCE:
occprof
INPUTS:
OPTIONAL INPUT PARAMETERS:
KEYWORD INPUT PARAMETERS:
FNCONFIG - name of configuration file (overrides xtrack.in),
the default is config.ini but if the configuration file
is not found then operation reverts to using xtrack.in
The minimal content of the config file must have:
[global]
event - Name of the event
objectid - string with the object id (see ephem.pro)
ora - Apparent position of star at time of occultation
odec - Apparent position of star at time of occultation
geomid - UT date and time of geocentric closest approach
tsig - 1-sigma uncertainty in event time (down-track) in seconds
xsig - 1-sigma cross-track uncertainty in km
FNCHORDS - Name of the file with the chord information, default='chords.dat'
FNXTRACK - Name of the file with the crosstrack position information,
default='crosstrack.dat'
FNXE - Name of the file to save the sky-plane points to.
default=event+'_xe.dat', the direct graphics will be saved
to the same root name with a suffix of .png.
FNRESULTS - Name of the file to save the fitting results to.
default=event+'.results'
EVENT - Name of the event. This is required if using xtrack.in
but ignored if using config.ini
HSIZE - half-size of the physical dimension of plot in km. Provide
a two element vector [x_hwidth,y_hwidth]. Default=[30,20]
OFFSET - amount, in km, to shift the center of the occultation profile
from its natural center. Provide a two element vector
[xoffset,yoffset]. Default is [0,0].
REFNAME - Name of site that is to serve as the reference chord for
extracting astrometry. If not provided the astrometry
step will be skipped.
TAGTWEAK - 2-d array, [N,2] where N must exactly match the numbers of
sites defined by the ancillary files. Default is 0. Units
of the tweak are in data units (km). These positions shift
the track tag labels by the requested amount from where the
automatic placement would put them.
PUBINFO - anonymous structure with information needed for building a
publiation quality graphic. If this structure is provided,
a mode is enabled that will use the function graphics calls
and the output is intended to be used for publication graphics.
Without this structure, direct graphics are used. The output
should look the same regardless of the mode used. Some control
options on the output products are provided by this structure.
The tags that will be used are:
fnlist - string or string array of names to save the
graphic to at the end. Using the array option
here let's you save a version of the graphic
in multiple formats from the same run. The file
suffix is used to dictate the output file type.
loc - This is passed to the plot() POSITION keyword
if not provided in the structure a default value of
loc=[0.1,0.9,0.1,0.9] is used.
dim - This is passed to the plot() DIMENSION keyword
if not provided in the structure a default value of
dim=[500,500] is used.
POSTFUNC - This is the name of a procedure to call at the end of the
built in plotting. It allows you to further modify or add
to the plot for non-standard cases. This procedure must
support one argument and a keyword, PUB. The PUB keyword
is a flag that when set dictates the use of the plot functions
for use in publications. This keyword is set in regard to
the use of the PUBINFO keyword. If /PUB is set, the argument
to the external procudure will be the id of the root level
graphic in the plot. You don't have to use it but it's there
if you need it. If PUB=0, then the argument will be set to
0 and would generally be ignored by your own routine.
to the plot for non-standard cases. This procedure must
support one argument and a keyword, PUB. The PUB keyword
is a flag that when set dictates the use of the plot functions
for use in publications. This keyword is set in regard to
the use of the PUBINFO keyword. If /PUB is set, the argument
to the external procudure will be the id of the root level
graphic in the plot. You don't have to use it but it's there
if you need it. If PUB=0, then the argument will be set to
0 and would generally be ignored by your own routine.
WEIGHTS - weighting factors for each constraint. The default is equal
weights for all points. This optional input should be
a 2 x N array, where N is equal to the number of stations
(not chords). Elements [0,*] are for the disappearance, and
[1,*] are for the disapperance and should appear in the
same order as found in the chords.dat file. You can choose
automatic weighting as well, see AUTO_WEIGHTS.
AUTO_WEIGHT - Flag, if set will compute and use weights based on the
timing uncertainties found in the chords.dat file.
If this is set, any values provided via the WEIGHTS
input keyword are ignored. The auto weights are set
to 1.0/(err > 0.001)
START_PARAMS - optional starting parameters for the ellipse fitting.
This is a five element vector:
0 = semi-major axis of ellipse
1 = semi-minor axis of ellipse
2 = ellipse center - x value
3 = ellipse center - y value
4 = PA of ellipse (radians)
PARINFO - for full documentation consult the Markwardt routine, MPFIT.PRO
there are a lot of detailed and potentially complex interactions
enabled by this optional routine. The most common use for this
is to control which parameters are fitted. The default is to
fit them all. This is an array of anonymous structures, one
for each parameter, in the case of this routine this structure
should have 5 elements in the array. Each array can have
tags from the set of supported tags, none are required. These
tags are the ones most likely to be of use to this routine.
.value - starting parameter value (semi-redundant with
START_PARMS, see MPFIT.PRO for more details).
.fixed - flag, if set, parameter is used, not fitted.
.limited - two element boolean array to control limits
on the allowed range for a variable and must
be paired with .limits
.limits - two element float or double array for the limits
CIRCULAR - Flag (passed to mpfitellipse) that if, set constrains the fit
to be circular. This keyword simplifies this common option
but can be replicated without this flag but more complex
options in PARINFO.
SHOWSTART - Flag, used only in direct graphics mode. If set will plot
START_PARAMS if provided.
LABEL_ANGLE - Angle to set labels to, default=0
WINDOW - if using direct graphcis, this controls which window is used,
(default=0)
NOLOG - Flag, if set will suppress writing a log file of output from the
fitting process.
SILENT - Flag, if set will suppress printing any results information to
the console. This does not apply to error messages.
OUTPUTS:
KEYWORD OUTPUT PARAMETERS:
CONFIGURATION:
COMMON BLOCKS:
SIDE EFFECTS:
RESTRICTIONS:
The weighting factors are not rigorously handled. The true uncertainties
are 1-D and aligned with the track of each site. The ellipse fitting
routine applies this to both xi and eta in equal measure.
Requires the Markwardt ellipse fitting program be in your IDL_PATH
(mpfitellipse.pro). This is from a separate library of routines.
PROCEDURE:
MODIFICATION HISTORY:
Written by Marc W. Buie, Southwest Research Institute, 2020/01/31
2020/03/31, MWB, many things cleaned up, new documentation, new keywords
2020/05/14, MWB, added START_PARAMS keyword
2020/05/21, MWB, added weighting keywords
2020/06/08, MWB, added saving the xi,eta D&R coordinates to a file
2020/10/07, MWB, added support for config.ini file
2021/01/25, MWB, added POSTFUNC keyword
2021/02/04, MWB, added FNCHORDS keyword
2021/03/10, MWB, added FNXTRACK and FNXE keywords
2021/05/13, MWB, added WINDOW keyword
2021/12/17, MWB, added FNRESULTS, NOLOG, and SILENT keywords