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
optional values:
nephpts - Number of ephemeris points to calculate for tracks,
default is 382.
ephdt - Time spacing in ephemeris points [seconds], default 0.1
FNSITES - name of the file with site location information (default=sites.dat)
FNEVENTS - name of occultation events file (default=events.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]
SHOWHULL- Flag, if set attempts to draw a smooth outline passing through
all of the data (fitted or not).
SHOWEXTRA - Flag, if set, shows the extra hull points
HULLPTS - extra points to add to hull (Nx2 array).
SAVEHULL - File to save the final hull to (default = hull.dat)
ARES - angular resolution smoothing width for the hull (degrees),
default=20 (mkhull2)
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.
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 events.dat file. You can choose
automatic weighting as well, see AUTO_WEIGHT.
AUTO_WEIGHT - Flag, if set will compute and use weights based on the
timing uncertainties found in the events.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.
NOSAVE - Flag, if set suppresses saving the images (direct graphics only)
EXTRATITLE - Extra string to append to title of plot. Used only for
the direct graphics version
TAGSTYLE - Optional control on what tags to show for site tracks
0 - default, show all of them that fit in the display window
1 - suppress labels for sites with no data
BODY - Single character string of the object to fit, default = '0'
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
2022/01/18, MWB, fixed problem with SHOWSTART keyword
2022/01/25, MWB, added NOSAVE keyword
2022/02/01, MWB, corrected an error in the appearance of the data in
the plot. Added GNDVIEW keyword. Also fixed a
serious error due to a missing coordinate
transformation.
2022/02/02, MWB, added compass and direction of motion arrows and
EXTRATITLE keyword
2022/02/27, MWB, added nephpts and ephdt to config.ini options as well
as cleaning up some output text formatting.
2022/08/22, MWB, added support for just D or R points from a site rather
than restricting it to just site with both
2022/12/07, MWB, removed FNCHORDS keyword, this is now split into FNSITES
and FNEVENTS
2022/12/13, MWB, removed GNDVIEW option and keyword, added BODY keyword
2023/03/09, MWB, fixed a problem with xe files
2023/03/28, MWB, added SHOWHULL, HULLPTS keyword
2023/04/03, MWB, added SHOWEXTRA keyword
2023/05/02, MWB, reactivated the pub graphics component that was broken
after the upgrades last August.
2023/08/17, MWB, changed to use new loadocc/rdevents to control what
gets used for the hull. Added ARES keyword
2023/09/05, MWB, added calculation for the area of the hull.
2023/09/14, MWB, added SAVEHULL keyword
2023/10/19, MWB, added support for using config file to control label
offsets. This new feature eliminates the use of
TAGTWEAK. Also added TAGSTYLE keyword.
2024/03/19, MWB, minor change to print the ephemeris position for the
reference site when doing astrometry
2024/06/04, MWB, new parameters to control direction arrow labels
2024/07/31, MWB, modified to use new ephem/obscode tools