[Previous]
[Next]
NAME:
MAG2FLUX
PURPOSE:
Convert from magnitudes to flux (ergs/s/cm^2/A).
EXPLANATION:
Use FLUX2MAG() for the opposite direction.
CALLING SEQUENCE:
flux = mag2flux( mag, [ zero_pt, ABwave = ] )
INPUTS:
mag - scalar or vector of magnitudes
OPTIONAL INPUT:
zero_pt - scalar giving the zero point level of the magnitude.
If not supplied then zero_pt = 21.1 (Code et al. 1976)
Ignored if the ABwave keyword is set.
OPTIONAL KEYWORD INPUT:
ABwave - wavelength scalar or vector in Angstroms. If supplied, then
the input vector, mag, is assumed to contain Oke AB magnitudes
(Oke & Gunn 1983, ApJ, 266, 713)
OUTPUT:
flux - scalar or vector flux vector, in erg cm-2 s-1 A-1
If the ABwave keyword is set, then the flux is given by
f = 10^(-0.4*(mag +2.406 + 4*alog10(ABwave)))
Otherwise the flux is given by
f = 10^(-0.4*(mag + zero_pt))
EXAMPLE:
Suppose one is given vectors of wavelengths and AB magnitudes, w (in
Angstroms) and mag. Plot the spectrum in erg cm-2 s-1 A-1
IDL> plot, w, mag2flux(mag,ABwave = w)
REVISION HISTORY:
Written J. Hill STX Co. 1988
Converted to IDL V5.0 W. Landsman September 1997
Added ABwave keyword, W. Landsman September 1998
[Previous]
[Next]
NAME:
MAG2GEO()
PURPOSE:
Convert from geomagnetic to geographic coordinates
EXPLANATION:
Converts from GEOMAGNETIC (latitude,longitude) to GEOGRAPHIC (latitude,
longitude). (altitude remains the same)
CALLING SEQUENCE:
gcoord=mag2geo(mcoord)
INPUT:
mcoord = a 2-element array of magnetic [latitude,longitude], or an
array [2,n] of n such coordinates.
KEYWORD INPUTS:
None
OUTPUT:
a 2-element array of geographic [latitude,longitude], or an array [2,n]
of n such coordinates
COMMON BLOCKS:
None
EXAMPLES:
IDL> gcoord=mag2geo([90,0]) ; coordinates of magnetic south pole
IDL> print,gcoord
79.300000 -71.409990
MODIFICATION HISTORY:
Written by Pascal Saint-Hilaire (Saint-Hilaire@astro.phys.ethz.ch),
May 2002
[Previous]
[Next]
NAME:
mail
PURPOSE:
To send a mail message to yourself or a list of users
CALLING SEQUENCE:
mail, message
mail, message, users='lemen,freeland'
mail, message, subj="Test"
mail, file=file, users=users, /self
OPTIONAL INPUT:
message - a string array of the message that is to
be sent. Either the "message" or the "file"
parameter must be used.
CALLS: ***
ARR2STR [1], Arr2Str [2], CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3]
FILE_EXIST [2], concat_dir [4], file_append [1], file_append [2], file_exist [1]
file_exist [3], get_logenv [1], get_logenv [2]
CALLED BY:
ACOPY [1], ACOPY_TEST, bbso_copy [1], bbso_copy [2], check_log [1], check_log [2]
check_oldprocess [1], check_oldprocess [2], check_oldprocess [3]
check_oldprocess [4], check_process [1], check_process [2], ckdderr, cp_fns [1]
cp_fns [2], daily_forecast [2], disk_monitor [1], disk_monitor [2], do_ads, dotar
eit_genx_cat, get_ads [1], get_selsis, get_sirius [1], get_sirius [2], goes2str
killold [1], killold [2], laststat [1], laststat [2], mk_gsn_obs_s1, mk_mo
mk_mo2 [1], mk_mo2 [2], mk_mo_disk2, mk_orbit [1], mk_orbit [2], mk_orbit_files
mk_pix [1], mk_pix [2], mk_sfc [1], mk_sfc [2], mo_patch, monitor_scratch [1]
monitor_scratch [2], nob_img_copy, nts_copy [1], nts_copy [2], rd_ydbtap
ref_term [2], search_obs, selsisi_copy, sfc_check, soon_search [1]
soon_search [3], ssw_check_contrib, ssw_conflicts, ssw_strfind, tr_build_img [1]
trace_do_data_requests, trace_special_movie [2], trace_special_movie [3]
wwwidl_server_check, xsxt_prep, ycopy, ydump, ys_contrib [1], ys_contrib [2]
OPTIONAL KEYWORD INPUT:
users - a string containing the users who should receive
the message. If it is undefined, it will send the
message to yourself only (can be used as notification
that a program is finished)
subj - a string that should appear on the subject line. It
cannot have the " character in the string
file - the name of a file that should be sent to the users
Either the "message" or the "file" parameter must
be used. File can be an array of file names.
self - if set, send a copy to yourself also
no_defsubj - if set, use user supplied subject only
RESTRICTIONS:
Only works on Unix machines right now
HISTORY:
Written 21-Mar-92 by M.Morrison
24-Nov-92 (MDM) - Modified not to use the subject option when running
on the SGI machine.
14-Dec-92 (MDM) - Modified to work on MIPS machines
18-Dec-92 (MDM) - Modified to have the file name in the subject on
non-SGI machines.
17-Feb-94 (SLF) - add no_defsubj
26-feb-95 (SLF) - make sure proper mail (Mail) is selected
(seperate from .cshrc/path) - avoid pipe (very slow)
if message is string array, make temporary file,
and recurse with file option, remove file...
3-mar-95 (SLF) - use /nodefsubj when recursing
18-Apr-97 (MDM) - Replace "which" with "which -f"
3-Nov-97 (MDM) - Allow subject option on SGI machines (undo Nov-92 mod)
[Previous]
[Next]
Name: main_execute
Purpose: execute idl 'command' file (in IDL_STARTUP format)
Input Paramters:
filename - file containing idl startup commands
Keyword Parameters:
text - text array already processed by rd_tfile(/compr,nocomm=';')
CALLED BY:
setssw_windows, ssw_addmm_gen, ssw_set_chianti, ssw_setup_windows
History:
slf - 5-feb-1993 - allow chaining of multiple IDL_STARTUP files
slf - 30-mar-1993 - return to caller on error
slf - 21-apr-1993 - trap executive commands (.run, .size, etc)
ras - 8-jul-1996 - take text array instead of file
ras - 19-jul-1996 - recursively traps and uses @file[.pro]
CALLS: ***
rd_tfile [1], rd_tfile [2]
Restrictions:
filename contents must conform to IDL_STARTUP format
Cannot execute idl executive commands (TBD)
Uses execute function so no recursion allowed - multiple line block
commands are limited to total string length of 512 (execute limit)
[Previous]
[Next]
NAME:
MAKE_2D
PURPOSE:
Change from 1-d indexing to 2-d indexing
EXPLANATION:
Convert an N element X vector, and an M element Y vector, into
N x M arrays giving all possible combination of X and Y pairs.
Useful for obtaining the X and Y positions of each element of
a regular grid.
CALLING SEQUENCE:
MAKE_2D, X, Y, [ XX, YY ]
INPUTS:
X - N element vector of X positions
Y - M element vector of Y positions
OUTPUTS:
XX - N x M element array giving the X position at each pixel
YY - N x M element array giving the Y position of each pixel
If only 2 parameters are supplied then X and Y will be
updated to contain the output arrays
CALLED BY:
GETPSF, RDPSF
EXAMPLE:
To obtain the X and Y position of each element of a 30 x 15 array
IDL> x = indgen(30) & y = indgen(15)
IDL> make_2d, x, y
REVISION HISTORY:
Written, Wayne Landsman ST Systems Co. May, 1988
Added /NOZERO keyword W. Landsman Mar, 1991
Converted to IDL V5.0 W. Landsman September 1997
Improved speed P. Broos July 2000
[Previous]
[Next]
NAME:
MAKE_ASTR
PURPOSE:
Build an astrometry structure from input parameter values
EXPLANATION:
This structure can be subsequently placed in a FITS header with
PUTAST
CALLING SEQUENCE:
MAKE_ASTR, astr, CD = , DELT =, CRPIX =, CRVAL =, CTYPE =,
LATPOLE = , LONGPOLE =, PV2_1 = PV2_2 = , PV2_3 =
OUTPUT PARAMETER:
ASTR - Anonymous structure containing astrometry info. See the
documentation for EXTAST for descriptions of the individual
tags
REQUIRED INPUT KEYWORDS
CRPIX - 2 element vector giving X and Y coordinates of reference pixel
(def = NAXIS/2). VALUES MUST BE IN FITS CONVENTION (first pixel
is [1,1]) AND NOT IDL CONVENTION (first pixel is [0,0]).
CRVAL - 2 element double precision vector giving R.A. and DEC of
reference pixel in DEGREES
OPTIONAL INPUT KEYWORDS
CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2
in DEGREES/PIXEL CD2_1 CD2_2
DELT - 2 element vector giving physical increment at reference pixel
CDELT default = [1.0D, 1.0D].
CTYPE - 2 element string vector giving projection types, default
['RA---TAN','DEC--TAN']
LATPOLE - Scalar latitude of the north pole, default = 0
LONGPOLE - scalar longitude of north pole, default = 180
Note that the default value of 180 is valid only for zenithal
projections; it should be set to PV2_1 for conic projections,
and zero for other projections.
PV2 - Vector of projection parameters. Not required for some
projections (e.g. TAN) and optional for others (e.g. SIN).
Usually a 2 element vector, but may contain up to 21 elements
for the Zenithal Polynomial (ZPN) projection. Corresponds to
the keywords PV2_1, PV2_2... Defaults to 0.0
NOTES:
(1) An anonymous structure is created to avoid structure definition
conflicts. This is needed because some projection systems
require additional dimensions (i.e. spherical cube
projections require a specification of the cube face).
(2) The name of the keyword for the CDELT parameter is DELT because
the IDL keyword CDELT would conflict with the CD keyword
(3) The astrometry structure definition was slightly modified in
July 2003; all angles are now double precision, and the
LATPOLE tag was added.
REVISION HISTORY:
Written by W. Landsman Mar. 1994
Converted to IDL V5.0 Jun 1998
Added LATPOLE, all angles double precision W. Landsman July 2003
Use PV2 keyword rather than PROJP1, PROJP2 W. Landsman May 2004
CALLED BY
STARAST
[Previous]
[Next]
PROJECT:
SOHO - CDS/SUMER
NAME:
MAKE_AUTO_FIT
PURPOSE:
Interface to procedures of auto limb fitting.
EXPLANATION:
CALLING SEQUENCE:
make_auto_fit
INPUTS:
None.
OPTIONAL INPUTS:
None.
OUTPUTS:
None.
OPTIONAL OUTPUTS:
None.
KEYWORD PARAMETERS:
None.
CALLS: ***
CNVT_COORD [1], CNVT_COORD [2], CURSOR_INFO, CW_FIELD, DELVARX [1], DELVARX [2]
DELVARX [3], DELVARX [4], FLASH_MSG, ITOOL_COPY_TO_PIX, ITOOL_CROSS_HAIR
ITOOL_DISPLAY, ITOOL_REFRESH, LIMBFIT_EVENT, LIMB_INFO, MAKE_MANUAL_FIT
MK_LIMBFIT_BS, NL_LSQFIT, NUM2STR, PB0R, RESET_LIMBFIT, SETWINDOW [1], SETWINDOW [2]
UPDATE_FITLIMB, XSHOW_HELP, delvarx [5]
CALLED BY:
ITOOL_LIMBFITTER, MAKE_MANUAL_FIT, MK_LIMBFIT_BS, UPDATE_FITLIMB
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
CATEGORY:
PREVIOUS HISTORY:
Written January 25, 1995, Liyun Wang, GSFC/ARC
MODIFICATION HISTORY:
Version 1, created, Liyun Wang, GSFC/ARC, January 25, 1995
VERSION:
Version 1, January 25, 1995
[Previous]
[Next]
PROJECT:
CHIANTI
PURPOSE:
Return CHIANTI version
CALLING SEQUENCE:
chianti_version, version
CALLS:
CALLED BY
GOES_TF, GOES_TF_COEFF
[Previous]
[Next]
PROJECT:
GOES
PURPOSE:
Generate CHIANTI spectra for calculation of GOES responses.
CATEGORY:
GOES
CALLING SEQUENCE:
generate_spectra [, /photospheric ]
INPUTS:
Set /PHOTOSPHERIC for photospheric abundances, default is coronal
OUTPUTS:
Individual SAVEGEN files containing spectra SPC for each of 62
temperatures, labelled ch<VERS>_cor_3e10_1e27_<LOGT>.genx or
ch<VERS>_pho_3e10_1e27_<LOGT>.genx
CALLS: ***
CHIANTI_VERSION, CH_SYNTHETIC, DELVARX [1], DELVARX [2], DELVARX [3], DELVARX [4]
FCHECK, FILE_EXIST [2], FOLD_SPEC_RESP, GENERATE_SPECTRA, GET_ENVIRON, GOES_TF
GOES_TF_COEFF, INT_TABULATED, MAKE_CHIANTI_SPEC, POLY, POLY_FIT, TABLES_02_TO_PRO
TODAY, anytim [1], anytim [2], anytim [3], anytim [4], anytim [5], delvarx [5]
file_exist [1], file_exist [3], restgen [1], restgen [2], savegen [1], savegen [2]
CALLED BY:
GOES_TF, GOES_TF_COEFF
PROCEDURE:
Calls MAKE_CHIANTI_SPEC
MODIFICATION HISTORY:
SW 2005 Jan
[Previous]
[Next]
PROJECT:
GOES
PURPOSE:
Generate GOES responses by folding CHIANTI spectra with wavelength
responses of individual satellites.
CALLING SEQUENCE:
fold_spec_resp , NSAT [, /PLOTSPEC ]
INPUTS:
NSAT = number of GOES satellites
Set /PLOTSPEC if you want results plotted as they are derived
OUTPUTS:
Individual save files containing temperature responses etc in files
idlsave.fit_coeffs_.02_GOES_<SAT> for each of 12 SATs.
CALLS: ***
CHIANTI_VERSION, CH_SYNTHETIC, DELVARX [1], DELVARX [2], DELVARX [3], DELVARX [4]
FCHECK, FILE_EXIST [2], FOLD_SPEC_RESP, GENERATE_SPECTRA, GET_ENVIRON, GOES_TF
GOES_TF_COEFF, INT_TABULATED, MAKE_CHIANTI_SPEC, POLY, POLY_FIT, TABLES_02_TO_PRO
TODAY, anytim [1], anytim [2], anytim [3], anytim [4], anytim [5], delvarx [5]
file_exist [1], file_exist [3], restgen [1], restgen [2], savegen [1], savegen [2]
CALLED BY:
GOES_TF, GOES_TF_COEFF
PROCEDURE:
Calls MAKE_CHIANTI_SPEC
MODIFICATION HISTORY:
SW 2005 Jan
[Previous]
[Next]
PROJECT:
GOES
PURPOSE:
Generate goes_get_chianti_temp.pro and goes_get_chianti_em.pro in /tmp
CATEGORY:
GOES
CALLING SEQUENCE:
tables_.02_to_pro, nsat
INPUTS:
NSAT = number of satellites
OUTPUTS:
Routines goes_get_chianti_temp.pro and goes_get_chianti_em.pro
ARE WRITTEN TO /TMP FOR SAFETY
CALLS: ***
CHIANTI_VERSION, CH_SYNTHETIC, DELVARX [1], DELVARX [2], DELVARX [3], DELVARX [4]
FCHECK, FILE_EXIST [2], FOLD_SPEC_RESP, GENERATE_SPECTRA, GET_ENVIRON, GOES_TF
GOES_TF_COEFF, INT_TABULATED, MAKE_CHIANTI_SPEC, POLY, POLY_FIT, TABLES_02_TO_PRO
TODAY, anytim [1], anytim [2], anytim [3], anytim [4], anytim [5], delvarx [5]
file_exist [1], file_exist [3], restgen [1], restgen [2], savegen [1], savegen [2]
CALLED BY:
GOES_TF, GOES_TF_COEFF
MODIFICATION HISTORY:
SW 2005 Jan
[Previous]
[Next]
Project:
SDAC
NAME:
MAKE_GOES_RESP
PURPOSE:
This procedure integrates the GOES transfer functions over a thermal solar
spectrum for 200 temperatures to set up an interpolation table.
Calculates the response in watts/m2 of the two GOES channels to the thermal
emission from a solar plasma of emission measure 1e49 cm-3 as a function
of the temperature in units of megaKelvin (1e6).
CATEGORY:
GOES, SPECTROSCOPY, ANALYSIS
CALLING SEQUENCE:
make_goes_resp, te6, goes_resp_49 [, goes8=goes8, goes9=goes9]
CALLS: ***
AVG [1], AVG [2], GOES_TRANSFER, INTERPOL, LOC_FILE [1], LOC_FILE [2], LOC_FILE [3]
RD_ASCII [1], RD_ASCII [2], XEDIT, edge_products, mewe_spec [1], mewe_spec [2]
prstr [1], prstr [2], restgen [1], restgen [2], savegen [1], savegen [2]
INPUTS:
none explicit, only through commons;
OPTIONAL INPUTS:
none
OUTPUTS:
te6 - Temperature vector in units of 1e6 Kelvin, 200 values
from 1e6 to 97.7e6
goes_resp_49(2,200) - GOES flux in units of Watts/m2 for emission measure of 1.e49 cm-3
Channel 0, 1-8 Angstroms
Channel 1, .5-4 Angstroms
OPTIONAL OUTPUTS:
none
KEYWORDS:
GOES6- Use transfer function for GOES6
GOES7- Use transfer function for GOES7
GOES8- Use transfer function for GOES8
GOES9- Use transfer function for GOES9
GOES10- Use transfer function for GOES10
SHORTWN - 2xN wavelength bins used with MEWE_SPEC, angstroms, short channel
LONGWN - 2XN wavelength bins for long channel (1-8 Angstrom nominal response)
GSHORT - Response for SHORTWN
GLONG - Response for LONGWN
WRITE - If set, response functions are written as an IDL save file (/xdr)
to SSWDB_GOES, intended for use on SDAC only.
COMMON BLOCKS:
none
SIDE EFFECTS:
none
RESTRICTIONS:
This procedure is designed to be run to write the data file, goes_resp2.dat
only on SDAC at GSFC
PROCEDURE:
This procedure integrates the GOES transfer functions over a thermal solar
spectrum for 200 temperatures to set up an interpolation table.
Needed Files:
Stored lookup table stored in goes_resp2.dat
goes_resp2.dat will usually be in the same directory as goes_tem.pro
so will be found by loc_file.
MODIFICATION HISTORY:
written 1991, RAS
5-dec-95, jmm, changed from restoration of the file
'richard$data:mewe_spec.vms', to the use of MEWE_SPEC for the photon flux
Version 3, RAS/SDAC/GSFC/HSTX incorporate GOES8 and 9
Version 4, RAS/SDAC/GSFC/HSTX incorporate GOES6 and 7, 20-nov-1996
Version 5, RAS, use the edge integration capability of MEWE_SPEC directly
Version 6, RAS, 4-feb-1997, write the goes resp into a comprehensive structure
to increase speed when switching between responses of GOES satellites!
Concommitant changes implemented in GOES_TEM.PRO
Version 7, RAS, 5-feb-1997, using savegen and restgen for the saved response file
Concommitant changes implemented in MAKE_GOES_RESP.PRO
Version 8, added GOES10
[Previous]
[Next]
Name:
MAKE_HIST2D
Purpose:
Form a 2-D histogram from two arrays or images.
Category:
Data processing
Calling sequence:
hist_img = MAKE_HIST2D(image1,image2 [ , MISSING=missing ,
/XLOG , /YLOG ,
XHRANGE=xrange , YHRANGE=yrange ,
XBIN=xbin , YBIN=ybin ,
INFO=hist_info , IMAGES=hist_input ] )
Inputs:
image1: 1st image (or set of images) [X]
image2: 2nd image ( " ) [Y]
Keyword parameters:
MISSING = value flagging missing/bad pixels (IN)
X/YLOG = use log of X/Y? (IN)
X/YHRANGE = range of X/Y values to be used in forming the histogram (IN)
X/YBIN = X/Y binning (IN)
INFO = info. (dimension, origin, binsize) about the histogram array;
array (2 elements) of structures (OUT), tags:
dim: i-th dimension of the histogram image;
zero: origin of the i-th axis;
bin: bin factor for the i-th axis;
log: (boolean) histogram in logarithm space?
IMAGES = actual images used to form the histogram; structure (OUT), tags:
flt: float input array (log scaled, if X/YLOG is set);
int: integer-scaled input array;
Given in output only if explicitly requested by setting
hist_input to some value.
Output:
hist_img : array (image) representing the two-dimensional histogram
obtained from the two input images.
Common blocks:
None
Calls: ***
HIST_2D
Side effects:
None
Notes:
When X/YLOG is specified, X/YHRANGE and X/YBIN are assumed to give
the range of values and bin size, respectively, in logarithm space.
Restrictions:
None
Modification history:
V. Andretta, 2/Jul/1998 - Created (adapted from HIST2ROI)
V. Andretta, Oct-Nov/1998 - Revised
Contact:
VAndretta@solar.stanford.edu
[Previous]
[Next]
Name: make_into_bytarr
Purpose: convert input to byte array
Input:
in0 - input data
Output:
function returns byte version
Keyword Parameters:
swap_lendian - if litte endian and keyword set, then swap
CALLS: ***
IS_LENDIAN, dec2sun [1], dec2sun [2]
CALLED BY:
gtt_info, trace_dph2struct [1]
History:
~ 1-Jan-1998 - Mons Morrison
16-Jun-1998 - S.L.Freeland - add /SWAP_LENDIAN keyword and function
[Previous]
[Next]
PROJECT:
SOHO - CDS/SUMER
NAME:
MAKE_MANUAL_FIT
PURPOSE:
Interface to the manual limb fitting process
EXPLANATION:
CALLING SEQUENCE:
make_manual_fit
INPUTS:
None.
OPTIONAL INPUTS:
None.
OUTPUTS:
None.
OPTIONAL OUTPUTS:
None.
KEYWORD PARAMETERS:
None.
CALLS: ***
CNVT_COORD [1], CNVT_COORD [2], CURSOR_INFO, CW_FIELD, DELVARX [1], DELVARX [2]
DELVARX [3], DELVARX [4], FLASH_MSG, ITOOL_COPY_TO_PIX, ITOOL_CROSS_HAIR
ITOOL_DISPLAY, ITOOL_REFRESH, LIMBFIT_EVENT, LIMB_INFO, MAKE_AUTO_FIT
MK_LIMBFIT_BS, NL_LSQFIT, NUM2STR, PB0R, RESET_LIMBFIT, SETWINDOW [1], SETWINDOW [2]
UPDATE_FITLIMB, XSHOW_HELP, delvarx [5]
CALLED BY:
ITOOL_LIMBFITTER, ITOOL_SWITCHER, MAKE_AUTO_FIT, MK_LIMBFIT_BS, UPDATE_FITLIMB
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
CATEGORY:
PREVIOUS HISTORY:
Written January 25, 1995, Liyun Wang, GSFC/ARC
MODIFICATION HISTORY:
Version 1, created, Liyun Wang, GSFC/ARC, January 25, 1995
VERSION:
Version 1, January 25, 1995
[Previous]
[Next]
Project : SOHO-CDS
Name : MAKE_MAP
Purpose : Make an image map
Category : imaging
Syntax : map=make_map(data)
Inputs : DATA = 2d data array
Outputs :
MAP ={data:data,xc:xc,yc:yc,dx:dx,dy:dy,time:time}
where,
DATA = 2d image array
or old format (which is more memory intensive),
MAP ={data:data,xp:xp,yp:yp,time:time}
where,
XP,YP = 2d cartesian coordinate arrays (old format)
OLD_FORMAT is used if XC and YC
are 2d arrays of coordinates for the center of each pixel.
Opt. Outputs: None
Keywords : XC,YC = center of image
DX,DY = pixel spacing in X and Y directions
TIME = image time
SUB = [x1,x2,y1,y2] = indicies of sub-array to extract
DATA_UNITS = units of subarray in data units [def=pixel number]
OLD_FORMAT = use old .xp, .yp format
ROLL_ANGLE = image roll (deg clockwise from N)
ROLL_CENTER = roll center
FOV = same as SUB, but with /DATA_UNITS
NO_COPY= set to not make new copy of data
BYTE_SCALE = bytescale data
CALLS: ***
ANYTIM2UTC [1], ANYTIM2UTC [2], COMDIM2, CSCALE, DATATYPE [1], DATATYPE [2]
DATATYPE [3], DPRINT, EXIST, GET_ARR_CENTER, GET_MAP_REGION, GET_UTC, IS_BLANK
MK_MAP_XP, MK_MAP_YP, PAIR_STRUCT, PR_SYNTAX, is_number [1], is_number [2]
CALLED BY:
CDS_ASRUN_POINT, CDS_PLAN_POINT, HESSI IMAGE STRATEGY CLASS DEFINITION
HSI_FITS2MAP [1], ITOOL2MAP, MAP__DEFINE, MK_CDS_IMAP, MK_CDS_SMAP, MK_EIT_MAP
MK_HXI_MAP, MK_IVM_MAP, MK_SXT_MAP, hsi_image__getaxis [2], hsi_image_plot
plotman
History : Written 22 October 1996, D. Zarro, ARC/GSFC
Modified 3 May 1999, Zarro (SM&A/GSFC)
- fixed roll angle definition. Roll angle measures
degrees clockwise that the image is rolled from
solar North.
Modified 10 August 1999, Zarro (SM&A/GSFC)
- included ROLL and ROLL_CENTER properties, even
if roll was zero.
Modified 12 Sept 2001, Zarro (EITI/GSFC)
- added /NO_COPY and replaced call to JOIN_STRUCT
with faster call to PAIR_STRUCT
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Name: make_mirror
Purpose: build a mirror file
Input Parameters:
site - remote site / ip
remote_dir - list of remote_dirs to mirror
local_dir - list of local dirs (destination)
Keyword Parameters:
remote_user - (default = anonymous)
remote_password (default = user@local_host)
packages - if passed, strarray containing package names (one per remote dir)
comments - is passed, strarray containing comments (one per remote dir)
mirror_file - output mirror file name w/path (default= "mk_mirror" in current)
no_symbolic_links - if set, dont follow remote links
XXX=NN - anyother where XXX=anyother mirror keword
and NN=associated value
Calling Sequence:
make_mirror, siteip, remote_dir, local_dir [,mirror_file='filename', $
packages=[package_names]
Calling Example:
IDL> <run routine to define remote and local directory lists>
IDL> make_mirror,'sohoftp.nascom.nasa.gov',remotedirs, localdirs, mirror_file='SSW.mirror'
IDL> make_mirror,ip,remote,local,MAX_DAYS=10 ; recent 10 days only
; (via keyword inherit)
18-march-1996 (S.L.Freeland) - originally for remote SSW install/upgrades
21-Oct-96 RDB Added comments keyword
21-Oct-96 S.L.Freeland - change compress_pat to compress_patt
23-Oct-96 S.L.Freeland - add /MODE_COPY keyword
12-nov-96 S.L.Freeland - add USE_TIMELOCAL (default=false)
31-mar-97 S.L.Freeland - add USER and GROUP keywords
22-may-97 S.L.Freeland - add MAX_DELETE_FILES and MAX_DELETE_DIRS
4-feb-98 S.L.Freeland - init MAX_DELETE_FILES MAX_DELETE_DIRS if
undefined (set to 10%, the mirror default)
20-mar-98 S.L.Freeland - enabled the keyword inheritance part
2-Feb-98 S.L.Freeland - include symbolic link following by default
22-Feb-98 S.L.Freeland - add /NO_SYMBOLIC_LINKS (override 2-feb default)
6-Dec-98 S.L.Freeland - add UPDATE_LOG keyword and function
8-Dec-98 S.L.Freeland - add /NOUSER and /NOGRROUP key/func
made those the Windows default (local_dir)
20-Mar-2000 S.L.Freeland - some windows stuff
30-Apr-2000 S.L.Freeland - due to Windows Mirror glitch, duplicate
the last package
4-Oct-2001 S.L.Freeland - add /PASSIVE_FTP keyword and function
17-mar-2003 S.L.Freeland - added an EXCLUDE_PATT for Windows
to avoid illegal DOS/Win filename from unix
CALLS: ***
ADD_TAG [1], ADD_TAG [2], ARR2STR [1], Arr2Str [2], BOX_MESSAGE, OS_FAMILY
data_chk [1], data_chk [2], file_append [1], file_append [2], get_host [1]
get_host [2], get_user [1], get_user [2], last_nelem, str_replace [1]
str_replace [2], str_subset, strlastchar [1], strlastchar [2], strmids [1]
strmids [2], tag_index [1], tag_index [2]
CALLED BY:
make_ssw_mirror, ssw_upgrade [1], ssw_upgrade [2], ssw_upgrade_backup
sswdb_upgrade
Restrictions:
must supply siteip and remote & local dirs (minimum)
assume one-one mapping between remote and local
[Previous]
[Next]
Project : SOHO - CDS
Name : MAKE_POINTER
Purpose : to make a pointer variable
Category : Help
Explanation : creates a pointer variable.
Pointer variable can be a:
- unrealized WIDGET)
- HANDLE (version 3.6 or greater
- real POINTER (version 5 or greater)
Syntax : IDL> make_pointer,pointer
Inputs : None
Opt. Inputs : None
Outputs : POINTER = pointer variable
Opt. Outputs: CHILD = optional child of parent pointer is returned
Keywords : WIDGET = force creating unrealized widget ID
HANDLE = force creating HANDLE
DIM = pointer dimensions
STATUS = 1/0 if success/failuer
CALLS: ***
DPRINT, EXIST, GET_CALLER, VALID_POINTER
CALLED BY:
BREAK_MAP, CACHE_DATA, CDS_STACK, COPY_VAR, GET_CDS_STUDY, ITOOL_LOAD_IMAGE
MK_PLAN_CUSTOM, MK_SOHO_CUSTOM, XANSWER, XCALENDAR, XCAMP, XCAT, XCHOICE, XCLONE_PLAN
XGET_UTC, XIAP, XINPUT, XLIST, XPROGRAM, XPROGRAM_ADD, XPS_SETUP, XREPORT, XREPORT_EDIT
XSEL_ITEM, XSEL_LIST [1], XSEL_LIST [2], XSET_COLOR, XSET_VALUE, XTEXT, XZOOM_PLAN
ethz_XCHOICE
Common : None
Restrictions: See explanation
Side effects: None
History : Version 1, 1-Sep-1995, D.M. Zarro. Written
Version 2, 17-Jul-1997, D.M. Zarro. Modified
-- Updated to version 5 pointers
Contact : DZARRO@SOLAR.STANFORD.EDU
[Previous]
[Next]
Project : SOHO - CDS
Name : MAKE_SFIT_STC
Purpose : Make an SFIT structure from a CFIT structure.
Explanation : An SFIT structure is a "short" structure describing a
component based fit function.
Use : SFIT = MAKE_SFIT_STC(CFIT)
Inputs : CFIT : Component Fit, designed with e.g., XCFIT
Opt. Inputs : None.
Outputs : Returns the short fit.
Opt. Outputs: None.
Keywords : VALUES : Set this to use the current values instead of the
initial values when constructing the parameter
array.
DOUBLE : Set this to promote values to doubles.
KEEP_LIMITS : Set to avoid setting min and max values equal to
the current value even if the const flag is set.
Used by e.g., CFIT_BLOCK.
Calls :
CALLED BY:
APPLY_CDS_ADEF, CDS_CORR_GRADIENT, CFIT, CFIT_APATCH, CFIT_BLOCK, CFIT_ERROR
EVAL_CFIT, XCFIT, XCFIT_BLOCK
Common : None.
Restrictions: None.
Side effects: None.
Category : Analysis
Prev. Hist. : None.
Written : S.V.H.Haugan, UiO, 21 January 1997
Modified : Version 2, 6 February 1997
Added KEEP_LIMITS keyword
Version 3, 6 August 1997
Added A_NOM (nominal values) in the sfits structure.
Version : 3, 6 August 1997
[Previous]
[Next]
PROJECT:
HESSI/PHOENIX
NAME:
MAKE_SPECTROGRAM()
PURPOSE:
Constructor for the spectrogram object. This is identical to
the function spectrogram()
CATEGORY:
Generic utilities
CALLING SEQUENCE:
o = make_spectrogram( spectrogram [, time_axis, energy_axis] ) or
o = make_spectrogram( spectrogram_struct )
INPUTS:
spectrogram: a 2d array containing the time/energy values
time_axis: the time axis associated with the spectrogram.
a 1 d vector with same # of elements as the x-axis
of the spectrogram. the time is referenced to 1-jan-79
(anytim format)
spectrum_axis: the spectrum axis associated with the spectrogram.
a 1 d vector with same # of elements as the y-axis
of the spectrogram
spectrogram_struct: a spectrogram structure with tags:
{spectrogram, time_axis, spectrum_axis}
OUTPUTS:
o: a spectrogram object
CALLED BY:
SPECTROGRAM, spectrogram__define
EXAMPLES:
SEE ALSO:
http://hessi.ssl.berkeley.edu/~csillag/idl/spectrogram_howto.html
more information in spectrogram__define
HISTORY:
20-jul-2004: documentation update
Version 1, August 21, 2003,
A Csillaghy, csillag@ssl.berkeley.edu
[Previous]
[Next]
Name: make_ssw_mirror
Purpose: generate the mirror file required for SSW install/upgrades
Input Parameters:
local_env - file name containing Environmentals to include
master_env - file with remote Environmental:directory mapping
Keyword Parameters:
mirror_file - optional user supplied name of mirror file
yohkoh - switch. If set, uses Yohkoh dbase defaults
remote_user, remote_password - optional (default=ANONYMOUS ftp)
Calls: ***
CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3], FILE_EXIST [2], concat_dir [4]
file_exist [1], file_exist [3], get_logenv [1], get_logenv [2], make_mirror
prstr [1], prstr [2], rd_tfile [1], rd_tfile [2], str_replace [1], str_replace [2]
History:
18-mar-1996 (S.L.Freeland) SSW Installation and Upgrades
21-oct-1996 (S.L.Freeland) Add /YOHOKH switch (work with pubconfig)
Input from Bob Bentley
23-oct-1996 (S.L.Freeland) Document, add remote_user, remote_password
24-oct-1996 (S.L.Freeland) Add /MODE_COPY in make_mirror call
Category:
SSW , system
Restrictions:
Assumes "SSW" or Yohkoh SW environment
[Previous]
[Next]
NAME:
MAKE_STR
PURPOSE:
Control dynamic structure building - avoids collision of
names which might result if different modules used the same
structure names and had different numbber/types of tag fields
CALLING SEQUENCE:
user_value= MAKE_STR(ustr_string [,str_name=str_name, /NOEXEC]
INPUTS:
USTR_STRING - string of form '{dummy,T1:intarr(10), T2:oL...}'
OUTPUTS:
return value = structure defined by USTR_STRING
OPTIONAL KEYWORD PARAMETERS:
STR_NAME - (Output) Structure name created
NOEXEC - If set, a unique name is allocated but no structure
is created - in this case, the return value is the
allocated name (string variable), not the structure
COMMON BLOCKS;
MAKE_STR_PRIVATE - used to generate unique names (via counter)
MAKE_STR_BLK - track previously created structures
MAKE_STR_BLK1 - flag to enable/disable structure exist checks
FILE I/O:
NONE
METHOD
uses a common block to store counter which is incremented on
each call and incorporated into the structrure name. Uses the
IDL EXECUTE statement to dynamically create the structure
CALLS: ***
STR2ARR [1], STR2ARR [2], str_checks [1], str_checks [2], strstat [1], strstat [2]
CALLED BY:
CALL_TRIWARP, CkTimeNkey, DO_TEEM, GT_CDS_QL, MERGE_STRUCT, MK_BSC_STR [1]
MK_BSC_STR [2], MkFnMapMake Filename Map, Multi_draw [1], Multi_draw [2]
RD_GEN [1], RD_GEN [2], READ_SPFDGRS, READ_SPFDHXS, SMK_FULLDET, SS2DSET, SUM_GAUSSB
WRT_GEN [1], WRT_GEN [2], aRCHsCRPT, build_str [1], build_str [2], ccd_sunc [1]
ccd_sunc [2], extract_val, fidmap, file_info [1], file_info [2], filter_os1
fitshead2struct, genx_head [1], genx_head [2], get1doc [1], get1doc [2]
get1hk_info [1], get1hk_info [2], get_elemabun [1], get_elemabun [2]
get_hk_info [1], get_hk_info [2], getmenu [1], getmenu [2], go_get_sirius
input_time [1], input_time [2], mkdirst, nn_rd2_sxt_noaa, nn_rd3_sxt_noaa
nn_rd_sxt_noaa, rd_rasm, rd_rdb [1], rd_rdb [2], rd_sumer [1], rd_sumer [2]
rd_sumer_genx, save_data [1], save_data [2], sparse [1], sparse [2], sparse [3]
str_merge [1], str_merge [2], str_subset, strpair2struct, struct2ms [1]
struct2ms [2], sxt_uniq [1], table2struct, tar_size, tim2intstr [1]
tim2intstr [2], timeavg [1], timeavg [2], tr_decode_head [1], tr_decode_head [2]
trace_bin_struct, trace_dph2struct [1], url_decode, wdefroi [3], wdefroi [4]
wfilpck, wmkkey [1], wmkkey [2], xspr [1], xspr [2], xstepper [1], xstepper [2]
MODIFICATION HISTORY:
Version 1 - SLF, 3/5/91 Samuel Freeland
Version 1.1 - SLF, 10/23/91 - added call to strstat to check for
structure existance
Version 2.0 - slf, 15-jan-93 - added 2nd common block to track
defined structures
slf, 18-jan-93 - add string compress
slf, 1-feb-93 - kludge for strings large than 512
slf, 3-feb-93 add make_str_blk for
slf, 7-feb-93 improved feb 1 upgrades
slf, 26-mar-93 use systime + counter for str names
slf, 15-jan-97 Version 5 (derivation of HOME)
richard.schwartz@gsfc.nasa.gov, 9-feb-1999.
Fix path to work on Windows and Mac, too.
Zarro (SM&A/GSFC) 25-May-99, added check for
undefined HOME and/or write access
Csillaghy (SSL/UCB) 8-Dec-1999, /QUIET keyword
to str_checks.
kim, 2-sep-2003. Instead of modifying path, cd to temp dir to
compile the temporary routine. Needed for IDL 6.0
kim, 4-sep-2003. Changed /either to /is_function for older IDL
[Previous]
[Next]
Project : SOHO-CDS
Name : MAKE_STRUCT
Purpose : a new way of creating structures
Category : structures
Explanation : uses keyword inheritance to dynamically create structures
Syntax : struct=make_struct(tagname=tagvalue)
CALLED BY:
hsi_flarelistdata_ext__define, spectrogram__define
Examples : IDL> struct=make_struct(a=1,b=findgen(100),c='test')
IDL> help,/st,struct
** Structure <40557288>, 3 tags, length=424, refs=1:
A INT 1
B FLOAT Array[100]
C STRING 'test'
Inputs : TAGNAME=TAGVALUE pair
Opt. Inputs : None
Outputs : STRUCT = created structure
Opt. Outputs: None
Keywords : NAME = structure name (def=anonymous)
CALLS: ***
DATATYPE [1], DATATYPE [2], DATATYPE [3], TRIM
Common : None
Restrictions: None
Side effects: None
History : Written 7 Jan 1998, D. Zarro, SMA/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MAKE_XY
Purpose : Make a uniform 2d X-Y grid of coordinates
Category : imaging
Syntax : make_xy,nx,ny,xp,yp
Inputs : NX,NY = X,Y dimensions
Outputs : XP,YP = 2d (X,Y) coordinates
Opt. Outputs: None
Keywords : DX, DY = grid spacing [def=1,1]
XC, YC = grid center [def=0,0]
CALLS: ***
EXIST, MK_MAP_XP, MK_MAP_YP, PR_SYNTAX
CALLED BY:
GRID_XY
History : Written 22 June 1997, D. Zarro, ARC/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
NAME:
MAKEX
PURPOSE:
Make an array with specified start, end and step values.
CATEGORY:
CALLING SEQUENCE:
x = makex(first, last, step)
INPUTS:
first, last = array start and end values. in
step = step size between values. in
KEYWORD PARAMETERS:
OUTPUTS:
x = resulting array. out
CALLED BY:
INRANGE [1], INRANGE [2], INRANGE [3], TIMEAXIS [1], TIMEAXIS [2], TIMEAXIS [3]
XPRINT [1], XPRINT [3]
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
Ray Sterner, 7 Dec, 1984.
Johns Hopkins University Applied Physics Laboratory.
Added FIX 20 Dec, 1984 to avoid roundoff error.
changed it to LONG 8 Mar, 1985 to avoid integer overflows.
Copyright (C) 1984, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
[Previous]
[Next]
Project : HESSI
Name : MAP2EARTH
Purpose : convert SOHO-view map to Earth-view
Category : imaging
Syntax : emap=map2earth(map)
Inputs : MAP = image map structure
Outputs : EMAP = remapped structure
Opt. Outputs: None
Keywords : None
CALLS: ***
MAP2L1
History : Written 18 Oct 1999, D. Zarro, SM&A/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MAP2FITS
Purpose : write image map to FITS file
Category : imaging
Syntax : map2fits,map,file
Inputs : MAP = image map structure
FILE = FITS file name
Keywords : ERR = error string
BYTE_SCALE = byte scale data
CALLS: ***
BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3], BSCALE, COMP_FITS_CRPIX
CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3], DATATYPE [1], DATATYPE [2]
DATATYPE [3], FXADDPAR [1], FXADDPAR [2], FXHMAKE [1], FXHMAKE [2], FXWRITE [1]
FXWRITE [2], PR_SYNTAX, TAG_EXIST [1], TAG_EXIST [2], TEST_OPEN, TRIM, UNPACK_MAP
VALID_MAP, break_file [4], concat_dir [4]
History : Written 22 August 1997, D. Zarro, SAC/GSFC
Version 2, 11-Jul-2003, William Thompson, GSFC
Write both DATE_OBS and DATE-OBS
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MAP2GIF
Purpose : make series of GIF images from series of maps
Category : imaging
Syntax : map2gif,map,names
Inputs : MAP = array of map structures
NAMES = array of output GIF names [def = framei.gif]
Keywords : DRANGE = [dmin,dmax], min and max values to scale data
SIZE = [min,max], dimensions of MPEG movie (def= [512,512])
PREFIX = If NAMES isn't provided, then gif file names will be
prefixnn.gif where nn is the image number
NOSCALE = If set, don't scale to min/max of all images (def=0)
STATUS = Returns 0/1 for failure/success
CALLS: ***
DATATYPE [1], DATATYPE [2], DATATYPE [3], DPRINT, EXIST, PLOT_MAP, PR_SYNTAX
SSW_WRITE_GIF, STR_FORMAT, TEST_DIR, TRIM, VALID_MAP, curdir [1], curdir [2]
History : Written 11 Jan 2000, D. Zarro, SM&A/GSFC
Version 2, 13-Aug-2003, William Thompson
Use SSW_WRITE_GIF instead of WRITE_GIF
10-Feb-2005, Kim Tolbert. Corrected !p.colors->!p.color, added
noscale and status keywords
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Name: map2index
Purpose: convert D.M.Zarro map object(s) to "standard index,data"
Input Parameters:
map - an image map or map array
index (optional) - the original index record (will be updated)
Note: if MAP includes INDEX property, that is used preferentially
Output Parameters:
index - IDL structure(s) with "standard" tags derived from map
If map.INDEX exists, that is starting template
ELSE if INDEX is INPUT, that is starting template
ELSE ssw standard structure template is used
data - 2D or 3D MAP data array(s)
Calling Sequence:
IDL> map2index, map, index , data
IN , IN/OUT , OUT
(opt.inp)
Context Sequence Example:
IDL> mreadfits, <files> , index, data ; files->index,data
IDL> [optional data scaling/processing] ; whatever...
IDL> index2map, index, data, maps ; index,data->maps
IDL> [map manip; drot_map, sub_map...] ; mapping SW
IDL> map2indx, newmaps,(new)index,newdata ; newmaps->index,data
IDL> mwritefits, newindex, newdata ; index,data->files
Note: mreadfits may be replaced by 'read_xxx'
History:
9-April-1998 - S.L.Freeland using struct2ssw & D.M. Zarro unpack_map
3-March-2000 - S.L.Freeland - revised (made it work!)
Use XCEN/YCEN centric and call to struct2ssw
4-March-2000 - S.L.Freeland - cont. 3-mar enhancments
add CROTA and (opt CROTACEN if it exists)
18-Dec-2002 - Zarro (EER/GSFC), changed ROLL -> ROLL_ANGLE and
converted some execute statements
CALLS: ***
COMP_FITS_CRPIX, PR_SYNTAX, STR2ARR [1], STR2ARR [2], TAG_EXIST [1], TAG_EXIST [2]
UNPACK_MAP, VALID_MAP, anytim [1], anytim [2], anytim [3], anytim [4], anytim [5]
data_chk [1], data_chk [2], gt_tagval [1], gt_tagval [2], sswfits_struct [1]
sswfits_struct [2], struct2ssw
Side Effects:
If INDEX is defined on INPUT , it is assumed to contain
the original INDEX - Fields associated with the input MAP
will be updated (clobbered if you want to put it that way)
to reflect rotation, pointing, time, binning map changes.
In conjunction with 'index2map.pro', this rotuine permits:
index,data(original) -> map(manipulations) -> index,data(new)
-> map via index2map -> [drot_map/sub_map...] -> via map2index
[Previous]
[Next]
Project : SOHO-CDS
Name : MAP2JPEG
Purpose : make series of JPEG images from series of maps
Category : imaging
Syntax : map2jpeg,map,names
Inputs : MAP = array of map structures
NAMES = array of output JPEG names [def = framei.jpeg]
Keywords : DRANGE = [dmin,dmax], min and max values to scale data
SIZE = [min,max], dimensions of JPEGs (def= [512,512])
PREFIX = If NAMES isn't provided, then jpeg file names will be
prefixnn.jpeg where nn is the image number
NOSCALE = If set, don't scale to min/max of all images (def=0)
STATUS = Returns 0/1 for failure/success
CALLS: ***
CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3], DATATYPE [1], DATATYPE [2]
DATATYPE [3], DPRINT, EXIST, FILE_BREAK, MK_24BIT, PLOT_MAP, PR_SYNTAX, STR_FORMAT
TEST_DIR, TRIM, VALID_MAP, concat_dir [4], curdir [1], curdir [2], prstr [1]
prstr [2]
CALLED BY:
HESSI IMAGE STRATEGY CLASS DEFINITION, hsi_image__getaxis [2]
History : Written 11 Jan 2000, D. Zarro, SM&A/GSFC
10-Feb-2005, Kim Tolbert. Corrected !p.colors->!p.color, added
noscale and status keywords
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MAP2L1
Purpose : convert EARTH-view image map to L1-view
Category : imaging
Syntax : lmap=map2l1(map)
Inputs : MAP = image map structure
Outputs : LMAP = remapped structure
Keywords : INVERSE = set to map SOHO to EARTH-view
PARTIAL = set to correct offset pointing for partial frame
images
CALLS: ***
DPRINT, EXIST, GET_MAP_PROP, VALID_MAP, soho_fac
CALLED BY:
MAP2EARTH, MAP2SOHO
History : Written 17 October 1999, D. Zarro, SM&A/GSFC
Modified 23 February 2005, Zarro (L-3Com/GSFC) - added /partial
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MAP2MPEG
Purpose : make MPEG movie from series of maps
Category : imaging
Syntax : map2mpeg,map,file
Inputs : MAP = array of map structures
FILE = MPEG file name
Keywords : DRANGE = [dmin,dmax], min and max values to scale data
SIZE = [min,max], dimensions of MPEG movie (def= [512,512])
NOSCALE = If set, don't scale to min/max of all images (def=0)
STATUS = Returns 0/1 for failure/success
CALLS: ***
BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3], DATATYPE [1], DATATYPE [2]
DATATYPE [3], EXIST, HAVE_PROC, MK_24BIT, MPEG_CLOSE, MPEG_OPEN, MPEG_PUT, MPEG_SAVE
PLOT_MAP, PR_SYNTAX, TEST_DIR, TRIM, VALID_MAP, break_file [4], curdir [1], curdir [2]
CALLED BY:
HESSI IMAGE STRATEGY CLASS DEFINITION, hsi_image__getaxis [2]
History : Written 11 Jan 2000, D. Zarro, SM&A/GSFC
Modified 1 Dec 2004, Zarro (L-3Com/GSFC)
- made compression quality default to 100.
10-Feb-2005, Kim Tolbert. Added noscale and status keywords, and added
catch error handler to reset device and close mpeg if error.
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : HESSI
Name : MAP2SOHO
Purpose : convert Earth-view map to SOHO-view
Category : imaging
Syntax : smap=map2soho(map)
Inputs : MAP = image map structure
Outputs : SMAP = remapped structure
Opt. Outputs: None
Keywords : None
CALLS: ***
MAP2L1
History : Written 18 Oct 1999, D. Zarro, SM&A/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO - CDS
Name : MAP2WCS
Purpose : Convert a SolarSoft image map into a WCS structure.
Category : FITS, Coordinates, WCS, Image-processing
Explanation : Converts a SolarSoft image map structure to a WCS structure.
Syntax : MAP2WCS, MAP, WCS
Inputs : MAP = SolarSoft image map structure.
Opt. Inputs : None.
Outputs : WCS = World Coordinate System structure
Opt. Outputs: None.
Keywords : None.
Calls : ***
ADD_TAG [1], ADD_TAG [2], ANYTIM2TAI, ANYTIM2UTC [1], ANYTIM2UTC [2], PB0R, TIM2CARR
VALID_MAP
Common : None.
Restrictions: None.
Side effects: None.
Prev. Hist. : None.
History : Version 1, 15-Apr-2005, William Thompson, GSFC
Version 2, 02-Mar-2006, William Thompson, GSFC
Changed test for get_orbit.pro
Contact : WTHOMPSON
[Previous]
[Next]
Project : HESSI
Name : MAP__DEFINE
Purpose : Define a MAP object
Category : imaging objects
Syntax : IDL> new=obj_new('map')
CALLS: ***
ADD_METHOD, ADD_TAG [1], ADD_TAG [2], ANYTIM2UTC [1], ANYTIM2UTC [2]
BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3], CHMOD, COMP_FITS_CRPIX
CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3], CONGRID [1], CONGRID [2]
CONGRID [3], DPRINT, DROT_MAP, ESPAWN, EXIST, FILE_BREAK, FIX_EXTRA, GET_FITS_PAR
HAVE_TAG, IS_BLANK, IS_STRING, JOIN_STRUCT [1], JOIN_STRUCT [2], MAKE_MAP
MAP::CLEANUP, MAP::CLONE, MAP::CLONE, MAP::DRANGE, MAP::DROTATE, MAP::DROTATE
MAP::EARTH_CORRECT, MAP::EMPTY, MAP::EXTRACT, MAP::EXTRACT, MAP::FITSWRITE
MAP::FITS_MAP, MAP::FITS_WRITTEN, MAP::GET, MAP::GETDATA, MAP::GET_MAP_PROP
MAP::GET_SOLRAD, MAP::HAS_DATA, MAP::HAS_HISTORY, MAP::HAS_INDEX, MAP::INIT
MAP::LOAD_CT, MAP::MK_MAP, MAP::PLOT, MAP::ROLL_CORRECT, MAP::ROLL_CORRECTED
MAP::ROTATE, MAP::ROTATE, MAP::SAVE_CT, MAP::SET, MAP::SETMAP, MAP::UPDATE_HISTORY
MAP::UPDATE_INDEX, MAP::WRITE, MAP::XP, MAP::XRANGE, MAP::YP, MAP::YRANGE
MAP::ZERO_LIMB, MK_MAP_XP, MK_MAP_YP, MRD_HEAD, OBJ_COPY, PB0R, PLOT_MAP, PTR_EXIST
REP_TAG_VALUE, ROT_FITS_HEAD, ROT_MAP, SUB_MAP, TRIM, TRIM2, VALID_MAP, VALID_OMAP
WRITEFITS [1], WRITEFITS [2], WRITE_DIR, break_file [4], concat_dir [4]
curdir [1], curdir [2], get_uniq, is_number [1], is_number [2], is_struct
rem_blanks, soho_fac, struct2fitshead
History : Written 22 Nov 1999, D. Zarro, SM&A/GSFC
: Modified 18 Sept 2001, D. Zarro (EITI/GSFC) - improved
memory management
Modified 5 Oct 2002, Zarro (LAC/GSFC) - added object
to store plot properties
Modified 2 Oct 2003, Zarro (GSI/GSFC) - added correction
for 180 degree rolled images
Modified 7 Feb 2004, Zarro (L-3Com/GSFC) - fixed bug with
plotting grid/limb
Modified 17 Mar 2004, Zarro (L-3Com/GSFC) - added FOV keyword
Modified 9 May 2006, Zarro (L-3Com/GSFC) - added COLOR support
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
NAME:
MAP_CARRINGTON.PRO
PURPOSE:
Project a solar image onto an area preserving longitude,SIN(latitude)
cylindrical map. The projection is referred to as a Lambert
projection in geographic literature and as a Carrington projection
in heliographic work. Meridians and latitude lines are perpendicular
the output image.
Preserves pixel scale so it returns an image that may be
substantially larger than the input image if the input image
is near the limb.
Assumes the Sun is a sphere and that image is oriented solar-north
(P angle = 0).
CATEGORY: mapping
CALLING SEQUENCE:
image = map_carrington(image,xycen,date,ps)
INPUTS:
IMAGE = image to be mapped onto a cylindrical projection
XYCEN = FLTARR(2): E/W & N/S arcsecond angle of image center from Solar
disk center. W and N are positive.
DATE = date of image in any of the accepted CDS date forms
PS = platescale: arcseconds/pixel image scale.
XYREF = LONARR[2], coordinates of a reference point in the original
image. If provided, the point is returned as the coordinates
in the remapped image. Useful for keeping track of a
sunspot, etc.
OPTIONAL INPUT PARAMETERS:
KEYWORD PARAMETERS:
PHIK = latitude of unity linear scale in cylindrical equal area
projection, in degrees. See "Map Projections" by Bugayevskiy and
Snyder, Ch. 2.
OUTPUTS:
Warped image using cubic interpolation in POLY_2D. Note that the
platescale of the warped image is the same as the input image. This
means that the warped image may be substantially larger in format
than the original, especially for near-limb images.
CALLS: ***
POLYWARP, get_rb0p [1], get_rb0p [2]
COMMON BLOCKS:
SIDE EFFECTS:
RESTRICTIONS:
Assumes image is oriented with Solar North UP.
Does not remap any pixels that are off the limb of the
Sun for the date given.
PROCEDURE:
EXAMPLE:
for TRACE images:
IDL> read_trace,filename,-1,index,image
IDL> traceplate = 0.4993 ;arcsec per pixel
IDL> warp_image =
map_carrington(image,[index.xcen,index,ycen],index.date,traceplate)
MODIFICATION HISTORY:
Written by Tom Berger, LMSAL, 8.13.02
Added reference point capability, TEB 8.16.02
Doc header only (syntax due to bad comment wraparound), SLFreeland 6-feb-2006
[Previous]
[Next]
Name: map_env2dir
Purpose: make file which maps between environmentals and local pathnames
Input Parameters:
NONE:
Keyword Parameters:
filter (in/out) - environmental filter to use (ex: 'SSW*')
envfile (in) - name of environmental file
Enivironmental files may be in one of two forms:
1) - simple list of environmentals
# commments ok
DIR_GEN_SHOWPIX
DIR_GEN_G71 # partial comments ok
2) - #!/bin/csh -f
# script file (setenv or define)
setenv DIR_GEN_SHOWPIX /ydb/showpix
setenv DIR_GEN_G71 /yd2/g71 # partial comments ok
mapfile (out) - optional output file name
mapfile format (read with rd_tfile(mapfile,2,/nocomment)
# [header section /system info]
# ....
Env1 Path1
Env2 Path2
EnvN PathN
Calling Sequence:
map_env2dir, envs, dirs, filter='envfilter'
map_env2dir, outarr, envfile=envfile
USE:
On SW master - map envs to master directory - (map files are distributed)
On local machine - map local env list to local pathnames
Together - generate auto-distribution mappings - for example,
generate MIRROR packages to run on local machine.
CALLS: ***
FILE_EXIST [2], data_chk [1], data_chk [2], file_append [1], file_append [2]
file_exist [1], file_exist [3], get_logenv [1], get_logenv [2], pr_status [1]
pr_status [2], rd_tfile [1], rd_tfile [2], str2cols [1], str2cols [2]
str_replace [1], str_replace [2], strjustify, strnocomment
History:
18-march-1996 (S.L.Freeland)
[Previous]
[Next]
Project : HESSI
Name : MAP_LIST__DEFINE
Purpose : Define a map linkedlist
Category : imaging objects
Syntax : IDL> new=obj_new('map_list')
CALLS: ***
DPRINT, IPRINT, MAP_LIST::ADD_MAP, MAP_LIST::CLEANUP, MAP_LIST::EARTH_VIEW
MAP_LIST::GETDATA, MAP_LIST::HAS_DATA, MAP_LIST::INIT, MAP_LIST::PLOT
MAP_LIST::ROTATE, MAP_LIST::TIMES, MAP_LIST::WRITE, TRIM, VALID_OMAP
is_number [1], is_number [2]
History : Written 22 Apr 2000, D. Zarro, SM&A/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
PROJECT:
SDAC
Name:
MAP_MATRIX
Purpose:
This procedure creates a linear transformation matrix between two data binnings.
CALLED BY:
HXT_CAL_FIX [1], HXT_CAL_FIX [2]
Procedure:
This procedure creates a linear transformation matrix which can be used
to rebin vector data such as count rates defined on a PHA scale.
It takes a matrix with n output bins defined on energy edges EDGE1, (n+1)
and create a transform, MAP, to interpolate a detector response, MATRIX1, from
narrow channels to broader output channels defined by EDGE2. The matrix
is defined in terms of counts/channel unless the keyword FLUX is set.
This operation is sometimes called flux rebinning. Matrix2 is generally
a matrix with mostly zeroes and can be easily represented with a sparse matrix
if the matrix is square.
for a bin defined on EDGE1 which falls wholly within a bin on EDGE2
the map matrix element is 1
for a bin defined on EDGE1 which falls partially within a bin on EDGE2
the map matrix element is given by the fraction of BIN1 contained by BIN2
Category:
GEN, SPECTRUM, UTILITY,
Calling Sequence:
MAP_MATRIX, Edge1, Matrix1, Edge2, Map, Matrix2
Inputs:
Edge1: N+1 energy edges of N output bins or 2xN energy edges
Matrix1: Response matrix N output bins, M input bins
Output rows in Counts/bin (NOT Counts/keV)
Edge2: K+1 output energy edges for new matrix, or 2xK edges
Outputs:
Map: The linear transform from input response, MATRIX1, to output MATRIX2
i.e. matrix2 = map # matrix1
Matrix2: New response matrix with K output bins, M input bins
Rows in Counts/bin
Keywords:
FLUX- Map operates on vectors in flux units, i.e. scaled by the
width of the channels.
CALLS: ***
F_DIV, edge_products
Restrictions:
This is not an optimized procedure
History:
Version 1, RAS, 9 Aug 93
Version 2, RAS, 24-apr-1996, allowed 2xN energy edges
Version 3, richard.schwartz@gsfc.nasa.gov, 7-sep-1997, more documentation
[Previous]
[Next]
DUMMY PROCEDURE - ONLY EXISTS TO GET YOPOS TO COMPILE
UNDER IDL VERSIONS < 4
WRITTEN Barry LaBonte July 21, 1995
CALLED BY
yopos [1], yopos [2]
[Previous]
[Next]
PROJECT:
SSW
NAME:
MAP_XYMOMENTS
PURPOSE:
Computes the centroid and standard deviation
along x and y (rows and columns) of a map distribution.
CATEGORY:
Math, Util
CALLING SEQUENCE:
map_xymoments, map, xaxis, yaxis, centroid, stdev
CALLS:
none
INPUTS:
Map- 2d array of map intensities
Xaxis - positions of pixels along first dimension of Map
Yaxis - positions of pixels along second dimension of Map
;
OPTIONAL INPUTS:
none
OUTPUTS:
Centroid - returns 2 element array of centroid along x and y
in the coordinates of xaxis and yaxis
Stdev - returns 2 element array of standard deviation along
x and y in the coordinates of xaxis and yaxis.
OPTIONAL OUTPUTS:
none
KEYWORDS:
none
COMMON BLOCKS:
none
SIDE EFFECTS:
none
RESTRICTIONS:
none
PROCEDURE:
Straighforward application of the definitions of mean and standard
deviations of the moments of a distribution
MODIFICATION HISTORY:
Version 1, richard.schwartz@gsfc.nasa.gov,
[Previous]
[Next]
Name:mapx
Purpose: hide/show map/unmap sensitize/desensitize widgets
Input Parameters:
ids - widget id(s) to map/show - longword vector or scaler
show - vector or scaler show parameter
map=map - vector or scaler map parameter
sensitive=sensitive - vector or scaler sensitive parameter
All parameters default to OFF (unmap, hide, desensitize)
CALLED BY:
get_hk_mnem, goes_widget, show_pix [1], show_pix [2], show_pix_event [1]
show_pix_event [2], show_pix_event [3], xanal_emi, xcheckip, xdisp_fits
xdisp_sci5k, xdisp_tfr, xdisp_trace [1], xdisp_trace2, xdisp_trace3, xhkplot
xread_hist, xsearch_obs, xset_chain [1], xset_chain [2], xspr [1], xspr [2]
xstep_uevent [1], xstep_uevent [2], xstepper [1], xstepper [2], xstepper_event
xsw2tree, xsw2tree_event, xswlist [2], xsxt_prep_event
History: slf, 7/91
slf, 2-8-92 - added sensitive parameter
allow vectors for parameters
slf, 31-oct-93 - added bad_id=destroyed
[Previous]
[Next]
Name: mark_intervals
Purpose: Mark events on a time plot
Calling sequence:
mark_intervals, stimes, etimes, label=label, n_bar=n_bar
Method:
For each start/end interval a thick colored bar is drawn at the top of the plot
for the duration of the interval. If start/end is -1, then the bar extends for
the entire x range. The label is placed to the right or left of the line depending
on where the line is on the plot. n_bar is both an input and output keyword.
It keeps track of how many bars are already drawn to decide how far down from
the top (or bottom) of the plot to draw the next bar.
Input arguments:
stimes,etimes - start, end times of intervals. If start[i]=-1 then the condition
applies to the entire plot interval
Input keyword arguments:
label - very short (like 1 or 2 letters) string to identify bar (like N for night)
color - color of bar
charsize - character size for label
n_bar - number of bars drawn on plot so far (also an output parameter after being
incremented)
longline - if set, draw lines the full y width of plot in addition to drawing bars
bottom - if set, draw bars at bottom of plot (top is default)
Output keyword arguments:
n_bar - (also input). n_bar is incremented and returned for potential use in
another call to mark_intervals. Total number of bars drawn on plot so far.
Modifications:
Written: 4-Mar-2002, Kim Tolbert.
15-May-2002 - Kim, for log plots, check that ycrange is OK (for GOES plots, where !y.crange is
not returned as log of limits, but the limits themselves)
27-May-2002 - Kim, show label only on first interval when multiple intervals on same level
20-Sep-2002 - Kim. Save !p.nsum, set to 1, and restore original value on exit.
19-Jan-2005 - Kim. Thick=2.6 isn't thick when drawing to the Z buffer in 6.1 (??), so
make it thicker in that case
CALLS:
CALLED BY
hsi_show_flags [2], spex_draw_bars
[Previous]
[Next]
Project : RHESSI
Name : MARK_POINT
Purpose : mark a point at a specified position on an existing plot
Category : display
Syntax : IDL> mark_point,mark_point
Inputs : MARK_POINT=[X,Y] = data coordinates at which to plot point
Outputs : None
Keywords : None
CALLS: ***
EXIST, arrow2, draw_circle [1], draw_circle [2], draw_circle [3]
CALLED BY:
PLOT_MAP
History : Written 26 December 2002, Zarro (EER/GSFC), based on Kim's earlier version
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
PROJECT: HESSI
NAME: mark_poly
PURPOSE: draw polygon
CATEGORY: display
CALLING SEQUENCE:
xy = mark_poly (widget_id, color=color, $
device=device, data=data, normal=normal, event=event)
INPUTS:
widget_id - widget id of draw widget
OPTIONAL INPUTS (KEYWORDS):
color - color index to draw with
device - if set returns vertices in device coordinates
data - if set returns vertices in data coordinates
normal - if set returns vertices in normal coordinates
event - draw window left click event that has already occurred, e.g. user
has already left clicked in draw widget, and this position should
be used as starting position for polygon
OUTPUTS:
Result of function is fltarr(2,n) where
xy(0,*) are x coordinates of vertices
xy(1,*) are y coordinates of vertices
OPTIONAL OUTPUTS: None
Calls: ***
APPEND_ARR, CHECKVAR [1], MARK_POLY_EVENT, checkvar [2]
COMMON BLOCKS: None
PROCEDURE:
RESTRICTIONS: Requires that window be a draw widget
SIDE EFFECTS: None.
EXAMPLES:
HISTORY:
Written, Kim Tolbert, April 22, 2001
[Previous]
[Next]
Project : SDAC
Name : MARK_REGION
Purpose : This procedure selects an interval from a plot window.
Category : UTIL, GEN, GRAPHICS
Explanation : The cursor is used to interactively select an x range.
Use : MARK_REGION, Start, Endr
Inputs : None
Opt. Inputs : None
Outputs : Start- Time in seconds from plot basetime
Endr - Time in seconds from plot basetime
Opt. Outputs: None
Keywords : WMESSAGE- a message to appear in a text widget as in GOES
Calls : ***
CROSSBAR [1], CROSSBAR [2], GRAPHICS_PAGE, XDEVICE
CALLED BY:
Y_AVERAGE [1], Y_AVERAGE [2]
Common : None
Restrictions:
Side effects: None.
Prev. Hist : UNKNOWN
Modified : Version 2, Documented, 29-jan-1997
Version 3, richard.schwartz 13-nov-1999. Fixed for windows and Mac.
Contact : richard.schwartz@gsfc.nasa.gov
[Previous]
[Next]
Name: markplot
Purpose: highlight features on plot (default is open crosshair)
Input Parameters:
dpix - distance from marked poition to start highlinght (def=10 pix)
(for /box, dpix=box half-width, for /circle, dpix= circle radius)
npix - length of highlight from dpix (only used for open crosshair)
Keyword Parameters:
box - if set, draw a box of diameter=2*dpix
circle - if set, draw a circle of radius=dpix
plus - if set, draw a plussign of length=2*dpix
Calling Sequence:
markplot [,dpix [,npix , /uselast , color=color, thick=thick, $
/box , /circle ]]
Calling Examples:
markplot ; open crosshair at cursor
markplot,15,/box,thick=2 ; 15x15 box at cursor.
markplot,5, /plus ; 10 pix long plussign at cursor
for i=5,55,10 do markplot,i,/uselast,/circle ; uselast & circle
for i=5,55,10 do markplot,i,/uselast,/box ; demo uselast & box
History:
10-Nov-1993 (SLF)
2-nov-1994 (SLF) add keyword inheritance - add PLUS keyword, document
Restrictions:
Uses keyword inheritance which was not introduced until IDL V3.2.
[Previous]
[Next]
PROJECT:
SOHO - CDS/SUMER
NAME:
MASK_MATRIX()
PURPOSE:
Create a mask matrix for image manipulation
CATEGORY:
EXPLANATION:
This function routine can be used for creating an interleave
(i.e., checkerboard) or an interlace mask matrix.
SYNTAX:
Result = mask_matrix()
CALLED BY:
ITOOL_COMPOSITE
EXAMPLES:
INPUTS:
M - The first dimension of the matrix
N - The second dimension of the matrix
OPTIONAL INPUTS:
None.
OUTPUTS:
RESULT - An MxN integer mask matrix
OPTIONAL OUTPUTS:
None.
KEYWORDS:
FIRST - If set, value of the first pixel is 1, otherwise 0
INTERLEAVE - Make interleave mask matrix. This is default if
there is no other keyword being set
XINTERLACE - Make X-direction interlaced mask matrix
YINTERLACE - Make Y-direction interlaced mask matrix
Note: Only one of above keywords can be set at a time.
ERROR - A named keyword variable that contains error message;
a null string is returned if no error occurs
COMMON:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
HISTORY:
Version 1, October 27, 1995, Liyun Wang, GSFC/ARC. Written
CONTACT:
Liyun Wang, GSFC/ARC (Liyun.Wang.1@gsfc.nasa.gov)
[Previous]
[Next]
NAME:
MATCH
PURPOSE:
Routine to match values in two vectors.
CALLING SEQUENCE:
match, a, b, suba, subb, [ COUNT =, /SORT ]
INPUTS:
a,b - two vectors to match elements, numeric or string data types
OUTPUTS:
suba - subscripts of elements in vector a with a match
in vector b
subb - subscripts of the positions of the elements in
vector b with matchs in vector a.
suba and subb are ordered such that a[suba] equals b[subb]
OPTIONAL INPUT KEYWORD:
/SORT - By default, MATCH uses two different algorithm: (1) the
/REVERSE_INDICES keyword to HISTOGRAM is used for integer data,
while a sorting algorithm is used for non-integer data. The
histogram algorithm is usually faster, except when the input
vectors are sparse and contain very large numbers, possibly
causing memory problems. Use the /SORT keyword to always use
the sort algorithm.
OPTIONAL KEYWORD OUTPUT:
COUNT - set to the number of matches, integer scalar
CALLED BY:
COPY_STRUCT [1], COPY_STRUCT [2], COPY_STRUCT [3], COPY_STRUCT_INX
DBFIND_SORT [1], DBFIND_SORT [2], DBFIND_SORT [3], GET_BSA_ANS [1]
GET_BSA_ANS [2], GET_PLAN_FUNCT, MATCH_STRUCT, MOVIE_MAP, MRDFITS [1], MRDFITS [2]
SHOW_SYNOP__DEFINE, SMK_FULLDET, SSEL_DATCOL, hsi_getflare, hsi_ui_flarecat
plot_bda, trace_movies_prioritize [1], trace_movies_prioritize [2]
SIDE EFFECTS:
The obsolete system variable !ERR is set to the number of matches;
however, the use !ERR is deprecated in favor of the COUNT keyword
RESTRICTIONS:
The vectors a and b should not have duplicate values within them.
You can use rem_dup function to remove duplicate values
in a vector
EXAMPLE:
If a = [3,5,7,9,11] & b = [5,6,7,8,9,10]
then
IDL> match, a, b, suba, subb, COUNT = count
will give suba = [1,2,3], subb = [0,2,4], COUNT = 3
and suba[a] = subb[b] = [5,7,9]
METHOD:
For non-integer data types, the two input vectors are combined and
sorted and the consecutive equal elements are identified. For integer
data types, the /REVERSE_INDICES keyword to HISTOGRAM of each array
is used to identify where the two arrays have elements in common.
HISTORY:
D. Lindler Mar. 1986.
Fixed "indgen" call for very large arrays W. Landsman Sep 1991
Added COUNT keyword W. Landsman Sep. 1992
Fixed case where single element array supplied W. Landsman Aug 95
Converted to IDL V5.0 W. Landsman September 1997
Use a HISTOGRAM algorithm for integer vector inputs for improved
performance W. Landsman March 2000
Work again for strings W. Landsman April 2000
Use size(/type) W. Landsman December 2002
Work for scalar integer input W. Landsman June 2003
[Previous]
[Next]
NAME:
MATCH
PURPOSE:
Routine to match values in two vectors.
CALLING SEQUENCE:
match, a, b, suba, subb, [ COUNT =, /SORT ]
INPUTS:
a,b - two vectors to match elements, numeric or string data types
OUTPUTS:
suba - subscripts of elements in vector a with a match
in vector b
subb - subscripts of the positions of the elements in
vector b with matchs in vector a.
suba and subb are ordered such that a[suba] equals b[subb]
OPTIONAL INPUT KEYWORD:
/SORT - By default, MATCH uses two different algorithm: (1) the
/REVERSE_INDICES keyword to HISTOGRAM is used for integer data,
while a sorting algorithm is used for non-integer data. The
histogram algorithm is usually faster, except when the input
vectors are sparse and contain very large numbers, possibly
causing memory problems. Use the /SORT keyword to always use
the sort algorithm.
OPTIONAL KEYWORD OUTPUT:
COUNT - set to the number of matches, integer scalar
CALLED BY:
COPY_STRUCT [1], COPY_STRUCT [2], COPY_STRUCT [3], COPY_STRUCT_INX
DBFIND_SORT [1], DBFIND_SORT [2], DBFIND_SORT [3], GET_BSA_ANS [1]
GET_BSA_ANS [2], GET_PLAN_FUNCT, MATCH_STRUCT, MOVIE_MAP, MRDFITS [1], MRDFITS [2]
SHOW_SYNOP__DEFINE, SMK_FULLDET, SSEL_DATCOL, hsi_getflare, hsi_ui_flarecat
plot_bda, trace_movies_prioritize [1], trace_movies_prioritize [2]
SIDE EFFECTS:
The obsolete system variable !ERR is set to the number of matches;
however, the use !ERR is deprecated in favor of the COUNT keyword
RESTRICTIONS:
The vectors a and b should not have duplicate values within them.
You can use rem_dup function to remove duplicate values
in a vector
EXAMPLE:
If a = [3,5,7,9,11] & b = [5,6,7,8,9,10]
then
IDL> match, a, b, suba, subb, COUNT = count
will give suba = [1,2,3], subb = [0,2,4], COUNT = 3
and a[suba] = b[subb] = [5,7,9]
METHOD:
For non-integer data types, the two input vectors are combined and
sorted and the consecutive equal elements are identified. For integer
data types, the /REVERSE_INDICES keyword to HISTOGRAM of each array
is used to identify where the two arrays have elements in common.
HISTORY:
D. Lindler Mar. 1986.
Fixed "indgen" call for very large arrays W. Landsman Sep 1991
Added COUNT keyword W. Landsman Sep. 1992
Fixed case where single element array supplied W. Landsman Aug 95
Converted to IDL V5.0 W. Landsman September 1997
Use a HISTOGRAM algorithm for integer vector inputs for improved
performance W. Landsman March 2000
Work again for strings W. Landsman April 2000
Use size(/type) W. Landsman December 2002
Work for scalar integer input W. Landsman June 2003
Assume since V5.4, use COMPLEMENT to WHERE() W. Landsman Apr 2006
[Previous]
[Next]
Project : SDAC
Name : MATCH_STRUCT
Purpose : check if two structures are identical
Explanation : cross-checks type and value of each field
Use : STATUS=MATCH_STRUCT(STRUCT1,STRUCT2)
Inputs : S1, S2 = input structures
Opt. Inputs : None.
Outputs : STATUS = 1/0 is input structure are/are not identical
Opt. Outputs: None.
Keywords : TAG_ONLY = set to check if only tags are the same
FLOATING = do checks in floating point
BLANK = treat string blanks as valid characters
TYPE_ONLY = set to check if datatype of each tag
is the same (values are not checked)
EXCLUDE = tags to exclude (e.g [1,3,4] or [tag1,tag2..])
INCLUDE = tags to include
SENSITIVE = make string matches case sensitive
DTAG = tag name where first difference is found
Category : Structure handling
Prev. Hist. : None.
Written : Dominic Zarro (ARC/GSFC)
Modified : To handle arrays of strings. CDP, 27-Feb-95
Removed redundant string check. DMZ, 1-March-95
Fixed subtle array bug that lurked for 6 years
(Zarro EITI,March 2001)
CALLS:
CALLED BY
ADD_ANOMALY, COMBINE_STRUCT, CONCAT_STRUCT, EIS_IMAGE_TOOL [1]
EIS_IMAGE_TOOL [2], EIS_IMAGE_TOOL_EVENT [1], EIS_IMAGE_TOOL_EVENT [2]
HSI_SAME_DATA, IMAGE_TOOL, IMAGE_TOOL_EVENT, ITOOL_OVERLAYER, MERGE_STRUCT
MK_CDS_PLAN, MK_PLAN_COMP, MK_SOHO, REP_STRUCT_NAME, SAME_DATA [1], SAME_DATA [2]
SAME_DATA2, UPDATE_CAMPAIGN, WHERE_STRUCT, WRITE_ANOMALY, WRITE_MONTH_CAT, XCAMP
XCAT, XCFIT_BLOCK, XCPT, XPORT, XPS_SETUP, XREPORT_EDIT, db_gbo, ihy_db
spectral_ratio [1], spectral_ratio [2]
[Previous]
[Next]
NAME:
MAX_ENTROPY
PURPOSE:
Deconvolution of data by Maximum Entropy analysis, given the PSF
EXPLANATION:
Deconvolution of data by Maximum Entropy analysis, given the
instrument point spread response function (spatially invariant psf).
Data can be an observed image or spectrum, result is always positive.
Default is convolutions using FFT (faster when image size = power of 2).
CALLING SEQUENCE:
for i=1,Niter do begin
Max_Entropy, image_data, psf, image_deconv, multipliers, FT_PSF=psf_ft
INPUTS:
data = observed image or spectrum, should be mostly positive,
with mean sky (background) near zero.
psf = Point Spread Function of instrument (response to point source,
must sum to unity).
deconv = result of previous call to Max_Entropy,
multipliers = the Lagrange multipliers of max.entropy theory
(on first call, set = 0, giving flat first result).
OUTPUTS:
deconv = deconvolution result of one more iteration by Max_Entropy.
multipliers = the Lagrange multipliers saved for next iteration.
OPTIONAL INPUT KEYWORDS:
FT_PSF = passes (out/in) the Fourier transform of the PSF,
so that it can be reused for the next time procedure is called,
/NO_FT overrides the use of FFT, using the IDL function convol() instead.
/LINEAR switches to Linear convergence mode, much slower than the
default Logarithmic convergence mode.
LOGMIN = minimum value constraint for taking Logarithms (default=1.e-9).
EXTERNAL CALLS:
function convolve( image, psf ) for convolutions using FFT or otherwise.
METHOD:
Iteration with PSF to maximize entropy of solution image with
constraint that the solution convolved with PSF fits data image.
Based on paper by Hollis, Dorband, Yusef-Zadeh, Ap.J. Feb.1992,
which refers to Agmon, Alhassid, Levine, J.Comp.Phys. 1979.
A more elaborate image deconvolution program using maximum entropy is
available at
http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/image/image_deconvolve.pro
CALLS: ***
CONVOLVE
HISTORY:
written by Frank Varosi at NASA/GSFC, 1992.
Converted to IDL V5.0 W. Landsman September 1997
[Previous]
[Next]
NAME:
MAX_LIKELIHOOD
PURPOSE:
Maximum likelihood deconvolution of an image or a spectrum.
EXPLANATION:
Deconvolution of an observed image (or spectrum) given the
instrument point spread response function (spatially invariant psf).
Performs iteration based on the Maximum Likelihood solution for
the restoration of a blurred image (or spectrum) with additive noise.
Maximum Likelihood formulation can assume Poisson noise statistics
or Gaussian additive noise, yielding two types of iteration.
CALLING SEQUENCE:
for i=1,Niter do Max_Likelihood, data, psf, deconv, FT_PSF=psf_ft
INPUTS PARAMETERS:
data = observed image or spectrum, should be mostly positive,
with mean sky (background) near zero.
psf = Point Spread Function of the observing instrument,
(response to a point source, must sum to unity).
INPUT/OUTPUT PARAMETERS:
deconv = as input: the result of previous call to Max_Likelihood,
(initial guess on first call, default = average of data),
as output: result of one more iteration by Max_Likelihood.
Re_conv = (optional) the current deconv image reconvolved with PSF
for use in next iteration and to check convergence.
OPTIONAL INPUT KEYWORDS:
/GAUSSIAN causes max-likelihood iteration for Gaussian additive noise
to be used, otherwise the default is Poisson statistics.
FT_PSF = passes (out/in) the Fourier transform of the PSF,
so that it can be reused for the next time procedure is called,
/NO_FT overrides the use of FFT, using the IDL function convol() instead.
POSITIVITY_EPS = value of epsilon passed to function positivity,
default = -1 which means no action (identity).
UNDERFLOW_ZERO = cutoff to consider as zero, if numbers less than this.
EXTERNAL CALLS:
function convolve( image, psf ) for convolutions using FFT or otherwise.
function positivity( image, EPS= ) to make image positive.
METHOD:
Maximum Likelihood solution is a fixed point of an iterative eq.
(derived by setting partial derivatives of Log(Likelihood) to zero).
Poisson noise case was derived by Richardson(1972) & Lucy(1974).
Gaussian noise case is similar with subtraction instead of division.
CALLS: ***
CONVOLVE, POSITIVITY
HISTORY:
written: Frank Varosi at NASA/GSFC, 1992.
F.V. 1993, added optional arg. Re_conv (to avoid doing it twice).
Converted to IDL V5.0 W. Landsman September 1997
[Previous]
[Next]
NAME:
MCURVEFIT
PURPOSE:
Non-linear least squares fit to a function of an arbitrary
number of parameters. The function may be any non-linear
function. If available, partial derivatives can be calculated by
the user function, else this routine will estimate partial derivatives
with a forward difference approximation.
CATEGORY:
E2 - Curve and Surface Fitting.
CALLING SEQUENCE:
Result = CURVEFIT(X, Y, W, A, SIGMAA, FUNCTION_NAME = name, $
ITMAX=ITMAX, ITER=ITER, TOL=TOL, /NODERIVATIVE)
INPUTS:
X: A row vector of independent variables.
Y: A row vector of dependent variable, the same length as x.
W: A row vector of weights, the same length as x and y.
For no weighting,
w(i) = 1.0.
For instrumental weighting,
w(i) = 1.0/y(i), etc.
A: A vector, with as many elements as the number of terms, that
contains the initial estimate for each parameter. If A is double-
precision, calculations are performed in double precision,
otherwise they are performed in single precision.
KEYWORDS:
FUNCTION_NAME: The name of the function (actually, a procedure) to
fit. If omitted, "FUNCT" is used. The procedure must be written as
described under RESTRICTIONS, below.
ITMAX: Maximum number of iterations. Default = 20.
ITER: The actual number of iterations which were performed
TOL: The convergence tolerance. The routine returns when the
relative decrease in chi-squared is less than TOL in an
interation. Default = 1.e-3.
CHI2: The value of chi-squared on exit
NODERIVATIVE: If this keyword is set then the user procedure will not
be requested to provide partial derivatives. The partial
derivatives will be estimated in CURVEFIT using forward
differences. If analytical derivatives are available they
should always be used.
SHOW_PROGRESS: If set, then print chi-square and params each iteration.
P_NOEFFECT: On exit, these are the indices of parameters that have
no effect (derivative is 0 when they are changed), which causes NaN's in the
results, and fail_type 3 to be returned. Caller may choose to set these
parameters as fixed (min=max) and try again. -1 means none.
ALLOW_ALLFIXED: If set, if all params are fixed (minarr eq maxarr), then just
calc chi2 and return yfit without changing any params. Default behaviour
is to generate message event and abort.
OUTPUTS:
Returns a vector of calculated values.
A: A vector of parameters containing fit.
OPTIONAL OUTPUT PARAMETERS:
Sigmaa: A vector of standard deviations for the parameters in A.
CALLS: ***
ARR2STR [1], Arr2Str [2], EXIST, F_DIV, MCURVEFIT_F_VAL, N_DIMENSIONS, TRIM
CALLED BY:
CFIT
COMMON BLOCKS:
NONE.
SIDE EFFECTS:
None.
RESTRICTIONS:
The function to be fit must be defined and called FUNCT,
unless the FUNCTION_NAME keyword is supplied. This function,
(actually written as a procedure) must accept values of
X (the independent variable), and A (the fitted function's
parameter values), and return F (the function's value at
X), and PDER (a 2D array of partial derivatives).
For an example, see FUNCT in the IDL User's Libaray.
A call to FUNCT is entered as:
FUNCT, X, A, F, PDER
where:
X = Vector of NPOINT independent variables, input.
A = Vector of NTERMS function parameters, input.
F = Vector of NPOINT values of function, y(i) = funct(x(i)), output.
PDER = Array, (NPOINT, NTERMS), of partial derivatives of funct.
PDER(I,J) = DErivative of function at ith point with
respect to jth parameter. Optional output parameter.
PDER should not be calculated if the parameter is not
supplied in call. If the /NODERIVATIVE keyword is set in the
call to CURVEFIT then the user routine will never need to
calculate PDER.
PROCEDURE:
Copied from "CURFIT", least squares fit to a non-linear
function, pages 237-239, Bevington, Data Reduction and Error
Analysis for the Physical Sciences.
"This method is the Gradient-expansion algorithm which
combines the best features of the gradient search with
the method of linearizing the fitting function."
Iterations are performed until the chi square changes by
only TOL or until ITMAX iterations have been performed.
The initial guess of the parameter values should be
as close to the actual values as possible or the solution
may not converge.
EXAMPLE: Fit a function of the form f(x) = a * exp(b*x) + c to
sample pairs contained in x and y.
In this example, a=a(0), b=a(1) and c=a(2).
The partials are easily computed symbolicaly:
df/da = exp(b*x), df/db = a * x * exp(b*x), and df/dc = 1.0
Here is the user-written procedure to return F(x) and
the partials, given x:
pro gfunct, x, a, f, pder ; Function + partials
bx = exp(a(1) * x)
f= a(0) * bx + a(2) ;Evaluate the function
if N_PARAMS() ge 4 then $ ;Return partials?
pder= [[bx], [a(0) * x * bx], [replicate(1.0, N_ELEMENTS(x))]]
end
x=findgen(10) ;Define indep & dep variables.
y=[12.0, 11.0,10.2,9.4,8.7,8.1,7.5,6.9,6.5,6.1]
w=1.0/y ;Weights
a=[10.0,-0.1,2.0] ;Initial guess
yfit=curvefit(x,y,w,a,sigmaa,function_name='gfunct')
print, 'Function parameters: ', a
print, yfit
end
MODIFICATION HISTORY:
Written, DMS, RSI, September, 1982.
Does not iterate if the first guess is good. DMS, Oct, 1990.
Added CALL_PROCEDURE to make the function's name a parameter.
(Nov 1990)
12/14/92 - modified to reflect the changes in the 1991
edition of Bevington (eq. II-27) (jiy-suggested by CreaSo)
Mark Rivers, U of Chicago, Feb. 12, 1995
- Added following keywords: ITMAX, ITER, TOL, CHI2, NODERIVATIVE
These make the routine much more generally useful.
- Removed Oct. 1990 modification so the routine does one iteration
even if first guess is good. Required to get meaningful output
for errors.
- Added forward difference derivative calculations required for
NODERIVATIVE keyword.
- Fixed a bug: PDER was passed to user's procedure on first call,
but was not defined. Thus, user's procedure might not calculate
it, but the result was then used.
Stein Vidar Hagfors Haugan, Univ. of Oslo, 7 May 1996
- Detecting NaN errors and deadlock repetitions inside the repeat
loop.
Stein Vidar Hagfors Haugan, 16 October 1996
- Added minarr/maxarr keywords for imposed min/max limits.
- Added PRIVATE keyword to send info w/o common blocks.
Stein Vidar Hagfors Haugan, 17 September 1997
- Added FAIL_TYPE (output) and ERROR_ONLY (for quick SIGMAA
estimates with no change in parameters.
Stein Vidar Hagfors Haugan, 30 July 1999
- Only decreasing flambda when > 1e-40 to avoid underflow/hang.
Kim Tolbert, 11 February 2004
- Added show_progress keyword. Also, handle 2-D x array. Also,
handle case where x has different length than y. Use ny, not nx
for defining ipder.
Linhui Sui, 20 May 2004
- To speed up, only compute partial derivative for free parameters
(i.e. minarr eq maxarr)
- Degrees of freedom (nfree) changed to # of data points minus # of free
(or fitting) params, instead of minus total number of params. Note:
this is used in the chisq calculation, so chisq values will be slightly
different from before.
Kim Tolbert, 23 June 2004
- Added p_noeffect keyword.
- In chisq calculation, subtract 1 from # degrees of freedom in denominator. This
change and Lin's change of 20-May-2004 make Chisq calc more standard -
Denominator is now # data points - # free parameters -1
Previously denominator was # data points - total # parameters
Kim Tolbert, 25 Aug 2005. Added allow_allfixed keyword
Kim Tolbert, 14 Sep 2005. In 'done:' section, only use array if it exists. For some
error conditions (like not enough points), array wasn't created.
Kim Tolbert, 15-Aug-2006, use f_div when dividing by c in case there are zeros in c
[Previous]
[Next]
Project : HESSI
Name : MDI__DEFINE
Purpose : Define an MDI data object
Category : Ancillary GBO Synoptic Objects
Syntax : IDL> c=obj_new('mdi')
CALLS: ***
ADD_TAG [1], ADD_TAG [2], COMP_FITS_CRPIX, HAVE_TAG, IS_STRING, LOC_FILE [1]
LOC_FILE [2], LOC_FILE [3], MDI::CLEANUP, MDI::FLAT_FIELD, MDI::FLAT_FIELDED
MDI::INDEX2FITS, MDI::INIT, MDI::LIMB_CORRECT, MDI::LIMB_CORRECTED, MDI::READ
PB0R, VALID_MAP, anytim [1], anytim [2], anytim [3], anytim [4], anytim [5]
darklimb_correct, gt_tagval [1], gt_tagval [2], is_struct, struct2ssw
History : Written 17 Feb 2001, D. Zarro, EIT/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Name: mdi_cat
Purpose: return MDI header/structures between time0 and time1
Input Parameters:
time0, time1 - time range desired
Output Parameters:
catout - output structure vector
CALLS: ***
BOX_MESSAGE, CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3], FILE_EXIST [2]
FMT_TIMER [1], FMT_TIMER [2], concat_dir [4], file_exist [1], file_exist [3]
get_logenv [1], get_logenv [2], read_genxcat, sel_timrange [1], sel_timrange [2]
CALLED BY:
mdi_files
History:
7-November-1998 - S.L.Freeland - simple interface to read_genxcat
5-March-2001 - S.L.Freeland - allow catalog files in
$MDI_MAGS_GENXCAT
[Previous]
[Next]
Project : HESSI
Name : MDI_COPY
Purpose : copy daily MDI magnetograms and intensitygrams to SYNOP_DATA
Category : synoptic gbo
Syntax : IDL> mdi_copy
Keywords : clobber = clobber existing files
BACK = # of days back to copy
CALLS: ***
APPEND_ARR, CHKLOG [1], CHKLOG [2], CHMOD, CONCAT_DIR [1], CONCAT_DIR [2]
CONCAT_DIR [3], ERR_STATE, ESPAWN, IS_DIR, IS_STRING, LOC_FILE [1], LOC_FILE [2]
LOC_FILE [3], MK_SUB_DIR, OS_FAMILY, REP_TAG_VALUE, TEST_DIR, TRIM, concat_dir [4]
get_ymd, is_number [1], is_number [2], strmids [1], strmids [2]
Restrictions: Unix only
History : Written 8 March 2001, D. Zarro (EITI/GSFC)
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Name: mdi_files
Purpose: return MDI file names between time0 and time0
Input Parameters:
time0 - start time or vector of times to match
time1 - stop time of range
CALLS: ***
BOX_MESSAGE, CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3], FILE_EXIST [2]
concat_dir [4], data_chk [1], data_chk [2], file_exist [1], file_exist [3]
get_logenv [1], get_logenv [2], last_nelem, mdi_cat, sel_timrange [1]
sel_timrange [2], tim2dset [1], tim2dset [2], timegrid
CALLED BY:
mdi_link
History:
7-November-1998 - S.L.Freeland - mimic eit_files/trace_files/cds_files
5-March-2001 - S.L.Freeland - allow genx catalogs to reside in
$MDI_MAGS_GENXCAT
[Previous]
[Next]
Project : HESSI
Name : MDI_GBO
Purpose : update Max Millennium catalog with MDI info
Category : synoptic gbo
Syntax : IDL> mdi_gbo
Inputs : TSTART,TEND = time range to process
Keywords : REPROCESS = reprocess existing entries
BACK = # of days back to process
VERBOSE = set verbose output
CALLS: ***
ANYTIM2TAI, ANYTIM2UTC [1], ANYTIM2UTC [2], ARR2STR [1], Arr2Str [2]
BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3], CONCAT_DIR [1], CONCAT_DIR [2]
CONCAT_DIR [3], DEF_GBO, IS_DIR, LIST_NAR, LOC_FILE [1], LOC_FILE [2], LOC_FILE [3]
NEAREST_GEV, OS_FAMILY, PARSE_TIME, PURGE_GBO, RESTORE_GBO, SYNOP_PATH, SYNOP_SERVER
TEST_OPEN, TRIM, UPDATE_GBO, VALID_TIME, break_file [4], concat_dir [4], gt_day [1]
gt_day [2], gt_time [1], gt_time [2], is_number [1], is_number [2], is_struct
Restrictions: Unix only
History : Written 4 Dec 2001, D. Zarro (EITI/GSFC)
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : HESSI
Name : MDI_LATEST
Purpose : List latest MDI files
Category : synoptic gbo
Syntax : IDL> files=mdi_files()
Keywords : BACK = # of days back to list
CALLS: ***
APPEND_ARR, ESPAWN, IS_DIR, OS_FAMILY, TRIM, is_number [1], is_number [2]
Restrictions: Unix only
History : Written 29 August 2006, D. Zarro (ADNET/GSFC)
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : HESSI
Name : mdi_link
Purpose : make a link between MDI file in $MDI_MAGS and
$SYNOP_DATA/fits/yymmdd
Category : synoptic gbo
Syntax : IDL> mk_mdi_link,tstart,tend,back=back
Inputs : TSTART, TEND = start and end times to consider
[def = current day]
Outputs : files named: mdi_mag_fd_yyyymmdd_hhmm.fits linked
to source files in $MDI_MAGS.
Keywords : BACK = days to look back
TARGET_DIR = target directory for links [def= $SYNOP_DATA/images]
CALLS: ***
CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3], DATATYPE [1], DATATYPE [2]
DATATYPE [3], ESPAWN, IS_DIR, MK_SUB_DIR, OS_FAMILY, TEST_DIR, TIME2FID
concat_dir [4], mdi_files
Restrictions: Unix only
History : Written 8 March 2001, D. Zarro (EITI/GSFC)
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
MDI_STRUCT
Return a structure containing a minimal subset of
MDI FITS keywords
Craig DeForest, 28-Apr-1997
Sam Freeland, add some soi pointing info
Zarro (EITI/GSFC), added REFTIME to support summary FITS files (28-Mar-01)
CALLED BY
mdialign, rd_mdi [1], rd_mdi [2]
[Previous]
[Next]
Name: mdi_time2file
Purpose: map from SSW times[ or time range -> mdi magnetogram fnames/URLS
Input Parameters:
time0 - vector of times or start time of range
time1 - optional stop time of range
Output Parameters:
fcount - number of files or urls returned
Keyword Parameters:
before - if set & one param, return closest BEFORE time0 (def=closest)
after - if set & one param, return closest AFTER time0 (def=closest)
deltat - deltaT(desired:actual) in minutes (negative~before)
stanford_url - if set, function returns full stanford URLs
gsfc_url - if set, function returns full gsfc urls
confirm - if switch, only return files/urls which actually exist
on server; default is "idealized" list
(fcount always reflects number of elements returned)
Calling Sequence:
mdimags=mdi_time2file(times [,/stanford] [,/confirm] ) ; Time vector
mdimags=mdi_time2file(time0,time1 [,/stanford] ... ) ; Time range
mdimags=mdi_time2file(time0, /AFTER , /stanford) ) ; 1st After T0
mdimags=mdi_time2file(time0, /BEFORE, /stanford) ) ; 1st Before T0
History:
25-Nov-2003 S.L.Freeland - long planned breakout of of a
local CoSEC/SSW socket "service"
Some heritage from sxi_files.pro
Will soon call from older mdi_files.pro but may
use standalone
CALLS: ***
BOX_MESSAGE, FSTRING, anytim [1], anytim [2], anytim [3], anytim [4], anytim [5]
reltime [1], reltime [2], timegrid
Restrictions:
Use of /CONFIRM requires IDL +5.4 (RSI socket utility)
Proto-version - not all keywords implemented as of
today but maybe pre Fall AGU 2003...
[Previous]
[Next]
Name: mdi_write_genxcat
Purpose: map mdi files (from SOI WWW requests) -> a time based catalog
Input Parameters:
NONE
Keyword Paramters:
pattern - directory file pattern to match
clean - if set, remove all mdi*genx in catalog directory (!)
prior to writing
testing - if set, only do this many directories (infrastructure test)
History:
Circa 15-Nov-1998 - S.L.Freeland
2-feb-1999 - S.L.Freeland - a little documentation
19-Mar-2001 - S.L.Freeland - allow multiple environmentals
09-May-2003, William Thompson - Use ssw_strsplit instead of strsplit
Restrictions:
$MDI_MAGS - points to top of mdi data tree
(also $MDI_MAGS_0, $MDI_MAGS_1... $MDI_MAGS_9 optional)
CALLS: ***
ADD_TAG [1], ADD_TAG [2], BOX_MESSAGE, BREAK_FILE [1], BREAK_FILE [2]
BREAK_FILE [3], CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3], DELVARX [1]
DELVARX [2], DELVARX [3], DELVARX [4], FILE_EXIST [2], IS_DIR, break_file [4]
concat_dir [4], data_chk [1], data_chk [2], delvarx [5], file_exist [1]
file_exist [3], file_list [1], file_list [2], get_logenv [1], get_logenv [2]
rd_mdi [1], rd_mdi [2], ssw_strsplit, str_subset, struct2ssw, write_genxcat
Side Effects:
Writes catalog files (genx format) in $MDI_MAGS/mdi_genxcat
Assumptions - data files are from a Stanford MDI data request
[Previous]
[Next]
Project : SOHO-CDS
Name : MEAN_MAP
Purpose : Compute mean value in vicinity of pixels
Category : imaging
Explanation : Points nearest input coordinates are averaged
Syntax : mean=mean_map(map,xc,yc)
CALLED BY:
LTC_MAP
Examples :
Inputs : MAP = map structure
XC,YC = coordinate arrays of pixels
Opt. Inputs : None
Outputs : MEAN = mean value
Opt. Outputs:
Keywords : TAG_ID = tag name or index to use
AREA = if set, average over total area bounded by (xc,yc)
TROTATE = rotate map coords to reference time before
averaging
SHIFT = [x,y] offsets to apply to coordinates (after rotation)
CALLS: ***
ANYTIM2TAI, DELVARX [1], DELVARX [2], DELVARX [3], DELVARX [4], EXIST, GET_MAP_TIME
PR_SYNTAX, ROT_XY, TAG_EXIST [1], TAG_EXIST [2], UNIQ [1], UNIQ [2], UNIQ [3]
UNPACK_MAP, VALID_MAP, delvarx [5]
Common : None
Restrictions: None
Side effects: None
History : Written 22 Jan 1997, D. Zarro, SAC/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
NAME:
MEANCLIP
PURPOSE:
Computes an iteratively sigma-clipped mean on a data set
EXPLANATION:
Clipping is done about median, but mean is returned.
Called by SKYADJ_CUBE
CATEGORY:
Statistics
CALLING SEQUENCE:
MEANCLIP, Data, Mean, [ Sigma, SUBS =
CLIPSIG=, MAXITER=, CONVERGE_NUM=, /VERBOSE, /DOUBLE ]
INPUT POSITIONAL PARAMETERS:
Data: Input data, any numeric array
OUTPUT POSITIONAL PARAMETERS:
Mean: N-sigma clipped mean.
Sigma: Standard deviation of remaining pixels.
INPUT KEYWORD PARAMETERS:
CLIPSIG: Number of sigma at which to clip. Default=3
MAXITER: Ceiling on number of clipping iterations. Default=5
CONVERGE_NUM: If the proportion of rejected pixels is less
than this fraction, the iterations stop. Default=0.02, i.e.,
iteration stops if fewer than 2% of pixels excluded.
/VERBOSE: Set this flag to get messages.
/DOUBLE - if set then perform all computations in double precision.
Otherwise double precision is used only if the input
data is double
OUTPUT KEYWORD PARAMETER:
SUBS: Subscript array for pixels finally used.
CALLS: ***
MOMENT, STRN [1], STRN [2], STRN [3]
CALLED BY:
APER, EXTRAP, SKY, SKYADJ_CUBE
MODIFICATION HISTORY:
Written by: RSH, RITSS, 21 Oct 98
20 Jan 99 - Added SUBS, fixed misplaced paren on float call,
improved doc. RSH
Nov 2005 Added /DOUBLE keyword, check if all pixels are removed
by clipping W. Landsman
[Previous]
[Next]
NAME:
med3x3gen
PURPOSE:
Generalized 3x3 median filter for image processing.
The generalization allows one to pick intensities other
than the median, or fifth brightest in each 3x3 environment.
For example, pick=1 returns the maximum, pick=9 the minimum,
and pick=6 the 3rd faintest of each 3x3 pixel neighborhood.
Edges and corners receive special treatment (same as in the
"amedian" function):
1 2 3 1 2 3 1 2 o 1 2 1
4 5 6 -> 4 5 6 3 4 o -> 3 4 3
o o o 1 2 3 o o o 1 2 1
CATEGORY:
CALLING SEQUENCE:
out = med3x3gen(in,pick=6)
out = med3x3gen(in,pick=5) = med3x3gen(in) = amedian(in,3)
INPUTS:
in = input image
KEYWORDS (INPUT):
pick = return the "pick"-brightest pixel of each 3x3 neighborhood.
default: pick=5 (regular median).
OUTPUTS:
out = filtered output image
KEYWORDS (OUTPUT):
COMMON BLOCKS:
None.
SIDE EFFECTS:
RESTRICTIONS:
PROCEDURE:
MODIFICATION HISTORY:
JPW, 28-apr-98
[Previous]
[Next]
NAME:
MEDARR
PURPOSE:
Compute the median at each pixel across a set of 2-d images
EXPLANATION:
Each pixel in the output array contains the median of the
corresponding pixels in the input arrays. Useful, for example to
combine a stack of CCD images, while removing cosmic ray hits.
This routine became partially obsolete in V5.6 with the introduction
of the DIMENSION keyword to the intrinsic MEDIAN() function. However,
it is still useful if a input mask is needed (though it is much
faster to set invalid pixels to NaN values.)
CALLING SEQUENCE:
MEDARR, inarr, outarr, [ mask, output_mask ]
INPUTS:
inarr -- A three dimensional array containing the input arrays to
combine together. Each of the input arrays must be two
dimensional and must have the same dimensions. These arrays
should then be stacked together into a single 3-D array,
creating INARR.
OPTIONAL INPUT:
mask -- Same structure as inarr, byte array with 1b where
pixels are to be included, 0b where they are to be
excluded. For floating point images, it is much faster to
set masked pixels in inarr equal to !VALUES.F_NAN (see below),
rather than use the mask parameter.
OUTPUTS:
outarr -- The output array. It will have dimensions equal to the
first two dimensions of the input array.
OPTIONAL OUTPUT:
output_mask -- Same structure as outarr, byte array with 1b
pixels are valid, 0b where all the input pixels
have been masked out.
CALLED BY:
CR_REJECT
RESTRICTIONS:
Prior to V5.6, this procedure was *SLOW* because it had to loop over
each pixel of the image. See notes below about an alternative with
CALL_EXTERNAL.
EXAMPLE:
Suppose one wants to combine three floating point 1024 x 1024 bias
frames which have been read into the IDL variables im1,im2,im3
IDL> bigim = fltarr(1024,1024,3) ;Create big array to hold images
IDL> bigim(0,0,0) = im1 & bigim(0,0,1) = im2 & bigim(0,0,2) = im2
IDL> medarr, bigim, avgbias
The variable avgbias will be the desired 1024x 1024 float image.
PROCEDURE:
A scalar median function over the third dimension is looped over
each pixel of the first two dimensions. The /EVEN keyword is used
with MEDIAN (which averages the two middle values), since this avoids
biasing the output for an even number of images.
Any values set to NAN (not a number) are ignored when computing the
median. If all values for a pixel location are NAN, then the median
is also returned as NAN.
MEDARR is also available as a C procedure linked to IDL via
CALL_EXTERNAL (but without the mask parameter). The callable C
version is 2-3 times faster for large (~ 500 x 500 x 7) images.
Contact W. Landsman (landsman@mpb.gsfc.nasa.gov) for the C program
MODIFICATION HISTORY:
Written by Michael R. Greason, STX, 12 June 1990.
Don't use MEDIAN function for even number of images.
W. Landsman Sep 1996
Mask added. RS Hill, HSTX, 13 Mar. 1997
Converted to IDL V5.0 W. Landsman September 1997
Use /EVEN keyword to MEDIAN W. Landsman September 1997
Rearranged code for faster execution W. Landsman January 1998
Faster execution for odd number of images W. Landsman July 2000
V5.4 fix for change in SIZE() definition of undefined variable
W. Landsman/E. Young May 2001
Use MEDIAN(/DIMEN) for V5.6 or later W. Landsman November 2002
Use keyword_set() instead of ARG_present() to test for presence of mask
parameter D. Hanish/W. Landsman June 2003
Use MEDIAN(/EVEN) when mask not set V5.6 or later W. Landsman Feb 2004
[Previous]
[Next]
NAME:
MEDSMOOTH
PURPOSE:
Median smoothing of a vector, including points near its ends.
CALLING SEQUENCE:
SMOOTHED = MEDSMOOTH( VECTOR, WINDOW_WIDTH )
INPUTS:
VECTOR = The (1-d numeric) vector to be smoothed
WINDOW = Odd integer giving the full width of the window over which
the median is determined for each point. (If WINDOW is
specified as an even number, then the effect is the same as
using WINDOW+1)
OUTPUT:
Function returns the smoothed vector
PROCEDURE:
Each point is replaced by the median of the nearest WINDOW of points.
The width of the window shrinks towards the ends of the vector, so that
only the first and last points are not filtered. These points are
replaced by forecasting from smoothed interior points.
EXAMPLE:
Create a vector with isolated high points near its ends
IDL> a = randomn(seed,40) & a[1] = 10 & a[38] = 10
Now do median smoothing with a 7 point window
IDL> b = medsmooth(a,7)
Note that, unlike MEDIAN(), that MEDSMOOTH will remove the isolated
high points near the ends.
REVISION HISTORY:
Written, H. Freudenreich, STX, 12/89
H.Freudenreich, 8/90: took care of end-points by shrinking window.
Speed up using vector median when possible W. Landsman February 2002
[Previous]
[Next]
Name: merge_fits_hdrs
Category: HESSI, UTIL
Purpose: Merge two FITS headers.
Calling sequence: rm2fits, 'file.fits', photon_edges, matrix, LO_THRES=1e-6
Inputs:
master - header to merge keywords into.
input - header to merge keywords from.
Outputs:
Input keywords:
Output keywords:
ERR_MSG = error message. Null if no error occurred.
ERR_CODE - 0/1 if [ no error / an error ] occurred during execution.
Calls: ***
FXADDPAR [1], FXADDPAR [2], FXPAR [1], FXPAR [2]
CALLED BY
mk_rate_hdr, mk_rmf_hdr, rm2fits, wrt_ebounds_ext, wrt_eneband_ext
[Previous]
[Next]
Name: merge_genxcat
Purpose: merge multiple genx catalogs -> fewer (reduce granularity)
Input Parameters:
indir - input path for existing catalogs -
outdir - desired output for merged catalogs -
Keyword Parameters
year - if set, granularity = 1 catalog per year
month - if set, granularity = 1 cat/month
day - if set, granularity = 1 cat/day
CALLS: ***
BOX_MESSAAGE, BOX_MESSAGE, BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3]
UNIQ [1], UNIQ [2], UNIQ [3], break_file [4], data_chk [1], data_chk [2]
extract_fids, file_list [1], file_list [2], restgen [1], restgen [2], ssw_strsplit
str2number [1], str2number [2], totvect, write_genxcat
Restrictions:
Currently assumes catalog names nnnn...YYYYMMDD_HHMM..NExxx....gen{x,y}
(ie, written via write_genxcat with /NELEMENTS switch set
09-May-2003, William Thompson - Use ssw_strsplit instead of strsplit
[Previous]
[Next]
Project : SOHO-CDS
Name : MERGE_MAP
Purpose : merge to image maps
Category : imaging
Syntax : imap=merge_map(map1,map2)
Inputs : MAP1, MAP2 = two image maps to merge
(MAP2 is rebinned to scale of MAP1)
Outputs : IMAP = merged map
Keywords : ERR = error strings
SPACE = [dx,dy] = grid spacing
DROTATE = set to differentially rotate MAP2 to
time of MAP1
CALLS: ***
DPRINT, DROT_MAP, GRID_XY, INTER_MAP, PR_SYNTAX, REPACK_MAP, REP_TAG_VALUE, UNPACK_MAP
VALID_MAP
History : Written, 13 January 1998, D. Zarro, SAC/GSFC
Modified, 26 June 2006, Zarro (L-3Com/GSFC)
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO - CDS
Name : MERGE_STRUCT
Purpose : merge/concatanate two structures
Explanation : concatanates two structures by using CREATE_STRUCT to
ensure that input structures have the same name and, thus,
avoid the problem of concatanating two differently named
structures.
Use : NEW_STRUCT=MERGE_STRUCT(STRUCT1,STRUCT2)
Inputs : STRUCT1,2 = input structures
Outputs : NEW_STRUCT = concatanated structure
Opt. Outputs: None.
Keywords : ERR = err string
NOTAG_CHECK = don't check if tag names match.
NOCHECK = skip input checking
Category : Structure handling
Written : 1-Apr-1999, Zarro (SAC/GSFC)
Modified : 31-July-2001, Zarro (EITI/GSFC) - use faster STRUCT_ASSIGN
to avoid and handle variable sized tags
20-Dec-2002, Zarro (EER/GSFC) - take advantage of relaxed
structure assignment
1-Feb-2007, Zarro (ADNET/GSFC) - disabled /RELAXED
Contact : dzarro@solar.stanford.edu
CALLS:
CALLED BY
ADD_TAG [2], BOOST_TAG, CDS_ASRUN_POINT, CDS_PLAN_POINT, CDS_STACK, CONCAT_STRUCT
DROT_MAP, DROT_MAP_FAST, DROT_NAR, ESPAWN, FITS2MAP [1], FITS2MAP [2], FITS__DEFINE
FIT_CDS_MAP, GET_NAR, GET_SID, GRID_MAP, HAVE_METHOD, HAVE_NETWORK, HAVE_PROC
HSI_FITS2MAP [1], INDEX2MAP, JOIN_STRUCT [2], MK_CDS_IMAP, MK_CDS_MAP, MK_CDS_SMAP
MK_HXI_MAP, MK_NEW_MAP, MK_OLD_MAP, MK_SUMER_DBASE, MK_SXT_MAP, OBJ_MANAGER
RD_CDS_POINT, REBIN_MAP, REM_ANON_TAG, REM_DUP_TAG, RESPACE_MAP, ROT_MAP
SMART_WINDOW, SUB_MAP, XCRON, keyword_db
[Previous]
[Next]
Project : HESSI
Name : MESOLA__DEFINE
Purpose : Define a MESOLA data object
Category : Ancillary GBO Synoptic Objects
Syntax : IDL> c=obj_new('mesola')
CALLS: ***
IS_COMPRESSED, MESOLA::CLEANUP, MESOLA::GET_SDIR, MESOLA::INIT
MESOLA::PARSE_TIME, MESOLA::RENAME_FILES, PARSE_TIME, TIME2FID
History : Written 20 Dec 1999, D. Zarro, SM&A/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : HESSI
Name : MEUDON__DEFINE
Purpose : Define a Meudon data object
Category : Ancillary GBO Synoptic Objects
Syntax : IDL> c=obj_new('meudon')
CALLS: ***
GET_UTC, MEUDON::CLEANUP, MEUDON::INIT, MEUDON::SETPROP, MEUDON::SYNOP, synop_link
History : Written 20 Dec 1999, D. Zarro, SM&A/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
NAME:
mewe_spec
PURPOSE:
Compute a Mewe thermal spectrum (line + continuum) for EM=1.e44 cm^-3
CALLING SEQUENCE:
Flux = mewe_spec(Te6,wave) ; ph s-1
Flux = mewe_spec(Te6,wave,/photon) ; ph s-1
Flux = mewe_spec(Te6,wave,/erg) ; erg s-1
Flux = mewe_spec(Te6,wave,/cosmic) ; Cosmic abundances
INPUTS:
Te6 = Electron Temperature in MK (may be a vector)
Wave = Vector of wavelengths (Ang) (centers of the wavelength bins)
or, if keyword EDGES is set,
a 2xN array of the 2 wavelength edges of N bins.
OUTPUTS:
Flux = Fluxes in ph s-1 or erg s-1 (total flux with each bin)
Fluxes = fltarr(N_elements(Te6),N_elements(wave))
OPTIONAL INPUT KEYWORDS:
Photon = If set, calculation is made in ph s-1 (default)
Erg = If set, calculation is made in erg s-1
Cosmic = If set, use cosmic abundances (solar is default)
Edges = If set, interpret Wave as a 2xN set of wavelength boundaries
file_in = To specify the input file for linflx explicity.
OPTIONAL OUTPUT KEYWORDS:
Abun = Abundances used for calculation
elem = Elements corresponding to the abundances
cont_flux = Continuum flux alone (without line contribution).
dwave = Widths of wavelength bins (Ang)
wave_range = Interval over which lines are extracted (Ang)
METHOD:
Calls linflx and conflx. Linflx reads the line data from either
$DIR_SXT_SENSITIVE/mewe_cosmic.genx or $DIR_SXT_SENSITIVE/mewe_solar.genx
The mewe_cosmic.genx file is taken from the following references:
Mewe, Gronenschild, van den Oord, 1985, (Paper V) A. & A. Suppl., 62, 197
Mewe, Lemen, and van den Oord, 1986, (Paper VI) A. & A. Suppl., 65, 511
The solar coronal abundances in mewe_solar.genx a adapted from:
Meyer, J.-P., 1985, ApJ Suppl., 57, 173.
CALLS: ***
CONFLX [1], CONFLX [2], DELVARX [1], DELVARX [2], DELVARX [3], DELVARX [4], UNIQ [1]
UNIQ [2], UNIQ [3], delvarx [5], linflx [1], linflx [2]
CALLED BY:
MAKE_GOES_RESP, ROUTINE_NAME [1], SXT_THERM, SXT_THERM_EBAR, SXT_WEIGHT
THERMAL_KEV, dfx_1th_lo, dfx_thppl_lo, fdf10_init, fx_1th_lo, get_slider, model_spec
out_spectra_4_designer, set_field, sxt_dn_int, sxt_erg_per_dn, sxt_etemp
tem_thermal_power
MODIFICATION HISTORY:
29-oct-92, Written, J. R. Lemen, LPARL
25-feb-93, JRL, Added /cosmic option
7-jul-93, JRL, Added the file_in= keyword
8-jun-94, JMM, Added IF block to avoid crashing when the line
flux comes out to be zero.
13-jul-94, JRL, Added /edges a la R. A. Schwartz cira 1993
2-aug-94, JRL, Added the file_in= keyword (again!). Changed header.
21-Jun-95, JRL, linflx changed to assume EM=1.e44 cm-3
6-Jan-96, JRL, Added the Mewe et al references to the header
16-Dec-96, LWA, Added the Meyer reference to the header.
[Previous]
[Next]
Project : YOHKOH-BCS
Name : MGAUSS
Purpose : Compute multiple gauss functions with quadratic background
Explanation : Program checks no. of elements in a, of which there must
at least 6. First three elements define background. Remaining
elements define gauss function(s) which must come in
multiples of 3.
Category : fitting
Syntax : f=mgauss(x,a,pder)
Inputs : x = dependent variable
a(0,1,2)=coefficients of quadratic background
a(3)= line intensity
a(4)= line center
a(5)= 1/e doppler width
Outputs : f = n gauss functions + quadratic background
Opt Outputs : pder = partial derivatives wrt 'a'
Keywords : extra = extra optional variable in which user can return
miscellaneous information.
CALLED BY:
BATSE_SPEC_DRM, CF_174LG, CF_177LG, CF_180LG, CF_765LG, CF_770LG, mgaussfit
Restrictions: None.
Side effects: None.
History : Version 1, 17-July-1993, D M Zarro. Written
Contact : DZARRO@SOLAR.STANFORD.EDU
[Previous]
[Next]
NAME:
MINF_BRACKET
PURPOSE:
Bracket a local minimum of a 1-D function with 3 points,
EXPLANATION:
Brackets a local minimum of a 1-d function with 3 points,
thus ensuring that a minimum exists somewhere in the interval.
This routine assumes that the function has a minimum somewhere....
Routine can also be applied to a scalar function of many variables,
for such case the local minimum in a specified direction is bracketed,
This routine is called by minF_conj_grad, to bracket minimum in the
direction of the conjugate gradient of function of many variables
CALLING EXAMPLE:
xa=0 & xb=1
minF_bracket, xa,xb,xc, fa,fb,fc, FUNC_NAME="name" ;for 1-D func.
or:
minF_bracket, xa,xb,xc, fa,fb,fc, FUNC="name", $
POINT=[0,1,1], $
DIRECTION=[2,1,1] ;for 3-D func.
INPUTS:
xa = scalar, guess for point bracketing location of minimum.
xb = scalar, second guess for point bracketing location of minimum.
KEYWORDS:
FUNC_NAME = function name (string)
Calling mechanism should be: F = func_name( px )
where:
px = scalar or vector of independent variables, input.
F = scalar value of function at px.
POINT_NDIM = when working with function of N variables,
use this keyword to specify the starting point in N-dim space.
Default = 0, which assumes function is 1-D.
DIRECTION = when working with function of N variables,
use this keyword to specify the direction in N-dim space
along which to bracket the local minimum, (default=1 for 1-D).
(xa,xb,xc) are then relative distances from POINT_NDIM.
OUTPUTS:
xa,xb,xc = scalars, 3 points which bracket location of minimum,
that is, f(xb) < f(xa) and f(xb) < f(xc), so minimum exists.
When working with function of N variables
(xa,xb,xc) are then relative distances from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION.
OPTIONAL OUTPUT:
fa,fb,fc = value of function at 3 points which bracket the minimum,
again note that fb < fa and fb < fc if minimum exists.
CALLED BY:
FITEXY, MINF_CONJ_GRAD, conj_grad2, minF_partan
PROCEDURE:
algorithm from Numerical Recipes (by Press, et al.), sec.10.1 (p.281).
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
Converted to IDL V5.0 W. Landsman September 1997
[Previous]
[Next]
NAME:
MINF_CONJ_GRAD
PURPOSE:
Find the local minimum of a scalar function using conjugate gradient
EXPLANATION:
Find the local minimum of a scalar function of several variables using
the Conjugate Gradient method (Fletcher-Reeves-Polak-Ribiere algorithm).
Function may be anything with computable partial derivatives.
Each call to minF_conj_grad performs one iteration of algorithm,
and returns an N-dim point closer to the local minimum of function.
CALLING EXAMPLE:
p_min = replicate( 1, N_dim )
minF_conj_grad, p_min, f_min, conv_factor, FUNC_NAME="name",/INITIALIZE
while (conv_factor GT 0) do begin
minF_conj_grad, p_min, f_min, conv_factor, FUNC_NAME="name"
endwhile
INPUTS:
p_min = vector of independent variables, location of minimum point
obtained from previous call to minF_conj_grad, (or first guess).
KEYWORDS:
FUNC_NAME = function name (string)
Calling mechanism should be: F = func_name( px, gradient )
where:
F = scalar value of function at px.
px = vector of independent variables, input.
gradient = vector of partial derivatives of the function
with respect to independent variables, evaluated at px.
This is an optional output parameter:
gradient should not be calculated if parameter is not
supplied in call (Unless you want to waste some time).
/INIT must be specified on first call (whenever p_min is a guess),
to initialize the iteration scheme of algorithm.
/USE_DERIV causes the directional derivative of function to be used
in the 1-D minimization part of algorithm
(default is not to use directional derivative).
TOLERANCE = desired accuracy of minimum location, default=sqrt(1.e-7).
/QUADRATIC runs simpler version which works only for quadratic function.
OUTPUTS:
p_min = vector giving improved solution for location of minimum point.
f_min = value of function at p_min.
conv_factor = gives the current rate of convergence (change in value),
iteration should be stopped when rate gets near zero.
EXTERNAL CALLS:
pro minF_bracket, to find 3 points which bracket the minimum in 1-D.
pro minF_parabolic, to find minimum point in 1-D.
pro minF_parabol_D, to find minimum point in 1-D, using derivatives.
CALLS: ***
MINF_BRACKET, MINF_PARABOLIC, MINF_PARABOL_D [2], minF_parabol_D [1]
CALLED BY:
AUTO_ALIGN_IMAGES, HSI_BTOT, HSI_PIXON_IMAGE [1], HSI_PIXON_IMAGE [2]
HXTFPB_FUZZY, IMAGE_DECONVOLVE
COMMON BLOCKS:
common minf_conj_grad, grad_conj, grad_save, gs_norm
(to keep conjugate gradient, gradient and norm from previous iteration)
PROCEDURE:
Algorithm adapted from Numerical Recipes, sec.10.6 (p.305).
Conjugate gradient is computed from gradient, which then gives
the best direction (in N-dim space) in which to proceed to find
the minimum point. The function is then minimized along
this direction of conjugate gradient (a 1-D minimization).
The algorithm is repeated starting at the new point by calling again.
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
Converted to IDL V5.0 W. Landsman September 1997
[Previous]
[Next]
NAME:
minF_parabol_D
PURPOSE:
Find a local minimum of a 1-D function up to specified tolerance,
using the first derivative of function in the algorithm.
This routine assumes that the function has a minimum nearby.
(recommend first calling minF_bracket, xa,xb,xc, to bracket minimum).
Routine can also be applied to a scalar function of many variables,
for such case the local minimum in a specified direction is found,
This routine is called by minF_conj_grad, to locate minimum in the
direction of the conjugate gradient of function of many variables.
CALLING EXAMPLES:
minF_parabol_D, xa,xb,xc, xmin, fmin, FUNC_NAME="name" ;for 1-D func.
or:
minF_parabol_D, xa,xb,xc, xmin, fmin, FUNC="name", $
POINT=[0,1,1], $
DIRECTION=[2,1,1] ;for 3-D func.
INPUTS:
xa,xb,xc = scalars, 3 points which bracket location of minimum,
that is, f(xb) < f(xa) and f(xb) < f(xc), so minimum exists.
When working with function of N variables
(xa,xb,xc) are then relative distances from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION.
KEYWORDS:
FUNC_NAME = function name (string)
Calling mechanism should be: F = func_name( px, gradient )
where:
px = scalar or vector of independent variables, input.
F = scalar value of function at px.
gradient = derivative of function, a scalar if 1-D,
a gradient vector if N-D,
(should only be computed if arg. is present).
POINT_NDIM = when working with function of N variables,
use this keyword to specify the starting point in N-dim space.
Default = 0, which assumes function is 1-D.
DIRECTION = when working with function of N variables,
use this keyword to specify the direction in N-dim space
along which to bracket the local minimum, (default=1 for 1-D).
(xa, xb, xc, x_min are then relative distances from POINT_NDIM)
MAX_ITER = maximum allowed number iterations, default=100.
TOLERANCE = desired accuracy of minimum location, default=sqrt(1.e-7).
OUTPUTS:
xmin = estimated location of minimum.
When working with function of N variables,
xmin is the relative distance from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION,
so that min. Loc. Pmin = Point_Ndim + xmin * Direction.
fmin = value of function at xmin (or Pmin).
CALLS: ***
CALL_FUNC_DERIV
CALLED BY:
MINF_CONJ_GRAD, conj_grad2, minF_partan
PROCEDURE:
Brent's method to minimize a function by using parabolic interpolation
and using first derivative of function,
from Numerical Recipes (by Press, et al.), sec.10.3 (p.287),
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
[Previous]
[Next]
NAME:
MINF_PARABOL_D
PURPOSE:
Minimize a function using a modified Brent's method with derivatives
EXPLANATION:
Based on the procedure DBRENT in Numerical Recipes by Press et al.
Finds a local minimum of a 1-D function up to specified tolerance,
using the first derivative of function in the algorithm.
This routine assumes that the function has a minimum nearby.
(recommend first calling minF_bracket, xa,xb,xc, to bracket minimum).
Routine can also be applied to a scalar function of many variables,
for such case the local minimum in a specified direction is found,
This routine is called by minF_conj_grad, to locate minimum in the
direction of the conjugate gradient of function of many variables.
CALLING EXAMPLES:
minF_parabol_D, xa,xb,xc, xmin, fmin, FUNC_NAME="name" ;for 1-D func.
or:
minF_parabol_D, xa,xb,xc, xmin, fmin, FUNC="name", $
POINT=[0,1,1], $
DIRECTION=[2,1,1] ;for 3-D func.
INPUTS:
xa,xb,xc = scalars, 3 points which bracket location of minimum,
that is, f(xb) < f(xa) and f(xb) < f(xc), so minimum exists.
When working with function of N variables
(xa,xb,xc) are then relative distances from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION.
KEYWORDS:
FUNC_NAME = function name (string)
Calling mechanism should be: F = func_name( px, gradient )
where:
px = scalar or vector of independent variables, input.
F = scalar value of function at px.
gradient = derivative of function, a scalar if 1-D,
a gradient vector if N-D,
(should only be computed if arg. is present).
POINT_NDIM = when working with function of N variables,
use this keyword to specify the starting point in N-dim space.
Default = 0, which assumes function is 1-D.
DIRECTION = when working with function of N variables,
use this keyword to specify the direction in N-dim space
along which to bracket the local minimum, (default=1 for 1-D).
(xa, xb, xc, x_min are then relative distances from POINT_NDIM)
MAX_ITER = maximum allowed number iterations, default=100.
TOLERANCE = desired accuracy of minimum location, default=sqrt(1.e-7).
OUTPUTS:
xmin = estimated location of minimum.
When working with function of N variables,
xmin is the relative distance from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION,
so that min. Loc. Pmin = Point_Ndim + xmin * Direction.
fmin = value of function at xmin (or Pmin).
CALLS: ***
CALL_FUNC_DERIV
CALLED BY:
MINF_CONJ_GRAD, conj_grad2, minF_partan
PROCEDURE:
Brent's method to minimize a function by using parabolic interpolation
and using first derivative of function,
from Numerical Recipes (by Press, et al.), sec.10.3 (p.287),
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
[Previous]
[Next]
NAME:
MINF_PARABOLIC
PURPOSE:
Minimize a function using Brent's method with parabolic interpolation
EXPLANATION:
Find a local minimum of a 1-D function up to specified tolerance.
This routine assumes that the function has a minimum nearby.
(recommend first calling minF_bracket, xa,xb,xc, to bracket minimum).
Routine can also be applied to a scalar function of many variables,
for such case the local minimum in a specified direction is found,
This routine is called by minF_conj_grad, to locate minimum in the
direction of the conjugate gradient of function of many variables.
CALLING EXAMPLES:
minF_parabolic, xa,xb,xc, xmin, fmin, FUNC_NAME="name" ;for 1-D func.
or:
minF_parabolic, xa,xb,xc, xmin, fmin, FUNC="name", $
POINT=[0,1,1], $
DIRECTION=[2,1,1] ;for 3-D func.
INPUTS:
xa,xb,xc = scalars, 3 points which bracket location of minimum,
that is, f(xb) < f(xa) and f(xb) < f(xc), so minimum exists.
When working with function of N variables
(xa,xb,xc) are then relative distances from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION.
INPUT KEYWORDS:
FUNC_NAME = function name (string)
Calling mechanism should be: F = func_name( px )
where:
px = scalar or vector of independent variables, input.
F = scalar value of function at px.
POINT_NDIM = when working with function of N variables,
use this keyword to specify the starting point in N-dim space.
Default = 0, which assumes function is 1-D.
DIRECTION = when working with function of N variables,
use this keyword to specify the direction in N-dim space
along which to bracket the local minimum, (default=1 for 1-D).
(xa, xb, xc, x_min are then relative distances from POINT_NDIM)
MAX_ITER = maximum allowed number iterations, default=100.
TOLERANCE = desired accuracy of minimum location, default=sqrt(1.e-7).
OUTPUTS:
xmin = estimated location of minimum.
When working with function of N variables,
xmin is the relative distance from POINT_NDIM,
in the direction specified by keyword DIRECTION,
with scale factor given by magnitude of DIRECTION,
so that min. Loc. Pmin = Point_Ndim + xmin * Direction.
fmin = value of function at xmin (or Pmin).
CALLED BY:
FITEXY, MINF_CONJ_GRAD, conj_grad2, minF_partan
PROCEDURE:
Brent's method to minimize a function by using parabolic interpolation.
Based on function BRENT in Numerical Recipes in FORTRAN (Press et al.
1992), sec.10.2 (p. 397).
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
Converted to IDL V5.0 W. Landsman September 1997
[Previous]
[Next]
NAME:
MINMAX
PURPOSE:
Return a 2 element array giving the minimum and maximum of an array
EXPLANATION:
Using MINMAX() is faster than doing a separate MAX and MIN.
CALLING SEQUENCE:
value = minmax( array )
INPUTS:
array - an IDL numeric scalar, vector or array.
OUTPUTS:
value = a two element vector (if DIMEN is not supplied)
value[0] = minimum value of array
value[1] = maximum value of array
If the DIMEN keyword is supplied then value will be a 2 x N element
array where N is the number of elements in the specified
dimension
OPTIONAL INPUT KEYWORDS:
/NAN - Set this keyword to cause the routine to check for occurrences
of the IEEE floating-point value NaN in the input data. Elements
with the value NaN are treated as missing data.
DIMEN - (V5.5 or later) integer (either 1 or 2) specifying which
dimension of a 2-d array to take the minimum and maximum. Note
that DIMEN is only valid for a 2-d array, larger dimensions are
not supported.
OPTIONAL OUTPUT KEYWORDS:
SUBSCRIPT_MAX and SUBSCRIPT_MIN Set either of these keywords to
named variables to return the subscripts of the MIN and MAX
values (V5.5 or later).
CALLED BY:
BATSE_FLARES_WEEK, BATSE_LAD_DRM, BATSE_SPEC_DRM, FIND_IX
FITS WRITER CLASS FOR ANY RHESSI DATA TYPES, FWD_CHI2, FWD_DISPLAY
GRS_EXTRACT, GRS_LIGHTCURVE, HESSI CLEAN ALGORITHM CLASS DEFINITION
HESSI IMAGE STRATEGY CLASS DEFINITION
HESSI MONITOR RATE CLASS DEFINITION, HESSI PACKET FILE ABSTRACT CLASS
HESSI RAW DATA READER, HESSI ROLL_DB CLASS DEFINITION
HESSI Score to Light Curve [2], HSI_ANY2SCTIME, HSI_APP100_UNPACK_TIME
HSI_DECIM_CORRECTION [1], HSI_DECIM_CORRECTION [2], HSI_EVENTLIST_TEST
HSI_EVFILE_TEST, HSI_Eventlist2Lightcurve, HSI_FILL_FORWARD, HSI_HIST_GROUP
HSI_LIGHTCURVE_TEST__define, HSI_LIVETIME_SIM, HSI_MODUL_PATTERN_PSF
HSI_RMAP_DIM, HSI_SCORE2FASTRATE_SUBPACKET, HSI_SCTIME2ANY
HSI_SPECTROGRAMCHAN_OVERLAP_FIX, HSI_SPECTROGRAM_DECIM_CORRECT
HSI_SPECTROGRAM_DECIM_TABLE, HSI_SPECTRUM__DEFINE, HSI_Score2Spectrum
JPLEPHINTERP, JPLEPHTEST, MODEL_to_SCORE [2], MOVIE_MAKER, OCC_AVG, OCC_FROM_FITS
PROFILES2, Pointing_Change, RAD_LOSS [1], RAD_LOSS [2], READ_CAL_SPEC
RESOLVE_NEW_OBS, ROUTINE_NAME [1], RUN_BATSE, SPECTROGRAM CLASS DEFINITION
SPECTRUM CLASS DEFINITION, SPEX_DRM__DEFINE, SPEX_FITINT__DEFINE
SPEX_FIT__DEFINE, SPEX_GEN__DEFINE, SPEX__DEFINE, Shers_load [1], XSM_VALID
countsmod_plot [1], countsmod_plot [2], drm_4_spex [1], drm_4_spex [2]
eit_parms, get_slider, hsi_aspect [1], hsi_aspect [2], hsi_calib_ev2vis
hsi_fits_header, hsi_image__getaxis [2], hsi_params2script
hsi_spectrogramACCBIN [2], hsi_spectrogram__define [1]
hsi_spectrogram__define [2], hsi_spectrogram__define [3]
hsi_spectrogram__get_obs [1], hsi_spectrogram__livetime [1], hsi_ui_flarecat
hsi_ui_img, hsi_ui_spec, model_to_score [1], out_spectra_4_designer
plot_goes_ospex, plotman, set_field, spec_plot [1], spec_plot [2], spec_plot [3]
spec_plot [4], spectro_plot, spectro_plot2, spectrogram__define
spex_bkint__define, spex_data__define, spex_data_strategy__define
spex_hessi_image__define, spex_intervals [1], spex_intervals [2]
spex_spec_plot [1], spex_spec_plot [2], spex_spec_plot [3], spex_spec_plot [4]
stretch_box
EXAMPLE:
(1) Print the minimum and maximum of an image array, im
IDL> print, minmax( im )
(2) Given a 2-dimension array of (echelle) wavelengths w, print the
minimum and maximum of each order (requires V5.5 or later)
print,minmax(w,dimen=1)
PROCEDURE:
The MIN function is used with the MAX keyword
REVISION HISTORY:
Written W. Landsman January, 1990
Converted to IDL V5.0 W. Landsman September 1997
Added NaN keyword. M. Buie June 1998
Added DIMENSION keyword W. Landsman January 2002
Added SUBSCRIPT_MIN and SUBSCRIPT_MAX BT Jan 2005
Check for IDL 5.5 or later, W. Thompson, 24-Feb-2005
[Previous]
[Next]
NAME:
MINMAX
PURPOSE:
Return a 2 element array giving the minimum and maximum of an array
EXPLANATION:
Using MINMAX() is faster than doing a separate MAX and MIN.
CALLING SEQUENCE:
value = minmax( array )
INPUTS:
array - an IDL numeric scalar, vector or array.
OUTPUTS:
value = a two element vector (if DIMEN is not supplied)
value[0] = minimum value of array
value[1] = maximum value of array
If the DIMEN keyword is supplied then value will be a 2 x N element
array where N is the number of elements in the specified
dimension
OPTIONAL INPUT KEYWORDS:
/NAN - Set this keyword to cause the routine to check for occurrences
of the IEEE floating-point value NaN in the input data. Elements
with the value NaN are treated as missing data.
DIMEN - integer (either 1 or 2) specifying which
dimension of a 2-d array to take the minimum and maximum. Note
that DIMEN is only valid for a 2-d array, larger dimensions are
not supported.
OPTIONAL OUTPUT KEYWORDS:
SUBSCRIPT_MAX and SUBSCRIPT_MIN Set either of these keywords to
named variables to return the subscripts of the MIN and MAX values.
CALLED BY:
BATSE_FLARES_WEEK, BATSE_LAD_DRM, BATSE_SPEC_DRM, FIND_IX
FITS WRITER CLASS FOR ANY RHESSI DATA TYPES, FWD_CHI2, FWD_DISPLAY
GRS_EXTRACT, GRS_LIGHTCURVE, HESSI CLEAN ALGORITHM CLASS DEFINITION
HESSI IMAGE STRATEGY CLASS DEFINITION
HESSI MONITOR RATE CLASS DEFINITION, HESSI PACKET FILE ABSTRACT CLASS
HESSI RAW DATA READER, HESSI ROLL_DB CLASS DEFINITION
HESSI Score to Light Curve [2], HSI_ANY2SCTIME, HSI_APP100_UNPACK_TIME
HSI_DECIM_CORRECTION [1], HSI_DECIM_CORRECTION [2], HSI_EVENTLIST_TEST
HSI_EVFILE_TEST, HSI_Eventlist2Lightcurve, HSI_FILL_FORWARD, HSI_HIST_GROUP
HSI_LIGHTCURVE_TEST__define, HSI_LIVETIME_SIM, HSI_MODUL_PATTERN_PSF
HSI_RMAP_DIM, HSI_SCORE2FASTRATE_SUBPACKET, HSI_SCTIME2ANY
HSI_SPECTROGRAMCHAN_OVERLAP_FIX, HSI_SPECTROGRAM_DECIM_CORRECT
HSI_SPECTROGRAM_DECIM_TABLE, HSI_SPECTRUM__DEFINE, HSI_Score2Spectrum
JPLEPHINTERP, JPLEPHTEST, MODEL_to_SCORE [2], MOVIE_MAKER, OCC_AVG, OCC_FROM_FITS
PROFILES2, Pointing_Change, RAD_LOSS [1], RAD_LOSS [2], READ_CAL_SPEC
RESOLVE_NEW_OBS, ROUTINE_NAME [1], RUN_BATSE, SPECTROGRAM CLASS DEFINITION
SPECTRUM CLASS DEFINITION, SPEX_DRM__DEFINE, SPEX_FITINT__DEFINE
SPEX_FIT__DEFINE, SPEX_GEN__DEFINE, SPEX__DEFINE, Shers_load [1], XSM_VALID
countsmod_plot [1], countsmod_plot [2], drm_4_spex [1], drm_4_spex [2]
eit_parms, get_slider, hsi_aspect [1], hsi_aspect [2], hsi_calib_ev2vis
hsi_fits_header, hsi_image__getaxis [2], hsi_params2script
hsi_spectrogramACCBIN [2], hsi_spectrogram__define [1]
hsi_spectrogram__define [2], hsi_spectrogram__define [3]
hsi_spectrogram__get_obs [1], hsi_spectrogram__livetime [1], hsi_ui_flarecat
hsi_ui_img, hsi_ui_spec, model_to_score [1], out_spectra_4_designer
plot_goes_ospex, plotman, set_field, spec_plot [1], spec_plot [2], spec_plot [3]
spec_plot [4], spectro_plot, spectro_plot2, spectrogram__define
spex_bkint__define, spex_data__define, spex_data_strategy__define
spex_hessi_image__define, spex_intervals [1], spex_intervals [2]
spex_spec_plot [1], spex_spec_plot [2], spex_spec_plot [3], spex_spec_plot [4]
stretch_box
EXAMPLE:
(1) Print the minimum and maximum of an image array, im
IDL> print, minmax( im )
(2) Given a 2-dimension array of (echelle) wavelengths w, print the
minimum and maximum of each order (requires V5.5 or later)
print,minmax(w,dimen=1)
PROCEDURE:
The MIN function is used with the MAX keyword
REVISION HISTORY:
Written W. Landsman January, 1990
Converted to IDL V5.0 W. Landsman September 1997
Added NaN keyword. M. Buie June 1998
Added DIMENSION keyword W. Landsman January 2002
Added SUBSCRIPT_MIN and SUBSCRIPT_MAX BT Jan 2005
[Previous]
[Next]
Project:
SPEX
NAME:
MJD2ANY
PURPOSE:
This function converts modified Julian days (MJD) to any of the anytim formats
MJD = JD - 2400000.5
JD is Julian Date
CATEGORY:
UTPLOT, TIME, BATSE
CALLING SEQUENCE:
time = mjd2any( item, /yoh)
INPUT:
Item - The input time in Modified Julian Day either as a numerical input or the
MJD structure available from anytim.pro
Form can be scalar or vector integer, long, float, double
OUTPUT:
The function returns the time in seconds from 1-jan-1979, ANYTIM
format or all anytim formats
CALLS: ***
anytim [1], anytim [2], anytim [3], anytim [4], anytim [5], chktag
KEYWORDS:
JULIAN - If set, input is in Julian days.
OUTPUT:
See anytim arguments
ERROR - set if there is an error in time conversion
CALLED BY:
SPEX_READ_FIT_RESULTS, read_hessi_4_ospex, read_hessi_4_spex [1]
read_hessi_4_spex [2]
RESTRICTIONS:
limited to output strings covered by ATIME.pro
HISTORY:
9-feb-2004, ras
MODIFIED:
[Previous]
[Next]
Project : SOHO - CDS
Name : MJD2DATE
Purpose : Converts MJD to year, month, and day.
Explanation : This procedure takes a Modified Julian Day number, and returns
the corresponding calendar date in year, month, day.
Use : MJD2DATE, MJD, YEAR, MONTH, DAY
Inputs : MJD = Modified Julian Day number.
Opt. Inputs : None.
Outputs : YEAR = Calendar year corresponding to MJD.
MONTH = Calendar month, from 1-12.
DAY = Calendar day, from 1-31, depending on the month.
Opt. Outputs: None.
Keywords : ERRMSG = If defined and passed, then any error messages
will be returned to the user in this parameter
rather than being handled by the IDL MESSAGE
utility. If no errors are encountered, then a null
string is returned. In order to use this feature,
the string ERRMSG must be defined first, e.g.,
ERRMSG = ''
MJD2DATE, MJD, YEAR, MONTH, DAY, ERRMSG=ERRMSG
IF ERRMSG NE '' THEN ...
Calls : None.
CALLED BY:
INT2UTC, MK_HEAD_CAT, STR2UTC [1], STR2UTC [2], STR2UTC [3]
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Time.
Prev. Hist. : None. However, part of the logic of this routine is taken from
DAYCNV by B. Pfarr, GSFC.
Written : William Thompson, GSFC, 13 September 1993.
Modified : Version 1, William Thompson, GSFC, 13 September 1993.
Version 2, Donald G. Luttermoser, GSFC/ARC, 28 December 1994.
Added the keyword ERRMSG. Note that there are no
internally called procedures that use the ERRMSG
keyword.
Version 3, Donald G. Luttermoser, GSFC/ARC, 30 January 1995.
Made the error handling procedure more robust. Note
that this routine handles both scalars and vectors as
input.
Version : Version 3, 30 January 1995.
[Previous]
[Next]
Project : SOHO - CDS
Name : MJD2STR
Purpose : Converts MJD to string format.
Explanation : This function takes a Modified Julian Day number, and returns
the corresponding calendar date as a string.
Use : DATE = MJD2DATE( MJD )
Inputs : MJD = Modified Julian Day number.
Opt. Inputs : None.
Outputs : Function returns string in the form 'yyyy-mm-dd'
Opt. Outputs: None.
Keywords : ERRMSG = If defined and passed, then any error messages
will be returned to the user in this parameter
rather than being handled by the IDL MESSAGE
utility. If no errors are encountered, then a null
string is returned. In order to use this feature,
the string ERRMSG must be defined first, e.g.,
ERRMSG = ''
DATE = MJD2DATE( MJD, ERRMSG=ERRMSG)
IF ERRMSG NE '' THEN ...
Calls : ***
TRIM
Common : None.
Restrictions: None.
Side effects: None.
Category : Utilities, Time.
Prev. Hist. : Based on MJD2DATE
Written : C D Pike, RAL 8-Jul-97
Modified :
Version : Version 1, 8-Jul-97.
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_24BIT
Purpose : scale image to 24 bit color table
Category : imaging
Syntax : mk_24bit,image,r,g,b
Inputs : IMAGE = input image
R,G,B = color table vectors
Outputs : IMAGE24 = scaled image
Keywords : NO_SCALE = set to not byte scale
CALLS: ***
PR_SYNTAX, data_chk [1], data_chk [2]
CALLED BY:
MAP2JPEG, MAP2MPEG, MK_MPEG, MK_PLAN_FORM, MK_PLAN_PLOT, PLOT_CDS_POINT [1]
PLOT_CDS_POINT [2]
History : Written 11 Jan 2000, D. Zarro, SM&A/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_8BIT
Purpose : scale image to 8 bit color table
Category : imaging
Syntax : mk_8bit,image,r,g,b
Inputs : IMAGE = input image
R,G,B = color table vectors
Outputs : IMAGE8 = scaled image
Keywords : None
CALLS: ***
PR_SYNTAX, data_chk [1], data_chk [2]
History : Written 21 Oct 2000, D. Zarro, EIT/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_AGIF
Purpose : Make animated GIF file from series of GIF files
Category : imaging
Explanation :
Syntax : IDL> mk_agif,gifs
CALLS: ***
BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3], CONCAT_DIR [1], CONCAT_DIR [2]
CONCAT_DIR [3], DATATYPE [1], DATATYPE [2], DATATYPE [3], ESPAWN, EXIST
LOC_FILE [1], LOC_FILE [2], LOC_FILE [3], RM_FILE, TEST_OPEN, TRIM, break_file [4]
concat_dir [4]
Examples :
Inputs : GIFS = filename with listing of GIF files
Opt. Inputs : None
Outputs : None
Opt. Outputs: None
Keywords : PATH = path to WHIRLGIF program
History : Written 22 March 1997, D. Zarro, ARC/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO - CDS
Name : MK_ANALYSIS()
Purpose : Create/initialize a CFIT ANALYSIS structure.
Explanation : A Component Fitting System (CFIT) ANALYSIS structure contains
all of the data blocks and the fitting structure associated
with one "block analysis" (e.g., (X)CFIT_BLOCK).
This facilitates a much more simple calling convention for
e.g.., CFIT_BLOCK and XCFIT_BLOCK.
This function returns a CFIT ANALYSIS structure, and
optionally initializes it by putting the supplied data blocks
in to the structure (on handles).
When you do not need an analysis structure anymore, you should
delete it with DELETE_ANALYSIS.
To simply create an analysis structure:
IDL> ana = mk_analysis()
To initialize it at once with data blocks:
IDL> ana = mk_analysis(lambda,data,weights,fit,$
missing,result,residual,include,const)
When called in this way, MK_ANALYSIS uses NO_COPY=1 when
setting the data on the structure's handles (thus making the
input variables undefined). To turn off this, set NO_COPY=0 in
the call to MK_ANALYSIS.
MK_ANALYSIS may also be used to make a COPY of an existing
analysis block, simply use:
IDL> ana2 = mk_analysis(source=ana)
to make an independent copy (new handles) of ANA.
To copy the contents of one existing analysis structure *into*
another analysis structure, use
IDL> ana2 = mk_analysis(source=ana,destination=ana2)
Here it is assumed that ana2 is an existing structure.
Use : ANALYSIS = MK_ANALYSIS()
Inputs :
Opt. Inputs : See the Explanation section, and e.g., CFIT_BLOCK.
Outputs : Returns a CFIT ANALYSIS structure.
Opt. Outputs: None.
Keywords : NO_COPY : Must be explicitly set to zero to turn off NO_COPY
behaviour.
Calls : ***
DEFAULT, EXIST, strextract
CALLED BY:
APPLY_CDS_ADEF, MK_CDS_ANALYSIS, RESTORE_ANALYSIS, XCDS_ANALYSIS, XCFIT_BLOCK
Common : None.
Restrictions: ?
Side effects: See NO_COPY keyword.
Category : Line fitting.
Prev. Hist. : None.
Written : SVH Haugan, UiO, 25 September 1997
Modified : Not yet.
Version : 1, 25 September 1997
[Previous]
[Next]
NAME:
MK_BSC_STR
PURPOSE:
Build the BSC data structure definition
SAMPLE CALLING SEQUENCE:
data = mk_bsc_str(1+2+4, 768)
data = mk_bsc_str(1+2+4, 768, ncopy=205)
data = mk_bsc_str(roadmap=roadmap)
data = mk_bsc_str(index=index)
index = mk_bsc_str(/sample_index)
index = mk_bsc_str(/sample_index, /fit)
INPUT:
datarectype - The bit pattern telling which data tags are
needed.
length - The length of the data arrays within the structure
(e.g.: the length of the wavelength/bin/counts array)
All tags will have the same number of elements
CALLS: ***
BSC_STRUCT [1], BSC_STRUCT [2], GEN_STRUCT [1], GEN_STRUCT [2], MAKE_STR [1]
MAKE_STR [2], bits [1], bits [2], str_merge [1], str_merge [2]
CALLED BY:
BCS_ACCUM [1], BCS_ACCUM [2], BSC_FIELD, MK_BSA_STC [1], MK_BSA_STC [2]
RD_BSC_DATA, dat2bsc, rdbda_smm
OPTIONAL KEYWORD INPUT:
ncopy - The number of copies of the structure to make. It
simply replicates the output structure "ncopy" times
roadmap - The BSC roadmap can be passed instead of datarectype/length
index - The BSC index can be passed instead of datarectype/length
sample_index - If set, return an index structure definition with
the nested .GEN and .BSC structures.
fit - If set, then return the nested .FIT structure when using
the /SAMPLE_INDEX option in addition to .GEN and .BSC
OUTPUT:
returns a BSC structure
OPTIONAL KEYWORD OUTPUT:
str - The structure definition of the output
HISTORY:
written 16-Dec-92 by Mons Morrison
3-Feb-93 (MDM) - Added DATA.FLUX capability
31-Jul-93 (SLF) - added /down to str_merge call
16-Sep-93 (MDM) - Added .WAVEC option (bit 6)
- Added /FIT option
2-Oct-93 (MDM) - Changed .WAVEC to WAVE_FIT and
changed .FIT to .FLUX_FIT
- Changed the order that the data tags are built
8-Nov-93 (MDM) - Added .FLUX_FIT2 (bit 8)
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_CDS_IMAP
Purpose : Make an image map from a CDS QL structure
Category : imaging
Syntax : map=mk_cds_imap(ql)
Inputs : QL = CDS quicklook data stucture
Outputs : MAP = map structure
Keywords : SUM = sum intensities over window wavelength
WRANGE = wavelength range to sum over
CALLS: ***
AVERAGE, CDS_WAVE_LABEL, EXIST, GET_ARR_CENTER, GT_BIMAGE, GT_CDS_WINDOW
GT_DIMENSION, GT_DURATION, GT_IIMAGE, GT_MIMAGE, GT_SOLAR_XY, GT_START, GT_WINSIZE
GT_WLIMITS, MAKE_MAP, MERGE_STRUCT, NUM2STR, QLMGR, TRIM2
CALLED BY:
MK_CDS_MAP
History : Written 22 October 1996, D. Zarro, ARC/GSFC
Modified 1 Sept 1999, Zarro (SM&A/GSFC)
-- added call to gt_solar_xy for more accurate pointing
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_CDS_MAP
Purpose : Make an image map from a CDS QL structure
Category : imaging
Syntax : map=mk_cds_map(ql,window)
Inputs : QL = CDS quicklook data stucture or CDS FITS file
WINDOW = window number
Outputs : MAP = map structure
Keywords : CLEAN = clean Cosmic ray hits
PEAK = use peak intensity
NO_CALIB = do not calibrate data
WRANGE = wavelength range over which to sum spectra
CALLS: ***
CDS_CLEAN_EXP, COPY_QLDS, DATATYPE [1], DATATYPE [2], DATATYPE [3], DELETE_QLDS
EXIST, GET_TAG_VALUE, GT_CDS_WINDOW, GT_DIMENSION, MERGE_STRUCT, MK_CDS_IMAP
MK_CDS_SMAP, NIS_ROTATE, READCDSFITS, VALID_MAP, VALID_QL, VDS_CALIB
CALLED BY:
FIT_CDS_MAP
History : Written 22 October 1996, D. Zarro, ARC/GSFC
Modified 1 September 1999, Zarro (SM&A/GSFC)
-- removed UPD_CDS_POINT call (done in READCDSFITS)
-- added rotate keyword
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_CDS_SMAP
Purpose : Make an image map from a CDS QL structure in which
slit spectrogram mode is used
Category : imaging
Syntax : map=mk_cds_smap(aa)
Inputs : aa = CDS quicklook data stucture
window = window number
Outputs : MAP = map structure
CALLS: ***
AVERAGE, CDS_WAVE_LABEL, EXIST, GET_ARR_CENTER, GT_CDS_WINDOW, GT_DIMENSION
GT_DURATION, GT_SOLAR_XY, GT_START, GT_WINDATA, MAKE_MAP, MERGE_STRUCT, QLMGR
CALLED BY:
MK_CDS_MAP
History : Written 22 June 1997, D. Zarro, ARC/GSFC
Modified 1 Sept 1999, Zarro (SM&A/GSFC)
-- added call to gt_solar_xy for more accurate pointing
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO - CDS
Name : mk_comp_bgauss()
Purpose : Create a structure describing the fit component "bgauss"
Explanation : Creates a Component Fit sub-structure describing a single
Gaussian component with broadened left and right wings.
Initial values for the five parameters, INTENSITY, POSITION,
FWHM, B_AMP, ASYM, are supplied as a 5-element array parameter.
All the initial values are supplied as NOMINAL values, except
when the VELOCITY keyword is DEFINED - this causes the
POSITION to be interpreted as a wavelength, the correct linear
transformation coefficients are calculated and the nominal
velocity value is taken from the contents of the VELOCITY
keyword.
Velocities are assumed to be in km/s
When the VELOCITY keyword is used, the default linear
transformation coefficients are set up to make BLUESHIFTS
correspond to POSITIVE velocities. If you're an observational
solar physicist, you'll probably want to switch the sign of
the TRANS_A tag of parameter 1 to get it the other way
around, i.e.:
comp = mk_comp_bgauss([10,300.0,0.3,0,0],velocity=0.0)
comp.param(1).trans_a = - comp.param(1).trans_a
The evaluation function for a broadened Gaussian component is
COMP_BGAUSS, taking three actual parameter values with the same
meaning as the three first parameters determined in GAUSSFIT,
i.e.:
G(x) = A0 * EXP(-((x-A1)/A2)^2/2)
The wings are defined as
W(x) = A0 * Alpha / ( ((x-A1)/(Kappa*A2))^2 + 1 )
where Kappa=2*SQRT(2*ALOG(2)) and Alpha is defined as
Alpha = A3 ;x GE A1 (right wing)
Alpha = A3 * A4 ;x LT A1 (left wing)
The broadened Gaussian is then defined as
F(x) = (1 - Alpha) * G(x) + W(x)
The nominal and actual parameter values are related by:
ACTUAL = NOMINAL * TRANS_A + TRANS_B
where e.g., TRANS_A defaults to 0.5/sqrt(2*alog(2)) for the
width parameter to be interpreted as the full width at half
maximum (FWHM).
Use : COMP = MK_COMP_BGAUSS(INT_POS_FWHM)
Inputs : INT_POS_FWHM : An array with 5 initial values for the
parameters of the Gaussian - intensity, position
and full width at half maximum, wing broadening
amplitude, and the left/right wing asymmetry.
If the VELOCITY keyword is DEFINED, the position
is interpreted as a lab wavelength, and the
linear transformation coefficients for the
velocity are calculated from that. The value of
VELOCITY is used as the nominal initial value.
Opt. Inputs : None.
Outputs : Returns structure.
Opt. Outputs: None.
Keywords : CONST : An array with 5 (byte) values, a nonzero entry means
the corresponding parameter is kept constant.
MAX_ARR : An array of maximum (nominal) parameter values.
MIN_ARR : An array of minimum (nominal) parameter values.
TRANS_A : An array with the linear transformation A values for
the parameters. Normally this is only used by the
programs written by e.g., PRINT_CFIT,..,/PROGRAM
TRANS_B : Array with linear transformation B values. See
TRANS_A
VELOCITY : Set this equal to the initial velocity if you want
the line position represented by the velocity
relative to a lab wavelength - the lab wavelength
is taken from the supplied POSITION, i.e.,
INT_POS_FWHM(1).
MAX_INTENS, MIN_INTENS, MAX_VEL, MIN_VEL, MAX_LAM, MIN_LAM,
MAX_FWHM, MIN_FWHM, MAX_B_AMP, MIN_B_AMP, MAX_ASYM, MIN_ASYM :
These keywords are alternative methods of specifying
min/max limits.
Calls : ***
DEFAULT, MK_COMPONENT_STC, TRIM
CALLED BY:
XCFIT
Common : None.
Restrictions: None.
Side effects: The output structure will initially be defined to hold the
B_AMP and ASYM parameters constant, unless otherwise specified.
The routine XCFIT should put in sensible values for these
parameters for the CDS NIS-1 and NIS-2 spectra.
Category : Analysis
Prev. Hist. : Modified from MK_COMP_GAUSS by S.V.H. Haugan.
Written : William Thompson, GSFC, 05-Jan-1999
Modified : Version 1, 05-Jan-1999, William Thompson, GSFC
Version : Version 1, 05-Jan-1999
[Previous]
[Next]
Project : SOHO - CDS
Name : mk_comp_gauss()
Purpose : Create a structure describing the fit component "gauss"
Explanation : Creates a Component Fit sub-structure describing a single
gaussian component. Initial values for the three parameters,
INTENSITY, POSITION, FWHM are supplied as a 3-element array
parameter.
All the initial values are supplied as NOMINAL values, except
when the VELOCITY keyword is DEFINED - this causes the
POSITION to be interpreted as a wavelength, the correct linear
transformation coefficients are calculated and the nominal
velocity value is taken from the contents of the VELOCITY
keyword.
Velocities are assumed to be in km/s
When the VELOCITY keyword is used, the default linear
transformation coefficients are set up to make BLUESHIFTS
correspond to POSITIVE velocities. If you're an observational
solar physicist, you'll probably want to switch the sign of
the TRANS_A tag of parameter 1 to get it the other way
around, i.e.:
comp = mk_comp_gauss([10,300.0,0.3],velocity=0.0)
comp.param(1).trans_a = - comp.param(1).trans_a
The evaluation function for a gaussian component is
COMP_GAUSS, taking three actual parameter values with the same
meaning as the three first parameters determined in GAUSSFIT,
i.e.:
F(x) = A0*EXP(-((x-A1)/A2)^2/2)
The nominal and actual parameter values are related by:
ACTUAL = NOMINAL * TRANS_A + TRANS_B
where e.g., TRANS_A defaults to 0.5/sqrt(2*alog(2)) for the
width parameter to be interpreted as the full width at half
maximum (FWHM).
Use : COMP = MK_COMP_GAUSS(INT_POS_FWHM)
Inputs : INT_POS_FWHM : An array with 3 initial values for the
parameters of the gaussian - intensity,
position and full width at half maximum. If
the VELOCITY keyword is DEFINED, the position
is interpreted as a lab wavelength, and the
linear transformation coefficients for the
velocity is calculated from that. The value of
VELOCITY is used as the nominal initial value.
Opt. Inputs : None.
Outputs : Returns structure.
Opt. Outputs: None.
Keywords : CONST : An array with 3 (byte) values, a nonzero entry means
the corresponding parameter is kept constant.
MAX_ARR : An array of maximum (nominal) parameter values.
MIN_ARR : An array of minimum (nominal) parameter values.
TRANS_A : An array with the linear transformation A values for
the parameters. Normally this is only used by the
programs written by e.g., PRINT_CFIT,..,/PROGRAM
TRANS_B : Array with linear transformation B values. See
TRANS_A
VELOCITY : Set this equal to the initial velocity if you want
the line position represented by the velocity
relative to a lab wavelength - the lab wavelength
is taken from the supplied POSITION, i.e.,
INT_POS_FWHM(1).
MAX_INTENS, MIN_INTENS, MAX_VEL, MIN_VEL, MAX_LAM, MIN_LAM,
MAX_FWHM, MIN_FWHM : These keywords are alternative methods
of specifying min/max limits.
Calls : ***
DEFAULT, MK_COMPONENT_STC, TRIM
CALLED BY:
CFIT_ERRDEMO, XCFIT
Common : None.
Restrictions: None.
Side effects: None.
Category : Analysis
Prev. Hist. : None.
Written : S.V.H.Haugan, UiO, 21 January 1997
Modified : Version 2, SVHH, 9 May 1997
Fixed a bug with initial/max values when in "implied
velocity mode".
Version 3, SVHH, 27 May 1997
Changed default values of min/max intensities to
relate to the initial intensity.
Version : 3, 27 May 1997
[Previous]
[Next]
Project : SOHO - CDS
Name : mk_comp_poly()
Purpose : Create a structure describing a polynomial fit component
Explanation : Creates an Nth order polynomial component for the component
fit system.
Use : COMP = MK_COMP_POLY( DEGREE_COEFF )
Inputs : DEGREE_COEFF : Either a scalar giving the degree of the
polynomial, or an array of the initial values
for the coefficients - implicitly determining
the polynomial degree.
Opt. Inputs : None.
Outputs : Returns component structure
Opt. Outputs: None.
Keywords : MAX_ARR : Array of maximum values for the coefficients.
MIN_ARR : Array of minimum values for the coefficients.
TRANS_A : Array of linear transformation A coefficients.
TRANS_B : Array of linear transformation B coefficients.
CONST : Array of (bytes) signifying which coefficients are to
be kept constant.
Calls : ***
DEFAULT, MK_COMPONENT_STC, TRIM
CALLED BY:
CFIT_ERRDEMO, XCFIT, XCFIT_BLOCK
Common : None.
Restrictions: None.
Side effects: None.
Category : Analysis
Prev. Hist. : None.
Written : S.V.H.Haugan, UiO, 21 January 1997
Modified : Not yet.
Version : 1, 21 January 1997
[Previous]
[Next]
Project : SOHO - CDS
Name : mk_comp_ppoly()
Purpose : Create a structure for a pivoted polynomial fit component
Explanation : Creates an Nth order pivoted polynomial component for the
component fit system. The first parameter is the pivot value.
The remaining parameters are the standard parameters for the
polynomial. The result is returned as
A1 + A2*(X-A0) + A3*(X-A0)^2 + ...
The normal usage is to hold A0 constant at a value within the
range of X, while fitting the remaining parameters. Since X-A0
is close to zero, roundoff errors are minimized.
Use : COMP = MK_COMP_PPOLY( DEGREE_COEFF )
Inputs : DEGREE_COEFF = Either a scalar giving the degree of the
polynomial, or an array of the initial values
for the coefficients - implicitly determining
the polynomial degree.
Opt. Inputs : None.
Outputs : Returns component structure
Opt. Outputs: None.
Keywords : MAX_ARR : Array of maximum values for the coefficients.
MIN_ARR : Array of minimum values for the coefficients.
TRANS_A : Array of linear transformation A coefficients.
TRANS_B : Array of linear transformation B coefficients.
CONST : Array of (bytes) signifying which coefficients are to
be kept constant. If not passed, then the pivot value
(first parameter) is held constant.
PIVOT : The pivot value. If DEGREE_COEFF is passed as an
array, then this keyword will override the pivot value.
Calls : ***
DEFAULT, MK_COMPONENT_STC, TRIM
Common : None.
Restrictions: None.
Side effects: None.
Category : Analysis
Prev. Hist. : From mk_comp_poly by S.V.H.Haugan, UiO, 21 January 1997
History : Version 1, 17-Feb-2000, William Thompson, GSFC
Version : Version 1, 17-Feb-2000
[Previous]
[Next]
Project : SOHO - CDS
Name : mk_comp_voigt()
Purpose : Create a structure describing the fit component "voigt"
Explanation : Creates a Component Fit sub-structure describing a single
Voigt component. Initial values for the four parameters,
INTENSITY, POSITION, WIDTH, RWIDTH, are supplied as a
4-element array parameter.
All the initial values are supplied as NOMINAL values, except
when the VELOCITY keyword is DEFINED - this causes the
POSITION to be interpreted as a wavelength, the correct linear
transformation coefficients are calculated and the nominal
velocity value is taken from the contents of the VELOCITY
keyword.
Velocities are assumed to be in km/s
When the VELOCITY keyword is used, the default linear
transformation coefficients are set up to make BLUESHIFTS
correspond to POSITIVE velocities. If you're an observational
solar physicist, you'll probably want to switch the sign of
the TRANS_A tag of parameter 1 to get it the other way
around, i.e.:
comp = mk_comp_voigt([10,300.0,0.3,1.5],velocity=0.0)
comp.param(1).trans_a = - comp.param(1).trans_a
The evaluation function for a Voigt component is COMP_VOIGT,
taking four actual parameter values for the amplitude, line
position, doppler width, and transition rate. The Voigt
profile is then evaluated as
PVOIGT, ABS(A3/A2), (x-A1)/A2, H
F(x) = A0 * H(x) / (SQRT(!PI)*A2)
The nominal and actual parameter values are related by:
ACTUAL = NOMINAL * TRANS_A + TRANS_B
Use : COMP = MK_COMP_VOIGT(INT_POS_WIDTH)
Inputs : INT_POS_WIDTH : An array with 4 initial values for the
parameters of the function - intensity,
position, doppler width, and transition rate.
If the VELOCITY keyword is DEFINED, the
position is interpreted as a lab wavelength,
and the linear transformation coefficients for
the velocity are calculated from that. The
value of VELOCITY is used as the nominal
initial value.
Opt. Inputs : None.
Outputs : Returns structure.
Opt. Outputs: None.
Keywords : CONST : An array with 4 (byte) values, a nonzero entry means
the corresponding parameter is kept constant.
MAX_ARR : An array of maximum (nominal) parameter values.
MIN_ARR : An array of minimum (nominal) parameter values.
TRANS_A : An array with the linear transformation A values for
the parameters. Normally this is only used by the
programs written by e.g., PRINT_CFIT,..,/PROGRAM
TRANS_B : Array with linear transformation B values. See
TRANS_A
VELOCITY : Set this equal to the initial velocity if you want
the line position represented by the velocity
relative to a lab wavelength - the lab wavelength
is taken from the supplied POSITION, i.e.,
INT_POS_WIDTH(1).
MAX_INTENS, MIN_INTENS, MAX_VEL, MIN_VEL, MAX_LAM, MIN_LAM,
MAX_WIDTH, MIN_WIDTH, MIN_RWIDTH, MAX_RWIDTH :
These keywords are alternative methods of specifying
min/max limits.
Calls : ***
DEFAULT, MK_COMPONENT_STC, TRIM
CALLED BY:
XCFIT
Common : None.
Restrictions: None.
Side effects: None.
Category : Analysis
Prev. Hist. : Modified from MK_COMP_GAUSS by S.V.H. Haugan.
Written : William Thompson, GSFC, 08-Jan-1999
Modified : Version 1, 12-Jan-1999, William Thompson, GSFC
Version : Version 1, 12-Jan-1999
[Previous]
[Next]
Project : SOHO - CDS
Name : MK_COMPONENT_STC()
Purpose : Return structure describing N-parameter fitting component
Explanation : This function creates a "dummy" structure to be filled in by
more specific routines, like MK_COMP_GAUSS() or
MK_COMP_POLY().
Use : STC = MK_COMPONENT_STC(NPARM)
Inputs : NPARM : The number of parmeters
Opt. Inputs : None.
Outputs : None.
Opt. Outputs: None.
Keywords : DOUBLE : Set to make parameters doubles
Calls : ***
DEFAULT, MK_PARAMETER_STC, TRIM
CALLED BY:
mk_comp_bgauss, mk_comp_gauss, mk_comp_poly, mk_comp_ppoly, mk_comp_voigt
Common : None.
Restrictions: None.
Side effects: None.
Category : Analysis
Prev. Hist. : None.
Written : S.V.H.Haugan, UiO, 21 January 1997
Modified : Not yet.
Version : 1, 21 January 1997
[Previous]
[Next]
PROJECT:
SSW/XRAY
Name:
MK_CONTIGUOUS
PURPOSE:
This routine checks that a set input EDGES are dimensioned 2xN and
that the hi and lo edges match for adjacent channels. If they don't match,
it produces a set of new edge bins, CEDGES, that are contiguous. Finally,
it also creates a set of indices, INDX, that have this relationship,
EDGES = CEDGES[*,INDX]
CALLING SEQUENCE:
mk_contiguous, edges, cedges, old_index, test=test, epsilon=epsilon
INPUTS:
EDGES - 2xN edges to test if they hi and lo edges of each bin are
contiguous to the neighboring bins.
EPSILON - optional keyword, default value of 1e-5. Fractional criterion
to determine whether edges[1, i] eq edges[0,i+1], so the test of
equality is abs(edges[1,i]-edges[0,i+1]) le epsilon*edges[1,i]
OUTPUTS:
CEDGES - new contiguous 2x(N+m) edges if needed
INDX - indices that map the new CEDGES into the EDGES, i.e. EDGES = CEDGES[INDX]
TEST - returns 0 or 1, If 1, cedges aren't needed and aren't created,
original EDGES are contiguous
CALLS: ***
DEFAULT, GET_EDGES
CALLED BY:
F_VTH
RESTRICTIONS:
MODIFICATION HISTORY:
29-Mar-2006, richard.schwartz@gsfc.nasa.gov
25-aug-2006, ras, forms contiguous edges using get_edges(/cont)
30-Aug-2006, Kim. Correct 25-aug mod - use /edges_2, and epsilon misspelled
[Previous]
[Next]
Project : SOHO - CDS
Name : MK_DFONT
Purpose : make some uniformly useful fonts for planning software
Category : utility
Explanation :
Syntax : IDL> mk_dfont,lfont=lfont,bfont=bfont
Inputs : None
Opt. Inputs : None
Outputs : See keywords
Opt. Outputs: None
Keywords : LFONT = a label font
BFONT = a button font
TFONT = a text font
DEFAULT = use default font if one of above does not exist
(otherwise, used fixed font)
CALLS: ***
EXIST, GET_DFONT [1], GET_DFONT [2], IS_STRING, OS_FAMILY
CALLED BY:
CD_DELETE_FILES, CD_LOAD_CDROM, CD_SUMER, EIS_CAT [1], EIS_CAT [2]
EIS_IMAGE_TOOL [1], EIS_IMAGE_TOOL [2], EIS_ITOOL_PTOOL [1]
EIS_ITOOL_PTOOL [2], GE_WINDOW_SIM, ITOOL_LIMBFITTER, ITOOL_OVERLAYER
ITOOL_PICKFILE, ITOOL_PTOOL, MK_CDS_DBASE, MK_CDS_PLAN, MK_PLAN_CUSTOM
MK_PLAN_SBASE, MK_SOHO_CUSTOM, MK_STUDY, PROGMETER, ROUTINE_NAME [4]
ROUTINE_NAME [7], SCANPATH, SHOW_SYNOP__DEFINE, ST_SUMER, ST_SUMER_WIN
SYNOP_DEFINE, TKI_PHOTO_BASE, TKI_SCL2OBJgroupgroup, XACK, XANSWER, XCALENDAR, XCAMP
XCAT, XCHOICE, XCLONE_PLAN, XCPT, XIAP, XINPUT, XLIST, XPORT, XPROGRAM, XPROGRAM_ADD
XPS_SETUP, XREPORT, XREPORT_EDIT, XSEL_LIST [1], XSEL_LIST [2], XSHOW_RASTER, XSPECT
XSTRUCT, XSTUDY, XTEXT, XTKI, XZOOM_PLAN, ethz_XCHOICE, xpickfile, xpickfile2
History : 17-Aug-1996, D M Zarro - written
16-Feb-2004, Zarro (L-3Com/GSFC) - optimized with common
Contact : DZARRO@SOLAR.STANFORD.EDU
[Previous]
[Next]
Project : HESSI
Name : MK_DIR
Purpose : wrapper around FILE_MKDIR that catches errors
Category : system utility
Syntax : IDL> mk_dir,dir
Outputs : None
CALLS: ***
CHKLOG [1], CHKLOG [2], CHMOD, ERR_STATE, ESPAWN, IS_BLANK, IS_DIR, SINCE_VERSION [1]
SINCE_VERSION [2], is_struct
CALLED BY:
EIT_GBO, EIT__DEFINE, FILE2FID, FTP_SYNOP, MK_SUB_DIR, MK_TEMP_DIR, RD_GOES_SDAC
TRACE_GBO, WR_MOVIE, rd_week_file [2], synop_link, uncompress, weekid [2]
ydb_exist [2]
History : 17 Apr 2003, Zarro (EER/GSFC)
13 Apr 2004, Zarro (L-3Com/GSFC) - added CHMOD
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
NAME:
mk_ebar
PURPOSE:
to compute error bars for a set of data arrays
CALLING SEQUENCE:
ebar=mk_ebar(a1,a2,a3,a4,a5,a6,a7,a8,a9,10)
INPUTS:
a= input arrays
OUTPUTS:
ebar = uncertainty array
KEYWORDS:
amean = mean of input arrays
RESTRICTIONS:
can handle up to 10 dimensions
PROCEDURE:
takes average of each element in input vector
MODIFICATION HISTORY:
Written by DMZ (ARC) March 1994
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_EIT_MAP
Purpose : Make an image map from EIT FITS data
Category : imaging
Syntax : map=mk_eit_map(data,header) or mk_eit_map(index,data)
Inputs : DATA,HEADER = FITS image/header combination
INDEX,DATA = index/data combination
Outputs : MAP = map structure
Keywords : SUB = set to compute subarray
OUTSIZE = output size of data
CALLS: ***
ADD_PROP, CONGRID [1], CONGRID [2], CONGRID [3], DATATYPE [1], DATATYPE [2]
DATATYPE [3], DELVARX [1], DELVARX [2], DELVARX [3], DELVARX [4], EIT_PREP, EXIST
EXPTV, GET_FITS_PAR, LOC_FILE [1], LOC_FILE [2], LOC_FILE [3], MAKE_MAP, NUM2STR
PR_SYNTAX, TVSUBIMAGE, data_chk [1], data_chk [2], delvarx [5], read_eit
CALLED BY:
DO_EIT_MAP, LOCATE_FFCAL
History : Written 22 January 1997, D. Zarro, ARC/GSFC
Modified 31 Oct 2000, Zarro (EIT/GSFC) - added file input option; Modified July 9, 2003 Zarro (EER/GSFC) - check SOHO orientation
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : HESSI
Name : MK_FID
Purpose : create FID directory (named YYMMDD based on date/time)
Category : utility system
Syntax : mk_fid,root,times
Inputs : ROOT = root directory under which to create subdir named FID
TIMES = array of times to compute FID
Keywords : ERR= error string
OUT_DIR = created directory names
CALLS: ***
CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3], EXIST, MK_SUB_DIR, TEST_DIR
TIME2FID, concat_dir [4]
CALLED BY:
SITE__DEFINE
History : Written, 3 March 2000, D. Zarro (SM&A/GSFC)
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : HESSI
Name : MK_FILE
Purpose : create an empty file
Category : system utility
Syntax : IDL> mk_file,name
Inputs : NAME = filename to create (with path, otherwise
create in current directory)
Outputs : None
Keywords : None
CALLS: ***
BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3], ESPAWN, EXIST, IS_STRING
LOC_FILE [1], LOC_FILE [2], LOC_FILE [3], OS_FAMILY, TEST_DIR, TRIM, break_file [4]
curdir [1], curdir [2]
History : 18-Oct-2000, Zarro (EIT/GSFC), written
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
NAME:
mk_fits_head
PURPOSE:
Given a data array, build the minimal FITS header.
CALLING SEQUENCE:
head = mk_fits_head(data)
head = mk_fits_head(data, time='17:00:01', date='27-Oct-92')
INPUT:
data - The data array
CALLS: ***
GET_NBYTES, data_type [1], data_type [2]
CALLED BY:
DISPLOI_MON5K, mk_limb_pixmap, mk_mdi_fits, norik_name_fix, raw_list2pixmap
rd_hirsaiso, read_mdi, wrt_fits [1], wrt_fits [2]
OPTIONAL KEYWORD INPUT:
time - Time that the image was taken
date - The date that the image was taken
comment - Optional comments
history - Optional history information
OUTPUT:
ASCII string array with the FITS header. The length is only the
length used, and the END string is not included
HISTORY:
Written 27-Oct-92 by M.Morrison
2-Feb-93 (MDM) - Modified to save floating points properly
17-Mar-94 (MDM) - Modified to make the string length 80
characters
28-Jun-94 (MDM) - Modified to save double points properly
30-Aug-96 (MDM) - Modified to shift the values over 1 character
to be proper FITS standard.
[Previous]
[Next]
Name: mk_formt_html
Purpose: make FORM-ready html segment for times (start [and stop])
Input Paramters:
start_select - set default start time
stop_select - set default stop time
Calling Sequence:
outarray=mk_formt_html(start_select [,stop_select], t0=tim0, t1=tim1)
CALLS: ***
SELECT_MENU, STR2ARR [1], STR2ARR [2], data_chk [1], data_chk [2], fmt_tim [1]
fmt_tim [2], str_replace [1], str_replace [2], strcapitalize [1]
strcapitalize [2], timegrid, ut_time [1], ut_time [2]
CALLED BY:
html_form_addtime [1], html_form_addtime [2], html_form_addtime [3]
History:
1-Jan-1996 (Circa) - S.L.Freeland - for auto-WWW FORM generation
12-Jan-1997 - S.L.Freeland - head off millenium crisis
(call anytim)
auto-range if select times
not within TIMERANGE
[Previous]
[Next]
PROJECT:
SOHO - CDS
NAME:
MK_GIF
PURPOSE:
Convert FITS files to GIF image files
EXPLANATION:
Reads one or more FITS files, byte scales them, and then
writes them to GIF files. If a title is to be plotted, it
will be plotted in upper center position.
CALLING SEQUENCE:
MK_GIF, FILE_STC
INPUTS:
FILE_STC - A structure with three tags:
FILENAME -- Name of the FITS file
TITLE -- Title to be attached in the GIF image
COLOR -- Color table to be loaded; defaults to 0
FLIP -- Flag indicating if the image should be flipped
before conversion.
GAMMA -- Gamma value used for changing the color table.
If gamma value is negative, the image is
logrithum scaled first before gamma correction
is made
TOP -- Portion of top color (0 to 100) to be used
BOTTOM -- Portion of bottom color (0 to 100) to be used
MIN -- String, minimum value to be used for byte scaling
MAX -- String, maximum value to be used for byte scaling
REBIN -- Factor of rebinning; defaults to 1
ICON -- If positive, create "iconized" GIF image as well;
its value also indicates rebinning factor for the
iconized image
ICON_STR -- Title to be used in iconized image
ICON_FNAME - Full name of iconized GIF image
OPTIONAL INPUTS:
None.
OUTPUTS:
None.
OPTIONAL OUTPUTS:
None.
KEYWORD PARAMETERS:
RED, GREEN, BLUE - optional color vectors to override COLOR
FRAC - fraction by which to increase image
size in Y-direction to fit title [def = 10%]
ROTATE - value for rotate (see ROTATE function)
FLIP - flip image to to bottom
RVS - flip (reverse) image left to right
SIG - select significant range of image
CALLS: ***
BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3], CHG_CTABLE, CONCAT_DIR [1]
CONCAT_DIR [2], CONCAT_DIR [3], CONGRID [1], CONGRID [2], CONGRID [3]
DATATYPE [1], DATATYPE [2], DATATYPE [3], DPRINT, EIT_PREP, EXIST, EXTEND_MATRIX
FXPAR [1], FXPAR [2], FXREAD [1], FXREAD [2], LOADCT, LOAD_EIT_COLOR, RESCALE_IMAGE
REVERSE, SIGRANGE [1], SIGRANGE [2], SSW_WRITE_GIF, TRIM, break_file [4]
concat_dir [4]
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
CATEGORY:
PREVIOUS HISTORY:
Written December 7, 1994, Liyun Wang, GSFC/ARC
MODIFICATION HISTORY:
Version 1, Liyun Wang, GSFC/ARC, December 7, 1994
Modified from FITS2GIF by Dominic Zarro (ARC)
Version 2, Liyun Wang, GSFC/ARC, February 1, 1995
Added one tag (FLIP) to the input file structure.
Version 3, August 16, 1995, Liyun Wang, GSFC/ARC
Used the ERRMSG keyword in the call to FXREAD so that the
loop can last if error occurs in reading a FITS file
Version 4, March 8, 1996, Liyun Wang, GSFC/ARC
Added EIT image auto-scaling, auto-color table loading
Version 5, April 4, 1996, Liyun Wang, GSFC/ARC
Implemented making iconized GIF files
Version 6, December 20, 1996, Liyun Wang, NASA/GSFC
Modified such that iconized images will have a fix width of
256 pixels, as long as FILE_STC.ICON is greater than 1
Version 7, January 28, 1997, Liyun Wang, NASA/GSFC
Modified such that if FILE_STC.REBIN is greater than 1 the
image is rebined to 512 pixel wide (instead of treating
FILE_STC.REBIN as a rebin factor)
Version 8, July 16, 1997, Liyun Wang, NASA/GSFC
Made call to EIT_PREP if env variable SSW_EIT is set
Version 9, William Thompson, GSFC, 8 April 1998
Changed !D.N_COLORS to !D.TABLE_SIZE for 24-bit displays
Version 10, 13-Aug-2003, William Thompson
Use SSW_WRITE_GIF instead of WRITE_GIF
VERSION:
Version 9, 8 April 1998
[Previous]
[Next]
NAME:
MK_GRID_COORDS
PURPOSE:
CATEGORY:
CALLING SEQUENCE:
INPUTS:
POSITIONAL PARAMETERS:
KEYWORDS PARAMETERS:
OUTPUTS:
POSITIONAL PARAMETERS:
KEYWORDS PARAMETERS:
CALLS: ***
REPVEC [1], REPVEC [2]
CALLED BY:
DRAW_GRID [1], DRAW_GRID [2], DRAW_GRID [3]
COMMON BLOCKS:
SIDE EFFECTS:
RESTRICTIONS:
PROCEDURE:
EXAMPLE:
MODIFICATION HISTORY:
July, 1992. - Written by GLS, LMSC.
[Previous]
[Next]
PROJECT:
SOHO - CDS
NAME:
MK_HELP_STC()
PURPOSE:
To create a help structure to be used in help mode
EXPLANATION:
This routine reads in a help file and creates a structure
whose tag names are help topics, and whose tag values are
string arrays or scalars corresponding to the topics. The help
file it reads should be in the same format as that readable by
WIDG_HELP. The only restricion is that the string for a help
topic can not exceed 15 characters (the rest of characters
will be truncated). Also the space between words in a help
topic will be converted into the underscore character in the
tag names.
CALLING SEQUENCE:
Result = mk_help_stc(help_file)
INPUTS:
HELP_FILE - The name of a file that contains the help
information to display. This program searches for a
file with this name first in the current directory,
and then in !PATH, and searches for the name by
itself, and with '.hlp' appended after it.
The file consists of a series of topic headers
followed by a text message about that topic. The
topic headers are differentiated by starting with
the "!" character in the first column (if the
keyword SEP_CHAR not set) or the character
specified via the SEP_CHAR keyword. For example,
!Overview
This is the overview for the
topic at hand.
!Button1
This is the help explanation
for button 1
etc.
The program assumes that the first line in the file
(except commentary lines or blank lines) contains
the first topic. Also, there must be at least one
line between any two topics. Thus,
!Button2
!Button3
is not allowed, but
!Button2
!Button3
is allowed. The last topic in the file must have at
least one non-topic line after it.
OPTIONAL INPUTS:
None.
OUTPUTS:
RESULT - An anonymous strucuture which has tags named the same as the
topic headers in the help file and the value of those tags
are the text messages about the topic. A -1 will be
returned for syntax error or failure to open the help file.
OPTIONAL OUTPUTS:
None.
KEYWORD PARAMETERS:
SEP_CHAR - Character used to differentiate topic
headers. The default SEP_CHAR is '!'
CALLS: ***
ADD_TAG [1], ADD_TAG [2], DATATYPE [1], DATATYPE [2], DATATYPE [3]
FIND_WITH_DEF [1], FIND_WITH_DEF [2], FIND_WITH_DEF [3], REPCHAR
CALLED BY:
EIS_IMAGE_TOOL_EVENT [1], EIS_IMAGE_TOOL_EVENT [2], IMAGE_TOOL_EVENT
COMMON BLOCKS:
None.
RESTRICTIONS:
Name of topic header is truncated at 16th character.
SIDE EFFECTS:
None.
CATEGORY:
Utilities, Help
PREVIOUS HISTORY:
Written May 12, 1995, Liyun Wang, GSFC/ARC
MODIFICATION HISTORY:
Version 1, created, Liyun Wang, GSFC/ARC, May 12, 1995
Version 2, August 8, 1996, Liyun Wang, NASA/GSFC
Used a more efficient way to create structure for OS
families other than VMS
VERSION:
Version 2, August 8, 1996
[Previous]
[Next]
Project : YOHKOH-HXT
Name : MK_HXI_MAP
Purpose : Make an image map from an HXI index/data structure
Category : imaging
Syntax : map=mk_hxi_map(index,data)
Inputs : INDEX,DATA = index/data combination
Outputs : MAP = map structure
Keywords : DIMENSIONS = [nx,ny] image dimensions to select
CALLS: ***
ADDTIME [1], ADDTIME [2], ANYTIM2TAI, CONV_HXT2A, DATATYPE [1], DATATYPE [2]
DATATYPE [3], EXIST, MAKE_MAP, MERGE_STRUCT, TRIM, fmt_tim [1], fmt_tim [2], get_roll
gt_day [1], gt_day [2], gt_time [1], gt_time [2]
History : Written 22 January 1997, D. Zarro, ARC/GSFC
: Rewritten to use HXI images, jmm, 3-aug-1998
: Offset double roll corrections, NVN, 17-Nov-2001
: Modified 3-Dec-01, Zarro (EITI/GSFC) - implemented
; suggestion by T. Metcalf
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_IMG_ICON
Purpose : iconize an image
Category : planning
Explanation : return a byte-scaled image array at a specified icon size
based on the original image. Use TV (not TVSCL) to display it
Syntax : icon=mk_img_icon(icon_size,image)
CALLED BY:
IMAGE_TOOL_EVENT, ITOOL_DRAW_ICON, ITOOL_LOAD_IMAGE
Examples :
Inputs : ICON_SIZE = output icon pixel size
IMAGE = input image array
Opt. Inputs :
Outputs : ICON = iconized image
Opt. Outputs:
Keywords : ERR = error string (blank if none)
CALLS: ***
CONGRID [1], CONGRID [2], CONGRID [3]
Common : None
Restrictions: None
Side effects: None
History : Written 1 July 1998 D. Zarro, SAC/GSFC
(extracted from IMAGE_TOOL)
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_IVM_MAP
Purpose : Make an image map from a Imaging Vector Magnetograph (IVM) data
Category : imaging
Explanation :
Syntax : map=mk_ivm_map(file)
map=mk_ivm_map(data,header)
Examples :
Inputs : FILE = FITS file name (or FITS data + HEADER)
Opt. Inputs : None
Outputs : MAP = map structure from MK_MAP
Opt. Outputs: None
Keywords : None
CALLS: ***
ANYTIM2TAI, ANYTIM2UTC [1], ANYTIM2UTC [2], DATATYPE [1], DATATYPE [2]
DATATYPE [3], EXIST, FXREAD [1], FXREAD [2], HEAD2STC, HEL2ARCMIN [1]
HEL2ARCMIN [2], LOC_FILE [1], LOC_FILE [2], LOC_FILE [3], MAKE_MAP, PR_SYNTAX
TAG_EXIST [1], TAG_EXIST [2], TRIM, USE_EARTH_VIEW
Common : None
Restrictions: None
Side effects: None
History : Written 22 January 1997, D. Zarro, ARC/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
NAME:
MK_LIBRARY_HELP
PURPOSE:
Given a directory or a VMS text library containing IDL user library
procedures, this procedure generates a file in the IDL help format
that contains the documentation for those routines that contain
a DOC_LIBRARY style documentation template. The output file is
compatible with the IDL "?" command.
A common problem encountered with the DOC_LIBRARY user library
procedure is that the user needs to know what topic to ask for
help on before anything is possible. The XDL widget library
procedure is one solution to this "chicken and egg" problem.
The MK_LIBRARY_HELP procedure offers another solution.
CATEGORY:
Help, documentation.
CALLING SEQUENCE:
MK_LIBRARY_HELP, Source, Outfile
INPUTS:
SOURCE: The directory or VMS text library containing the
.pro files for which help is desired. If SOURCE is
a VMS text library, it must include the ".TLB" file
extension, as this is what MK_LIBRARY_HELP uses to
tell the difference.
OUTFILE: The name of the output file which will be generated.
If you place this file in the help subdirectory of the
IDL distribution, and if it has a ".help" extension, then
the IDL ? command will find the file and offer it as one
of the availible help categories. Note that it uses the
name of the file as the name of the topic.
KEYWORDS:
TITLE: If present, a string which supplies the name that
should appear on the topic button for this file
in the online help. This title is only used on
systems that allow very short file names (i.e. MS DOS),
so it won't always have a visible effect. However,
it should be used for the broadest compatibility. If
a title is not specified, IDL on short name systems
will use a trucated copy of the file name.
VERBOSE: Normally, MK_LIBRARY_HELP does its work silently.
Setting this keyword to a non-zero value causes the procedure
to issue informational messages that indicate what it
is currently doing.
OUTPUTS:
None.
CALLS: ***
FILEPATH, MLH_GEN_FILE, MLH_GRAB_HEADER, UNIQ [1], UNIQ [2], UNIQ [3], file_list [1]
file_list [2]
COMMON BLOCKS:
None.
SIDE EFFECTS:
A help file with the name given by the OUTFILE argument is
created.
RESTRICTIONS:
If you put the resulting file into the "help" subdirectory of
the IDL distribution, it will be overwritten when you install a
new release of IDL. To avoid this problem, keep a backup copy of
your created help files in another directory and move them into
the new distribution.
Since this routine copies the documentation block from the
functions and procedures, subsequent changes will not be
reflected in the help file unless you run MK_LIBRARY_HELP
again.
The following rules must be followed in formating the .pro
files which are searched.
(a) The first line of the documentation block contains
only the characters ";+", starting in column 1.
(b) The last line of the documentation block contains
only the characters ";-", starting in column 1.
(c) Every other line in the documentation block contains
a ";" in column 1.
No reformatting of the documentation is done.
MODIFICATION HISTORY:
17 April, 1991, Written by AB, RSI.
1 December 1992, Reorganized internally. No functionality change.
31 December 1992, Added the TITLE keyword as part of the effort
towards releasing the Microsoft Windows version of IDL.
20 January 1993, Corrected for VMS, W. Landsman HSTX
17 March 1993, Corrected for MSDOS and VMS, AB.
13 January 1994, Added the VERSION attribute and modified format to
accomodate extended identifier names (the old format was
limited to 15 characters.
30 June 1995, M.Morrison - replaced FINDFILE with FILE_LIST so
that a list of directories can be passed as input.
Also protected against a ;+ existing but no ;-
[Previous]
[Next]
PROJECT:
SOHO - CDS/SUMER
NAME:
MK_LIMBFIT_BS
PURPOSE:
Make widget interface for limb-fitting on a given parent base
EXPLANATION:
CALLING SEQUENCE:
mk_limbfit_bs, parent, child
INPUTS:
PARENT - ID of parent widget upon which the limbfit widget is built
OPTIONAL INPUTS:
FONT - Font name to be used for labelling
OUTPUTS:
CHILD - ID of the base widget being built and leter on remapped
OPTIONAL OUTPUTS:
None.
KEYWORD PARAMETERS:
None.
CALLS: ***
CNVT_COORD [1], CNVT_COORD [2], CURSOR_INFO, CW_FIELD, DELVARX [1], DELVARX [2]
DELVARX [3], DELVARX [4], FLASH_MSG, ITOOL_COPY_TO_PIX, ITOOL_CROSS_HAIR
ITOOL_DISPLAY, ITOOL_REFRESH, LIMBFIT_EVENT, LIMB_INFO, MAKE_AUTO_FIT
MAKE_MANUAL_FIT, NL_LSQFIT, NUM2STR, PB0R, RESET_LIMBFIT, SETWINDOW [1]
SETWINDOW [2], UPDATE_FITLIMB, XSHOW_HELP, delvarx [5]
CALLED BY:
MAKE_AUTO_FIT, MAKE_MANUAL_FIT, UPDATE_FITLIMB
COMMON BLOCKS:
LIMB_FITTING - Internal common block used by this routine and
LIMBFIT_EVENT
Others - Included in image_tool_com.pro
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
CATEGORY:
PREVIOUS HISTORY:
Written January 25, 1995, Liyun Wang, GSFC/ARC
MODIFICATION HISTORY:
Version 1, created, Liyun Wang, GSFC/ARC, January 25, 1995
Version 2, Liyun Wang, GSFC/ARC, April 27, 1995
Added the FONT keyword
VERSION:
Version 2, April 27, 1995
[Previous]
[Next]
Project : HESSI
Name : MK_LINK
Purpose : Link file(s) to a directory
Explanation : Uses spawn,'ln -s'
Category : utility system io
Syntax : IDL> link_file,file,dir
Inputs : FILE = file name(s) to link
DIR = dir name in which to link
Keywords : OUT = spawn error string
CALLS: ***
APPEND_ARR, BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3], ESPAWN, EXIST, IS_STRING
LOC_FILE [1], LOC_FILE [2], LOC_FILE [3], OS_FAMILY, PR_SYNTAX, TEST_DIR, TRIM
break_file [4]
History : 15-March-2000, D.M. Zarro (SM&A). Written
Contact : DZARRO@SOLAR.STANFORD.EDU
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_MAP_XP
Purpose : compute X-coordinate arrays from center and spacing
Category : imaging
Explanation :
Syntax : xp=mk_map_xp(xc,dx,nx,ny)
CALLED BY:
GET_MAP_XP, MAKE_MAP, MAKE_XY, MAP__DEFINE, REBIN_MAP
Examples :
Inputs : XC = x-coord image center (arcsecs)
DX = pixel spacing in x-direc (arcsecs)
NX,NY = output dimensions
Opt. Inputs : None
Outputs : XP = 2d X-coordinate array
Opt. Outputs: None
Keywords : None
CALLS: ***
EXIST
Common : None
Restrictions: None
Side effects: None
History : Written 16 Feb 1998, D. Zarro, SAC/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_MAP_YP
Purpose : compute Y-coordinate arrays from center and spacing
Category : imaging
Explanation :
Syntax : yp=mk_map_yp(yc,dy,nx,ny)
CALLED BY:
GET_MAP_YP, MAKE_MAP, MAKE_XY, MAP__DEFINE, REBIN_MAP
Examples :
Inputs : YC = y-coord image center (arcsecs)
DY = pixel spacing in y-direc (arcsecs)
NX,NY = output dimensions
Opt. Inputs : None
Outputs : YP = 2d Y-coordinate array
Opt. Outputs: None
Keywords : None
CALLS: ***
EXIST
Common : None
Restrictions: None
Side effects: None
History : Written 16 Feb 1998, D. Zarro, SAC/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
NAME:
MK_MDI_MAP_EARTH
PURPOSE:
Make an MDI map structure with the image as it would have
been seen from the Earth perspective. The pointing is
updated and the image is warped to the Earth view.
CATEGORY:
CALLING SEQUENCE:
mdi_map = mk_mdi_map_earth(mdi_index,mdi_data)
INPUTS:
mdi_index = MDI index structure(s)
mdi_data = MDI image(s)
OPTIONAL INPUT PARAMETERS:
KEYWORD PARAMETERS:
/use_warp_tri = Use warp_tri instead of polywarp to do the
image warping. This is much more robust,
particularly near the limb, but also much
slower. The default is to use polywarp since
it is faster.
/quintic,/extrapolate = Passed to warp_tri if use_warp_tri is set.
degree = integer degree of warping passed to polywarp.
The default is 2. The best value is about 3 or 4,
but that takes longer. Higher than 5 will fail
rather dramatically. Ignored if use_warp_tri is set.
/verbose = print some diagnostics
OUTPUTS:
mdi_map = MDI map structure for plot_map etc. with the
correct information to plot Earth data on
top of it.
CALLS: ***
BILINEAR, DELVARX [1], DELVARX [2], DELVARX [3], DELVARX [4], GET_LATLON, INDEX2MAP
LONLAT2XY, POLYWARP, PQ2XY, WARP_TRI, delvarx [5], xy2lonlat
COMMON BLOCKS:
SIDE EFFECTS:
RESTRICTIONS:
PROCEDURE:
This routine is like map2earth.pro, but it accounts for the
parallax between L1 and Earth. map2earth only corrects the
pixel scale.
MODIFICATION HISTORY:
T. Metcalf 2002-Apr-04
T. Metcalf 2002-Apr-09 Fixed index problem in call to polywarp.
Added nowarp keyword.
T. Metcalf 2002-Apr-11 Fixed small bug in map center. Added
degree keyword.
T. Metcalf 2002-Apr-12 Added warp_tri option which is very slow
but also very robust.
T. Metcalf 2002-Apr-23 Fixed a bug that caused the warping to fail
near the limb.
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_MPEG
Purpose : make an MPEG movie from a series of image files (def = GIF)
Category : imaging
Syntax : mk_mpeg,images,file
Inputs : IMAGE = array of GIF filenames
FILE = output MPEG name
Keywords : JPEG = set for JPEG
CALLS: ***
BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3], DATATYPE [1], DATATYPE [2]
DATATYPE [3], EXIST, HAVE_PROC, MK_24BIT, MPEG_CLOSE, MPEG_OPEN, MPEG_PUT, MPEG_SAVE
PR_SYNTAX, QUERY_GIF, READ_GIF, TEST_DIR, TRIM, break_file [4], curdir [1], curdir [2]
data_chk [1], data_chk [2]
History : Written 11 Jan 2000, D. Zarro, SM&A/GSFC
Modified 8 Dec 2004, Zarro (L-3Com/GSFC)
- made QUALITY=100 the default
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
PROJECT:
SOHO - CDS/SUMER
NAME:
MK_NEW_CSI()
PURPOSE:
Create a new CSI (coordinate system info) structure
EXPLANATION:
CALLING SEQUENCE:
csi = mk_new_csi()
INPUTS:
None.
OPTIONAL INPUTS:
None.
OUTPUTS:
CSI -- Coordinate system information structure that contains some
basic information of the coordinate systems involved. It should
have the following 15 tags:
XD0 -- X position of the first pixel of the
image (lower left corner), in device pixels
YD0 -- Y position of the first pixel of the
image (lower left corner), in device pixels
XU0 -- X position of the first pixel of the image (lower
left corner), in user (or data) pixels.
YU0 -- Y position of the first pixel of the image (lower
left corner), in user (or data) pixels
MX -- X size of the image in device pixels
MY -- Y size of the image in device pixels
RX -- ratio of SX/MX, (data unit)/(device pixel),
where SX is the image size in X direction in data pixels
RY -- ratio of SY/MY, (data unit)/(device pixel),
where SY is the image size in Y direction in data pixels
X0 -- X position of the reference point in data pixels
Y0 -- Y position of the reference point in data pixels
XV0 -- X value of the reference point in absolute units
YV0 -- Y value of the reference point in absolute units
SRX -- scaling factor for X direction in arcsec/(data pixel)
SRY -- scaling factor for Y direction in arcsec/(data pixel)
FLAG - indicator with value 0 or 1 showing if the solar
coodinate system is established. 1 is yes.
RADIUS - Solar disc radius in arcsecs, initialized to 960.0
OPTIONAL OUTPUTS:
None.
KEYWORD PARAMETERS:
None.
CALLS:
None.
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
CATEGORY:
HISTORY:
Version 1, June 2, 1995, Liyun Wang, GSFC/ARC. Written
Version 2, April 1, 1996, Liyun Wang, GSFC/ARC
Added RADIUS tag in output structure
VERSION:
Version 2, April 1, 1996
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_NEW_MAP
Purpose : convert old format map to new format
Category : imaging
Syntax : new=mk_map_new(map)
Inputs : MAP = map structure with old format
Outputs : NEW = map structure with new format
Keywords : ERR = error string
CALLS: ***
ADD_TAG [1], ADD_TAG [2], GET_ARR_CENTER, MERGE_STRUCT, MK_MAP_NEW, PR_SYNTAX
REM_TAG [1], REM_TAG [2], VALID_MAP
History : Written 16 Feb 1998, D. Zarro, SAC/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO-CDS
Name : MK_OLD_MAP
Purpose : convert new format map to old format
Category : imaging
Explanation :
Syntax : new=mk_map_old(map)
Examples :
Inputs : MAP = map structure with new format
Opt. Inputs : None
Outputs : OMAP = map structure with old format
Opt. Outputs: None
Keywords : ERR = error string
CALLS: ***
ADD_TAG [1], ADD_TAG [2], GET_MAP_PROP, MERGE_STRUCT, MK_MAP_OLD, PR_SYNTAX
REM_TAG [1], REM_TAG [2], VALID_MAP
Common : None
Restrictions: None
Side effects: None
History : Written 16 Feb 1998, D. Zarro, SAC/GSFC
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project : SOHO - CDS
Name : MK_PARAMETER_STC()
Purpose : Return an "empty" structure describing a fitting parameter
Explanation : Used by MK_COMPONENT_STC.
Use : STC = MK_PARAMETER_STC()
Inputs : None.
Opt. Inputs : None.
Outputs : None.
Opt. Outputs: None.
Keywords : DOUBLE : Set to make parameter value double
Calls : None.
CALLED BY:
MK_COMPONENT_STC
Common : None.
Restrictions: None.
Side effects: None.
Category : Analysis
Prev. Hist. : None.
Written : S.V.H.Haugan, UiO, 21 January 1997
Modified : Not yet.
Version : 1, 21 January 1997
[Previous]
[Next]
Name: mk_pix
Purpose: make a genx file of image or current window for display by show_pix
Calling Sequence:
mk_pix [image, r, g, b, filename='filename', text=text, /replace]
Calling Examples:
mk_pix ; read image and r/g/b from current window
mk_pix, /norgb ; dont include r/g/b vectors
mk_pix,image,r,g,b,filename='name' ; user supplied image and r/g/b
mk_pix,'filename' ; pass filename (will prompt otherwise)
mk_pix,image,R,G,B, text=text ; image and colors passed
mk_pix,/notext ; dont prompt for text description
mk_pix,img,r,g,b, subdir='calibration' ; subdir = showpix subdirectory
mk_pix,'filename', /replace ; replace (overwrite) an existing file
mk_pix,'filename', opath=curdir() ; write file to current directory
mk_pix,'filename', text='filename' ; if text=file, read text from file
mk_pix,'filename', text='filename', /newcaption ; update text of existing file
mk_pix,im,r,g,b,/http ; update HTTP (mosaic) area
Keyword Parmaeters:
filename - filename to use (scaler string)
norgb - if set, dont save R/G/B vectors
notext - switch if set, dont prompt for text
moon OR eclipse - if set, use moon directory
mercury - if set, use mercury directory
misc OR other - if set, use misc(ellaneous) directory
opath - path for output (default is showpix common area)
subdir - specify subdirectory under showpix common area)
newcapt - if set, update text (only) from existing file
text - string or string array desrcribing image (prompts if not passed)
(text may be name of file which contains the desired text)
nodist - if set, do not send mail to ysserver (triggers distribution)
CALLS: ***
BOX_MESSAGE, BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3], CONCAT_DIR [1]
CONCAT_DIR [2], CONCAT_DIR [3], CT2RGB, FILE_EXIST [2], break_file [4]
concat_dir [4], curdir [1], curdir [2], data_chk [1], data_chk [2], dir_list [1]
dir_list [2], file_append [1], file_append [2], file_exist [1], file_exist [3]
file_list [1], file_list [2], genx2html [1], genx2html [2], get_logenv [1]
get_logenv [2], mail [1], mail [2], rd_tfile [1], rd_tfile [2], restgen [1]
restgen [2], savegen [1], savegen [2], str_replace [1], str_replace [2], tbeep [1]
tbeep [2], tbeep [3], wc_where [1], wc_where [2], wmenu_sel [1], wmenu_sel [2]
yesnox [1], yesnox [2]
CALLED BY:
daily_forecast [2], eit_mirror, fl_goesplot [1], fl_goesplot [2]
fl_goesplot [3], fl_summary [1], fl_summary [2], fl_summary [3], fl_suntoday [1]
fl_suntoday [2], fl_suntoday [3], fl_sxtobsnar [1], fl_sxtobsnar [2]
sun_today [1], sun_today [2], sun_today [3]
History:
13-Nov-1993 (SLF)
17-Nov-1993 (SLF) - fix bug with text
7-Dec-1993 (SLF) - add replace switch
1-Mar-1994 (SLF) - add opath keyword, allow text to be file name
15-Mar-1994 (SLF) - add subdir keyword
18-Mar-1994 (SLF) - use $DIR_GEN_SHOWPIX instead of $DIR_SITE_GENPIX
26-Jun-1994 (SLF) - filename logic and document, add FILENAME keyword
14-Jul-1994 (SLF) - send mail to ysserver account (trigger distribution)
22-Jul-1994 (ETB/SLF) - add index keyword
12-oct-1994 (SLF) - fix potential scaler/array mismatch
7-Dec-1994 (SLF) - make dummy file to prevent distribution of
'replaced' files...
14-Feb-1995 (SLF) - add HTTP keyword and function
10-apr-1995 (SLF) - insure that subdir is defined
23-Feb-1998 (SLF) - permit ...fname,image,r,g,b
26-Feb-1998 (SLF) - fix problem with 23-feb update
[Previous]
[Next]
PROJECT:
SOHO - CDS/SUMER
NAME:
MK_POINT_BASE
PURPOSE:
Make a widget base for pointing for an appropriate SOHO instrument
EXPLANATION:
This routine creates a widget interface based on a given "parent"
base in IMAGE_TOOL for the pointing purpose. Events genereated from
this widget set is handled by routine POINTING_EVENT. It requies a
pointing structure be defined (in the common block included in
image_tool_com.pro) for a given instrument. This pointing structure
should include the following tags:
MESSENGER - ID of widget in the caller that triggers a
timer event in the planning tool to signal the
completion of pointing; must be a widget that
does not usually generate any event
INSTRUME - Code specifying the instrument; e.g., 'C' for CDS
SCI_SPEC - Science specification
STD_ID - Study ID
G_LABEL - Generic label for the pointing; e.g., 'RASTER'
X_LABEL - Label for X coordinate of pointing; e.g., 'INS_X'
Y_LABEL - Label for Y coordinate of pointing; e.g., 'INS_Y'
DATE_OBS - Date/time of beginning of observation, in TAI format
DO_POINTING- An integer of value 0 or 1 indicating whether pointing
should be handled at the planning level (i.e., by
IMAGE_TOOL)
N_POINTINGS- Number of pointings to be performed by IMAGE_TOOL
POINTINGS - A structure array (with N_POINTINGS elements) of type
"DETAIL_POINT" to be handled by IMAGE_TOOL. It has the
following tags:
POINT_ID - A string scalar for pointing ID
INS_X - X coordinate of pointing area center in arcs
INS_Y - Y coordinate of pointing area center in arcs
WIDTH - Area width (E/W extent) in arcsec
HEIGHT - Area height (N/S extent) in arcsec
OFF_LIMB - An interger with value 1 or 0 indicating
whether or not the pointing area should
be off limb
N_RASTERS - Number of rasters for each pointing (this is
irrelevant to the SUMER)
RASTERS - A structure array (N_RASTERS-element) of type
"RASTER_POINT" that contains raster size and pointing
information (this is irrelevant to the SUMER). It has
the following tags:
POINTING - Pointing handling code; valis
values are: 1, 0, and -1
INS_X - Together with INS_Y, the pointing to use
when user-supplied values are not
allowed. Only valid when POINTING=0
(absolute) or POINTING=-1 (relative to
1st raster).
INS_Y - ...
WIDTH - Width (E/W extent) of the raster, in arcs
HEIGHT - Height (N/S extent) of the raster, in arcs
Note: For the case of CDS, pointings.width, pointings.height,
pointings.ins_x, and pointings.ins_y should match the first
raster's rasters.width, rasters.height, rasters.ins_x, and
rasters.ins_y, respectively.
CALLING SEQUENCE:
MK_POINT_BASE, parent, child [,font=font]
INPUTS:
PARENT - ID of parent widget upon which the pointing widget is built
OPTIONAL INPUTS:
FONT - Font name to be used for labelling
OUTPUTS:
CHILD - ID of the base widget being built and leter on remapped
OPTIONAL OUTPUTS:
None.
KEYWORD PARAMETERS:
None.
CALLS: ***
CNVT_COORD [1], CNVT_COORD [2], DATATYPE [1], DATATYPE [2], DATATYPE [3]
DELVARX [1], DELVARX [2], DELVARX [3], DELVARX [4], DHELP, DIFF_ROT [1]
DIFF_ROT [2], DPRINT, FLASH_MSG, FLASH_PLOTS, GET_DFONT [1], GET_DFONT [2]
GET_POINTING_SHAPE, ITOOL_COPY_TO_PIX, ITOOL_GETXY_FIELD, ITOOL_INSIDE_LIMB
ITOOL_POINT_PLOT, ITOOL_REFRESH, ITOOL_RESTORE_PIX, JUSTIFY, NUM2STR
POINTING_EVENT, POINTING_RESET, POINTING_UPDATE, POINT_DSHAPE, POLYGON_CSR
PT_BUTTON_UPDATE, ROTATE_POINT, SETWINDOW [1], SETWINDOW [2], SET_POINT_BASE
TAI2UTC, UTC2TAI, VALID_CDS_POINT, XACK, XANSWER, XSHOW_HELP, delvarx [5]
COMMON BLOCKS:
FOR_POINTING - Internal common block used by this routine and
MK_POINT_BASE
Others - Included in image_tool_com.pro
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
CATEGORY:
Planning, pointing
PREVIOUS HISTORY:
Written January 23, 1995, Liyun Wang, NASA/GSFC
Separated from the origina code of IMAGE_TOOL
MODIFICATION HISTORY:
Version 2, Liyun Wang, NASA/GSFC, March 8, 1995
Added indicator showing if a selected pointed area is pointed
Added Warnings if there is any pointing area remain unpointed
Version 3, Liyun Wang, NASA/GSFC, March 31, 1995
Added undo feature
Version 4, Liyun Wang, NASA/GSFC, April 27, 1995
Added the FONT keyword
Version 5, November 2, 1995, Liyun Wang, NASA/GSFC
Modified to cope with image icon stacking
Version 6, November 17, 1995, Liyun Wang, NASA/GSFC
Added validity check for CDS
Version 7, December 27, 1995, Liyun Wang, NASA/GSFC
Added pointing for MK_SOHO
Version 8, April 17, 1996, Liyun Wang, NASA/GSFC
Fixed a bug that caused the program crash when switching
studies with different pointing numbers
Version 9, August 19, 1996, Liyun Wang, NASA/GSFC
Corrected an error in plotting rasters with relative pointings
Version 10, December 18, 1996, Liyun Wang, NASA/GSFC
Modified such that the time projection is turned off if
raster is placed off the limb
Version 11, February 12, 1997, Liyun Wang, NASA/GSFC
Fixed a bug causing text widgets remaining inactive when
studies with variable pointings are received
Version 12, February 18, 1997, Liyun Wang, NASA/GSFC
Added fields SCI_SPEC and ID in pointing tool
Version 13, April 1, 1997, Liyun Wang, NASA/GSFC
Fixed a bug occurred during plotting off_limb rasters
VERSION:
Version 13, April 1, 1997
[Previous]
[Next]
PROJECT:
SOHO - CDS/SUMER
NAME:
MK_POINT_STC
PURPOSE:
Make a fresh pointing structure to be used by IMAGE_TOOL
EXPLANATION:
CALLING SEQUENCE:
mk_point_stc, structure
INPUTS:
None required.
OPTIONAL INPUTS:
N_POINTINGS - Number of pointings desired. Default is 1.
N_RASTERS - Number of rasters for each pointing. Default is 1.
OUTPUTS:
STRUCTURE - The pointing structure siutable for use in IMAGE_TOOL. It
contains the following tags:
MESSENGER - ID of widget in the caller that triggers a
timer event in the planning tool to signal the
completion of pointing; must be a widget that
does not usually generate any event
INSTRUME - Code specifying the instrument; e.g., 'C' for CDS
SCI_SPEC - Science specification
STD_ID - Study ID
G_LABEL - Generic label for the pointing; e.g., 'RASTER'
X_LABEL - Label for X coordinate of pointing; e.g., 'INS_X'
Y_LABEL - Label for Y coordinate of pointing; e.g., 'INS_Y'
DATE_OBS - Date/time of beginning of observation, in TAI format
DO_POINTING- An integer of value 0 or 1 indicating whether pointing
should be handled at the planning level (i.e., by
IMAGE_TOOL); default is set to 1.
N_POINTINGS- Number of pointings to be performed by IMAGE_TOOL
POINTINGS - A structure array (with N_POINTINGS elements) of type
"DETAIL_POINT" to be handled by IMAGE_TOOL. It has
the following tags:
POINT_ID - A string scalar for pointing ID
INS_X - X coordinate of pointing area center in arcs
INS_Y - Y coordinate of pointing area center in arcs
WIDTH - Area width (E/W extent) in arcsec
HEIGHT - Area height (N/S extent) in arcsec
ZONE - Description of the zone for pointing
OFF_LIMB - An interger with value 1 or 0 indicating
whether or not the pointing area should
be off limb
N_RASTERS - Number of rasters for each pointing (this is
irrelevant to the SUMER)
RASTERS - A structure array (N_RASTERS-element) of type
"RASTER_POINT" that contains raster size and pointing
information (this is irrelevant to the SUMER). It has
the following tags:
POINTING - Pointing handling code; valis
values are: 1, 0, and -1
INS_X - Together with INS_Y, the pointing to use
when user-supplied values are not
allowed. Only valid when POINTING=0
(absolute) or POINTING=-1 (relative to
1st raster).
INS_Y - ...
WIDTH - Width (E/W extent) of the raster, in arcs
HEIGHT - Height (N/S extent) of the raster, in arcs
CALLS: ***
ADD_TAG [1], ADD_TAG [2], ANYTIM2TAI, GET_UTC, TRIM
CALLED BY:
DSP_POINT, DSP_RASTER, EIS_IMAGE_TOOL [1], EIS_IMAGE_TOOL [2], EIS_ITOOL_STC [1]
EIS_ITOOL_STC [2], FAKE_POINT_STC, GET_CDS_POINT, GET_SUMER_POINT, IMAGE_TOOL
MK_CDS_PLAN, MK_PLAN_POINT, SUMER_POINT_STC, XCAT, dsp_fov, mdi_imagetool
Note: For the case of CDS, pointings.width, pointings.height,
pointings.ins_x, and pointings.ins_y should match the first
raster's rasters.width, rasters.height, rasters.ins_x, and
rasters.ins_y, respectively.
CATEGORY:
Planning, Image_tool, pointing
PREVIOUS HISTORY:
Written January 26, 1995, Liyun Wang, NASA/GSFC
MODIFICATION HISTORY:
Version 1, created, Liyun Wang, NASA/GSFC, January 26, 1995
Version 2, Liyun Wang, NASA/GSFC, April 5, 1995
Added the ZONE tagname in POINTINGS
Version 3, December 27, 1995, Liyun Wang, NASA/GSFC
Added MESSENGER tag in the returned pointing structure
Version 4, February 7, 1996, Liyun Wang, NASA/GSFC
Set raster and ppinting default size to 20x20 so that engineering
studies can be pointed with Pointing Tool
Version 5, February 18, 1997, Liyun Wang, NASA/GSFC
Added tags SCI_SPEC and STD_ID
Version 6, March 22, 1997, Zarro, GSFC
Enlarged default rasters sizes to 240
Version 7, Feb, 1998, Zarro, GSFC
Enlarged default rasters sizes to 480
29 August 2006, Zarro (ADNET/GSFC) - added /FOV
[Previous]
[Next]
Name: mk_rate_hdr
Category: HESSI, UTIL
Purpose: Make a basic FITS header for a RATE EXTENSION and merge it
with an optional input header.
Calling sequence:
new_hdr = mk_rate_hdr( hdr, N_ROWS=256 )
Inputs:
hdr - FITS header to merge with rate header.
Outputs:
Returns a valid FITS RATE extension header.
Input keywords:
N_ROWS - number of rows in RATE extension
EVENT_LIST - Set if the extension is an event list, not a rate.
Output keywords:
ERR_MSG = error message. Null if no error occurred.
ERR_CODE - 0/1 if [ no error / an error ] occurred during execution.
Calls: ***
TRIM, merge_fits_hdrs
CALLED BY:
wrt_rate_ext
Modification History:
28-June-2001 Paul Bilodeau - added event_list keyword. Removed N_CHAN
keyword and ability to merge time independent data into the header.
01-Sep-2004 Sandhia Bansal - Remove TIME-OBS and TIME-END. This information
is already included in DATE-OBS and DATE-END.
03-Sep-2004 Sandhia Bansal - Added several keywords that are required for
RATE extension. The values are now passed to this function via
rate_struct structure. Also add the fitswrite object fptr to
the argument list so that the keys can be written via this pointer
instead of using fx-routines directly.
24-Sep-2004 Sandhia Bansal - Write Author keyword.
09-Nov-2004 Sandhia Bansal - Write GEOAREA keyword.
20-Nov-2004 Sandhia Bansal - Write BACKAPP, DEADAPP, VIGNAPP, OBSERVER AND
TIMVERSN keywords.
[Previous]
[Next]
NAME:
mk_refbar
PURPOSE:
To display a reference color bar (to go along side an image)
SAMPLE CALLING SEQUENCE:
mk_refbar, x0, y0, imin, imax
mk_refbar, x0, y0, imin, imax, /horiz, fmt=fmt, nlab=lab, /log
mk_refbar, x0, y0, imin, imax, xsiz=xsiz, ysiz=ysiz
INPUT:
x0 - The lower left X corner for the color bar
y0 - The lower left Y corner for the color bar
imin - The minimum data value displayed (color=0)
imax - The maximum data value displayed (color=!d.table_size-1)
CALLS: ***
HIST_EQUAL, tv2 [1], tv2 [2], xyouts2 [1], xyouts2 [2]
CALLED BY:
disp_gen [1], disp_gen [2], fig_summary, img_summary [1], img_summary [2]
OPTIONAL KEYWORD INPUT:
horiz - If set, make the color bar horizontal
nlab - The number of labels (default=16)
fmt - The format statement for the label values
xsiz - The X size of the color bar (def = 24)
ysiz - The Y size of the color bar (def = 256)
size - The font size for the labels
hist - If set, then the image was displayed with histogram
equalization
average - If set, then display a message about the average
deviation-If set, then display a message about the deviation
delta - If set, then display a message about the range
log_scale-If set, then the data was log scaled before display
HISTORY:
Written Feb-94 by M.Morrison
5-Apr-94 (MDM) - Added "log_scale" and "log_offset" options
3-May-94 (MDM) - Slight changes (make bar go to a value of 255,
not !d.n_colors)
2-Apr-96 (MDM) - Added /horizontal option
- Added /qdebug
22-Apr-96 (MDM) - Replaced to scale to !d.n_colors (this time N-1)
11-Nov-96 (MDM) - Changed !d.n_colors to !d.table_size
- Added some header info
[Previous]
[Next]
Name: mk_rmf_hdr
Category: HESSI, UTIL
Purpose: Make an header for a response matrix FITS extension.
Calling sequence:
rmf_hdr = mk_rmf_hdr( HEADER=basic_header, N_HDR_ROWS=12, $
EXTNAME='SPECRESP MATRIX' )
Inputs:
Input keywords:
HEADER - primary header for the file. This contains any information
that should be in the header in addition to the mandatory
keywords.
_EXTRA - included to capture any keywords that should be added to
the header.
Output keywords:
ERR_MSG = error message. Null if no error occurred.
ERR_CODE - 0/1 if [ no error / an error ] occurred during execution.
Calls: ***
FXBHMAKE [1], FXBHMAKE [2], add_kw2hdr, merge_fits_hdrs
CALLED BY
rm2fits
[Previous]
[Next]
NAME:
MK_SOHO_MAP_EARTH
PURPOSE:
Make a SOHO map structure with the image as it would have
been seen from the Earth perspective. The pointing is
updated and the image is warped to the Earth view.
CATEGORY:
CALLING SEQUENCE:
map = mk_soho_map_earth(index,data)
INPUTS:
index = SOHO index structure(s)
data = SOHO image(s)
OPTIONAL INPUT PARAMETERS:
KEYWORD PARAMETERS:
/use_warp_tri = Use warp_tri instead of polywarp to do the
image warping. This is much more robust,
particularly near the limb, but also much
slower. The default is to use polywarp since
it is faster.
/quintic,/extrapolate = Passed to warp_tri if use_warp_tri is set.
degree = integer degree of warping passed to polywarp.
The default is 2. The best value is about 3 or 4,
but that takes longer. Higher than 5 will fail
rather dramatically. Ignored if use_warp_tri is set.
/verbose = print some diagnostics
OUTPUTS:
map = map structure for plot_map etc. with the
correct information to plot Earth data on
top of it.
CALLS: ***
BILINEAR, DELVARX [1], DELVARX [2], DELVARX [3], DELVARX [4], GET_FITS_PAR
GET_FITS_TIME, GET_LATLON, GET_ORBIT [1], GET_ORBIT [2], INDEX2MAP, LONLAT2XY
OCONTOUR2, POLYWARP, PQ2XY, WARP_TRI, WDEF [1], WDEF [2], delvarx [5], get_rb0p [1]
get_rb0p [2], soho_fac, tag_index [1], tag_index [2], xy2lonlat
COMMON BLOCKS:
SIDE EFFECTS:
RESTRICTIONS:
PROCEDURE:
This routine is like map2earth.pro, but it accounts for the
parallax between L1 and Earth. map2earth only corrects the
pixel scale.
MODIFICATION HISTORY:
T. Metcalf 2002-Apr-04
T. Metcalf 2002-Apr-09 Fixed index problem in call to polywarp.
Added nowarp keyword.
T. Metcalf 2002-Apr-11 Fixed small bug in map center. Added
degree keyword.
T. Metcalf 2002-Apr-12 Added warp_tri option which is very slow
but also very robust.
T. Metcalf 2002-Apr-23 Fixed a bug that caused the warping to fail
near the limb.
T. Metcalf 2002-Oct-21 Upgraded mk_mdi_map_earth to mk_soho_map_earth
T. Metcalf 2003-Jan-29 Cleaned up code and did some more testing.
T. Metcalf 2005-Jan-25 Force the roll angle in the output map to
be zero since the roll angle is correctd
in the warping process.
[Previous]
[Next]
Project : HESSI
Name : MK_SUB_DIR
Purpose : create subdirectories under parent
Category : utility system
Syntax : mk_sub_dir,parent,sub_dir
Inputs : PARENT = parent directory under which to create sub_dir
SUB_DIR = subdir names
Keywords : ERR= error string
OUT_DIR = created directory names
CALLS: ***
CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3], IS_BLANK, MK_DIR, TEST_DIR
concat_dir [4], get_uniq
CALLED BY:
EIT_COPY, MDI_COPY, MK_FID, TRACE_COPY, mdi_link
History : Written, 22 March 2001, D. Zarro (EITI/GSFC)
Modified, 13 April 2004, Zarro (L-3Com/GSFC) - call MK_DIR
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Project:
SOHO - SUMER
Name:
mk_sumer_map
Purpose:
Make an image map from SUMER data structure
Explanation
This program is analigous to mk_cds_map. The default output is
a structure containing a single 2-D map and other information
suitable of entering in certain CDS image manipulation programs
Catagory:
Imaging
Use:
map= mk_sumer_map(index,data,col)
Inputs
index - The index structure returned from rd_sumer.
data - data structrure from rd_sumer
col - column to use in making map. If not specified, the user will
be prompted.
Output
Map = {data:data,xp:xp,yp:yp,id:id,time:time,soho:soho,rot:rot_num}
where
DATA = 2d image array
XP,YP = 2d cartesian coordinate arrays
ID = Wavelength and BTE of map (from data tagname)
TIME = start time of image
SOHO = 1, flag identifying that image is SOHO-viewed
ROT_NUM = Direction input used for ROTATE function
or, if the keyword IMAGE_ONLY is used, return only the 2d map
Input Keywords:
Peak - make map at wavelength of peak intesity. The default is to
sum over the wavelength range
WPRange - the range in pixels in the wavelength direction to use.
Default is the entire range.
Image_Only - return a 2d image rather than the default, a strucuture
plot_image - Return an altrnate data structure with PLOT_IMAGE
inputs:
Map = {data:data,origin:origin,scale:scale,id:id,time:time,$
soho:soho,rot:rot_num}
where
DATA = 2d image array
ORIGIN = coordinates of bottom Left corner of map
SCALE = scale of map in the X and Y directions
ID = Wavelength and BTE of map (from data tagname)
TIME = start time of image
SOHO = 1, flag identifying that image is SOHO-viewed
ROT_NUM = Direction input used for ROTATE function
Calls: ***
ANYTIM2TAI, ANYTIM2UTC [1], ANYTIM2UTC [2], DATATYPE [1], DATATYPE [2]
DATATYPE [3], MK_MAP_NEW, get_sum_column, sgt_det_y, sgt_dettime, sgt_dims
sgt_solar_x
Common:
None
Written:
Terry Kucera, Oct 23, 1996.
Modifications:
"Time" tag now correct for sumer data with more than one raster.
Dominic Zarro, May 15, 1997
"PLOT_IMAGE" keyword added. TAK Oct 6, 1997
Added conversion to new map format - Zarro (SM&A), 29-Dec-98
Used boolean instead of string to determine rotation
- Zarro (L-3Com/GSFC), 28-May-05
Contact:
tkucera@solar.stanford.edu
[Previous]
[Next]
Name : MK_SXT_MAP
Purpose : Make an image map from an SXT index/data structure
Category : imaging
Explanation :
Syntax : map=mk_sxt_map(index,data)
Examples :
Inputs : INDEX,DATA = index/data combination
Opt. Inputs : None
Outputs : MAP = map structure
Opt. Outputs: None
Keywords : DIMENSIONS = [nx,ny] image dimensions to select
CALLS: ***
ANYTIM2TAI, DATATYPE [1], DATATYPE [2], DATATYPE [3], EXIST, MAKE_MAP, MERGE_STRUCT
TAG_EXIST [1], TAG_EXIST [2], TRIM, get_roll, gt_center, gt_day [1], gt_day [2]
gt_expdur [1], gt_expdur [2], gt_filtb, gt_pix_size, gt_shape, gt_time [1]
gt_time [2]
Common : None
Restrictions: None
Side effects: None
History : Written 22 January 1997, D. Zarro, ARC/GSFC
Dec 5, 2001, T. Metcalf rewriten to get the roll correction
correct.
Dec 7, 2001: TRM Fixed a small problem when an index array
is passed and prevented multiple warnings
about using the predicted roll angle.
[Previous]
[Next]
Project : SOHO - CDS
Name : MK_TEMP_DIR
Purpose : Create a temporary directory
Category : Utility
Explanation :
Syntax : IDL>mk_temp_dir,dir,temp_dir
Inputs : DIR = directory in which to create temporary sub-directory
Opt. Inputs : None
Outputs : TEMP_DIR = name of created sub-directory
Opt. Outputs: None
Keywords : ERR = error string
CALLED BY:
ssw_get_sources
Restrictions: None
CALLS: ***
CONCAT_DIR [1], CONCAT_DIR [2], CONCAT_DIR [3], GET_RID, IS_DIR, MK_DIR, OS_FAMILY
PR_SYNTAX, WRITE_DIR, concat_dir [4]
Side effects: Subdirectory named temp$$$$ is created
History : Version 1, 9-June-1999, D.M. Zarro. Written
Contact : DZARRO@SOLAR.STANFORD.EDU
[Previous]
[Next]
Project : SOHO - CDS
Name : MK_TEMP_FILE
Purpose : Create a temporary filename
Category : Utility
Syntax : IDL> file=mk_temp_file()
Inputs : FILE = file name [def='temp.dat']
Opt. Inputs : None
Outputs : NAME = file name with added path
Keywords : RANDOM - prepend a random set of digits to force uniqueness
DIREC (input) - specified directory location of temp file
PATH (output) - actual directory location of temp file
CALLS: ***
BREAK_FILE [1], BREAK_FILE [2], BREAK_FILE [3], CONCAT_DIR [1], CONCAT_DIR [2]
CONCAT_DIR [3], GET_RID, GET_TEMP_DIR, IS_BLANK, IS_STRING, TRIM, WRITE_DIR
break_file [4], concat_dir [4]
CALLED BY:
ADD_METHOD, ALLOW_GIF, CHECK_FTP, FTP__DEFINE, GET_TEMP_FILE, MK_PLAN_PLOT
SMART_FTP, URL_GET, WBSC_LTC_EV [1], WBSC_LTC_EV [2], WBSC_SPC_EV [1]
WBSC_SPC_EV [2], WIN_SPAWN, XCAMP, XCAT, set_hard, uncompress
History : Version 1, 25-May-1997, D.M. Zarro. Written
17 April 2000, Zarro (SM&A/GSFC) - added DIREC keyword
Contact : DZARRO@SOLAR.STANFORD.EDU
[Previous]
[Next]
PROJECT:
SOHO - CDS/SUMER
NAME:
MK_TIMETICK
PURPOSE:
Create time ticks to be used by AXIS
CATEGORY:
Utilities, Graphics
EXPLANATION:
SYNTAX:
mk_timetick, tmin, tmax, basetime, label=lable, value=value
INPUTS:
TMIN - Beginning time of the plot, in hours
TMAX - End time of the plot, in hours
BASETIME - Base time, in any CDS time format
OPTIONAL INPUTS:
None.
OUTPUTS:
None.
OPTIONAL OUTPUTS:
None.
KEYWORDS:
LABEL - String array, ticknames to be used in AXIS with the
[XY]TICKNAME keyword
VALUE - Values at the major tickmarks to be used in AXIS with
the [XY]TICKV keyword
MAJOR - Number of major tickmarks, to be used with the
[XY]TICKS keyword in AXIS
MINOR - Number of minor tickmarks, to be used with the
[XY]MINOR keyword in AXIS
LOCAL - Set this keyword to make time ticks w.r.t local time
NODOW - Suppress day of week in date string
CALLS: ***
ANYTIM2UTC [1], ANYTIM2UTC [2], LOCAL_DIFF, UTC2DOW, UTC2TAI
CALLED BY:
PLOT_UTFRAME, eis_timeline_plot_gui [1], eis_timeline_plot_gui [2]
COMMON:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
HISTORY:
Version 1, May 8, 1996, Liyun Wang, NASA/GSFC. Written
Version 2, May 17, 1996, Liyun Wang, NASA/GSFC
Fixed a bug which may occur when TMAX-TMIN is less than 3 hours
Added seconds in label if TMAX-TMIN is less than 3 hours
Version 3, June 3, 1996, Liyun Wang, NASA/GSFC
Changed date string to dd-MMM format
Version 4, June 12, 1997, Liyun Wang, NASA/GSFC
Added day of week in date string as default; use NODOY
keyword to suppress it
Added keyword NODOW
CONTACT:
Liyun Wang, NASA/GSFC (Liyun.Wang.1@gsfc.nasa.gov)
[Previous]
[Next]
NAME: MKDARR
PURPOSE: To make an array having two elements such as:
[(a0,b0),(a0,b1),,,(a0,bn),(a1,b0),(a1,b1),,,(a1,bn),,,
(am,b0),(am,b1),,,(am,bn)] out of [a0,,,am] and
[b0,,,bn], or, with xy switch,
[(a0,b0),(a1,b0),,,(am,b0),(a0,b1),(a1,b1),,,(am,b1),,,
(a0,bn),(a1,bn),,,(am,bn)] out of [a0,,,am] and [b0,,,bn].
CATEGORY:
CALLING SEQUENCE: c = mkdarr(a,b)
INPUTS: a = arbitraty 1-d array.
b = arbitraty 1-d array.
OPTIONAL INPUTS: none.
OUTPUTS: result = c = two-element array [(a0,b0),(a0,b1),...,(a0,bn),
(a1,b0),(a1,b1),...,(a1,bn),...(am,b0),(am,b1),
....,(am,bn)] or, with xy switch [(a0,b0),,,(am,bn),
,,,,(a0,bn),,,(am,bn)].
OPTIONAL OUTPUTS: none.
CALLED BY:
ACGAUNT [1], ACGAUNT [2], FIND_LIMB_INIT, str_perm
COMMON BLOCKS: none.
SIDE EFFECTS: none.
RESTRICTIONS: none.
MODIFICATIONS: written by N.Nitta, March 1991.
modified to handle scalar inputs and the order of the
inputs, by NN, March 1992
[Previous]
[Next]
NAME:
MKHDR
PURPOSE:
Make a minimal primary (or IMAGE extension) FITS header
EXPLANATION:
If an array is supplied, then the created FITS header will be
appropriate to the supplied array. Otherwise, the user can specify
the dimensions and datatype.
CALLING SEQUENCE:
MKHDR, header ;Prompt for image size and type
or
MKHDR, header, im, [ /IMAGE, /EXTEND ]
or
MKHDR, header, type, naxisx, [/IMAGE, /EXTEND ]
OPTIONAL INPUTS:
IM - If IM is a vector or array then the header will be made
appropriate to the size and type of IM. IM does not have
to be the actual data; it can be a dummy array of the same
type and size as the data. Set IM = '' to create a dummy
header with NAXIS = 0.
TYPE - If more than 2 parameters are supplied, then the second parameter
is interpreted as an integer giving the IDL datatype e.g.
1 - LOGICAL*1, 2 - INTEGER*2, 4 - REAL*4, 3 - INTEGER*4
NAXISX - Vector giving the size of each dimension (NAXIS1, NAXIS2,
etc.).
OUTPUT:
HEADER - image header, (string array) with required keywords
BITPIX, NAXIS, NAXIS1, ... Further keywords can be added
to the header with SXADDPAR.
OPTIONAL INPUT KEYWORDS:
/IMAGE = If set, then a minimal header for a FITS IMAGE extension
is created. An IMAGE extension header is identical to
a primary FITS header except the first keyword is
'XTENSION' = 'IMAGE' instead of 'SIMPLE ' = 'T'
/EXTEND = If set, then the keyword EXTEND is inserted into the file,
with the value of "T" (true). The EXTEND keyword must be
included in a primary header, if the FITS file contains
extensions.
CALLS: ***
GET_DATE [1], GET_DATE [2], SXADDPAR [1], SXADDPAR [2], SXADDPAR [3]
CALLED BY:
CHANDLE, GETPSF, MODEL_to_SCORE [2], MVI2FRAMES, WRITEFITS [1], WRITEFITS [2]
ZMKHDR, model_to_score [1], smei_frm_cvhdr, smei_mkglare, smei_mksidereal
smei_mkstdstar, smei_star_remove, smei_zodiac_remove, wso_write
RESTRICTIONS:
(1) MKHDR should not be used to make an STSDAS header or a FITS
ASCII or Binary Table extension header. Instead use
SXHMAKE - to create a minimal STSDAS header
FXBHMAKE - to create a minimal FITS binary table header
FTCREATE - to create a minimal FITS ASCII table header
(2) Any data already in the header before calling MKHDR
will be destroyed.
EXAMPLE:
Create a minimal FITS header, Hdr, for a 30 x 40 x 50 INTEGER*2 array
IDL> mkhdr, Hdr, 2, [30,40,50]
Alternatively, if the array already exists as an IDL variable, Array,
IDL> mkhdr, Hdr, Array
PROCEDURES CALLED:
SXADDPAR, GET_DATE
REVISION HISTORY:
Written November, 1988 W. Landsman
May, 1990, Adapted for IDL Version 2.0, J. Isensee
Aug, 1997, Use SYSTIME(), new DATE format W. Landsman
Converted to IDL V5.0 W. Landsman September 1997
Allow unsigned data types W. Landsman December 1999
Set BZERO = 0 for unsigned integer data W. Landsman January 2000
EXTEND keyword must immediately follow last NAXISi W. Landsman Sep 2000
Add FITS definition COMMENT to primary headers W. Landsman Oct. 2001
Allow (nonstandard) 64 bit integers W. Landsman Feb. 2003
[Previous]
[Next]
NAME:
MKHDR
PURPOSE:
Make a minimal primary (or IMAGE extension) FITS header
EXPLANATION:
If an array is supplied, then the created FITS header will be
appropriate to the supplied array. Otherwise, the user can specify
the dimensions and datatype.
CALLING SEQUENCE:
MKHDR, header ;Prompt for image size and type
or
MKHDR, header, im, [ /IMAGE, /EXTEND ]
or
MKHDR, header, type, naxisx, [/IMAGE, /EXTEND ]
OPTIONAL INPUTS:
IM - If IM is a vector or array then the header will be made
appropriate to the size and type of IM. IM does not have
to be the actual data; it can be a dummy array of the same
type and size as the data. Set IM = '' to create a dummy
header with NAXIS = 0.
TYPE - If more than 2 parameters are supplied, then the second parameter
is interpreted as an integer giving the IDL datatype e.g.
1 - LOGICAL*1, 2 - INTEGER*2, 4 - REAL*4, 3 - INTEGER*4
NAXISX - Vector giving the size of each dimension (NAXIS1, NAXIS2,
etc.).
OUTPUT:
HEADER - image header, (string array) with required keywords
BITPIX, NAXIS, NAXIS1, ... Further keywords can be added
to the header with SXADDPAR.
OPTIONAL INPUT KEYWORDS:
/IMAGE = If set, then a minimal header for a FITS IMAGE extension
is created. An IMAGE extension header is identical to
a primary FITS header except the first keyword is
'XTENSION' = 'IMAGE' instead of 'SIMPLE ' = 'T'
/EXTEND = If set, then the keyword EXTEND is inserted into the file,
with the value of "T" (true). The EXTEND keyword must be
included in a primary header, if the FITS file contains
extensions.
CALLS: ***
GET_DATE [1], GET_DATE [2], SXADDPAR [1], SXADDPAR [2], SXADDPAR [3]
CALLED BY:
CHANDLE, GETPSF, MODEL_to_SCORE [2], MVI2FRAMES, WRITEFITS [1], WRITEFITS [2]
ZMKHDR, model_to_score [1], smei_frm_cvhdr, smei_mkglare, smei_mksidereal
smei_mkstdstar, smei_star_remove, smei_zodiac_remove, wso_write
RESTRICTIONS:
(1) MKHDR should not be used to make an STSDAS header or a FITS
ASCII or Binary Table extension header. Instead use
SXHMAKE - to create a minimal STSDAS header
FXBHMAKE - to create a minimal FITS binary table header
FTCREATE - to create a minimal FITS ASCII table header
(2) Any data already in the header before calling MKHDR
will be destroyed.
EXAMPLE:
Create a minimal FITS header, Hdr, for a 30 x 40 x 50 INTEGER*2 array
IDL> mkhdr, Hdr, 2, [30,40,50]
Alternatively, if the array already exists as an IDL variable, Array,
IDL> mkhdr, Hdr, Array
PROCEDURES CALLED:
SXADDPAR, GET_DATE
REVISION HISTORY:
Written November, 1988 W. Landsman
May, 1990, Adapted for IDL Version 2.0, J. Isensee
Aug, 1997, Use SYSTIME(), new DATE format W. Landsman
Converted to IDL V5.0 W. Landsman September 1997
Allow unsigned data types W. Landsman December 1999
Set BZERO = 0 for unsigned integer data W. Landsman January 2000
EXTEND keyword must immediately follow last NAXISi W. Landsman Sep 2000
Add FITS definition COMMENT to primary headers W. Landsman Oct. 2001
Allow (nonstandard) 64 bit integers W. Landsman Feb. 2003
[Previous]
[Next]
Project : SOHO - CDS
Name : MKLOG
Purpose : define a logical (VMS) or environment (UNIX) variable
Category : Utility, OS
Explanation : checks OS to determine which SET function to use
Syntax : IDL> mklog,name,value
Inputs : NAME = string name of variable to define logical for
: VALUE = string name of logical
Keywords : VERBOSE = print result
CALLS: ***
CHKLOG [1], CHKLOG [2], EXIST, OS_FAMILY
CALLED BY:
APPEND_SDB, BCS, CHECK_ANOMALY, EIS_CAT [1], EIS_CAT [2], EIS_DBASE, EXP_ZDBASE, FCS
GET_NAR, MKLOG_LIST, MK_PLAN_FORM, MK_PLAN_RECOVER, PLOT_SPLAN, RD_CDS_POINT, RD_DMP
RD_EXB, RD_GOES_SDAC, SEARCH_NETWORK, TRACE_JSMOVIE, WRITE_ANOMALY, XCPT, XREPORT
db_gbo, gextal, ihy_db, mewe, mksort, rdbda_smm
Side effects: logical will become undefined if name=''
History : Written, 1-Sep-1992, D.M. Zarro.
Modified, 25-May-99, Zarro (SM&A/GSC) - add better OS check
Contact : DZARRO@SOLAR.STANFORD.EDU
[Previous]
[Next]
Project : HESSI
Name : MKLOG_LIST
Purpose : define environmental for first valid listed argument
Category : system utility
Explanation :
Syntax : IDL> mklog_list,name,value1,value2....
Examples :
Inputs : NAME = environment variable to define
VALUE1 = first argument to check
VALUE2 = second argument to check
Opt. Inputs : None
Outputs : None
Opt. Outputs: None
Keywords : VERBOSE = print result
Restrictions: Probably works in Windows. Up to 10 arguments checked.
CALLS: ***
DATATYPE [1], DATATYPE [2], DATATYPE [3], LOC_FILE [1], LOC_FILE [2], LOC_FILE [3]
MKLOG, NUM2STR, TRIM
Side effects: Env NAME is defined to first found argument
History : Version 1, 26-May-1999, Zarro (SM&A/GSFC)
Contact : dzarro@solar.stanford.edu
[Previous]
[Next]
Name: mkthumb
Purpose: make a thumbnail of an image or movie sequence
Input Parameters:
data - full size 2D or 3D image array (may use GIF files instead)
Keyword Parameters:
ingif - optionally use GIF files for input (instead of DATA)
outsize - if set, thumbnail output size (nx or [nx,ny])
factor - thumbnail scale, as a percentage or fraction of input size
labels - if set, image lables (like times information, etc)
nx,ny - if set, thumbnail output size (in lieu of OUTSIZE or FACTOR)
maxxy - if set, apply this to largest nx/ny dimension
(used to limit output size for extremely rectangular input)
r,g,b - optional color table (only used if outfile specified)
vertical - if set, stack movies and lables in vertical icon
CALLS: ***
CONGRID [1], CONGRID [2], CONGRID [3], DELVARX [1], DELVARX [2], DELVARX [3]
DELVARX [4], READ_GIF, SSW_WRITE_GIF, WDEF [1], WDEF [2], data_chk [1], data_chk [2]
delvarx [5], film_thumbnail [1], film_thumbnail [2]
CALLED BY:
LATEST_SFDS_GIF, eit_proton_summary, image2movie, soon_search_www
ssw_findstuff2html, sxt2mpeg, thumbnail_table_html, trace_get1www_image
History:
25-oct-1995 - S.L.Freeland - for mpeg/WWW movie icons
6-nov-1995 (SLF) - keywords, add gif file option
1-may-1996 (SLF) - bug fix (1 image case)
20-nov-1997 (SLF) - if only nx supplied, scale ny properly
(correct aspect ratio for non-square sequences)
17-nov-1999 (SLF) - add LABSTYLE (execute string -> align_label.pro)
8-Sep-2005, Zarro (L-3Com/GSFC) - add SSW_WRITE_GIF
11-oct-2006 (SLF) - add MAXXY keyword & function
[Previous]
[Next]
NAME:
MMM
PURPOSE:
Estimate the sky background in a stellar contaminated field.
EXPLANATION:
MMM assumes that contaminated sky pixel values overwhelmingly display
POSITIVE departures from the true value. Adapted from DAOPHOT
routine of the same name.
CALLING SEQUENCE:
MMM, sky, [ skymod, sigma, skew, HIGHBAD = , READNOISE=, /DEBUG,
NSKY=, /INTEGER,/SILENT]
INPUTS:
SKY - Array or Vector containing sky values. This version of
MMM does not require SKY to be sorted beforehand. SKY
is unaltered by this program.
OPTIONAL OUTPUTS:
skymod - Scalar giving estimated mode of the sky values
SIGMA - Scalar giving standard deviation of the peak in the sky
histogram. If for some reason it is impossible to derive
skymod, then SIGMA = -1.0
SKEW - Scalar giving skewness of the peak in the sky histogram
If no output variables are supplied or if /DEBUG is set
then the values of skymod, SIGMA and SKEW will be printed.
OPTIONAL KEYWORD INPUTS:
HIGHBAD - scalar value of the (lowest) "bad" pixel level (e.g. cosmic
rays or saturated pixels) If not supplied, then there is
assumed to be no high bad pixels.
READNOISE - Scalar giving the read noise (or minimum noise for any
pixel). Normally, MMM determines the (robust) median by
averaging the central 20% of the sky values. In some cases
where the noise is low, and pixel values are quantized a
larger fraction may be needed. By supplying the optional
read noise parameter, MMM is better able to adjust the
fraction of pixels used to determine the median.
/INTEGER - Set this keyword if the input SKY vector only contains
discrete integer values. This keyword is only needed if the
SKY vector is of type float or double precision, but contains
only discrete integer values. (Prior to July 2004, the
equivalent of /INTEGER was set for all data types)
/DEBUG - If this keyword is set and non-zero, then additional
information is displayed at the terminal.
/SILENT - If set, then error messages will be suppressed when MMM
cannot compute a background. Sigma will still be set to -1
OPTIONAL OUTPUT KEYWORD:
NSKY - Integer scalar giving the number of pixels actually used for the
sky computation (after outliers have been removed).
NOTES:
(1) Program assumes that low "bad" pixels (e.g. bad CCD columns) have
already been deleted from the SKY vector.
(2) MMM was updated in June 2004 to better match more recent versions
of DAOPHOT.
(3) Does not work well in the limit of low Poisson integer counts
(4) MMM may fail for strongly skewed distributions.
METHOD:
The algorithm used by MMM consists of roughly two parts:
(1) The average and sigma of the sky pixels is computed. These values
are used to eliminate outliers, i.e. values with a low probability
given a Gaussian with specified average and sigma. The average
and sigma are then recomputed and the process repeated up to 20
iterations:
(2) The amount of contamination by stars is estimated by comparing the
mean and median of the remaining sky pixels. If the mean is larger
than the median then the true sky value is estimated by
3*median - 2*mean
REVISION HISTORY:
Adapted to IDL from 1986 version of DAOPHOT in STSDAS,
W. Landsman, STX Feb 1987
Added HIGHBAD keyword, W. Landsman January, 1991
Fixed occasional problem with integer inputs W. Landsman Feb, 1994
Avoid possible 16 bit integer overflow W. Landsman November 2001
Added READNOISE, NSKY keywords, new median computation
W. Landsman June 2004
Added INTEGER keyword W. Landsman July 2004
Improve numerical precision W. Landsman October 2004
Fewer aborts on strange input sky histograms W. Landsman October 2005
Added /SILENT keyword November 2005
Fix too many /CON keywords to MESSAGE W.L. December 2005
Fix bug introduced June 2004 removing outliers when READNOISE not set
N. Cunningham/W. Landsman January 2006
CALLED BY
APER, SKY
[Previous]
[Next]
NAME: modd
PURPOSE: calculate a modulus
CALLING SEQUENCE: out=modulus(num,mod)
mod should be an integer
num can be anything, but the limit for integers is ~32700 < 512x512
CALLED BY:
coord_l2v, dskcntr, r_coord
HISTORY: drafted apr. 1992, A. McAllister
[Previous]
[Next]
Project : SOHO - CDS
Name : MODE_VAL()
Purpose : Returns the modal value of an array.
Explanation : The modal value of an array (any dimension) is deduced from
the max value of the histogram. If several values occur
with equal frequency, a warning is given but only the smallest
value of the group is returned.
Use : IDL> m = mode_val(array [,freq])
eq print,mode_val([2,3,4,5,2,2,3,4,2,2,7,8,9]) --> 2
print,mode_val('asdfghaaasdfvbnm') --> a
print,mode_val(['asdf','ghaaa','asdf','vbnam'],freq) --> a
and freq returned with value 6
Inputs : array - the n-dimensional integer array in which to find the
mode.
Can be a string array but not a structure. The string
option is a little restricted in that whatever the
input format, the string is viewed as a byte array
and the most frequent byte value returned
Opt. Inputs : None
Outputs : Function return is the modal value
Opt. Outputs: freq - the number of occurrences of the modal value
Keywords : BIN - sets binning size for histogram and hence 'resolution'
of modal value.
Calls : ***
Bell, DATATYPE [1], DATATYPE [2], DATATYPE [3]
CALLED BY:
LOAD_TP_STRUCT
Restrictions: Non-real arrays or strings only
Side effects: None
Category : Utilities, Numerical
Prev. Hist. : None
Written : C D Pike, RAL, 1-Jul-1993
Modified : Fix typo, add BIN keyword. CDP, 24-Jul-96
Version : Version 2, 24-Jul-96
[Previous]
[Next]
NAME:
MODFITS
PURPOSE:
Modify a FITS file by updating the header and/or data array.
EXPLANATION:
The size of the supplied FITS header or data array
does not need to match the size of the existing header or data array.
***NOTE** This version of MODFITS must be used with a post Sep 2006
version of FITS_OPEN.
CALLING SEQUENCE:
MODFITS, Filename_or_fcb, Data, [ Header, EXTEN_NO =, ERRMSG=]
INPUTS:
FILENAME/FCB = Scalar string containing either the name of the FITS file
to be modified, or the IO file control block returned after
opening the file with FITS_OPEN,/UPDATE. The explicit
use of FITS_OPEN can save time if many extensions in a
single file will be updated.
DATA - data array to be inserted into the FITS file. Set DATA = 0
to leave the data portion of the FITS file unmodified
HEADER - FITS header (string array) to be updated in the FITS file.
OPTIONAL INPUT KEYWORDS:
EXTEN_NO - scalar integer specifying the FITS extension to modified. For
example, specify EXTEN = 1 or /EXTEN to modify the first
FITS extension.
OPTIONAL OUTPUT KEYWORD:
ERRMSG - If this keyword is supplied, then any error mesasges will be
returned to the user in this parameter rather than depending on
on the MESSAGE routine in IDL. If no errors are encountered
then a null string is returned.
CALLED BY:
INTGCOMP_NRH2
EXAMPLES:
(1) Modify the value of the DATE keyword in the primary header of a
file TEST.FITS.
IDL> h = headfits('test.fits') ;Read primary header
IDL> sxaddpar,h,'DATE','2001-03-23' ;Modify value of DATE
IDL> modfits,'test.fits',0,h ;Update header only
(2) Replace the values of the primary image array in 'test.fits' with
their absolute values
IDL> im = readfits('test.fits') ;Read image array
IDL> im = abs(im) ;Take absolute values
IDL> modfits,'test.fits',im ;Update image array
(3) Add some HISTORY records to the FITS header in the first extension
of a file 'test.fits'
IDL> h = headfits('test.fits',/ext) ;Read first extension hdr
IDL> sxaddhist,['Comment 1','Comment 2'],h
IDL> modfits,'test.fits',0,h,/ext ;Update extension hdr
(4) Change 'OBSDATE' keyword to 'OBS-DATE' in every extension in a
FITS file. Explicitly open with FITS_OPEN to save compute time.
fits_open,'test.fits',io,/update ;Faster to explicity open
for i = 1,nextend do begin ;Loop over extensions
fits_read,io,0,h,/header_only,exten_no=i,/No_PDU ;Get header
date= sxpar(h,'OBSDATE') ;Save keyword value
sxaddpar,h,'OBS-DATE',date,after='OBSDATE'
sxdelpar,h,'OBSDATE' ;Delete bad keyword
modfits,io,0,h,exten_no=i ;Update header
endfor
Note the use of the /No_PDU keyword in the FITS_READ call -- one
does *not* want to append the primary header, if the STScI
inheritance convention is adopted.
NOTES:
Uses the BLKSHIFT procedure to shift the contents of the FITS file if
the new data or header differs in size by more than 2880 bytes from the
old data or header.
Also see the procedures FXHMODIFY to add a single FITS keyword to a
header in a FITS files, and FXBGROW to enlarge the size of a binary
table.
CALLS: ***
BLKSHIFT [1], BLKSHIFT [2], CHECK_FITS [1], CHECK_FITS [2], FITS_ADD_CHECKSUM
FITS_CLOSE, FITS_OPEN, FITS_READ, N_bytes, SXADDPAR [1], SXADDPAR [2], SXADDPAR [3]
SXPAR [1], SXPAR [2], SXPAR [3]
RESTRICTIONS:
(1) Cannot be used to modifiy the data in FITS files with random
groups or variable length binary tables. (The headers in such
files *can* be modified.)
(2) If a data array but no FITS header is supplied, then MODFITS does
not check to make sure that the existing header is consistent with
the new data.
(3) Does not work with compressed files
PROCEDURES USED:
Functions: N_BYTES(), SXPAR()
Procedures: BLKSHIFT, CHECK_FITS, FITS_OPEN, FITS_READ
MODIFICATION HISTORY:
Written, Wayne Landsman December, 1994
Converted to IDL V5.0 W. Landsman September 1997
Fixed possible problem when using WRITEU after READU October 1997
New and old sizes need only be the same within multiple of 2880 bytes
Added call to IS_IEEE_BIG() W. Landsman May 1999
Added ERRMSG output keyword W. Landsman May 2000
Update tests for incompatible sizes W. Landsman December 2000
Major rewrite to use FITS_OPEN procedures W. Landsman November 2001
Add /No_PDU call to FITS_READ call W. Landsman June 2002
Update CHECKSUM keywords if already present in header, add padding
if new data size is smaller than old W.Landsman December 2002
Only check XTENSION value if EXTEN_NO > 1 W. Landsman Feb. 2003
Correct for unsigned data on little endian machines W. Landsman Apr 2003
Major rewrite to allow changing size of data or header W.L. Aug 2003
Fixed case where updated header exactly fills boundary W.L. Feb 2004
More robust error reporting W.L. Dec 2004
Make sure input header ends with a END W.L. March 2006
Assume since V5.5, remove VMS support, assume FITS_OPEN will
perform byte swapping W.L. Sep 2006
[Previous]
[Next]
NAME:
moment2d
PURPOSE:
Calculate the generalized moment of an array relative to
a specified coordinate pair (i,j) (not necessarily located
within the array).
CALL:
moment = moment2d(input_array, i, j [,order])
INPUTS:
A - Input array
i,j - xy indices of pixel relative to which moment is calculated
OPTIONAL INPUT:
order - The exponent applied to distance array when weighting
each element's contribution to the moment
mask - Optional mask in which valid pixels are set to 1 and
invalid pixels are set to 0.
OUTPUTS:
Scalar moment of array relative to specified coordinate pair.
OPTIONAL OUTPUT:
METHOD:
Calculate the array of distances of each element in the input
array relative to the specified center coordinates. Then multiply
this distance array by the input array. Total the resulting array,
normalize the total by the number of points in the array, baste
in Hollandaise sauce, chill overnight, and serve with garnishes.
Serves 6-8 hungry scientists.
CALLS: ***
DIJ, EXIST
HISTORY:
10-Aug-2001 - Written by GLS.
[Previous]
[Next]
NAME:
MONTH_CNV
PURPOSE:
Convert between a month name and the equivalent number
EXPLANATION: (e.g.,
For example, converts from 'January' to 1 or vice-versa.
CALLING SEQUENCE:
Result = MONTH_CNV( MonthInput, [/UP, /LOW, /SHORT ] )
INPUTS:
MonthInput - either a string ('January', 'Jan', 'Decem', etc.) or
an number from 1 to 12. Scalar or array.
OPTIONAL KEYWORDS:
UP - if set and if a string is being returned, it will be in all
uppercase letters.
LOW - if set and if a string is being returned, it will be in all
lowercase letters.
SHORT - if set and if a string is being returned, only the first
three letters are returned.
OUTPUTS:
If the input is a string, the output is the matching month number.If
an input string isn't a valid month name, -1 is returned.
If the input is a number, the output is the matching month name. The
default format is only the first letter is capitalized.
CALLED BY:
GET_DATE [1], GET_DATE [2], ksc_commands
EXAMPLE:
To get a vector of all the month names:
Names = month_cnv(indgen(12)+1)
MODIFICATION HISTORY:
Written by: Joel Wm. Parker, SwRI, 1998 Dec 9
[Previous]
[Next]
NAME:
Month_id
PURPOSE:
Return the month number (1-12) as a function of the 3 letter
Month string.
CATEGORY:
Time format manipulation.
CALLING SEQUENCE:
Numbers = Month_id( Months )
CALLED BY:
Utime
INPUTS:
Months, a string array or scalar, upper or lower case.
The standard 3-letter representation for the months
jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec
OUTPUTS:
none explicit, only through commons;
Optional OUTPUTS:
error - set if function doesn't return values between 1-12
CALLED BY:
UTIME [1], UTIME [2], eit_files, eit_mirror, get_selsis
RESTRICTIONS:
Months must be given as strings with the first three letters spelled
explicitly, i.e. ['Jan','Feb',...].
PROCEDURE:
Converts months to uppercase and then 3 byte vectors. Arithmetic
operations then return a unique number for each month which is
used as the index into an array to return the number, 1-12. A
returned value of 0 indicates that the string was not a valid
input. It is possible for for invalid strings to return a number
from 1-12. Written to replace looping "where" statements. Output
has the same dimensions as the input, scalar returned as scalar.
For a function m defined below as
function m, month
nm=n_elements(month)
return, rebin((byte(strupcase(strmid(month(*),0,3)))-65)*3,1,nm)-9
end
The strings for each of the months have a unique numerical result.
We use this algorithm to provide the mapping from these strings to
the numerical representation of the months
IDL> print,test
jan feb mar apr may jun jul aug sep oct nov dec
IDL> print,m(test)
14
2
21
24
28
34
32
18
29
27
40
1
Warning -
While the transformation of each 3 letter string is unique, other Ascii
combinations may also map into these positions.
MODIFICATION HISTORY:
03-May-93, RAS
28-nov-94, ras, fixed error in translating November to number
[Previous]
[Next]
NAME:
MONTHNAMES
PURPOSE:
Returns a string array of month names.
CATEGORY:
CALLING SEQUENCE:
mnam = monthnames()
INPUTS:
KEYWORD PARAMETERS:
OUTPUTS:
mnam = string array of 13 items: out
['Error','January',...'December']
CALLED BY:
DT_TM_MAK [1], DT_TM_MAK [2], DT_TM_MAK [3], SUN [1], SUN [2]
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 18 Sep, 1989
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
[Previous]
[Next]
NAME:
MOONPOS
PURPOSE:
To compute the RA and Dec of the Moon at specified Julian date(s).
CALLING SEQUENCE:
MOONPOS, jd, ra, dec, dis, geolong, geolat, [/RADIAN ]
INPUTS:
JD - Julian date, scalar or vector, double precision suggested
OUTPUTS:
Ra - Apparent right ascension of the moon in DEGREES, referred to the
true equator of the specified date(s)
Dec - The declination of the moon in DEGREES
Dis - The Earth-moon distance in kilometers (between the center of the
Earth and the center of the Moon).
Geolong - Apparent longitude of the moon in DEGREES, referred to the
ecliptic of the specified date(s)
Geolat - Apparent longitude of the moon in DEGREES, referred to the
ecliptic of the specified date(s)
The output variables will all have the same number of elements as the
input Julian date vector, JD. If JD is a scalar then the output
variables will be also.
OPTIONAL INPUT KEYWORD:
/RADIAN - If this keyword is set and non-zero, then all output variables
are given in Radians rather than Degrees
CALLS: ***
CIRRANGE, ISARRAY [1], ISARRAY [2], ISARRAY [3], NUTATE, POLY, TEN
CALLED BY:
MPHASE
EXAMPLES:
(1) Find the position of the moon on April 12, 1992
IDL> jdcnv,1992,4,12,0,jd ;Get Julian date
IDL> moonpos, jd, ra ,dec ;Get RA and Dec of moon
IDL> print,adstring(ra,dec,1)
==> 08 58 45.23 +13 46 6.1
This is within 1" from the position given in the Astronomical Almanac
(2) Plot the Earth-moon distance for every day at 0 TD in July, 1996
IDL> jdcnv,1996,7,1,0,jd ;Get Julian date of July 1
IDL> moonpos,jd+dindgen(31), ra, dec, dis ;Position at all 31 days
IDL> plot,indgen(31),dis, /YNOZ
METHOD:
Derived from the Chapront ELP2000/82 Lunar Theory (Chapront-Touze' and
Chapront, 1983, 124, 50), as described by Jean Meeus in Chapter 47 of
``Astronomical Algorithms'' (Willmann-Bell, Richmond), 2nd edition,
1998. Meeus quotes an approximate accuracy of 10" in longitude and
4" in latitude, but he does not give the time range for this accuracy.
Comparison of this IDL procedure with the example in ``Astronomical
Algorithms'' reveals a very small discrepancy (~1 km) in the distance
computation, but no difference in the position calculation.
This procedure underwent a major rewrite in June 1996, and the new
calling sequence is *incompatible with the old* (e.g. angles now
returned in degrees instead of radians).
PROCEDURES CALLED:
CIRRANGE, ISARRAY(), NUTATE, TEN() - from IDL Astronomy Library
POLY() - from IDL User's Library
MODIFICATION HISTORY:
Written by Michael R. Greason, STX, 31 October 1988.
Major rewrite, new (incompatible) calling sequence, much improved
accuracy, W. Landsman Hughes STX June 1996
Added /RADIAN keyword W. Landsman August 1997
Converted to IDL V5.0 W. Landsman September 1997
Use improved expressions for L',D,M,M', and F given in 2nd edition of
Meeus (very slight change), W. Landsman November 2000
Avoid 32767 overflow W. Landsman January 2005
[Previous]
[Next]
NAME:
MORE
PURPOSE:
Display a text array using the MORE method.
CATEGORY:
CALLING SEQUENCE:
more, txtarr
INPUTS:
txtarr = string array to display. in
KEYWORD PARAMETERS:
Keywords:
/NUMBERS means display line numbers.
FORMAT=fmt specify format string (def=A).
Useful for listing numeric arrays, ex:
more,a,form='f8.3' or more,a,form='3x,f8.3'
OUTPUTS:
CALLS: ***
FILEPATH
CALLED BY:
ANNOUNCEMENTS, BATSE_ONTIMES, FLARE_XRAY_MODEL, FLDISPLAY, FLIST, FSPLOT, GD
GE_WINDOW [1], HSI_SPECTROSCOPY_LIST, LATEST_SFDS_GIF, N511_VS_HVSPEC, OCC_DBASE
PULSE_SPREAD, QLDISPLAY, RAWDUMP, RESP_CALC response calculation, batse_menu
doc_library2 [1], doc_library2 [2], eit_getobs, fastdoc [1], fastdoc [2]
go_lasdisk golaserdisk, go_lasdisk2 golaserdisk, hsi_ui_img, hsi_ui_spec
mk_sfc [1], mk_sfc [2], mo_init [1], mo_init [2], op_bdr_opt, op_term_score
plot_eit_mirror, pr_his_index [1], pr_his_index [2], pr_his_index [3]
pr_logwindows, pr_status [1], pr_status [2], prcols [1], prcols [2], prcols [3]
pro ratesdump, prstr [1], prstr [2], read_spartan, search_obs, spectral_ratio [1]
spectral_ratio [2], ssw_conflicts, sswloc, sxt_get_grill [1], sxt_get_grill [2]
tbb_info [1], tbb_info [2], teambb [1], teambb [2]
COMMON BLOCKS:
NOTES:
Note: when screen is full output will pause
until user presses SPACE to continue.
MODIFICATION HISTORY:
R. Sterner, 26 Feb, 1992
Jayant Murthy murthy@pha.jhu.edu 31 Oct 92 --- added FORMAT keyword.
R. Sterner, 29 Apr, 1993 --- changed for loop to long int.
25-Apr-94 (M.Morrison) - Added "on_ioerror" because it was crashing
on SGI machine at "FREE_LUN" command (even though it closed properly)
8-feb-1998, richard.schwartz@gsfc.nasa.gov,
Added protection for windows and macs, which do not support filepath(/terminal).
Send text to a standard IDL text widget, XDISPLAYFILE, instead.
25-Jul-2001, Kim.tolbert@gsfc.nasa.gov, added font=fixedsys on xdisplayfile call
30-Aug-2002, mimster@stars.gsfc.nasa.gov, added compatibility for IDLDE for unix
Copyright (C) 1992, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
[Previous]
[Next]
Project : SOHO-CDS
Name : MOVIE_MAP
Purpose : make movie of series of map images
Category : imaging
Syntax : movie_map,map
Inputs : MAP = array of map structures created by MAKE_MAP
Keywords : ROTATE = differentially rotate images
TREF = reference time to rotate to [def = first image]
GIF = make series of GIF files
MAX = data max to scale to
CMAP = contour map to overlay
CMIN,CMAX = min/max values for contoured data
TSTART/TSTOP = movie start/stop times
CROTATE = diff_rot contour images
GNAME = name for GIF frame [def = frame, e.g. frame00.gif]
RATE = RATE to show movie, percent of max rate (def=100)
NOSCALE = If set, don't scale to min/max of all images (def=0)
CALLS: ***
ANYTIM2TAI, CHECKVAR [1], CLEANPLOT [1], CLEANPLOT [2], CLEANPLOT [3]
DATATYPE [1], DATATYPE [2], DATATYPE [3], DPRINT, DROT_MAP, EXIST, GET_MAP_TIME
GET_TAG_INDEX, MATCH [1], MATCH [2], MATCH [3], PLOT_MAP, PR_SYNTAX, TRIM, VALID_MAP
X2GIF, XINTERANIMATE2, checkvar [2]
CALLED BY:
HESSI IMAGE STRATEGY CLASS DEFINITION, hsi_image__getaxis [2]
History : Written 22 November 1996, D. Zarro, ARC/GSFC
Contact : dzarro@solar.stanford.edu
Modifications:
9-Dec-2004, Kim Tolbert. Removed xkill,/all
10-Feb-2005, Kim Tolbert. Added noscale, rate, and abort keywords. Also, previously if
a window existed, used its xsize,ysize and ignored keywords. Now open new window with
requested size, and close it when finished. Use xinteranimate2 instead of xinteranimate
(cleans up after itself in a crash), remove /keep keyword, and set /track on.
[Previous]
[Next]
NAME:
MPCHILIM
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Compute confidence limits for chi-square statistic
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
DELCHI = MPCHILIM(PROB, DOF, [/SIGMA, /CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPCHILIM() computes confidence limits of the
chi-square statistic for a desired probability level. The returned
values, DELCHI, are the limiting chi-squared values: a chi-squared
value of greater than DELCHI will occur by chance with probability
PROB:
P_CHI(CHI > DELCHI; DOF) = PROB
In specifying the probability level the user has three choices:
* give the confidence level (default);
* give the significance level (i.e., 1 - confidence level) and
pass the /SLEVEL keyword; OR
* give the "sigma" of the probability (i.e., compute the
probability based on the normal distribution) and pass the
/SIGMA keyword.
Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.
INPUTS:
PROB - scalar or vector number, giving the desired probability
level as described above.
DOF - scalar or vector number, giving the number of degrees of
freedom in the chi-square distribution.
RETURNS:
Returns a scalar or vector of chi-square confidence limits.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level.
CLEVEL - if set, then PROB describes the confidence level
(default).
SIGMA - if set, then PROB is the number of "sigma" away from the
mean in the normal distribution.
EXAMPLES:
print, mpchilim(0.99d, 2d, /clevel)
Print the 99% confidence limit for a chi-squared of 2 degrees of
freedom.
print, mpchilim(5d, 2d, /sigma)
Print the "5 sigma" confidence limit for a chi-squared of 2
degrees of freedom. Here "5 sigma" indicates the gaussian
probability of a 5 sigma event or greater.
P_GAUSS(5D) = 1D - 5.7330314e-07
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/ )
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
$Id: mpchilim.pro,v 1.5 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
NAME:
MPCHITEST
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Compute the probability of a given chi-squared value
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
PROB = MPCHITEST(CHI, DOF, [/SIGMA, /CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPCHITEST() computes the probability for a value drawn
from the chi-square distribution to equal or exceed the given value
CHI. This can be used for confidence testing of a measured value
obeying the chi-squared distribution.
P_CHI(X > CHI; DOF) = PROB
In specifying the returned probability level the user has three
choices:
* return the confidence level when the /CLEVEL keyword is passed;
OR
* return the significance level (i.e., 1 - confidence level) when
the /SLEVEL keyword is passed (default); OR
* return the "sigma" of the probability (i.e., compute the
probability based on the normal distribution) when the /SIGMA
keyword is passed.
Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.
INPUTS:
CHI - chi-squared value to be tested.
DOF - scalar or vector number, giving the number of degrees of
freedom in the chi-square distribution.
RETURNS:
Returns a scalar or vector of probabilities, as described above,
and according to the /SLEVEL, /CLEVEL and /SIGMA keywords.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level
(default).
CLEVEL - if set, then PROB describes the confidence level.
SIGMA - if set, then PROB is the number of "sigma" away from the
mean in the normal distribution.
EXAMPLES:
print, mpchitest(1300d,1252d)
Print the probability for a chi-squared value with 1252 degrees of
freedom to exceed a value of 1300, as a confidence level.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/ )
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
$Id: mpchitest.pro,v 1.6 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
NAME:
MPCURVEFIT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Perform Levenberg-Marquardt least-squares fit (replaces CURVEFIT)
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
YFIT = MPCURVEFIT(X, Y, WEIGHTS, P, [SIGMA,] FUNCTION_NAME=FUNC,
ITER=iter, ITMAX=itmax,
CHISQ=chisq, NFREE=nfree, DOF=dof,
NFEV=nfev, COVAR=covar, [/NOCOVAR, ] [/NODERIVATIVE, ]
FUNCTARGS=functargs, PARINFO=parinfo,
FTOL=ftol, XTOL=xtol, GTOL=gtol, TOL=tol,
ITERPROC=iterproc, ITERARGS=iterargs,
NPRINT=nprint, QUIET=quiet,
ERRMSG=errmsg, STATUS=status)
DESCRIPTION:
MPCURVEFIT fits a user-supplied model -- in the form of an IDL
function -- to a set of user-supplied data. MPCURVEFIT calls
MPFIT, the MINPACK-1 least-squares minimizer, to do the main
work.
Given the data and their uncertainties, MPCURVEFIT finds the best
set of model parameters which match the data (in a least-squares
sense) and returns them in the parameter P.
MPCURVEFIT returns the best fit function.
The user must supply the following items:
- An array of independent variable values ("X").
- An array of "measured" *dependent* variable values ("Y").
- An array of weighting values ("WEIGHTS").
- The name of an IDL function which computes Y given X ("FUNC").
- Starting guesses for all of the parameters ("P").
There are very few restrictions placed on X, Y or FUNCT. Simply
put, FUNCT must map the "X" values into "Y" values given the
model parameters. The "X" values may represent any independent
variable (not just Cartesian X), and indeed may be multidimensional
themselves. For example, in the application of image fitting, X
may be a 2xN array of image positions.
MPCURVEFIT carefully avoids passing large arrays where possible to
improve performance.
See below for an example of usage.
USER FUNCTION
The user must define a function which returns the model value. For
applications which use finite-difference derivatives -- the default
-- the user function should be declared in the following way:
PRO MYFUNCT, X, P, YMOD
; The independent variable is X
; Parameter values are passed in "P"
YMOD = ... computed model values at X ...
END
The returned array YMOD must have the same dimensions and type as
the "measured" Y values.
User functions may also indicate a fatal error condition
using the ERROR_CODE common block variable, as described
below under the MPFIT_ERROR common block definition.
See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
in MPFIT.PRO if you wish to compute the derivatives for yourself.
AUTODERIVATIVE is accepted and passed directly to MPFIT. The user
function must accept one additional parameter, DP, which contains
the derivative of the user function with respect to each parameter
at each data point, as described in MPFIT.PRO.
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of MPFIT can be modified with respect to each
parameter to be fitted. A parameter value can be fixed; simple
boundary constraints can be imposed; limitations on the parameter
changes can be imposed; properties of the automatic derivative can
be modified; and parameters can be tied to one another.
These properties are governed by the PARINFO structure, which is
passed as a keyword parameter to MPFIT.
PARINFO should be an array of structures, one for each parameter.
Each parameter is associated with one element of the array, in
numerical order. The structure can have the following entries
(none are required):
.VALUE - the starting parameter value (but see the START_PARAMS
parameter for more information).
.FIXED - a boolean value, whether the parameter is to be held
fixed or not. Fixed parameters are not varied by
MPFIT, but are passed on to MYFUNCT for evaluation.
.LIMITED - a two-element boolean array. If the first/second
element is set, then the parameter is bounded on the
lower/upper side. A parameter can be bounded on both
sides. Both LIMITED and LIMITS must be given
together.
.LIMITS - a two-element float or double array. Gives the
parameter limits on the lower and upper sides,
respectively. Zero, one or two of these values can be
set, depending on the values of LIMITED. Both LIMITED
and LIMITS must be given together.
.PARNAME - a string, giving the name of the parameter. The
fitting code of MPFIT does not use this tag in any
way. However, the default ITERPROC will print the
parameter name if available.
.STEP - the step size to be used in calculating the numerical
derivatives. If set to zero, then the step size is
computed automatically. Ignored when AUTODERIVATIVE=0.
This value is superceded by the RELSTEP value.
.RELSTEP - the *relative* step size to be used in calculating
the numerical derivatives. This number is the
fractional size of the step, compared to the
parameter value. This value supercedes the STEP
setting. If the parameter is zero, then a default
step size is chosen.
.MPSIDE - the sidedness of the finite difference when computing
numerical derivatives. This field can take four
values:
0 - one-sided derivative computed automatically
1 - one-sided derivative (f(x+h) - f(x) )/h
-1 - one-sided derivative (f(x) - f(x-h))/h
2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)
Where H is the STEP parameter described above. The
"automatic" one-sided derivative method will chose a
direction for the finite difference which does not
violate any constraints. The other methods do not
perform this check. The two-sided method is in
principle more precise, but requires twice as many
function evaluations. Default: 0.
.MPMAXSTEP - the maximum change to be made in the parameter
value. During the fitting process, the parameter
will never be changed by more than this value in
one iteration.
A value of 0 indicates no maximum. Default: 0.
.TIED - a string expression which "ties" the parameter to other
free or fixed parameters. Any expression involving
constants and the parameter array P are permitted.
Example: if parameter 2 is always to be twice parameter
1 then use the following: parinfo(2).tied = '2 * P(1)'.
Since they are totally constrained, tied parameters are
considered to be fixed; no errors are computed for them.
[ NOTE: the PARNAME can't be used in expressions. ]
.MPPRINT - if set to 1, then the default ITERPROC will print the
parameter value. If set to 0, the parameter value
will not be printed. This tag can be used to
selectively print only a few parameter values out of
many. Default: 1 (all parameters printed)
Future modifications to the PARINFO structure, if any, will involve
adding structure tags beginning with the two letters "MP".
Therefore programmers are urged to avoid using tags starting with
the same letters; otherwise they are free to include their own
fields within the PARINFO structure, and they will be ignored.
PARINFO Example:
parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
limits:[0.D,0]}, 5)
parinfo(0).fixed = 1
parinfo(4).limited(0) = 1
parinfo(4).limits(0) = 50.D
parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
A total of 5 parameters, with starting values of 5.7,
2.2, 500, 1.5, and 2000 are given. The first parameter
is fixed at a value of 5.7, and the last parameter is
constrained to be above 50.
INPUTS:
X - Array of independent variable values.
Y - Array of "measured" dependent variable values. Y should have
the same data type as X. The function FUNCT should map
X->Y.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERR
parameter is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Y-FUNCT(X,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Y - Poisson weighting (counting statistics)
1D - Unweighted
P - An array of starting values for each of the parameters of the
model. The number of parameters should be fewer than the
number of measurements. Also, the parameters should have the
same data type as the measurements (double is preferred).
Upon successful completion the new parameter values are
returned in P.
If both START_PARAMS and PARINFO are passed, then the starting
*value* is taken from START_PARAMS, but the *constraints* are
taken from PARINFO.
SIGMA - The formal 1-sigma errors in each parameter, computed from
the covariance matrix. If a parameter is held fixed, or
if it touches a boundary, then the error is reported as
zero.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then SIGMA will
probably not represent the true parameter uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling SIGMA
by the measured chi-squared value.
DOF = N_ELEMENTS(X) - N_ELEMENTS(P) ; deg of freedom
CSIGMA = SIGMA * SQRT(CHISQ / DOF) ; scaled uncertainties
RETURNS:
Returns the array containing the best-fitting function.
KEYWORD PARAMETERS:
CHISQ - the value of the summed, squared, weighted residuals for
the returned parameter values, i.e. the chi-square value.
COVAR - the covariance matrix for the set of parameters returned
by MPFIT. The matrix is NxN where N is the number of
parameters. The square root of the diagonal elements
gives the formal 1-sigma statistical errors on the
parameters IF errors were treated "properly" in MYFUNC.
Parameter errors are also returned in PERROR.
To compute the correlation matrix, PCOR, use this:
IDL> PCOR = COV * 0
IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))
If NOCOVAR is set or MPFIT terminated abnormally, then
COVAR is set to a scalar with value !VALUES.D_NAN.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERRMSG - a string error or warning message is returned.
FTOL - a nonnegative input variable. Termination occurs when both
the actual and predicted relative reductions in the sum of
squares are at most FTOL (and STATUS is accordingly set to
1 or 3). Therefore, FTOL measures the relative error
desired in the sum of squares. Default: 1D-10
FUNCTION_NAME - a scalar string containing the name of an IDL
procedure to compute the user model values, as
described above in the "USER MODEL" section.
FUNCTARGS - A structure which contains the parameters to be passed
to the user-supplied function specified by FUNCT via
the _EXTRA mechanism. This is the way you can pass
additional data to your user-supplied function without
using common blocks.
By default, no extra parameters are passed to the
user-supplied function.
GTOL - a nonnegative input variable. Termination occurs when the
cosine of the angle between fvec and any column of the
jacobian is at most GTOL in absolute value (and STATUS is
accordingly set to 4). Therefore, GTOL measures the
orthogonality desired between the function vector and the
columns of the jacobian. Default: 1D-10
ITER - the number of iterations completed.
ITERARGS - The keyword arguments to be passed to ITERPROC via the
_EXTRA mechanism. This should be a structure, and is
similar in operation to FUNCTARGS.
Default: no arguments are passed.
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the MPFIT routine. It should be declared
in the following way:
PRO ITERPROC, FUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, ...
; perform custom iteration update
END
ITERPROC must either accept all three keyword
parameters (FUNCTARGS, PARINFO and QUIET), or at least
accept them via the _EXTRA keyword.
FUNCT is the user-supplied function to be minimized,
P is the current set of model parameters, ITER is the
iteration number, and FUNCTARGS are the arguments to be
passed to FUNCT. FNORM should be the
chi-squared value. QUIET is set when no textual output
should be printed. See below for documentation of
PARINFO.
In implementation, ITERPROC can perform updates to the
terminal or graphical user interface, to provide
feedback while the fit proceeds. If the fit is to be
stopped for any reason, then ITERPROC should set the
common block variable ERROR_CODE to negative value (see
MPFIT_ERROR common block below). In principle,
ITERPROC should probably not modify the parameter
values, because it may interfere with the algorithm's
stability. In practice it is allowed.
Default: an internal routine is used to print the
parameter values.
ITMAX - The maximum number of iterations to perform. If the
number is exceeded, then the STATUS value is set to 5
and MPFIT returns.
Default: 200 iterations
NFEV - the number of FUNCT function evaluations performed.
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
NOCOVAR - set this keyword to prevent the calculation of the
covariance matrix before returning (see COVAR)
NODERIVATIVE - if set, then the user function will not be queried
for analytical derivatives, and instead the
derivatives will be computed by finite differences
(and according to the PARINFO derivative settings;
see above for a description).
NPRINT - The frequency with which ITERPROC is called. A value of
1 indicates that ITERPROC is called with every iteration,
while 2 indicates every other iteration, etc. Note that
several Levenberg-Marquardt attempts can be made in a
single iteration.
Default value: 1
PARINFO - Provides a mechanism for more sophisticated constraints
to be placed on parameter values. When PARINFO is not
passed, then it is assumed that all parameters are free
and unconstrained. Values in PARINFO are never
modified during a call to MPFIT.
See description above for the structure of PARINFO.
Default value: all parameters are free and unconstrained.
QUIET - set this keyword when no textual output should be printed
by MPFIT
STATUS - an integer status code is returned. All values other
than zero can represent success. It can have one of the
following values:
0 improper input parameters.
1 both actual and predicted relative reductions
in the sum of squares are at most FTOL.
2 relative error between two consecutive iterates
is at most XTOL
3 conditions for STATUS = 1 and STATUS = 2 both hold.
4 the cosine of the angle between fvec and any
column of the jacobian is at most GTOL in
absolute value.
5 the maximum number of iterations has been reached
6 FTOL is too small. no further reduction in
the sum of squares is possible.
7 XTOL is too small. no further improvement in
the approximate solution x is possible.
8 GTOL is too small. fvec is orthogonal to the
columns of the jacobian to machine precision.
TOL - synonym for FTOL. Use FTOL instead.
XTOL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at most
XTOL (and STATUS is accordingly set to 2 or 3). Therefore,
XTOL measures the relative error desired in the approximate
solution. Default: 1D-10
YERROR - upon return, the root-mean-square variance of the
residuals.
EXAMPLE:
; First, generate some synthetic data
npts = 200
x = dindgen(npts) * 0.1 - 10. ; Independent variable
yi = gauss1(x, [2.2D, 1.4, 3000.]) ; "Ideal" Y variable
y = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
sy = sqrt(1000.D + y) ; Poisson errors
; Now fit a Gaussian to see how well we can recover
p0 = [1.D, 1., 1000.] ; Initial guess
yfit = mpcurvefit(x, y, 1/sy^2, p0, $ ; Fit a function
FUNCTION_NAME='GAUSS1P',/autoderivative)
print, p
Generates a synthetic data set with a Gaussian peak, and Poisson
statistical uncertainty. Then the same function is fitted to the
data to see how close we can get. GAUSS1 and GAUSS1P are
available from the same web page.
COMMON BLOCKS:
COMMON MPFIT_ERROR, ERROR_CODE
User routines may stop the fitting process at any time by
setting an error condition. This condition may be set in either
the user's model computation routine (MYFUNCT), or in the
iteration procedure (ITERPROC).
To stop the fitting, the above common block must be declared,
and ERROR_CODE must be set to a negative number. After the user
procedure or function returns, MPFIT checks the value of this
common block variable and exits immediately if the error
condition has been set. By default the value of ERROR_CODE is
zero, indicating a successful function/procedure call.
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
Translated from MPFITFUN, 25 Sep 1999, CM
Alphabetized documented keywords, 02 Oct 1999, CM
Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
Check to be sure that X and Y are present, 02 Nov 1999, CM
Documented SIGMA for unweighted fits, 03 Nov 1999, CM
Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Propagated improvements from MPFIT, 17 Dec 2000, CM
Corrected behavior of NODERIVATIVE, 13 May 2002, CM
Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
Make more consistent with comparable IDL routines, 30 Jun 2003, CM
Minor documentation adjustment, 03 Feb 2004, CM
Fix error in documentation, 26 Aug 2005, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
$Id: mpcurvefit.pro,v 1.8 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
NAME:
MPFIT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Perform Levenberg-Marquardt least-squares minimization (MINPACK-1)
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
parms = MPFIT(MYFUNCT, start_parms, FUNCTARGS=fcnargs, NFEV=nfev,
MAXITER=maxiter, ERRMSG=errmsg, NPRINT=nprint, QUIET=quiet,
FTOL=ftol, XTOL=xtol, GTOL=gtol, NITER=niter,
STATUS=status, ITERPROC=iterproc, ITERARGS=iterargs,
COVAR=covar, PERROR=perror, BESTNORM=bestnorm,
PARINFO=parinfo)
DESCRIPTION:
MPFIT uses the Levenberg-Marquardt technique to solve the
least-squares problem. In its typical use, MPFIT will be used to
fit a user-supplied function (the "model") to user-supplied data
points (the "data") by adjusting a set of parameters. MPFIT is
based upon MINPACK-1 (LMDIF.F) by More' and collaborators.
For example, a researcher may think that a set of observed data
points is best modelled with a Gaussian curve. A Gaussian curve is
parameterized by its mean, standard deviation and normalization.
MPFIT will, within certain constraints, find the set of parameters
which best fits the data. The fit is "best" in the least-squares
sense; that is, the sum of the weighted squared differences between
the model and data is minimized.
The Levenberg-Marquardt technique is a particular strategy for
iteratively searching for the best fit. This particular
implementation is drawn from MINPACK-1 (see NETLIB), and seems to
be more robust than routines provided with IDL. This version
allows upper and lower bounding constraints to be placed on each
parameter, or the parameter can be held fixed.
The IDL user-supplied function should return an array of weighted
deviations between model and data. In a typical scientific problem
the residuals should be weighted so that each deviate has a
gaussian sigma of 1.0. If X represents values of the independent
variable, Y represents a measurement for each value of X, and ERR
represents the error in the measurements, then the deviates could
be calculated as follows:
DEVIATES = (Y - F(X)) / ERR
where F is the analytical function representing the model. You are
recommended to use the convenience functions MPFITFUN and
MPFITEXPR, which are driver functions that calculate the deviates
for you. If ERR are the 1-sigma uncertainties in Y, then
TOTAL( DEVIATES^2 )
will be the total chi-squared value. MPFIT will minimize the
chi-square value. The values of X, Y and ERR are passed through
MPFIT to the user-supplied function via the FUNCTARGS keyword.
Simple constraints can be placed on parameter values by using the
PARINFO keyword to MPFIT. See below for a description of this
keyword.
MPFIT does not perform more general optimization tasks. See TNMIN
instead. MPFIT is customized, based on MINPACK-1, to the
least-squares minimization problem.
USER FUNCTION
The user must define a function which returns the appropriate
values as specified above. The function should return the weighted
deviations between the model and the data. For applications which
use finite-difference derivatives -- the default -- the user
function should be declared in the following way:
FUNCTION MYFUNCT, p, X=x, Y=y, ERR=err
; Parameter values are passed in "p"
model = F(x, p)
return, (y-model)/err
END
See below for applications with analytical derivatives.
The keyword parameters X, Y, and ERR in the example above are
suggestive but not required. Any parameters can be passed to
MYFUNCT by using the FUNCTARGS keyword to MPFIT. Use MPFITFUN and
MPFITEXPR if you need ideas on how to do that. The function *must*
accept a parameter list, P.
In general there are no restrictions on the number of dimensions in
X, Y or ERR. However the deviates *must* be returned in a
one-dimensional array, and must have the same type (float or
double) as the input arrays.
User functions may also indicate a fatal error condition using the
ERROR_CODE common block variable, as described below under the
MPFIT_ERROR common block definition (by setting ERROR_CODE to a
number between -15 and -1).
ANALYTIC DERIVATIVES
In the search for the best-fit solution, MPFIT by default
calculates derivatives numerically via a finite difference
approximation. The user-supplied function need not calculate the
derivatives explicitly. However, if you desire to compute them
analytically, then the AUTODERIVATIVE=0 keyword must be passed. As
a practical matter, it is often sufficient and even faster to allow
MPFIT to calculate the derivatives numerically, and so
AUTODERIVATIVE=0 is not necessary.
Also, the user function must be declared with one additional
parameter, as follows:
FUNCTION MYFUNCT, p, dp, X=x, Y=y, ERR=err
model = F(x, p)
if n_params() GT 1 then begin
; Compute derivatives
dp = make_array(n_elements(x), n_elements(p), value=x[0]*0)
for i = 0, n_elements(p)-1 do $
dp(*,i) = FGRAD(x, p, i)
endif
return, (y-model)/err
END
where FGRAD(x, p, i) is a user function which must compute the
derivative of the model with respect to parameter P(i) at X. When
finite differencing is used for computing derivatives (ie, when
AUTODERIVATIVE=1), the parameter DP is not passed. Therefore
functions can use N_PARAMS() to indicate whether they must compute
the derivatives or not.
Derivatives should be returned in the DP array. DP should be an m x
n array, where m is the number of data points and n is the number
of parameters. dp[i,j] is the derivative at the ith point with
respect to the jth parameter.
The derivatives with respect to fixed parameters are ignored; zero
is an appropriate value to insert for those derivatives. Upon
input to the user function, DP is set to a vector with the same
length as P, with a value of 1 for a parameter which is free, and a
value of zero for a parameter which is fixed (and hence no
derivative needs to be calculated). This input vector may be
overwritten as needed.
If the data is higher than one dimensional, then the *last*
dimension should be the parameter dimension. Example: fitting a
50x50 image, "dp" should be 50x50xNPAR.
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of MPFIT can be modified with respect to each
parameter to be fitted. A parameter value can be fixed; simple
boundary constraints can be imposed; limitations on the parameter
changes can be imposed; properties of the automatic derivative can
be modified; and parameters can be tied to one another.
These properties are governed by the PARINFO structure, which is
passed as a keyword parameter to MPFIT.
PARINFO should be an array of structures, one for each parameter.
Each parameter is associated with one element of the array, in
numerical order. The structure can have the following entries
(none are required):
.VALUE - the starting parameter value (but see the START_PARAMS
parameter for more information).
.FIXED - a boolean value, whether the parameter is to be held
fixed or not. Fixed parameters are not varied by
MPFIT, but are passed on to MYFUNCT for evaluation.
.LIMITED - a two-element boolean array. If the first/second
element is set, then the parameter is bounded on the
lower/upper side. A parameter can be bounded on both
sides. Both LIMITED and LIMITS must be given
together.
.LIMITS - a two-element float or double array. Gives the
parameter limits on the lower and upper sides,
respectively. Zero, one or two of these values can be
set, depending on the values of LIMITED. Both LIMITED
and LIMITS must be given together.
.PARNAME - a string, giving the name of the parameter. The
fitting code of MPFIT does not use this tag in any
way. However, the default ITERPROC will print the
parameter name if available.
.STEP - the step size to be used in calculating the numerical
derivatives. If set to zero, then the step size is
computed automatically. Ignored when AUTODERIVATIVE=0.
This value is superceded by the RELSTEP value.
.RELSTEP - the *relative* step size to be used in calculating
the numerical derivatives. This number is the
fractional size of the step, compared to the
parameter value. This value supercedes the STEP
setting. If the parameter is zero, then a default
step size is chosen.
.MPSIDE - the sidedness of the finite difference when computing
numerical derivatives. This field can take four
values:
0 - one-sided derivative computed automatically
1 - one-sided derivative (f(x+h) - f(x) )/h
-1 - one-sided derivative (f(x) - f(x-h))/h
2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)
Where H is the STEP parameter described above. The
"automatic" one-sided derivative method will chose a
direction for the finite difference which does not
violate any constraints. The other methods do not
perform this check. The two-sided method is in
principle more precise, but requires twice as many
function evaluations. Default: 0.
.MPMAXSTEP - the maximum change to be made in the parameter
value. During the fitting process, the parameter
will never be changed by more than this value in
one iteration.
A value of 0 indicates no maximum. Default: 0.
.TIED - a string expression which "ties" the parameter to other
free or fixed parameters as an equality constraint. Any
expression involving constants and the parameter array P
are permitted.
CALLED BY:
OVSA_EXPLORER formerly OVSA_PRESUB, OVSA_MPFIT
Example: if parameter 2 is always to be twice parameter
1 then use the following: parinfo[2].tied = '2 * P[1]'.
Since they are totally constrained, tied parameters are
considered to be fixed; no errors are computed for them.
[ NOTE: the PARNAME can't be used in expressions. ]
.MPPRINT - if set to 1, then the default ITERPROC will print the
parameter value. If set to 0, the parameter value
will not be printed. This tag can be used to
selectively print only a few parameter values out of
many. Default: 1 (all parameters printed)
.MPFORMAT - IDL format string to print the parameter within
ITERPROC. Default: '(G20.6)' An empty string will
also use the default.
Future modifications to the PARINFO structure, if any, will involve
adding structure tags beginning with the two letters "MP".
Therefore programmers are urged to avoid using tags starting with
the same letters; otherwise they are free to include their own
fields within the PARINFO structure, and they will be ignored.
PARINFO Example:
parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
limits:[0.D,0]}, 5)
parinfo[0].fixed = 1
parinfo[4].limited(0) = 1
parinfo[4].limits(0) = 50.D
parinfo[*].value = [5.7D, 2.2, 500., 1.5, 2000.]
A total of 5 parameters, with starting values of 5.7,
2.2, 500, 1.5, and 2000 are given. The first parameter
is fixed at a value of 5.7, and the last parameter is
constrained to be above 50.
HARD-TO-COMPUTE FUNCTIONS: "EXTERNAL" EVALUATION
The normal mode of operation for MPFIT is for the user to pass a
function name, and MPFIT will call the user function multiple times
as it iterates toward a solution.
Some user functions are particularly hard to compute using the
standard model of MPFIT. Usually these are functions that depend
on a large amount of external data, and so it is not feasible, or
at least highly impractical, to have MPFIT call it. In those cases
it may be possible to use the "(EXTERNAL)" evaluation option.
In this case the user is responsible for making all function *and
derivative* evaluations. The function and Jacobian data are passed
in through the EXTERNAL_FVEC and EXTERNAL_FJAC keywords,
respectively. The user indicates the selection of this option by
specifying a function name (MYFUNCT) of "(EXTERNAL)". No
user-function calls are made when EXTERNAL evaluation is being
used.
At the end of each iteration, control returns to the user, who must
reevaluate the function at its new parameter values. Users should
check the return value of the STATUS keyword, where a value of 9
indicates the user should supply more data for the next iteration,
and re-call MPFIT. The user may refrain from calling MPFIT
further; as usual, STATUS will indicate when the solution has
converged and no more iterations are required.
Because MPFIT must maintain its own data structures between calls,
the user must also pass a named variable to the EXTERNAL_STATE
keyword. This variable must be maintained by the user, but not
changed, throughout the fitting process. When no more iterations
are desired, the named variable may be discarded.
INPUTS:
MYFUNCT - a string variable containing the name of the function to
be minimized. The function should return the weighted
deviations between the model and the data, as described
above.
For EXTERNAL evaluation of functions, this parameter
should be set to a value of "(EXTERNAL)".
START_PARAMS - An array of starting values for each of the
parameters of the model. The number of parameters
should be fewer than the number of measurements.
Also, the parameters should have the same data type
as the measurements (double is preferred).
This parameter is optional if the PARINFO keyword
is used (but see PARINFO). The PARINFO keyword
provides a mechanism to fix or constrain individual
parameters. If both START_PARAMS and PARINFO are
passed, then the starting *value* is taken from
START_PARAMS, but the *constraints* are taken from
PARINFO.
RETURNS:
Returns the array of best-fit parameters.
KEYWORD PARAMETERS:
AUTODERIVATIVE - If this is set, derivatives of the function will
be computed automatically via a finite
differencing procedure. If not set, then MYFUNCT
must provide the (analytical) derivatives.
Default: set (=1)
NOTE: to supply your own analytical derivatives,
explicitly pass AUTODERIVATIVE=0
BESTNORM - the value of the summed squared weighted residuals for
the returned parameter values, i.e. TOTAL(DEVIATES^2).
COVAR - the covariance matrix for the set of parameters returned
by MPFIT. The matrix is NxN where N is the number of
parameters. The square root of the diagonal elements
gives the formal 1-sigma statistical errors on the
parameters IF errors were treated "properly" in MYFUNC.
Parameter errors are also returned in PERROR.
To compute the correlation matrix, PCOR, use this example:
IDL> PCOR = COV * 0
IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
PCOR[i,j] = COV[i,j]/sqrt(COV[i,i]*COV[j,j])
If NOCOVAR is set or MPFIT terminated abnormally, then
COVAR is set to a scalar with value !VALUES.D_NAN.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERRMSG - a string error or warning message is returned.
EXTERNAL_FVEC - upon input, the function values, evaluated at
START_PARAMS. This should be an M-vector, where M
is the number of data points.
EXTERNAL_FJAC - upon input, the Jacobian array of partial
derivative values. This should be a M x N array,
where M is the number of data points and N is the
number of parameters. NOTE: that all FIXED or
TIED parameters must *not* be included in this
array.
EXTERNAL_STATE - a named variable to store MPFIT-related state
information between iterations (used in input and
output to MPFIT). The user must not manipulate
or discard this data until the final iteration is
performed.
FASTNORM - set this keyword to select a faster algorithm to
compute sum-of-square values internally. For systems
with large numbers of data points, the standard
algorithm can become prohibitively slow because it
cannot be vectorized well. By setting this keyword,
MPFIT will run faster, but it will be more prone to
floating point overflows and underflows. Thus, setting
this keyword may sacrifice some stability in the
fitting process.
FTOL - a nonnegative input variable. Termination occurs when both
the actual and predicted relative reductions in the sum of
squares are at most FTOL (and STATUS is accordingly set to
1 or 3). Therefore, FTOL measures the relative error
desired in the sum of squares. Default: 1D-10
FUNCTARGS - A structure which contains the parameters to be passed
to the user-supplied function specified by MYFUNCT via
the _EXTRA mechanism. This is the way you can pass
additional data to your user-supplied function without
using common blocks.
Consider the following example:
if FUNCTARGS = { XVAL:[1.D,2,3], YVAL:[1.D,4,9],
ERRVAL:[1.D,1,1] }
then the user supplied function should be declared
like this:
FUNCTION MYFUNCT, P, XVAL=x, YVAL=y, ERRVAL=err
By default, no extra parameters are passed to the
user-supplied function, but your function should
accept *at least* one keyword parameter. [ This is to
accomodate a limitation in IDL's _EXTRA
parameter-passing mechanism. ]
GTOL - a nonnegative input variable. Termination occurs when the
cosine of the angle between fvec and any column of the
jacobian is at most GTOL in absolute value (and STATUS is
accordingly set to 4). Therefore, GTOL measures the
orthogonality desired between the function vector and the
columns of the jacobian. Default: 1D-10
ITERARGS - The keyword arguments to be passed to ITERPROC via the
_EXTRA mechanism. This should be a structure, and is
similar in operation to FUNCTARGS.
Default: no arguments are passed.
ITERPRINT - The name of an IDL procedure, equivalent to PRINT,
that ITERPROC will use to render output. ITERPRINT
should be able to accept at least four positional
arguments. In addition, it should be able to accept
the standard FORMAT keyword for output formatting; and
the UNIT keyword, to redirect output to a logical file
unit (default should be UNIT=1, standard output).
These keywords are passed using the ITERARGS keyword
above. The ITERPRINT procedure must accept the _EXTRA
keyword.
NOTE: that much formatting can be handled with the
MPPRINT and MPFORMAT tags.
Default: 'MPFIT_DEFPRINT' (default internal formatter)
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the MPFIT routine. ITERPROC is always
called in the final iteration. It should be declared
in the following way:
PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, DOF=dof, PFORMAT=pformat, $
UNIT=unit, ...
; perform custom iteration update
END
ITERPROC must either accept all three keyword
parameters (FUNCTARGS, PARINFO and QUIET), or at least
accept them via the _EXTRA keyword.
MYFUNCT is the user-supplied function to be minimized,
P is the current set of model parameters, ITER is the
iteration number, and FUNCTARGS are the arguments to be
passed to MYFUNCT. FNORM should be the chi-squared
value. QUIET is set when no textual output should be
printed. DOF is the number of degrees of freedom,
normally the number of points less the number of free
parameters. See below for documentation of PARINFO.
PFORMAT is the default parameter value format. UNIT is
passed on to the ITERPRINT procedure, and should
indicate the file unit where log output will be sent
(default: standard output).
In implementation, ITERPROC can perform updates to the
terminal or graphical user interface, to provide
feedback while the fit proceeds. If the fit is to be
stopped for any reason, then ITERPROC should set the
common block variable ERROR_CODE to negative value
between -15 and -1 (see MPFIT_ERROR common block
below). In principle, ITERPROC should probably not
modify the parameter values, because it may interfere
with the algorithm's stability. In practice it is
allowed.
Default: an internal routine is used to print the
parameter values.
ITERSTOP - Set this keyword if you wish to be able to stop the
fitting by hitting the predefined ITERKEYSTOP key on
the keyboard. This only works if you use the default
ITERPROC.
ITERKEYSTOP - A keyboard key which will halt the fit (and if
ITERSTOP is set and the default ITERPROC is used).
ITERSTOPKEY may either be a one-character string
with the desired key, or a scalar integer giving the
ASCII code of the desired key.
Default: 7b (control-g)
NOTE: the default value of ASCI 7 (control-G) cannot
be read in some windowing environments, so you must
change to a printable character like 'q'.
MAXITER - The maximum number of iterations to perform. If the
number is exceeded, then the STATUS value is set to 5
and MPFIT returns.
Default: 200 iterations
NFEV - the number of MYFUNCT function evaluations performed.
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
NITER - the number of iterations completed.
NOCOVAR - set this keyword to prevent the calculation of the
covariance matrix before returning (see COVAR)
NPEGGED - the number of free parameters which are pegged at a
LIMIT.
NPRINT - The frequency with which ITERPROC is called. A value of
1 indicates that ITERPROC is called with every iteration,
while 2 indicates every other iteration, etc. Be aware
that several Levenberg-Marquardt attempts can be made in
a single iteration. Also, the ITERPROC is *always*
called for the final iteration, regardless of the
iteration number.
Default value: 1
PARINFO - Provides a mechanism for more sophisticated constraints
to be placed on parameter values. When PARINFO is not
passed, then it is assumed that all parameters are free
and unconstrained. Values in PARINFO are never
modified during a call to MPFIT.
See description above for the structure of PARINFO.
Default value: all parameters are free and unconstrained.
PERROR - The formal 1-sigma errors in each parameter, computed
from the covariance matrix. If a parameter is held
fixed, or if it touches a boundary, then the error is
reported as zero.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling PERROR
by the measured chi-squared value.
DOF = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
QUIET - set this keyword when no textual output should be printed
by MPFIT
RESDAMP - a scalar number, indicating the cut-off value of
residuals where "damping" will occur. Residuals with
magnitudes greater than this number will be replaced by
their logarithm. This partially mitigates the so-called
large residual problem inherent in least-squares solvers
(as for the test problem CURVI, http://www.maxthis.com/-
curviex.htm). A value of 0 indicates no damping.
Default: 0
Note: RESDAMP doesn't work with AUTODERIV=0
STATUS - an integer status code is returned. All values greater
than zero can represent success (however STATUS EQ 5 may
indicate failure to converge). It can have one of the
following values:
-16 a parameter or function value has become infinite or an
undefined number. This is usually a consequence of
numerical overflow in the user's model function, which
must be avoided.
-15 to -1
these are error codes that either MYFUNCT or ITERPROC
may return to terminate the fitting process (see
description of MPFIT_ERROR common below). If either
MYFUNCT or ITERPROC set ERROR_CODE to a negative number,
then that number is returned in STATUS. Values from -15
to -1 are reserved for the user functions and will not
clash with MPFIT.
0 improper input parameters.
1 both actual and predicted relative reductions
in the sum of squares are at most FTOL.
2 relative error between two consecutive iterates
is at most XTOL
3 conditions for STATUS = 1 and STATUS = 2 both hold.
4 the cosine of the angle between fvec and any
column of the jacobian is at most GTOL in
absolute value.
5 the maximum number of iterations has been reached
6 FTOL is too small. no further reduction in
the sum of squares is possible.
7 XTOL is too small. no further improvement in
the approximate solution x is possible.
8 GTOL is too small. fvec is orthogonal to the
columns of the jacobian to machine precision.
9 A successful single iteration has been completed, and
the user must supply another "EXTERNAL" evaluation of
the function and its derivatives. This status indicator
is neither an error nor a convergence indicator.
XTOL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at most
XTOL (and STATUS is accordingly set to 2 or 3). Therefore,
XTOL measures the relative error desired in the approximate
solution. Default: 1D-10
EXAMPLE:
p0 = [5.7D, 2.2, 500., 1.5, 2000.]
fa = {X:x, Y:y, ERR:err}
p = mpfit('MYFUNCT', p0, functargs=fa)
Minimizes sum of squares of MYFUNCT. MYFUNCT is called with the X,
Y, and ERR keyword parameters that are given by FUNCTARGS. The
resulting parameter values are returned in p.
COMMON BLOCKS:
COMMON MPFIT_ERROR, ERROR_CODE
User routines may stop the fitting process at any time by
setting an error condition. This condition may be set in either
the user's model computation routine (MYFUNCT), or in the
iteration procedure (ITERPROC).
To stop the fitting, the above common block must be declared,
and ERROR_CODE must be set to a negative number. After the user
procedure or function returns, MPFIT checks the value of this
common block variable and exits immediately if the error
condition has been set. This value is also returned in the
STATUS keyword: values of -1 through -15 are reserved error
codes for the user routines. By default the value of ERROR_CODE
is zero, indicating a successful function/procedure call.
COMMON MPFIT_PROFILE
COMMON MPFIT_MACHAR
COMMON MPFIT_CONFIG
These are undocumented common blocks are used internally by
MPFIT and may change in future implementations.
THEORY OF OPERATION:
There are many specific strategies for function minimization. One
very popular technique is to use function gradient information to
realize the local structure of the function. Near a local minimum
the function value can be taylor expanded about x0 as follows:
f(x) = f(x0) + f'(x0) . (x-x0) + (1/2) (x-x0) . f''(x0) . (x-x0)
----- --------------- ------------------------------- (1)
Order 0th 1st 2nd
Here f'(x) is the gradient vector of f at x, and f''(x) is the
Hessian matrix of second derivatives of f at x. The vector x is
the set of function parameters, not the measured data vector. One
can find the minimum of f, f(xm) using Newton's method, and
arrives at the following linear equation:
f''(x0) . (xm-x0) = - f'(x0) (2)
If an inverse can be found for f''(x0) then one can solve for
(xm-x0), the step vector from the current position x0 to the new
projected minimum. Here the problem has been linearized (ie, the
gradient information is known to first order). f''(x0) is
symmetric n x n matrix, and should be positive definite.
The Levenberg - Marquardt technique is a variation on this theme.
It adds an additional diagonal term to the equation which may aid the
convergence properties:
(f''(x0) + nu I) . (xm-x0) = -f'(x0) (2a)
where I is the identity matrix. When nu is large, the overall
matrix is diagonally dominant, and the iterations follow steepest
descent. When nu is small, the iterations are quadratically
convergent.
In principle, if f''(x0) and f'(x0) are known then xm-x0 can be
determined. However the Hessian matrix is often difficult or
impossible to compute. The gradient f'(x0) may be easier to
compute, if even by finite difference techniques. So-called
quasi-Newton techniques attempt to successively estimate f''(x0)
by building up gradient information as the iterations proceed.
In the least squares problem there are further simplifications
which assist in solving eqn (2). The function to be minimized is
a sum of squares:
f = Sum(hi^2) (3)
where hi is the ith residual out of m residuals as described
above. This can be substituted back into eqn (2) after computing
the derivatives:
f' = 2 Sum(hi hi')
f'' = 2 Sum(hi' hj') + 2 Sum(hi hi'') (4)
If one assumes that the parameters are already close enough to a
minimum, then one typically finds that the second term in f'' is
negligible [or, in any case, is too difficult to compute]. Thus,
equation (2) can be solved, at least approximately, using only
gradient information.
In matrix notation, the combination of eqns (2) and (4) becomes:
hT' . h' . dx = - hT' . h (5)
Where h is the residual vector (length m), hT is its transpose, h'
is the Jacobian matrix (dimensions n x m), and dx is (xm-x0). The
user function supplies the residual vector h, and in some cases h'
when it is not found by finite differences (see MPFIT_FDJAC2,
which finds h and hT'). Even if dx is not the best absolute step
to take, it does provide a good estimate of the best *direction*,
so often a line minimization will occur along the dx vector
direction.
The method of solution employed by MINPACK is to form the Q . R
factorization of h', where Q is an orthogonal matrix such that QT .
Q = I, and R is upper right triangular. Using h' = Q . R and the
ortogonality of Q, eqn (5) becomes
(RT . QT) . (Q . R) . dx = - (RT . QT) . h
RT . R . dx = - RT . QT . h (6)
R . dx = - QT . h
where the last statement follows because R is upper triangular.
Here, R, QT and h are known so this is a matter of solving for dx.
The routine MPFIT_QRFAC provides the QR factorization of h, with
pivoting, and MPFIT_QRSOLV provides the solution for dx.
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
More', Jorge J., "The Levenberg-Marquardt Algorithm:
Implementation and Theory," in *Numerical Analysis*, ed. Watson,
G. A., Lecture Notes in Mathematics 630, Springer-Verlag, 1977.
MODIFICATION HISTORY:
Translated from MINPACK-1 in FORTRAN, Apr-Jul 1998, CM
Fixed bug in parameter limits (x vs xnew), 04 Aug 1998, CM
Added PERROR keyword, 04 Aug 1998, CM
Added COVAR keyword, 20 Aug 1998, CM
Added NITER output keyword, 05 Oct 1998
D.L Windt, Bell Labs, windt@bell-labs.com;
Made each PARINFO component optional, 05 Oct 1998 CM
Analytical derivatives allowed via AUTODERIVATIVE keyword, 09 Nov 1998
Parameter values can be tied to others, 09 Nov 1998
Fixed small bugs (Wayne Landsman), 24 Nov 1998
Added better exception error reporting, 24 Nov 1998 CM
Cosmetic documentation changes, 02 Jan 1999 CM
Changed definition of ITERPROC to be consistent with TNMIN, 19 Jan 1999 CM
Fixed bug when AUTDERIVATIVE=0. Incorrect sign, 02 Feb 1999 CM
Added keyboard stop to MPFIT_DEFITER, 28 Feb 1999 CM
Cosmetic documentation changes, 14 May 1999 CM
IDL optimizations for speed & FASTNORM keyword, 15 May 1999 CM
Tried a faster version of mpfit_enorm, 30 May 1999 CM
Changed web address to cow.physics.wisc.edu, 14 Jun 1999 CM
Found malformation of FDJAC in MPFIT for 1 parm, 03 Aug 1999 CM
Factored out user-function call into MPFIT_CALL. It is possible,
but currently disabled, to call procedures. The calling format
is similar to CURVEFIT, 25 Sep 1999, CM
Slightly changed mpfit_tie to be less intrusive, 25 Sep 1999, CM
Fixed some bugs associated with tied parameters in mpfit_fdjac, 25
Sep 1999, CM
Reordered documentation; now alphabetical, 02 Oct 1999, CM
Added QUERY keyword for more robust error detection in drivers, 29
Oct 1999, CM
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Split out MPFIT_RESETPROF to aid in profiling, 03 Nov 1999, CM
Some profiling and speed optimization, 03 Nov 1999, CM
Worst offenders, in order: fdjac2, qrfac, qrsolv, enorm.
fdjac2 depends on user function, qrfac and enorm seem to be
fully optimized. qrsolv probably could be tweaked a little, but
is still <10% of total compute time.
Made sure that !err was set to 0 in MPFIT_DEFITER, 10 Jan 2000, CM
Fixed small inconsistency in setting of QANYLIM, 28 Jan 2000, CM
Added PARINFO field RELSTEP, 28 Jan 2000, CM
Converted to MPFIT_ERROR common block for indicating error
conditions, 28 Jan 2000, CM
Corrected scope of MPFIT_ERROR common block, CM, 07 Mar 2000
Minor speed improvement in MPFIT_ENORM, CM 26 Mar 2000
Corrected case where ITERPROC changed parameter values and
parameter values were TIED, CM 26 Mar 2000
Changed MPFIT_CALL to modify NFEV automatically, and to support
user procedures more, CM 26 Mar 2000
Copying permission terms have been liberalized, 26 Mar 2000, CM
Catch zero value of zero a(j,lj) in MPFIT_QRFAC, 20 Jul 2000, CM
(thanks to David Schlegel <schlegel@astro.princeton.edu>)
MPFIT_SETMACHAR is called only once at init; only one common block
is created (MPFIT_MACHAR); it is now a structure; removed almost
all CHECK_MATH calls for compatibility with IDL5 and !EXCEPT;
profiling data is now in a structure too; noted some
mathematical discrepancies in Linux IDL5.0, 17 Nov 2000, CM
Some significant changes. New PARINFO fields: MPSIDE, MPMINSTEP,
MPMAXSTEP. Improved documentation. Now PTIED constraints are
maintained in the MPCONFIG common block. A new procedure to
parse PARINFO fields. FDJAC2 now computes a larger variety of
one-sided and two-sided finite difference derivatives. NFEV is
stored in the MPCONFIG common now. 17 Dec 2000, CM
Added check that PARINFO and XALL have same size, 29 Dec 2000 CM
Don't call function in TERMINATE when there is an error, 05 Jan
2000
Check for float vs. double discrepancies; corrected implementation
of MIN/MAXSTEP, which I still am not sure of, but now at least
the correct behavior occurs *without* it, CM 08 Jan 2001
Added SCALE_FCN keyword, to allow for scaling, as for the CASH
statistic; added documentation about the theory of operation,
and under the QR factorization; slowly I'm beginning to
understand the bowels of this algorithm, CM 10 Jan 2001
Remove MPMINSTEP field of PARINFO, for now at least, CM 11 Jan
2001
Added RESDAMP keyword, CM, 14 Jan 2001
Tried to improve the DAMP handling a little, CM, 13 Mar 2001
Corrected .PARNAME behavior in _DEFITER, CM, 19 Mar 2001
Added checks for parameter and function overflow; a new STATUS
value to reflect this; STATUS values of -15 to -1 are reserved
for user function errors, CM, 03 Apr 2001
DAMP keyword is now a TANH, CM, 03 Apr 2001
Added more error checking of float vs. double, CM, 07 Apr 2001
Fixed bug in handling of parameter lower limits; moved overflow
checking to end of loop, CM, 20 Apr 2001
Failure using GOTO, TERMINATE more graceful if FNORM1 not defined,
CM, 13 Aug 2001
Add MPPRINT tag to PARINFO, CM, 19 Nov 2001
Add DOF keyword to DEFITER procedure, and print degrees of
freedom, CM, 28 Nov 2001
Add check to be sure MYFUNCT is a scalar string, CM, 14 Jan 2002
Addition of EXTERNAL_FJAC, EXTERNAL_FVEC keywords; ability to save
fitter's state from one call to the next; allow '(EXTERNAL)'
function name, which implies that user will supply function and
Jacobian at each iteration, CM, 10 Mar 2002
Documented EXTERNAL evaluation code, CM, 10 Mar 2002
Corrected signficant bug in the way that the STEP parameter, and
FIXED parameters interacted (Thanks Andrew Steffl), CM, 02 Apr
2002
Allow COVAR and PERROR keywords to be computed, even in case of
'(EXTERNAL)' function, 26 May 2002
Add NFREE and NPEGGED keywords; compute NPEGGED; compute DOF using
NFREE instead of n_elements(X), thanks to Kristian Kjaer, CM 11
Sep 2002
Hopefully PERROR is all positive now, CM 13 Sep 2002
Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
Error checking to detect missing start pars, CM 12 Apr 2003
Add DOF keyword to return degrees of freedom, CM, 30 June 2003
Always call ITERPROC in the final iteration; add ITERKEYSTOP
keyword, CM, 30 June 2003
Correct bug in MPFIT_LMPAR of singularity handling, which might
likely be fatal for one-parameter fits, CM, 21 Nov 2003
(with thanks to Peter Tuthill for the proper test case)
Minor documentation adjustment, 03 Feb 2004, CM
Correct small error in QR factorization when pivoting; document
the return values of QRFAC when pivoting, 21 May 2004, CM
Add MPFORMAT field to PARINFO, and correct behavior of interaction
between MPPRINT and PARNAME in MPFIT_DEFITERPROC (thanks to Tim
Robishaw), 23 May 2004, CM
Add the ITERPRINT keyword to allow redirecting output, 26 Sep
2004, CM
Correct MAXSTEP behavior in case of a negative parameter, 26 Sep
2004, CM
Fix bug in the parsing of MINSTEP/MAXSTEP, 10 Apr 2005, CM
Fix bug in the handling of upper/lower limits when the limit was
negative (the fitting code would never "stick" to the lower
limit), 29 Jun 2005, CM
Small documentation update for the TIED field, 05 Sep 2005, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
If MAXITER equals zero, then do the basic parameter checking and
uncertainty analysis, but do not adjust the parameters, 15 Aug
2006, CM
Added documentation, 18 Sep 2006, CM
$Id: mpfit.pro,v 1.41 2006/09/21 05:00:41 craigm Exp $
[Previous]
[Next]
NAME:
MPFIT2DFUN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Perform Levenberg-Marquardt least-squares fit to a 2-D IDL function
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
parms = MPFIT2DFUN(MYFUNCT, X, Y, Z, ERR, start_parms, ...)
DESCRIPTION:
MPFIT2DFUN fits a user-supplied model -- in the form of an IDL
function -- to a set of user-supplied data. MPFIT2DFUN calls
MPFIT, the MINPACK-1 least-squares minimizer, to do the main
work. MPFIT2DFUN is a specialized version for two-dimensional
data.
Given the data and their uncertainties, MPFIT2DFUN finds the best set
of model parameters which match the data (in a least-squares
sense) and returns them in an array.
The user must supply the following items:
- Two arrays of independent variable values ("X", "Y").
- An array of "measured" *dependent* variable values ("Z").
- An array of "measured" 1-sigma uncertainty values ("ERR").
- The name of an IDL function which computes Z given (X,Y) ("MYFUNCT").
- Starting guesses for all of the parameters ("START_PARAMS").
There are very few restrictions placed on X, Y, Z, or MYFUNCT.
Simply put, MYFUNCT must map the (X,Y) values into Z values given
the model parameters. The (X,Y) values are usually the independent
X and Y coordinate positions in the two dimensional plane, but need
not be.
MPFIT2DFUN carefully avoids passing large arrays where possible to
improve performance.
See below for an example of usage.
USER FUNCTION
The user must define a function which returns the model value. For
applications which use finite-difference derivatives -- the default
-- the user function should be declared in the following way:
FUNCTION MYFUNCT, X, Y, P
; The independent variables are X and Y
; Parameter values are passed in "P"
ZMOD = ... computed model values at (X,Y) ...
return, ZMOD
END
The returned array YMOD must have the same dimensions and type as
the "measured" Z values.
User functions may also indicate a fatal error condition
using the ERROR_CODE common block variable, as described
below under the MPFIT_ERROR common block definition.
See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
in MPFIT.PRO if you wish to compute the derivatives for yourself.
AUTODERIVATIVE is accepted and passed directly to MPFIT. The user
function must accept one additional parameter, DP, which contains
the derivative of the user function with respect to each parameter
at each data point, as described in MPFIT.PRO.
CREATING APPROPRIATELY DIMENSIONED INDEPENDENT VARIABLES
The user must supply appropriate independent variables to
MPFIT2DFUN. For image fitting applications, this variable should
be two-dimensional *arrays* describing the X and Y positions of
every *pixel*. [ Thus any two dimensional sampling is permitted,
including irregular sampling. ]
If the sampling is regular, then the x coordinates are the same for
each row, and the y coordinates are the same for each column. Call
the x-row and y-column coordinates XR and YC respectively. You can
then compute X and Y as follows:
X = XR # (YC*0 + 1) eqn. 1
Y = (XR*0 + 1) # YC eqn. 2
For example, if XR and YC have the following values:
XR = [ 1, 2, 3, 4, 5,] ;; X positions of one row of pixels
YC = [ 15,16,17 ] ;; Y positions of one column of
pixels
Then using equations 1 and 2 above will give these values to X and
Y:
X : 1 2 3 4 5 ;; X positions of all pixels
1 2 3 4 5
1 2 3 4 5
Y : 15 15 15 15 15 ;; Y positions of all pixels
16 16 16 16 16
17 17 17 17 17
Using the above technique is suggested, but *not* required. You
can do anything you wish with the X and Y values. This technique
only makes it easier to compute your model function values.
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of MPFIT can be modified with respect to each
parameter to be fitted. A parameter value can be fixed; simple
boundary constraints can be imposed; limitations on the parameter
changes can be imposed; properties of the automatic derivative can
be modified; and parameters can be tied to one another.
These properties are governed by the PARINFO structure, which is
passed as a keyword parameter to MPFIT.
PARINFO should be an array of structures, one for each parameter.
Each parameter is associated with one element of the array, in
numerical order. The structure can have the following entries
(none are required):
.VALUE - the starting parameter value (but see the START_PARAMS
parameter for more information).
.FIXED - a boolean value, whether the parameter is to be held
fixed or not. Fixed parameters are not varied by
MPFIT, but are passed on to MYFUNCT for evaluation.
.LIMITED - a two-element boolean array. If the first/second
element is set, then the parameter is bounded on the
lower/upper side. A parameter can be bounded on both
sides. Both LIMITED and LIMITS must be given
together.
.LIMITS - a two-element float or double array. Gives the
parameter limits on the lower and upper sides,
respectively. Zero, one or two of these values can be
set, depending on the values of LIMITED. Both LIMITED
and LIMITS must be given together.
.PARNAME - a string, giving the name of the parameter. The
fitting code of MPFIT does not use this tag in any
way. However, the default ITERPROC will print the
parameter name if available.
.STEP - the step size to be used in calculating the numerical
derivatives. If set to zero, then the step size is
computed automatically. Ignored when AUTODERIVATIVE=0.
This value is superceded by the RELSTEP value.
.RELSTEP - the *relative* step size to be used in calculating
the numerical derivatives. This number is the
fractional size of the step, compared to the
parameter value. This value supercedes the STEP
setting. If the parameter is zero, then a default
step size is chosen.
.MPSIDE - the sidedness of the finite difference when computing
numerical derivatives. This field can take four
values:
0 - one-sided derivative computed automatically
1 - one-sided derivative (f(x+h) - f(x) )/h
-1 - one-sided derivative (f(x) - f(x-h))/h
2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)
Where H is the STEP parameter described above. The
"automatic" one-sided derivative method will chose a
direction for the finite difference which does not
violate any constraints. The other methods do not
perform this check. The two-sided method is in
principle more precise, but requires twice as many
function evaluations. Default: 0.
.MPMINSTEP - the minimum change to be made in the parameter
value. During the fitting process, the parameter
will be changed by multiples of this value. The
actual step is computed as:
DELTA1 = MPMINSTEP*ROUND(DELTA0/MPMINSTEP)
where DELTA0 and DELTA1 are the estimated parameter
changes before and after this constraint is
applied. Note that this constraint should be used
with care since it may cause non-converging,
oscillating solutions.
A value of 0 indicates no minimum. Default: 0.
.MPMAXSTEP - the maximum change to be made in the parameter
value. During the fitting process, the parameter
will never be changed by more than this value.
A value of 0 indicates no maximum. Default: 0.
.TIED - a string expression which "ties" the parameter to other
free or fixed parameters. Any expression involving
constants and the parameter array P are permitted.
Example: if parameter 2 is always to be twice parameter
1 then use the following: parinfo[2].tied = '2 * P[1]'.
Since they are totally constrained, tied parameters are
considered to be fixed; no errors are computed for them.
[ NOTE: the PARNAME can't be used in expressions. ]
Future modifications to the PARINFO structure, if any, will involve
adding structure tags beginning with the two letters "MP".
Therefore programmers are urged to avoid using tags starting with
the same letters; otherwise they are free to include their own
fields within the PARINFO structure, and they will be ignored.
PARINFO Example:
parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
limits:[0.D,0]}, 5)
parinfo[0].fixed = 1
parinfo[4].limited(0) = 1
parinfo[4].limits(0) = 50.D
parinfo[*].value = [5.7D, 2.2, 500., 1.5, 2000.]
A total of 5 parameters, with starting values of 5.7,
2.2, 500, 1.5, and 2000 are given. The first parameter
is fixed at a value of 5.7, and the last parameter is
constrained to be above 50.
INPUTS:
MYFUNCT - a string variable containing the name of an IDL
function. This function computes the "model" Z values
given the X,Y values and model parameters, as described above.
X - Array of "X" independent variable values, as described above.
These values are passed directly to the fitting function
unmodified.
Y - Array of "Y" independent variable values, as described
above. X and Y should have the same data type.
Z - Array of "measured" dependent variable values. Z should have
the same data type as X and Y. The function MYFUNCT should
map (X,Y)->Z.
ERR - Array of "measured" 1-sigma uncertainties. ERR should have
the same data type as Z. ERR is ignored if the WEIGHTS
keyword is specified.
START_PARAMS - An array of starting values for each of the
parameters of the model. The number of parameters
should be fewer than the number of measurements.
Also, the parameters should have the same data type
as the measurements (double is preferred).
This parameter is optional if the PARINFO keyword
is used (see MPFIT). The PARINFO keyword provides
a mechanism to fix or constrain individual
parameters. If both START_PARAMS and PARINFO are
passed, then the starting *value* is taken from
START_PARAMS, but the *constraints* are taken from
PARINFO.
RETURNS:
Returns the array of best-fit parameters.
KEYWORD PARAMETERS:
BESTNORM - the value of the summed, squared, weighted residuals
for the returned parameter values, i.e. the chi-square value.
COVAR - the covariance matrix for the set of parameters returned
by MPFIT. The matrix is NxN where N is the number of
parameters. The square root of the diagonal elements
gives the formal 1-sigma statistical errors on the
parameters IF errors were treated "properly" in MYFUNC.
Parameter errors are also returned in PERROR.
To compute the correlation matrix, PCOR, use this:
IDL> PCOR = COV * 0
IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
PCOR[i,j] = COV[i,j]/sqrt(COV[i,i]*COV[j,j])
If NOCOVAR is set or MPFIT terminated abnormally, then
COVAR is set to a scalar with value !VALUES.D_NAN.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERRMSG - a string error or warning message is returned.
FTOL - a nonnegative input variable. Termination occurs when both
the actual and predicted relative reductions in the sum of
squares are at most FTOL (and STATUS is accordingly set to
1 or 3). Therefore, FTOL measures the relative error
desired in the sum of squares. Default: 1D-10
FUNCTARGS - A structure which contains the parameters to be passed
to the user-supplied function specified by MYFUNCT via
the _EXTRA mechanism. This is the way you can pass
additional data to your user-supplied function without
using common blocks.
By default, no extra parameters are passed to the
user-supplied function.
GTOL - a nonnegative input variable. Termination occurs when the
cosine of the angle between fvec and any column of the
jacobian is at most GTOL in absolute value (and STATUS is
accordingly set to 4). Therefore, GTOL measures the
orthogonality desired between the function vector and the
columns of the jacobian. Default: 1D-10
ITERARGS - The keyword arguments to be passed to ITERPROC via the
_EXTRA mechanism. This should be a structure, and is
similar in operation to FUNCTARGS.
Default: no arguments are passed.
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the MPFIT routine. It should be declared
in the following way:
PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, ...
; perform custom iteration update
END
ITERPROC must either accept all three keyword
parameters (FUNCTARGS, PARINFO and QUIET), or at least
accept them via the _EXTRA keyword.
MYFUNCT is the user-supplied function to be minimized,
P is the current set of model parameters, ITER is the
iteration number, and FUNCTARGS are the arguments to be
passed to MYFUNCT. FNORM should be the
chi-squared value. QUIET is set when no textual output
should be printed. See below for documentation of
PARINFO.
In implementation, ITERPROC can perform updates to the
terminal or graphical user interface, to provide
feedback while the fit proceeds. If the fit is to be
stopped for any reason, then ITERPROC should set the
common block variable ERROR_CODE to negative value (see
MPFIT_ERROR common block below). In principle,
ITERPROC should probably not modify the parameter
values, because it may interfere with the algorithm's
stability. In practice it is allowed.
Default: an internal routine is used to print the
parameter values.
MAXITER - The maximum number of iterations to perform. If the
number is exceeded, then the STATUS value is set to 5
and MPFIT returns.
Default: 200 iterations
NFEV - the number of MYFUNCT function evaluations performed.
NITER - the number of iterations completed.
NOCOVAR - set this keyword to prevent the calculation of the
covariance matrix before returning (see COVAR)
NPRINT - The frequency with which ITERPROC is called. A value of
1 indicates that ITERPROC is called with every iteration,
while 2 indicates every other iteration, etc. Note that
several Levenberg-Marquardt attempts can be made in a
single iteration.
Default value: 1
PARINFO - Provides a mechanism for more sophisticated constraints
to be placed on parameter values. When PARINFO is not
passed, then it is assumed that all parameters are free
and unconstrained. Values in PARINFO are never
modified during a call to MPFIT.
See description above for the structure of PARINFO.
Default value: all parameters are free and unconstrained.
PERROR - The formal 1-sigma errors in each parameter, computed
from the covariance matrix. If a parameter is held
fixed, or if it touches a boundary, then the error is
reported as zero.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties. *If* you can assume that the true reduced
chi-squared value is unity -- meaning that the fit is
implicitly assumed to be of good quality -- then the
estimated parameter uncertainties can be computed by
scaling PERROR by the measured chi-squared value.
DOF = N_ELEMENTS(Z) - N_ELEMENTS(PARMS) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
QUIET - set this keyword when no textual output should be printed
by MPFIT
STATUS - an integer status code is returned. All values other
than zero can represent success. It can have one of the
following values:
0 improper input parameters.
1 both actual and predicted relative reductions
in the sum of squares are at most FTOL.
2 relative error between two consecutive iterates
is at most XTOL
3 conditions for STATUS = 1 and STATUS = 2 both hold.
4 the cosine of the angle between fvec and any
column of the jacobian is at most GTOL in
absolute value.
5 the maximum number of iterations has been reached
6 FTOL is too small. no further reduction in
the sum of squares is possible.
7 XTOL is too small. no further improvement in
the approximate solution x is possible.
8 GTOL is too small. fvec is orthogonal to the
columns of the jacobian to machine precision.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERR
parameter is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Z-MYFUNCT(X,Y,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Z - Poisson weighting (counting statistics)
1D - Unweighted
XTOL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at most
XTOL (and STATUS is accordingly set to 2 or 3). Therefore,
XTOL measures the relative error desired in the approximate
solution. Default: 1D-10
YFIT - the best-fit model function, as returned by MYFUNCT.
EXAMPLE:
p = [2.2D, -0.7D, 1.4D, 3000.D]
x = (dindgen(200)*0.1 - 10.) # (dblarr(200) + 1)
y = (dblarr(200) + 1) # (dindgen(200)*0.1 - 10.)
zi = gauss2(x, y, p)
sz = sqrt(zi>1)
z = zi + randomn(seed, 200, 200) * sz
p0 = [0D, 0D, 1D, 10D]
p = mpfit2dfun('GAUSS2', x, y, z, sz, p0)
Generates a synthetic data set with a Gaussian peak, and Poisson
statistical uncertainty. Then the same function (but different
starting parameters) is fitted to the data to see how close we can
get.
It is especially worthy to notice that the X and Y values are
created as full images, so that a coordinate is attached to each
pixel independently. This is the format that GAUSS2 accepts, and
the easiest for you to use in your own functions.
COMMON BLOCKS:
COMMON MPFIT_ERROR, ERROR_CODE
User routines may stop the fitting process at any time by
setting an error condition. This condition may be set in either
the user's model computation routine (MYFUNCT), or in the
iteration procedure (ITERPROC).
To stop the fitting, the above common block must be declared,
and ERROR_CODE must be set to a negative number. After the user
procedure or function returns, MPFIT checks the value of this
common block variable and exits immediately if the error
condition has been set. By default the value of ERROR_CODE is
zero, indicating a successful function/procedure call.
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
Written, transformed from MPFITFUN, 26 Sep 1999, CM
Alphabetized documented keywords, 02 Oct 1999, CM
Added example, 02 Oct 1999, CM
Tried to clarify definitions of X and Y, 29 Oct 1999, CM
Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
Check to be sure that X, Y and Z are present, 02 Nov 1999, CM
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Propagated improvements from MPFIT, 17 Dec 2000, CM
Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
Add DOF keyword to return degrees of freedom, CM, 23 June 2003
Minor documentation adjustment, 03 Feb 2004, CM
Fix the example to prevent zero errorbars, 28 Mar 2005, CM
Defend against users supplying strangely dimensioned X and Y, 29
Jun 2005, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
$Id: mpfit2dfun.pro,v 1.8 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
NAME:
MPFIT2DPEAK
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Fit a gaussian, lorentzian or Moffat model to data
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
yfit = MPFIT2DPEAK(Z, A [, X, Y, /TILT ...] )
DESCRIPTION:
MPFIT2DPEAK fits a gaussian, lorentzian or Moffat model using the
non-linear least squares fitter MPFIT. MPFIT2DPEAK is meant to be
a drop-in replacement for IDL's GAUSS2DFIT function (and requires
MPFIT and MPFIT2DFUN).
The choice of the fitting function is determined by the keywords
GAUSSIAN, LORENTZIAN and MOFFAT. By default the gaussian model
function is used. [ The Moffat function is a modified Lorentzian
with variable power law index. ] The two-dimensional peak has
independent semimajor and semiminor axes, with an optional
rotation term activated by setting the TILT keyword. The baseline
is assumed to be a constant.
GAUSSIAN A[0] + A[1]*exp(-0.5*u)
LORENTZIAN A[0] + A[1]/(u + 1)
MOFFAT A[0] + A[1]/(u + 1)^A[7]
u = ( (x-A[4])/A[2] )^2 + ( (y-A[5])/A[3] )^2
where x and y are cartesian coordinates in rotated
coordinate system if TILT keyword is set.
The returned parameter array elements have the following meanings:
A[0] Constant baseline level
A[1] Peak value
A[2] Peak half-width (x) -- gaussian sigma or half-width at half-max
A[3] Peak half-width (y) -- gaussian sigma or half-width at half-max
A[4] Peak centroid (x)
A[5] Peak centroid (y)
A[6] Rotation angle (radians) if TILT keyword set
A[7] Moffat power law index if MOFFAT keyword set
By default the initial starting values for the parameters A are
estimated from the data. However, explicit starting values can be
supplied using the ESTIMATES keyword. Also, error or weighting
values can optionally be provided; otherwise the fit is
unweighted.
RESTRICTIONS:
If no starting parameter ESTIMATES are provided, then MPFIT2DPEAK
attempts to estimate them from the data. This is not a perfect
science; however, the author believes that the technique
implemented here is more robust than the one used in IDL's
GAUSS2DFIT. The author has tested cases of strong peaks, noisy
peaks and broad peaks, all with success.
INPUTS:
Z - Two dimensional array of "measured" dependent variable values.
Z should be of the same type and dimension as (X # Y).
X - Optional vector of x positions for a single row of Z.
X[i] should provide the x position of Z[i,*]
Default: X values are integer increments from 0 to NX-1
Y - Optional vector of y positions for a single column of Z.
Y[j] should provide the y position of Z[*,j]
Default: Y values are integer increments from 0 to NY-1
OUTPUTS:
A - Upon return, an array of best fit parameter values. See the
table above for the meanings of each parameter element.
RETURNS:
Returns the best fitting model function as a 2D array.
KEYWORDS:
** NOTE ** Additional keywords such as PARINFO, BESTNORM, and
STATUS are accepted by MPFIT2DPEAK but not documented
here. Please see the documentation for MPFIT for the
description of these advanced options.
CHISQ - the value of the summed squared residuals for the
returned parameter values.
CIRCULAR - if set, then the peak profile is assumed to be
azimuthally symmetric. When set, the parameters A[2)
and A[3) will be identical and the TILT keyword will
have no effect.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERROR - upon input, the measured 1-sigma uncertainties in the "Z"
values. If no ERROR or WEIGHTS are given, then the fit is
unweighted.
ESTIMATES - Array of starting values for each parameter of the
model.
Default: parameter values are estimated from data.
GAUSSIAN - if set, fit a gaussian model function. The Default.
LORENTZIAN - if set, fit a lorentzian model function.
MOFFAT - if set, fit a Moffat model function.
MEASURE_ERRORS - synonym for ERRORS, for consistency with built-in
IDL fitting routines.
NEGATIVE - if set, and ESTIMATES is not provided, then MPFIT2DPEAK
will assume that a negative peak is present -- a
valley. Specifying this keyword is not normally
required, since MPFIT2DPEAK can determine this
automatically.
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
PERROR - upon return, the 1-sigma uncertainties of the parameter
values A. These values are only meaningful if the ERRORS
or WEIGHTS keywords are specified properly.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling PERROR
by the measured chi-squared value.
DOF = N_ELEMENTS(Z) - N_ELEMENTS(A) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
QUIET - if set then diagnostic fitting messages are suppressed.
Default: QUIET=1 (i.e., no diagnostics)
SIGMA - synonym for PERROR (1-sigma parameter uncertainties), for
compatibility with GAUSSFIT. Do not confuse this with the
Gaussian "sigma" width parameter.
TILT - if set, then the major and minor axes of the peak profile
are allowed to rotate with respect to the image axes.
Parameter A[6] will be set to the clockwise rotation angle
of the A[2] axis in radians.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERR
parameter is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Z-MYFUNCT(X,Y,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Y - Poisson weighting (counting statistics)
1D - Unweighted
The ERROR keyword takes precedence over any WEIGHTS
keyword values. If no ERROR or WEIGHTS are given, then
the fit is unweighted.
EXAMPLE:
; Construct a sample gaussian surface in range [-5,5] centered at [2,-3]
x = findgen(100)*0.1 - 5. & y = x
xx = x # (y*0 + 1)
yy = (x*0 + 1) # y
rr = sqrt((xx-2.)^2 + (yy+3.)^2)
; Gaussian surface with sigma=0.5, peak value of 3, noise with sigma=0.2
z = 3.*exp(-(rr/0.5)^2) + randomn(seed,100,100)*.2
; Fit gaussian parameters A
zfit = mpfit2dpeak(z, a, x, y)
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
New algorithm for estimating starting values, CM, 31 Oct 1999
Documented, 02 Nov 1999
Small documentation fixes, 02 Nov 1999
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Small cosmetic changes, 21 Sep 2000, CM
Corrected bug introduced by cosmetic changes, 11 Oct 2000, CM :-)
Added POSITIVE keyword, 17 Nov 2000, CM
Removed TILT in common, in favor of FUNCTARGS approach, 23 Nov
2000, CM
Added SYMMETRIC keyword, documentation for TILT, and an example,
24 Nov 2000, CM
Changed SYMMETRIC to CIRCULAR, 17 Dec 2000, CM
Really change SYMMETRIC to CIRCULAR!, 13 Sep 2002, CM
Add error messages for SYMMETRIC and CIRCLE, 08 Nov 2002, CM
Make more consistent with comparable IDL routines, 30 Jun 2003, CM
Defend against users supplying strangely dimensioned X and Y, 29
Jun 2005, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
$Id: mpfit2dpeak.pro,v 1.7 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
NAME:
MPFITELLIPSE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Approximate fit to points forming an ellipse
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
parms = MPFITELLIPSE(X, Y, start_parms, [/TILT, WEIGHTS=wts, ...])
DESCRIPTION:
MPFITELLIPSE fits a closed elliptical or circular curve to a two
dimensional set of data points. The user specifies the X and Y
positions of the points, and an optional set of weights. The
ellipse may also be tilted at an arbitrary angle.
The best fitting ellipse parameters are returned from by
MPFITELLIPSE as a vector, whose values are:
P[0] Ellipse semi axis 1
P[1] Ellipse semi axis 2 ( = P[0] if CIRCLE keyword set)
P[2] Ellipse center - x value
P[3] Ellipse center - y value
P[4] Ellipse rotation angle (radians) if TILT keyword set
The user may specify an initial set of trial parameters, but by
default MPFITELLIPSE will estimate the parameters automatically.
Users should be aware that in the presence of large amounts of
noise, namely when the measurement error becomes significant
compared to the ellipse axis length, then the estimated parameters
become unreliable. Generally speaking the computed axes will
overestimate the true axes. For example when (SIGMA_R/R) becomes
0.5, the radius of the ellipse is overestimated by about 40%.
Users can weight their data as they see appropriate. However, the
following prescription for the weighting appears to be the correct
one, and produces values comparable to the typical chi-squared
value.
WEIGHTS = 0.75/(SIGMA_X^2 + SIGMA_Y^2)
where SIGMA_X and SIGMA_Y are the measurement error vectors in the
X and Y directions respectively. However, it should be pointed
out that this weighting is only appropriate for a set of points
whose measurement errors are comparable. If a more robust
estimation of the parameter values is needed, the so-called
orthogonal distance regression package should be used (ODRPACK,
available in FORTRAN at www.netlib.org).
INPUTS:
X - measured X positions of the points in the ellipse.
Y - measured Y positions of the points in the ellipse.
START_PARAMS - an array of starting values for the ellipse
parameters, as described above. This parameter is
optional; if not specified by the user, then the
ellipse parameters are estimated automatically from
the properties of the data.
RETURNS:
Returns the best fitting model ellipse parameters.
KEYWORDS:
** NOTE ** Additional keywords such as PARINFO, BESTNORM, and
STATUS are accepted by MPFITELLIPSE but not documented
here. Please see the documentation for MPFIT for the
description of these advanced options.
PERROR - upon return, the 1-sigma uncertainties of the returned
ellipse parameter values. These values are only
meaningful if the WEIGHTS keyword is specified properly.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
QUIET - if set then diagnostic fitting messages are suppressed.
Default: QUIET=1 (i.e., no diagnostics]
CIRCULAR - if set, then the curve is assumed to be a circle
instead of ellipse. When set, the parameters P[0] and
P[1] will be identical and the TILT keyword will have
no effect.
TILT - if set, then the major and minor axes of the ellipse
are allowed to rotate with respect to the data axes.
Parameter P[4] will be set to the clockwise rotation angle
of the P[0] axis in radians.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERR
parameter is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Z-MYFUNCT(X,Y,P))^2 * ABS(WEIGHTS)^2 )
Users may wish to follow the guidelines for WEIGHTS
described above.
EXAMPLE:
; Construct a set of points on an ellipse, with some noise
ph0 = 2*!pi*randomu(seed,50)
x = 50. + 32.*cos(ph0) + 4.0*randomn(seed, 50)
y = -75. + 65.*sin(ph0) + 0.1*randomn(seed, 50)
; Compute weights function
weights = 0.75/(4.0^2 + 0.1^2)
; Fit ellipse and plot result
p = mpfitellipse(x, y)
plot, x, y, psym=1
phi = dindgen(101)*2D*!dpi/100
oplot, p[2]+p[0]*cos(phi), p[3]+p[1]*sin(phi)
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
Ported from MPFIT2DPEAK, 17 Dec 2000, CM
More documentation, 11 Jan 2001, CM
Example corrected, 18 Nov 2001, CM
Change CIRCLE keyword to the correct CIRCULAR keyword, 13 Sep
2002, CM
Add error messages for SYMMETRIC and CIRCLE, 08 Nov 2002, CM
Found small error in computation of _EVAL (when CIRCULAR) was set;
sanity check when CIRCULAR is set, 21 Jan 2003, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
$Id: mpfitellipse.pro,v 1.9 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
NAME:
MPFITEXPR
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Perform Levenberg-Marquardt least-squares fit to arbitrary expression
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
MYFUNCT = 'X*(1-X)+3'
parms = MPFITEXPR(MYFUNCT, XVAL, YVAL, ERR, start_parms, ...)
DESCRIPTION:
MPFITEXPR fits a user-supplied model -- in the form of an arbitrary IDL
expression -- to a set of user-supplied data. MPFITEXPR calls
MPFIT, the MINPACK-1 least-squares minimizer, to do the main
work.
Given the data and their uncertainties, MPFITEXPR finds the best set
of model parameters which match the data (in a least-squares
sense) and returns them in an array.
The user must supply the following items:
- An array of independent variable values ("X").
- An array of "measured" *dependent* variable values ("Y").
- An array of "measured" 1-sigma uncertainty values ("ERR").
- A text IDL expression which computes Y given X.
- Starting guesses for all of the parameters ("START_PARAMS").
There are very few restrictions placed on X, Y or the expression of
the model. Simply put, the expression must map the "X" values into
"Y" values given the model parameters. The "X" values may
represent any independent variable (not just Cartesian X), and
indeed may be multidimensional themselves. For example, in the
application of image fitting, X may be a 2xN array of image
positions.
Some rules must be obeyed in constructing the expression. First,
the independent variable name *MUST* be "X" in the expression,
regardless of the name of the variable being passed to MPFITEXPR.
This is demonstrated in the above calling sequence, where the X
variable passed in is called "XVAL" but the expression still refers
to "X". Second, parameter values must be referred to as an array
named "P".
If you do not pass in starting values for the model parameters,
MPFITEXPR will attempt to determine the number of parameters you
intend to have (it does this by looking for references to the array
variable named "P"). When no starting values are passed in, the
values are assumed to start at zero.
MPFITEXPR carefully avoids passing large arrays where possible to
improve performance.
See below for an example of usage.
EVALUATING EXPRESSIONS
This source module also provides a function called MPEVALEXPR. You
can use this function to evaluate your expression, given a list of
parameters. This is one of the easier ways to compute the model
once the best-fit parameters have been found. Here is an example:
YMOD = MPEVALEXPR(MYFUNCT, XVAL, PARMS)
where MYFUNCT is the expression (see MYFUNCT below), XVAL is the
list of "X" values, and PARMS is an array of parameters. The
returned array YMOD contains the expression MYFUNCT evaluated at
each point in XVAL.
PASSING PRIVATE DATA TO AN EXPRESSION
The most complicated optimization problems typically involve other
external parameters, in addition to the fitted parameters. While
it is extremely easy to rewrite an expression dynamically, in case
one of the external parameters changes, the other possibility is to
use the PRIVATE data structure.
The user merely passes a structure to the FUNCTARGS keyword. The
user expression receives this value as the variable PRIVATE.
MPFITEXPR nevers accesses this variable so it can contain any
desired values. Usually it would be an IDL structure so that any
named external parameters can be passed to the expression.
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of MPFIT can be modified with respect to each
parameter to be fitted. A parameter value can be fixed; simple
boundary constraints can be imposed; limitations on the parameter
changes can be imposed; properties of the automatic derivative can
be modified; and parameters can be tied to one another.
These properties are governed by the PARINFO structure, which is
passed as a keyword parameter to MPFIT.
PARINFO should be an array of structures, one for each parameter.
Each parameter is associated with one element of the array, in
numerical order. The structure can have the following entries
(none are required):
.VALUE - the starting parameter value (but see the START_PARAMS
parameter for more information).
.FIXED - a boolean value, whether the parameter is to be held
fixed or not. Fixed parameters are not varied by
MPFIT, but are passed on to MYFUNCT for evaluation.
.LIMITED - a two-element boolean array. If the first/second
element is set, then the parameter is bounded on the
lower/upper side. A parameter can be bounded on both
sides. Both LIMITED and LIMITS must be given
together.
.LIMITS - a two-element float or double array. Gives the
parameter limits on the lower and upper sides,
respectively. Zero, one or two of these values can be
set, depending on the values of LIMITED. Both LIMITED
and LIMITS must be given together.
.PARNAME - a string, giving the name of the parameter. The
fitting code of MPFIT does not use this tag in any
way. However, the default ITERPROC will print the
parameter name if available.
.STEP - the step size to be used in calculating the numerical
derivatives. If set to zero, then the step size is
computed automatically. Ignored when AUTODERIVATIVE=0.
This value is superceded by the RELSTEP value.
.RELSTEP - the *relative* step size to be used in calculating
the numerical derivatives. This number is the
fractional size of the step, compared to the
parameter value. This value supercedes the STEP
setting. If the parameter is zero, then a default
step size is chosen.
.MPSIDE - the sidedness of the finite difference when computing
numerical derivatives. This field can take four
values:
0 - one-sided derivative computed automatically
1 - one-sided derivative (f(x+h) - f(x) )/h
-1 - one-sided derivative (f(x) - f(x-h))/h
2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)
Where H is the STEP parameter described above. The
"automatic" one-sided derivative method will chose a
direction for the finite difference which does not
violate any constraints. The other methods do not
perform this check. The two-sided method is in
principle more precise, but requires twice as many
function evaluations. Default: 0.
.MPMINSTEP - the minimum change to be made in the parameter
value. During the fitting process, the parameter
will be changed by multiples of this value. The
actual step is computed as:
DELTA1 = MPMINSTEP*ROUND(DELTA0/MPMINSTEP)
where DELTA0 and DELTA1 are the estimated parameter
changes before and after this constraint is
applied. Note that this constraint should be used
with care since it may cause non-converging,
oscillating solutions.
A value of 0 indicates no minimum. Default: 0.
.MPMAXSTEP - the maximum change to be made in the parameter
value. During the fitting process, the parameter
will never be changed by more than this value.
A value of 0 indicates no maximum. Default: 0.
.TIED - a string expression which "ties" the parameter to other
free or fixed parameters. Any expression involving
constants and the parameter array P are permitted.
CALLED BY:
OVSA_FIT, TP_FIT
Example: if parameter 2 is always to be twice parameter
1 then use the following: parinfo[2].tied = '2 * P[1]'.
Since they are totally constrained, tied parameters are
considered to be fixed; no errors are computed for them.
[ NOTE: the PARNAME can't be used in expressions. ]
Future modifications to the PARINFO structure, if any, will involve
adding structure tags beginning with the two letters "MP".
Therefore programmers are urged to avoid using tags starting with
the same letters; otherwise they are free to include their own
fields within the PARINFO structure, and they will be ignored.
PARINFO Example:
parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
limits:[0.D,0]}, 5)
parinfo[0].fixed = 1
parinfo[4].limited[0] = 1
parinfo[4].limits[0] = 50.D
parinfo[*].value = [5.7D, 2.2, 500., 1.5, 2000.]
A total of 5 parameters, with starting values of 5.7,
2.2, 500, 1.5, and 2000 are given. The first parameter
is fixed at a value of 5.7, and the last parameter is
constrained to be above 50.
INPUTS:
MYFUNCT - a string variable containing an IDL expression. The
only restriction is that the independent variable *must*
be referred to as "X" and model parameters *must* be
referred to as an array called "P". Do not use symbol
names beginning with the underscore, "_".
The expression should calculate "model" Y values given
the X values and model parameters. Using the vector
notation of IDL, this can be quite easy to do. If your
expression gets complicated, you may wish to make an IDL
function which will improve performance and readibility.
The resulting array should be of the same size and
dimensions as the "measured" Y values.
X - Array of independent variable values.
Y - Array of "measured" dependent variable values. Y should have
the same data type as X. The function MYFUNCT should map
X->Y.
ERR - Array of "measured" 1-sigma uncertainties. ERR should have
the same data type as Y. ERR is ignored if the WEIGHTS
keyword is specified.
START_PARAMS - An array of starting values for each of the
parameters of the model. The number of parameters
should be fewer than the number of measurements.
Also, the parameters should have the same data type
as the measurements (double is preferred).
This parameter is optional if the PARINFO keyword
is used (see MPFIT). The PARINFO keyword provides
a mechanism to fix or constrain individual
parameters. If both START_PARAMS and PARINFO are
passed, then the starting *value* is taken from
START_PARAMS, but the *constraints* are taken from
PARINFO.
If no parameters are given, then MPFITEXPR attempts
to determine the number of parameters by scanning
the expression. Parameters determined this way are
initialized to zero. This technique is not fully
reliable, so users are advised to pass explicit
parameter starting values.
RETURNS:
Returns the array of best-fit parameters.
KEYWORD PARAMETERS:
BESTNORM - the value of the summed, squared, weighted residuals
for the returned parameter values, i.e. the chi-square value.
COVAR - the covariance matrix for the set of parameters returned
by MPFIT. The matrix is NxN where N is the number of
parameters. The square root of the diagonal elements
gives the formal 1-sigma statistical errors on the
parameters IF errors were treated "properly" in MYFUNC.
Parameter errors are also returned in PERROR.
To compute the correlation matrix, PCOR, use this:
IDL> PCOR = COV * 0
IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
PCOR[i,j] = COV[i,j]/sqrt(COV[i,i]*COV[j,j])
If NOCOVAR is set or MPFIT terminated abnormally, then
COVAR is set to a scalar with value !VALUES.D_NAN.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERRMSG - a string error or warning message is returned.
FTOL - a nonnegative input variable. Termination occurs when both
the actual and predicted relative reductions in the sum of
squares are at most FTOL (and STATUS is accordingly set to
1 or 3). Therefore, FTOL measures the relative error
desired in the sum of squares. Default: 1D-10
FUNCTARGS - passed directly to the expression as the variable
PRIVATE. Any user-private data can be communicated to
the user expression using this keyword.
Default: PRIVATE is undefined in user expression
GTOL - a nonnegative input variable. Termination occurs when the
cosine of the angle between fvec and any column of the
jacobian is at most GTOL in absolute value (and STATUS is
accordingly set to 4). Therefore, GTOL measures the
orthogonality desired between the function vector and the
columns of the jacobian. Default: 1D-10
ITERARGS - The keyword arguments to be passed to ITERPROC via the
_EXTRA mechanism. This should be a structure, and is
similar in operation to FUNCTARGS.
Default: no arguments are passed.
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the MPFIT routine. It should be declared
in the following way:
PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, ...
; perform custom iteration update
END
ITERPROC must either accept all three keyword
parameters (FUNCTARGS, PARINFO and QUIET), or at least
accept them via the _EXTRA keyword.
MYFUNCT is the user-supplied function to be minimized,
P is the current set of model parameters, ITER is the
iteration number, and FUNCTARGS are the arguments to be
passed to MYFUNCT. FNORM should be the
chi-squared value. QUIET is set when no textual output
should be printed. See below for documentation of
PARINFO.
In implementation, ITERPROC can perform updates to the
terminal or graphical user interface, to provide
feedback while the fit proceeds. If the fit is to be
stopped for any reason, then ITERPROC should set the
common block variable ERROR_CODE to negative value (see
MPFIT_ERROR common block below). In principle,
ITERPROC should probably not modify the parameter
values, because it may interfere with the algorithm's
stability. In practice it is allowed.
Default: an internal routine is used to print the
parameter values.
MAXITER - The maximum number of iterations to perform. If the
number is exceeded, then the STATUS value is set to 5
and MPFIT returns.
Default: 200 iterations
NFEV - the number of MYFUNCT function evaluations performed.
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
NITER - the number of iterations completed.
NOCOVAR - set this keyword to prevent the calculation of the
covariance matrix before returning (see COVAR)
NPEGGED - the number of free parameters which are pegged at a
LIMIT.
NPRINT - The frequency with which ITERPROC is called. A value of
1 indicates that ITERPROC is called with every iteration,
while 2 indicates every other iteration, etc. Note that
several Levenberg-Marquardt attempts can be made in a
single iteration.
Default value: 1
PARINFO - Provides a mechanism for more sophisticated constraints
to be placed on parameter values. When PARINFO is not
passed, then it is assumed that all parameters are free
and unconstrained. Values in PARINFO are never
modified during a call to MPFIT.
See description above for the structure of PARINFO.
Default value: all parameters are free and unconstrained.
PERROR - The formal 1-sigma errors in each parameter, computed
from the covariance matrix. If a parameter is held
fixed, or if it touches a boundary, then the error is
reported as zero.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling PERROR
by the measured chi-squared value.
DOF = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
QUIET - set this keyword when no textual output should be printed
by MPFIT
STATUS - an integer status code is returned. All values other
than zero can represent success. It can have one of the
following values:
0 improper input parameters.
1 both actual and predicted relative reductions
in the sum of squares are at most FTOL.
2 relative error between two consecutive iterates
is at most XTOL
3 conditions for STATUS = 1 and STATUS = 2 both hold.
4 the cosine of the angle between fvec and any
column of the jacobian is at most GTOL in
absolute value.
5 the maximum number of iterations has been reached
6 FTOL is too small. no further reduction in
the sum of squares is possible.
7 XTOL is too small. no further improvement in
the approximate solution x is possible.
8 GTOL is too small. fvec is orthogonal to the
columns of the jacobian to machine precision.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERR
parameter is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Y-MYFUNCT(X,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Y - Poisson weighting (counting statistics)
1D - Unweighted
XTOL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at most
XTOL (and STATUS is accordingly set to 2 or 3). Therefore,
XTOL measures the relative error desired in the approximate
solution. Default: 1D-10
YFIT - the best-fit model function, as returned by MYFUNCT.
EXAMPLE:
; First, generate some synthetic data
x = dindgen(200) * 0.1 - 10. ; Independent variable
yi = gauss1(x, [2.2D, 1.4, 3000.]) + 1000 ; "Ideal" Y variable
y = yi + randomn(seed, 200) * sqrt(yi) ; Measured, w/ noise
sy = sqrt(y) ; Poisson errors
; Now fit a Gaussian to see how well we can recover
expr = 'P[0] + GAUSS1(X, P[1:3])' ; fitting function
p0 = [800.D, 1.D, 1., 500.] ; Initial guess
p = mpfitexpr(expr, x, y, sy, p0) ; Fit the expression
print, p
plot, x, y ; Plot data
oplot, x, mpevalexpr(expr, x, p) ; Plot model
Generates a synthetic data set with a Gaussian peak, and Poisson
statistical uncertainty. Then a model consisting of a constant
plus Gaussian is fit to the data.
COMMON BLOCKS:
COMMON MPFIT_ERROR, ERROR_CODE
User routines may stop the fitting process at any time by
setting an error condition. This condition may be set in either
the user's model computation routine (MYFUNCT), or in the
iteration procedure (ITERPROC).
To stop the fitting, the above common block must be declared,
and ERROR_CODE must be set to a negative number. After the user
procedure or function returns, MPFIT checks the value of this
common block variable and exits immediately if the error
condition has been set. By default the value of ERROR_CODE is
zero, indicating a successful function/procedure call.
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
Written, Apr-Jul 1998, CM
Added PERROR keyword, 04 Aug 1998, CM
Added COVAR keyword, 20 Aug 1998, CM
Added NITER output keyword, 05 Oct 1998
D.L Windt, Bell Labs, windt@bell-labs.com;
Added ability to return model function in YFIT, 09 Nov 1998
Parameter values can be tied to others, 09 Nov 1998
Added MPEVALEXPR utility function, 09 Dec 1998
Cosmetic documentation updates, 16 Apr 1999, CM
More cosmetic documentation updates, 14 May 1999, CM
Made sure to update STATUS value, 25 Sep 1999, CM
Added WEIGHTS keyword, 25 Sep 1999, CM
Changed from handles to common blocks, 25 Sep 1999, CM
- commons seem much cleaner and more logical in this case.
Alphabetized documented keywords, 02 Oct 1999, CM
Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
Check to be sure that X and Y are present, 02 Nov 1999, CM
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Removed ITERPROC='' when quiet EQ 1, 10 Jan 2000, CM
Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
Updated the EXAMPLE, 26 Mar 2000, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Propagated improvements from MPFIT, 17 Dec 2000, CM
Correct reference to _WTS in MPFITEXPR_EVAL, 25 May 2001, CM
(thanks to Mark Fardal)
Added useful FUNCTARGS behavior (as yet undocumented), 04 Jul
2002, CM
Documented FUNCTARGS/PRIVATE behavior, 22 Jul 2002, CM
Added NFREE and NPEGGED keywords, 13 Sep 2002, CM
Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
Add DOF keyword, CM, 31 Jul 2003
Add FUNCTARGS keyword to MPEVALEXPR, CM 08 Aug 2003
Minor documentation adjustment, 03 Feb 2004, CM
$Id: mpfitexpr.pro,v 1.12 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
NAME:
MPFITFUN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Perform Levenberg-Marquardt least-squares fit to IDL function
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
parms = MPFITFUN(MYFUNCT, X, Y, ERR, start_params, ...)
DESCRIPTION:
MPFITFUN fits a user-supplied model -- in the form of an IDL
function -- to a set of user-supplied data. MPFITFUN calls
MPFIT, the MINPACK-1 least-squares minimizer, to do the main
work.
Given the data and their uncertainties, MPFITFUN finds the best set
of model parameters which match the data (in a least-squares
sense) and returns them in an array.
The user must supply the following items:
- An array of independent variable values ("X").
- An array of "measured" *dependent* variable values ("Y").
- An array of "measured" 1-sigma uncertainty values ("ERR").
- The name of an IDL function which computes Y given X ("MYFUNCT").
- Starting guesses for all of the parameters ("START_PARAMS").
There are very few restrictions placed on X, Y or MYFUNCT. Simply
put, MYFUNCT must map the "X" values into "Y" values given the
model parameters. The "X" values may represent any independent
variable (not just Cartesian X), and indeed may be multidimensional
themselves. For example, in the application of image fitting, X
may be a 2xN array of image positions.
MPFITFUN carefully avoids passing large arrays where possible to
improve performance.
See below for an example of usage.
USER FUNCTION
The user must define a function which returns the model value. For
applications which use finite-difference derivatives -- the default
-- the user function should be declared in the following way:
FUNCTION MYFUNCT, X, P
; The independent variable is X
; Parameter values are passed in "P"
YMOD = ... computed model values at X ...
return, YMOD
END
The returned array YMOD must have the same dimensions and type as
the "measured" Y values.
User functions may also indicate a fatal error condition
using the ERROR_CODE common block variable, as described
below under the MPFIT_ERROR common block definition.
See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
in MPFIT.PRO if you wish to compute the derivatives for yourself.
AUTODERIVATIVE is accepted by MPFITFUN and passed directly to
MPFIT. The user function must accept one additional parameter, DP,
which contains the derivative of the user function with respect to
each parameter at each data point, as described in MPFIT.PRO.
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of MPFIT can be modified with respect to each
parameter to be fitted. A parameter value can be fixed; simple
boundary constraints can be imposed; limitations on the parameter
changes can be imposed; properties of the automatic derivative can
be modified; and parameters can be tied to one another.
These properties are governed by the PARINFO structure, which is
passed as a keyword parameter to MPFIT.
PARINFO should be an array of structures, one for each parameter.
Each parameter is associated with one element of the array, in
numerical order. The structure can have the following entries
(none are required):
.VALUE - the starting parameter value (but see the START_PARAMS
parameter for more information).
.FIXED - a boolean value, whether the parameter is to be held
fixed or not. Fixed parameters are not varied by
MPFIT, but are passed on to MYFUNCT for evaluation.
.LIMITED - a two-element boolean array. If the first/second
element is set, then the parameter is bounded on the
lower/upper side. A parameter can be bounded on both
sides. Both LIMITED and LIMITS must be given
together.
.LIMITS - a two-element float or double array. Gives the
parameter limits on the lower and upper sides,
respectively. Zero, one or two of these values can be
set, depending on the values of LIMITED. Both LIMITED
and LIMITS must be given together.
.PARNAME - a string, giving the name of the parameter. The
fitting code of MPFIT does not use this tag in any
way. However, the default ITERPROC will print the
parameter name if available.
.STEP - the step size to be used in calculating the numerical
derivatives. If set to zero, then the step size is
computed automatically. Ignored when AUTODERIVATIVE=0.
This value is superceded by the RELSTEP value.
.RELSTEP - the *relative* step size to be used in calculating
the numerical derivatives. This number is the
fractional size of the step, compared to the
parameter value. This value supercedes the STEP
setting. If the parameter is zero, then a default
step size is chosen.
.MPSIDE - the sidedness of the finite difference when computing
numerical derivatives. This field can take four
values:
0 - one-sided derivative computed automatically
1 - one-sided derivative (f(x+h) - f(x) )/h
-1 - one-sided derivative (f(x) - f(x-h))/h
2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)
Where H is the STEP parameter described above. The
"automatic" one-sided derivative method will chose a
direction for the finite difference which does not
violate any constraints. The other methods do not
perform this check. The two-sided method is in
principle more precise, but requires twice as many
function evaluations. Default: 0.
.MPMINSTEP - the minimum change to be made in the parameter
value. During the fitting process, the parameter
will be changed by multiples of this value. The
actual step is computed as:
DELTA1 = MPMINSTEP*ROUND(DELTA0/MPMINSTEP)
where DELTA0 and DELTA1 are the estimated parameter
changes before and after this constraint is
applied. Note that this constraint should be used
with care since it may cause non-converging,
oscillating solutions.
A value of 0 indicates no minimum. Default: 0.
.MPMAXSTEP - the maximum change to be made in the parameter
value. During the fitting process, the parameter
will never be changed by more than this value.
A value of 0 indicates no maximum. Default: 0.
.TIED - a string expression which "ties" the parameter to other
free or fixed parameters. Any expression involving
constants and the parameter array P are permitted.
Example: if parameter 2 is always to be twice parameter
1 then use the following: parinfo[2].tied = '2 * P[1]'.
Since they are totally constrained, tied parameters are
considered to be fixed; no errors are computed for them.
[ NOTE: the PARNAME can't be used in expressions. ]
Future modifications to the PARINFO structure, if any, will involve
adding structure tags beginning with the two letters "MP".
Therefore programmers are urged to avoid using tags starting with
the same letters; otherwise they are free to include their own
fields within the PARINFO structure, and they will be ignored.
PARINFO Example:
parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
limits:[0.D,0]}, 5)
parinfo[0].fixed = 1
parinfo[4].limited[0] = 1
parinfo[4].limits[0] = 50.D
parinfo[*].value = [5.7D, 2.2, 500., 1.5, 2000.]
A total of 5 parameters, with starting values of 5.7,
2.2, 500, 1.5, and 2000 are given. The first parameter
is fixed at a value of 5.7, and the last parameter is
constrained to be above 50.
INPUTS:
MYFUNCT - a string variable containing the name of an IDL function.
This function computes the "model" Y values given the
X values and model parameters, as desribed above.
X - Array of independent variable values.
Y - Array of "measured" dependent variable values. Y should have
the same data type as X. The function MYFUNCT should map
X->Y.
ERR - Array of "measured" 1-sigma uncertainties. ERR should have
the same data type as Y. ERR is ignored if the WEIGHTS
keyword is specified.
START_PARAMS - An array of starting values for each of the
parameters of the model. The number of parameters
should be fewer than the number of measurements.
Also, the parameters should have the same data type
as the measurements (double is preferred).
This parameter is optional if the PARINFO keyword
is used (see MPFIT). The PARINFO keyword provides
a mechanism to fix or constrain individual
parameters. If both START_PARAMS and PARINFO are
passed, then the starting *value* is taken from
START_PARAMS, but the *constraints* are taken from
PARINFO.
RETURNS:
Returns the array of best-fit parameters.
KEYWORD PARAMETERS:
BESTNORM - the value of the summed squared residuals for the
returned parameter values.
COVAR - the covariance matrix for the set of parameters returned
by MPFIT. The matrix is NxN where N is the number of
parameters. The square root of the diagonal elements
gives the formal 1-sigma statistical errors on the
parameters IF errors were treated "properly" in MYFUNC.
Parameter errors are also returned in PERROR.
To compute the correlation matrix, PCOR, use this:
IDL> PCOR = COV * 0
IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
PCOR[i,j] = COV[i,j]/sqrt(COV[i,i]*COV[j,j])
If NOCOVAR is set or MPFIT terminated abnormally, then
COVAR is set to a scalar with value !VALUES.D_NAN.
CASH - when set, the fit statistic is changed to a derivative of
the CASH statistic. The model function must be strictly
positive.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERRMSG - a string error or warning message is returned.
FTOL - a nonnegative input variable. Termination occurs when both
the actual and predicted relative reductions in the sum of
squares are at most FTOL (and STATUS is accordingly set to
1 or 3). Therefore, FTOL measures the relative error
desired in the sum of squares. Default: 1D-10
FUNCTARGS - A structure which contains the parameters to be passed
to the user-supplied function specified by MYFUNCT via
the _EXTRA mechanism. This is the way you can pass
additional data to your user-supplied function without
using common blocks.
By default, no extra parameters are passed to the
user-supplied function.
GTOL - a nonnegative input variable. Termination occurs when the
cosine of the angle between fvec and any column of the
jacobian is at most GTOL in absolute value (and STATUS is
accordingly set to 4). Therefore, GTOL measures the
orthogonality desired between the function vector and the
columns of the jacobian. Default: 1D-10
ITERARGS - The keyword arguments to be passed to ITERPROC via the
_EXTRA mechanism. This should be a structure, and is
similar in operation to FUNCTARGS.
Default: no arguments are passed.
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the MPFIT routine. It should be declared
in the following way:
PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, ...
; perform custom iteration update
END
ITERPROC must either accept all three keyword
parameters (FUNCTARGS, PARINFO and QUIET), or at least
accept them via the _EXTRA keyword.
MYFUNCT is the user-supplied function to be minimized,
P is the current set of model parameters, ITER is the
iteration number, and FUNCTARGS are the arguments to be
passed to MYFUNCT. FNORM should be the
chi-squared value. QUIET is set when no textual output
should be printed. See below for documentation of
PARINFO.
In implementation, ITERPROC can perform updates to the
terminal or graphical user interface, to provide
feedback while the fit proceeds. If the fit is to be
stopped for any reason, then ITERPROC should set the
common block variable ERROR_CODE to negative value (see
MPFIT_ERROR common block below). In principle,
ITERPROC should probably not modify the parameter
values, because it may interfere with the algorithm's
stability. In practice it is allowed.
Default: an internal routine is used to print the
parameter values.
MAXITER - The maximum number of iterations to perform. If the
number is exceeded, then the STATUS value is set to 5
and MPFIT returns.
Default: 200 iterations
NFEV - the number of MYFUNCT function evaluations performed.
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
NITER - the number of iterations completed.
NOCOVAR - set this keyword to prevent the calculation of the
covariance matrix before returning (see COVAR)
NPEGGED - the number of free parameters which are pegged at a
LIMIT.
NPRINT - The frequency with which ITERPROC is called. A value of
1 indicates that ITERPROC is called with every iteration,
while 2 indicates every other iteration, etc. Note that
several Levenberg-Marquardt attempts can be made in a
single iteration.
Default value: 1
PARINFO - Provides a mechanism for more sophisticated constraints
to be placed on parameter values. When PARINFO is not
passed, then it is assumed that all parameters are free
and unconstrained. Values in PARINFO are never
modified during a call to MPFIT.
See description above for the structure of PARINFO.
Default value: all parameters are free and unconstrained.
PERROR - The formal 1-sigma errors in each parameter, computed
from the covariance matrix. If a parameter is held
fixed, or if it touches a boundary, then the error is
reported as zero.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling PERROR
by the measured chi-squared value.
DOF = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
QUIET - set this keyword when no textual output should be printed
by MPFIT
STATUS - an integer status code is returned. All values other
than zero can represent success. It can have one of the
following values:
0 improper input parameters.
1 both actual and predicted relative reductions
in the sum of squares are at most FTOL.
2 relative error between two consecutive iterates
is at most XTOL
3 conditions for STATUS = 1 and STATUS = 2 both hold.
4 the cosine of the angle between fvec and any
column of the jacobian is at most GTOL in
absolute value.
5 the maximum number of iterations has been reached
6 FTOL is too small. no further reduction in
the sum of squares is possible.
7 XTOL is too small. no further improvement in
the approximate solution x is possible.
8 GTOL is too small. fvec is orthogonal to the
columns of the jacobian to machine precision.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERR
parameter is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Y-MYFUNCT(X,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Y - Poisson weighting (counting statistics)
1D - Unweighted
XTOL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at most
XTOL (and STATUS is accordingly set to 2 or 3). Therefore,
XTOL measures the relative error desired in the approximate
solution. Default: 1D-10
YFIT - the best-fit model function, as returned by MYFUNCT.
EXAMPLE:
; First, generate some synthetic data
npts = 200
x = dindgen(npts) * 0.1 - 10. ; Independent variable
yi = gauss1(x, [2.2D, 1.4, 3000.]) ; "Ideal" Y variable
y = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
sy = sqrt(1000.D + y) ; Poisson errors
; Now fit a Gaussian to see how well we can recover
p0 = [1.D, 1., 1000.] ; Initial guess (cent, width, area)
p = mpfitfun('GAUSS1', x, y, sy, p0) ; Fit a function
print, p
Generates a synthetic data set with a Gaussian peak, and Poisson
statistical uncertainty. Then the same function is fitted to the
data (with different starting parameters) to see how close we can
get.
COMMON BLOCKS:
COMMON MPFIT_ERROR, ERROR_CODE
User routines may stop the fitting process at any time by
setting an error condition. This condition may be set in either
the user's model computation routine (MYFUNCT), or in the
iteration procedure (ITERPROC).
To stop the fitting, the above common block must be declared,
and ERROR_CODE must be set to a negative number. After the user
procedure or function returns, MPFIT checks the value of this
common block variable and exits immediately if the error
condition has been set. By default the value of ERROR_CODE is
zero, indicating a successful function/procedure call.
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
Written, Apr-Jul 1998, CM
Added PERROR keyword, 04 Aug 1998, CM
Added COVAR keyword, 20 Aug 1998, CM
Added ITER output keyword, 05 Oct 1998
D.L Windt, Bell Labs, windt@bell-labs.com;
Added ability to return model function in YFIT, 09 Nov 1998
Analytical derivatives allowed via AUTODERIVATIVE keyword, 09 Nov 1998
Parameter values can be tied to others, 09 Nov 1998
Cosmetic documentation updates, 16 Apr 1999, CM
More cosmetic documentation updates, 14 May 1999, CM
Made sure to update STATUS, 25 Sep 1999, CM
Added WEIGHTS keyword, 25 Sep 1999, CM
Changed from handles to common blocks, 25 Sep 1999, CM
- commons seem much cleaner and more logical in this case.
Alphabetized documented keywords, 02 Oct 1999, CM
Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
Corrected EXAMPLE (offset of 1000), 30 Oct 1999, CM
Check to be sure that X and Y are present, 02 Nov 1999, CM
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
Corrected errors in EXAMPLE, 26 Mar 2000, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Propagated improvements from MPFIT, 17 Dec 2000, CM
Added CASH statistic, 10 Jan 2001
Added NFREE and NPEGGED keywords, 11 Sep 2002, CM
Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
Add DOF keyword to return degrees of freedom, CM, 23 June 2003
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
$Id: mpfitfun.pro,v 1.7 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
NAME:
MPFITPEAK
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Fit a gaussian, lorentzian or Moffat model to data
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
yfit = MPFITPEAK(X, Y, A, NTERMS=nterms, ...)
DESCRIPTION:
MPFITPEAK fits a gaussian, lorentzian or Moffat model using the
non-linear least squares fitter MPFIT. MPFITPEAK is meant to be a
drop-in replacement for IDL's GAUSSFIT function (and requires
MPFIT and MPFITFUN).
The choice of the fitting function is determined by the keywords
GAUSSIAN, LORENTZIAN and MOFFAT. By default the gaussian model
function is used. [ The Moffat function is a modified Lorentzian
with variable power law index. (Moffat, A. F. J. 1969, Astronomy &
Astrophysics, v. 3, p. 455-461) ]
The functional form of the baseline is determined by NTERMS and
the function to be fitted. NTERMS represents the total number of
parameters, A, to be fitted. The functional forms and the
meanings of the parameters are described in this table:
GAUSSIAN# Lorentzian# Moffat#
Model A[0]*exp(-0.5*u^2) A[0]/(u^2 + 1) A[0]/(u^2 + 1)^A[3]
A[0] Peak Value Peak Value Peak Value
A[1] Peak Centroid Peak Centroid Peak Centroid
A[2] Gaussian Sigma HWHM% HWHM%
A[3] + A[3] * + A[3] * Moffat Index
A[4] + A[4]*x * + A[4]*x * + A[4] *
A[5] + A[5]*x *
Notes: # u = (x - A[1])/A[2]
% Half-width at half maximum
* Optional depending on NTERMS
By default the initial starting values for the parameters A are
estimated from the data. However, explicit starting values can be
supplied using the ESTIMATES keyword. Also, error or weighting
values can optionally be provided; otherwise the fit is
unweighted.
MPFITPEAK fits the peak value of the curve. The area under a
gaussian peak is A[0]*A[2]*SQRT(2*!DPI); the area under a
lorentzian peak is A[0]*A[2]*!DPI.
RESTRICTIONS:
If no starting parameter ESTIMATES are provided, then MPFITPEAK
attempts to estimate them from the data. This is not a perfect
science; however, the author believes that the technique
implemented here is more robust than the one used in IDL's
GAUSSFIT. The author has tested cases of strong peaks, noisy
peaks and broad peaks, all with success.
Users should be aware that if the baseline term contains a strong
linear component then the automatic estimation may fail. For
automatic estimation to work the peak amplitude should dominate
over the the maximum baseline.
INPUTS:
X - Array of independent variable values, whose values should
monotonically increase.
Y - Array of "measured" dependent variable values. Y should have
the same data type and dimension as X.
OUTPUTS:
A - Upon return, an array of NTERMS best fit parameter values.
See the table above for the meanings of each parameter
element.
RETURNS:
Returns the best fitting model function.
KEYWORDS:
** NOTE ** Additional keywords such as PARINFO, BESTNORM, and
STATUS are accepted by MPFITPEAK but not documented
here. Please see the documentation for MPFIT for the
description of these advanced options.
CHISQ - the value of the summed squared residuals for the
returned parameter values.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERROR - upon input, the measured 1-sigma uncertainties in the "Y"
values. If no ERROR or WEIGHTS are given, then the fit is
unweighted.
ESTIMATES - Array of starting values for each parameter of the
model. The number of parameters should at least be
three (four for Moffat), and if less than NTERMS, will
be extended with zeroes.
Default: parameter values are estimated from data.
GAUSSIAN - if set, fit a gaussian model function. The Default.
LORENTZIAN - if set, fit a lorentzian model function.
MOFFAT - if set, fit a Moffat model function.
MEASURE_ERRORS - synonym for ERRORS, for consistency with built-in
IDL fitting routines.
NEGATIVE / POSITIVE - if set, and ESTIMATES is not provided, then
MPFITPEAK will assume that a
negative/positive peak is present.
Default: determined automatically
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
NTERMS - An integer describing the number of fitting terms.
NTERMS must have a minimum value, but can optionally be
larger depending on the desired baseline.
For gaussian and lorentzian models, NTERMS must be three
(zero baseline), four (constant baseline) or five (linear
baseline). Default: 4
For the Moffat model, NTERMS must be four (zero
baseline), five (constant baseline), or six (linear
baseline). Default: 5
PERROR - upon return, the 1-sigma uncertainties of the parameter
values A. These values are only meaningful if the ERRORS
or WEIGHTS keywords are specified properly.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling PERROR
by the measured chi-squared value.
DOF = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
QUIET - if set then diagnostic fitting messages are suppressed.
Default: QUIET=1 (i.e., no diagnostics)
SIGMA - synonym for PERROR (1-sigma parameter uncertainties), for
compatibility with GAUSSFIT. Do not confuse this with the
Gaussian "sigma" width parameter.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERROR
keyword is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Y-MYFUNCT(X,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Y - Poisson weighting (counting statistics)
1D - Unweighted
The ERROR keyword takes precedence over any WEIGHTS
keyword values. If no ERROR or WEIGHTS are given, then
the fit is unweighted.
YERROR - upon return, the root-mean-square variance of the
residuals.
EXAMPLE:
; First, generate some synthetic data
npts = 200
x = dindgen(npts) * 0.1 - 10. ; Independent variable
yi = gauss1(x, [2.2D, 1.4, 3000.]) + 1000 ; "Ideal" Y variable
y = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
sy = sqrt(1000.D + y) ; Poisson errors
; Now fit a Gaussian to see how well we can recover the original
yfit = mpfitpeak(x, y, a, error=sy)
print, p
Generates a synthetic data set with a Gaussian peak, and Poisson
statistical uncertainty. Then the same function is fitted to the
data.
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
New algorithm for estimating starting values, CM, 31 Oct 1999
Documented, 02 Nov 1999
Small documentation fixes, 02 Nov 1999
Slight correction to calculation of dx, CM, 02 Nov 1999
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Change requirements on # elements in X and Y, 20 Jul 2000, CM
(thanks to David Schlegel <schlegel@astro.princeton.edu>)
Added documentation on area under curve, 29 Aug 2000, CM
Added POSITIVE and NEGATIVE keywords, 17 Nov 2000, CM
Added reference to Moffat paper, 10 Jan 2001, CM
Added usage message, 26 Jul 2001, CM
Documentation clarification, 05 Sep 2001, CM
Make more consistent with comparable IDL routines, 30 Jun 2003, CM
Assumption of sorted data was removed, CM, 06 Sep 2003, CM
Add some defensive code against divide by zero, 30 Nov 2005, CM
Add some defensive code against all Y values equal to each other,
17 Apr 2005, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
$Id: mpfitpeak.pro,v 1.10 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
NAME:
MPFTEST
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Compute the probability of a given F value
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
PROB = MPFTEST(F, DOF1, DOF2, [/SIGMA, /CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPFTEST() computes the probability for a value drawn
from the F-distribution to equal or exceed the given value of F.
This can be used for confidence testing of a measured value obeying
the F-distribution (i.e., for testing the ratio of variances, or
equivalently for the addition of parameters to a fitted model).
P_F(X > F; DOF1, DOF2) = PROB
In specifying the returned probability level the user has three
choices:
* return the confidence level when the /CLEVEL keyword is passed;
OR
* return the significance level (i.e., 1 - confidence level) when
the /SLEVEL keyword is passed (default); OR
* return the "sigma" of the probability (i.e., compute the
probability based on the normal distribution) when the /SIGMA
keyword is passed.
Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.
For the ratio of variance test, the two variances, VAR1 and VAR2,
should be distributed according to the chi-squared distribution
with degrees of freedom DOF1 and DOF2 respectively. The F-value is
computed as:
F = (VAR1/DOF1) / (VAR2/DOF2)
and then the probability is computed as:
PROB = MPFTEST(F, DOF1, DOF2, ... )
For the test of additional parameters in least squares fitting, the
user should perform two separate fits, and have two chi-squared
values. One fit should be the "original" fit with no additional
parameters, and one fit should be the "new" fit with M additional
parameters.
CHI1 - chi-squared value for original fit
DOF1 - number of degrees of freedom of CHI1 (number of data
points minus number of original parameters)
CHI2 - chi-squared value for new fit
DOF2 - number of degrees of freedom of CHI2
Note that according to this formalism, the number of degrees of
freedom in the "new" fit, DOF2, should be less than the number of
degrees of freedom in the "original" fit, DOF1 (DOF2 < DOF1); and
also CHI2 < CHI1.
With the above definition, the F value is computed as:
F = ( (CHI1-CHI2)/(DOF1-DOF2) ) / (CHI2/DOF2)
where DOF1-DOF2 is equal to M, and then the F-test probability is
computed as:
PROB = MPFTEST(F, DOF1-DOF2, DOF2, ... )
Note that this formalism assumes that the addition of the M
parameters is a small peturbation to the overall fit. If the
additional parameters dramatically changes the character of the
model, then the first "ratio of variance" test is more appropriate,
where F = (CHI1/DOF1) / (CHI2/DOF2).
INPUTS:
F - ratio of variances as defined above.
DOF1 - number of degrees of freedom in first variance component.
DOF2 - number of degrees of freedom in second variance component.
RETURNS:
Returns a scalar or vector of probabilities, as described above,
and according to the /SLEVEL, /CLEVEL and /SIGMA keywords.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level
(default).
CLEVEL - if set, then PROB describes the confidence level.
SIGMA - if set, then PROB is the number of "sigma" away from the
mean in the normal distribution.
EXAMPLE:
chi1 = 62.3D & dof1 = 42d
chi2 = 54.6D & dof2 = 40d
f = ((chi1-chi2)/(dof1-dof2)) / (chi2/dof2)
print, mpftest(f, dof1-dof2, dof2)
This is a test for addition of parameters. The "original"
chi-squared value was 62.3 with 42 degrees of freedom, and the
"new" chi-squared value was 54.6 with 40 degrees of freedom.
These values reflect the addition of 2 parameters and the
reduction of the chi-squared value by 7.7. The significance of
this set of circumstances is 0.071464757.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/ )
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
Added documentation, 30 Dec 2001, CM
Documentation corrections (thanks W. Landsman), 17 Jan 2002, CM
Example docs were corrected (Thanks M. Perez-Torres), 17 Feb 2002,
CM
Example corrected again (sigh...), 13 Feb 2003, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
$Id: mpftest.pro,v 1.8 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
NAME:
MPHASE
PURPOSE:
Return the illuminated fraction of the Moon at given Julian date(s)
CALLING SEQUENCE:
MPHASE, jd, k
INPUT:
JD - Julian date, scalar or vector, double precision recommended
OUTPUT:
k - illuminated fraction of Moon's disk (0.0 < k < 1.0), same number
of elements as jd. k = 0 indicates a new moon, while k = 1 for
a full moon.
CALLS: ***
MOONPOS, SUNPOS
EXAMPLE:
Plot the illuminated fraction of the moon for every day in July
1996 at 0 TD (~Greenwich noon).
IDL> jdcnv, 1996, 7, 1, 0, jd ;Get Julian date of July 1
IDL> mphase, jd+dindgen(31), k ;Moon phase for all 31 days
IDL> plot, indgen(31),k ;Plot phase vs. July day number
METHOD:
Algorithm from Chapter 46 of "Astronomical Algorithms" by Jean Meeus
(Willmann-Bell, Richmond) 1991. SUNPOS and MOONPOS are used to get
positions of the Sun and the Moon (and the Moon distance). The
selenocentric elongation of the Earth from the Sun (phase angle)
is then computed, and used to determine the illuminated fraction.
PROCEDURES CALLED:
MOONPOS, SUNPOS
REVISION HISTORY:
Written W. Landsman Hughes STX June 1996
Converted to IDL V5.0 W. Landsman September 1997
Use /RADIAN keywords to MOONPOS, SUNPOS internally W. Landsman Aug 2000
[Previous]
[Next]
NAME:
MPNORMLIM
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Compute confidence limits for normally distributed variable
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
Z = MPNORMLIM(PROB, [/CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPNORMLIM() computes confidence limits of a normally
distributed variable (with zero mean and unit variance), for a
desired probability level. The returned values, Z, are the
limiting values: a the magnitude of a normally distributed value
is greater than Z by chance with a probability PROB:
P_NORM(ABS(X) > Z) = PROB
In specifying the probability level the user has two choices:
* give the confidence level (default);
* give the significance level (i.e., 1 - confidence level) and
pass the /SLEVEL keyword; OR
Note that /SLEVEL and /CLEVEL are mutually exclusive.
INPUTS:
PROB - scalar or vector number, giving the desired probability
level as described above.
RETURNS:
Returns a scalar or vector of normal confidence limits.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level.
CLEVEL - if set, then PROB describes the confidence level
(default).
EXAMPLE:
print, mpnormlim(0.99d, /clevel)
Print the 99% confidence limit for a normally distributed
variable. In this case it is about 2.58 sigma.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/ )
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
$Id: mpnormlim.pro,v 1.4 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
NAME:
MPNORMTEST
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Compute the probability of a given normally distributed Z value
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
PROB = MPNORMTEST(Z, [/CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPNORMTEST() computes the probability for the
magnitude of a value drawn from the normal distribution to equal or
exceed the given value Z. This can be used for confidence testing
of a measured value obeying the normal distribution.
P_NORM(ABS(X) > Z) = PROB
In specifying the returned probability level the user has two
choices:
* return the confidence level when the /CLEVEL keyword is passed;
OR
* return the significance level (i.e., 1 - confidence level) when
the /SLEVEL keyword is passed (default).
Note that /SLEVEL and /CLEVEL are mutually exclusive.
INPUTS:
Z - the value to best tested. Z should be drawn from a normal
distribution with zero mean and unit variance. If a given
quantity Y has mean MU and standard deviation STD, then Z can
be computed as Z = (Y-MU)/STD.
RETURNS:
Returns a scalar or vector of probabilities, as described above,
and according to the /SLEVEL and /CLEVEL keywords.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level
(default).
CLEVEL - if set, then PROB describes the confidence level.
EXAMPLES:
print, mpnormtest(5d, /slevel)
Print the probability for the magnitude of a randomly distributed
variable with zero mean and unit variance to exceed 5, as a
significance level.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/ )
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
Corrected error in handling of CLEVEL keyword, 05 Sep 2003
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
$Id: mpnormtest.pro,v 1.6 2006/08/11 01:13:27 craigm Exp $
[Previous]
[Next]
Project : HESSI
Name : MRD_HEAD
Purpose : wrapper around MRD_HREAD to simplify reading FITS file
headers
Category : FITS I/O
Syntax : IDL> hread,file,header
Inputs : FILE = input file name
Outputs : HEADER = string header
Keywords : EXTENSION = binary extension [def=0]
ERR = error string
Written : Zarro (EIT/GSFC), 13 Aug 2001
Contact : dzarro@solar.stanford.edu
CALLS:
CALLED BY
EIT__DEFINE, FITS__DEFINE, HXRS__DEFINE, MAP__DEFINE
[Previous]
[Next]
NAME:
MRD_HREAD
PURPOSE:
Reads a FITS header from an opened disk file or Unix pipe
EXPLANATION:
Like FXHREAD but also works with compressed Unix files
CALLING SEQUENCE:
MRD_HREAD, UNIT, HEADER [, STATUS, /SILENT ]
INPUTS:
UNIT = Logical unit number of an open FITS file
OUTPUTS:
HEADER = String array containing the FITS header.
OPT. OUTPUTS:
STATUS = Condition code giving the status of the read. Normally, this
is zero, but is set to -1 if an error occurs, or if the
first byte of the header is zero (ASCII null).
CALLED BY:
EIS_GET_HDR [1], EIS_GET_HDR [2], FITSDIR, FITSFILE__DEFINE [2], FXMOVE [1]
FXMOVE [2], HEADFITS [1], HEADFITS [2], HFITS__DEFINE, MRDFITS [1], MRDFITS [2]
MRD_HEAD, WRITEFITS [1], WRITEFITS [2]
OPTIONAL KEYWORD INPUT:
/SILENT - If set, then warning messages about any invalid characters in
the header are suppressed.
/FIRSTBLOCK - If set, then only the first block (36 lines or less) of
the FITS header are read into the output variable. If only
size information (e.g. BITPIX, NAXIS) is needed from the
header, then the use of this keyword can save time. The
file pointer is still positioned at the end of the header,
even if the /FIRSTBLOCK keyword is supplied.
RESTRICTIONS:
The file must already be positioned at the start of the header. It
must be a proper FITS file.
SIDE EFFECTS:
The file ends by being positioned at the end of the FITS header, unless
an error occurs.
REVISION HISTORY:
Written, Thomas McGlynn August 1995
Modified, Thomas McGlynn January 1996
Changed MRD_HREAD to handle Headers which have null characters
A warning message is printed out but the program continues.
Previously MRD_HREAD would fail if the null characters were
not in the last 2880 byte block of the header. Note that
such characters are illegal in the header but frequently
are produced by poor FITS writers.
Converted to IDL V5.0 W. Landsman September 1997
Added /SILENT keyword W. Landsman December 2000
Added /FIRSTBLOCK keyword W. Landsman February 2003
[Previous]
[Next]
NAME:
MRD_HREAD
PURPOSE:
Reads a FITS header from an opened disk file or Unix pipe
EXPLANATION:
Like FXHREAD but also works with compressed Unix files
CALLING SEQUENCE:
MRD_HREAD, UNIT, HEADER [, STATUS, /SILENT ]
INPUTS:
UNIT = Logical unit number of an open FITS file
OUTPUTS:
HEADER = String array containing the FITS header.
OPT. OUTPUTS:
STATUS = Condition code giving the status of the read. Normally, this
is zero, but is set to -1 if an error occurs, or if the
first byte of the header is zero (ASCII null).
CALLED BY:
EIS_GET_HDR [1], EIS_GET_HDR [2], FITSDIR, FITSFILE__DEFINE [2], FXMOVE [1]
FXMOVE [2], HEADFITS [1], HEADFITS [2], HFITS__DEFINE, MRDFITS [1], MRDFITS [2]
MRD_HEAD, WRITEFITS [1], WRITEFITS [2]
OPTIONAL KEYWORD INPUT:
/SILENT - If set, then warning messages about any invalid characters in
the header are suppressed.
/FIRSTBLOCK - If set, then only the first block (36 lines or less) of
the FITS header are read into the output variable. If only
size information (e.g. BITPIX, NAXIS) is needed from the
header, then the use of this keyword can save time. The
file pointer is still positioned at the end of the header,
even if the /FIRSTBLOCK keyword is supplied.
RESTRICTIONS:
The file must already be positioned at the start of the header. It
must be a proper FITS file.
SIDE EFFECTS:
The file ends by being positioned at the end of the FITS header, unless
an error occurs.
REVISION HISTORY:
Written, Thomas McGlynn August 1995
Modified, Thomas McGlynn January 1996
Changed MRD_HREAD to handle Headers which have null characters
A warning message is printed out but the program continues.
Previously MRD_HREAD would fail if the null characters were
not in the last 2880 byte block of the header. Note that
such characters are illegal in the header but frequently
are produced by poor FITS writers.
Converted to IDL V5.0 W. Landsman September 1997
Added /SILENT keyword W. Landsman December 2000
Added /FIRSTBLOCK keyword W. Landsman February 2003
[Previous]
[Next]
NAME:
MRD_SKIP
PURPOSE:
Skip a number of bytes from the current location in a file or a pipe
EXPLANATION:
First tries using POINT_LUN and if this doesn't work, perhaps because
the unit is a pipe, MRD_SKIP will just read in the requisite number
of bytes. GZIP files opened with /COMPRESS (in V5.3 or later) are
also read as a series of bytes, since this is faster than using
POINT_LUN when not at the beginning of a file.
CALLING SEQUENCE:
MRD_SKIP, Unit, Nskip
INPUTS:
Unit - File unit for the file or pipe in question, integer scalar
Nskip - Number of bytes to be skipped, positive integer
NOTES:
This routine should be used in place of POINT_LUN wherever a pipe
may be the input unit (see the procedure FXPOSIT for an example).
Note that it assumes that it can only work with nskip >= 0 so it
doesn't even try for negative values.
For reading a pipe, MRD_SKIP currently uses a maximum buffer size
of 8 MB. This chunk value can be increased for improved efficiency
(or decreased if you really have little memory.)
REVISION HISTORY:
Written, Thomas A. McGlynn July 1995
Don't even try to skip bytes on a pipe with POINT_LUN, since this
might reset the current pointer W. Landsman April 1996
Increase buffer size, check fstat.compress W. Landsman Jan 2001
Only a warning if trying read past EOF W. Landsman Sep 2001
Use 64bit longword for skipping in very large files W. Landsman Sep 2003
CALLED BY
FITS_INFO [1], FITS_INFO [2], FXMOVE [1], FXMOVE [2], HESSI Packet Read [2]
HESSI RAW DATA READER, MRDFITS [1], MRDFITS [2]
[Previous]
[Next]
NAME:
MRD_SKIP
PURPOSE:
Skip a number of bytes from the current location in a file or a pipe
EXPLANATION:
First tries using POINT_LUN and if this doesn't work, perhaps because
the unit is a pipe or a socket, MRD_SKIP will just read in the
requisite number of bytes.
CALLING SEQUENCE:
MRD_SKIP, Unit, Nskip
INPUTS:
Unit - File unit for the file or pipe in question, integer scalar
Nskip - Number of bytes to be skipped, positive integer
NOTES:
This routine should be used in place of POINT_LUN wherever a pipe
or socket may be the input unit (see the procedure FXPOSIT for an
example). Note that it assumes that it can only work with nskip >= 0
so it doesn't even try for negative values.
For reading a pipe, MRD_SKIP currently uses a maximum buffer size
of 8 MB. This chunk value can be increased for improved efficiency
(or decreased if you really have little memory.)
REVISION HISTORY:
Written, Thomas A. McGlynn July 1995
Don't even try to skip bytes on a pipe with POINT_LUN, since this
might reset the current pointer W. Landsman April 1996
Increase buffer size, check fstat.compress W. Landsman Jan 2001
Only a warning if trying read past EOF W. Landsman Sep 2001
Use 64bit longword for skipping in very large files W. Landsman Sep 2003
Assume since V5.4, fstat.compress available W. Landsman April 2006
POINT_LUN for compressed files is as fast as any W. Landsman Oct 2006
Don't try to use POINT_LUN on compressed files W. Landsman Dec. 2006
CALLED BY
FITS_INFO [1], FITS_INFO [2], FXMOVE [1], FXMOVE [2], HESSI Packet Read [2]
HESSI RAW DATA READER, MRDFITS [1], MRDFITS [2]
[Previous]
[Next]
NAME:
MRD_STRUCT
PURPOSE:
Return a structure as defined in the names and values data.
CALLING SEQUENCE:
struct = MRD_STRUCT(NAMES, VALUES, NROW, STRUCTYP='name' )
INPUT PARAMETERS:
NAMES = A string array of names of structure fields.
VALUES = A string array giving the values of the structure
fields. See examples below.
NROW = The number of elements in the structure array.
RETURNS:
A structure as described in the parameters or 0 if an error
is detected.
OPTIONAL KEYWORD PARAMETERS:
/NO_EXECUTE - If set then the use of the EXECUTE() statement is avoided.
By default, the NO_EXECUTE pathway is used if IDL is
running under the Virtual Machine. Note if /NO_EXECUTE
is set, then the user cannot supply arbitary values, but
all possible values used by MRDFITS will be allowed.
STRUCTYP = The structure type. Since IDL does not allow the
redefinition of a named structure it is an error
to call MRD_STRUCT with different parameters but
the same STRUCTYP in the same session. If this
keyword is not set an anonymous structure is created.
CALLS: ***
GETTOK [1], GETTOK [2], GETTOK [3], GETTOK [4], strsplit
CALLED BY:
MRDFITS [1], MRDFITS [2]
COMMON BLOCKS:
MRD_COMMON
SIDE EFFECTS:
May create a temporary file if the structure definition is too long
for the EXECUTE function and using old style structures
RESTRICTIONS:
By default, the program defines the structure in a long string
which is executed with CREATE_STRUCT within a single EXECUTE statement.
If program is being run in the IDL Virtual machine (EXECUTE statement
not allowed), then a separate CREATE_STRUCT statement is called
for each tag. This mode does not have the full capabilities of the
normal mode, but should be sufficient for use with MRDFITS().
PROCEDURE:
A structure definition is created using the parameter values.
MRD_NSTRUCT is called and generates the structure in pieces using the
execute and create_struct keywords.
EXAMPLES:
(1) str = mrd_struct(['fld1', 'fld2'], ['0','dblarr(10,10)'],3)
print, str(0).fld2(3,3)
(2) str = mrd_struct(['a','b','c','d'],['1', '1.', '1.d0', "'1'"],1)
; returns a structure with integer, float, double and string
; fields.
PROCEDURE CALLS:
GETTOK() - needed for virtual machine mode only
MINIMUM IDL VERSION:
V5.3 (uses STRSPLIT)
MODIFICATION HISTORY:
Created by T. McGlynn October, 1994.
Modified by T. McGlynn September, 1995.
Added capability to create substructures so that structure
may contain up to 4096 distinct elements. [This can be
increased by futher iteration of the process used if needed.]
Converted to IDL V5.0 W. Landsman September 1997
Removed V4.0 reference to common block October 1997
Allowed unlimited number of structure elements if the version
is greater than 5.0. Put back in code to handle prior versions.
The [] will need to be translated back to () for this to
work. T. McGlynn December 15 1998.
Add MRD_NSTRUCT since IDL has mysterious problems compiling
very large structures.
Removed TEMPDIR and OLD_STRUCT keywords W. Landsman October 2003
Alternate pathway without EXECUTE for V6.0 virtual machine, D. Lindler
Removed limit on EXECUTE statement. W. Landsman October 2003
Restore EXECUTE limit (sigh...), added NO_EXECUTE keyword
W. Landsman July 2004
[Previous]
[Next]
NAME:
MRD_STRUCT
PURPOSE:
Return a structure as defined in the names and values data.
CALLING SEQUENCE:
struct = MRD_STRUCT(NAMES, VALUES, NROW, STRUCTYP='name' )
INPUT PARAMETERS:
NAMES = A string array of names of structure fields.
VALUES = A string array giving the values of the structure
fields. See examples below.
NROW = The number of elements in the structure array.
RETURNS:
A structure as described in the parameters or 0 if an error
is detected.
OPTIONAL KEYWORD PARAMETERS:
/NO_EXECUTE - If set then the use of the EXECUTE() statement is avoided.
By default, the NO_EXECUTE pathway is used if IDL is
running under the Virtual Machine. Note if /NO_EXECUTE
is set, then the user cannot supply arbitary values, but
all possible values used by MRDFITS will be allowed.
STRUCTYP = The structure type. Since IDL does not allow the
redefinition of a named structure it is an error
to call MRD_STRUCT with different parameters but
the same STRUCTYP in the same session. If this
keyword is not set an anonymous structure is created.
CALLS: ***
GETTOK [1], GETTOK [2], GETTOK [3], GETTOK [4], strsplit
CALLED BY:
MRDFITS [1], MRDFITS [2]
COMMON BLOCKS:
MRD_COMMON
SIDE EFFECTS:
May create a temporary file if the structure definition is too long
for the EXECUTE function and using old style structures
RESTRICTIONS:
By default, the program defines the structure in a long string
which is executed with CREATE_STRUCT within a single EXECUTE statement.
If program is being run in the IDL Virtual machine (EXECUTE statement
not allowed), then a separate CREATE_STRUCT statement is called
for each tag. This mode does not have the full capabilities of the
normal mode, but should be sufficient for use with MRDFITS().
PROCEDURE:
A structure definition is created using the parameter values.
MRD_NSTRUCT is called and generates the structure in pieces using the
execute and create_struct keywords.
EXAMPLES:
(1) str = mrd_struct(['fld1', 'fld2'], ['0','dblarr(10,10)'],3)
print, str(0).fld2(3,3)
(2) str = mrd_struct(['a','b','c','d'],['1', '1.', '1.d0', "'1'"],1)
; returns a structure with integer, float, double and string
; fields.
PROCEDURE CALLS:
GETTOK() - needed for virtual machine mode only
MINIMUM IDL VERSION:
V5.3 (uses STRSPLIT)
MODIFICATION HISTORY:
Created by T. McGlynn October, 1994.
Modified by T. McGlynn September, 1995.
Added capability to create substructures so that structure
may contain up to 4096 distinct elements. [This can be
increased by futher iteration of the process used if needed.]
Removed V4.0 reference to common block October 1997
Allowed unlimited number of structure elements if the version
is greater than 5.0. Put back in code to handle prior versions.
The [] will need to be translated back to () for this to
work. T. McGlynn December 15 1998.
Add MRD_NSTRUCT since IDL has mysterious problems compiling
very large structures.
Removed TEMPDIR and OLD_STRUCT keywords W. Landsman October 2003
Alternate pathway without EXECUTE for V6.0 virtual machine, D. Lindler
Removed limit on EXECUTE statement. W. Landsman October 2003
Restore EXECUTE limit (sigh...), added NO_EXECUTE keyword
W. Landsman July 2004
Fix use of STRUCTYP with /NO_EXECUTE W. Landsman June 2005
[Previous]
[Next]
NAME:
MRDFITS
PURPOSE:
Read all standard FITS data types into arrays or structures.
EXPLANATION:
Further information on MRDFITS is available at
http://idlastro.gsfc.nasa.gov/mrdfits.html
CALLING SEQUENCE:
Result = MRDFITS( Filename/FileUnit,[Exten_no/Exten_name, Header],
/FSCALE , /DSCALE , /UNSIGNED,
ALIAS=strarr[2,n], /USE_COLNUM,
/NO_TDIM, ROWS = [a,b,...], $
/POINTER_VAR, /FIXED_VAR, EXTNUM=
RANGE=[a,b], COLUMNS=[a,b,...]), ERROR_ACTION=x,
COMPRESS=comp_prog, STATUS=status, /VERSION )
INPUTS:
Filename = String containing the name of the file to be read or
file number of an open unit. If a unit is specified
if will be left open positioned to read the next HDU.
If the file name ends in .gz (or .Z on Unix systems)
the file will be dynamically decompressed.
FiluUnit = An integer file unit which has already been
opened for input. Data will be read from this
unit and the unit will be left pointing immediately
after the HDU that is read. Thus to read a compressed
file with many HDU's a user might do something like:
lun=fxposit(filename, 3) ; Skip the first three HDU's
repeat begin
thisHDU = mrdfits(lun, 0, hdr, status=status)
... process the HDU ...
endrep until status lt 0
Exten_no= Extension number to be read, 0 for primary array.
Assumed 0 if not specified.
If a unit rather than a filename
is specified in the first argument, this is
the number of HDU's to skip from the current position.
Exten_name - Name of the extension to read (as stored in the EXTNAME
keyword). This is a slightly slower method then specifying
the extension number.
OUTPUTS:
Result = FITS data array or structure constructed from
the designated extension. The format of result depends
upon the type of FITS data read.
Non-group primary array or IMAGE extension:
A simple multidimensional array is returned with the
dimensions given in the NAXISn keywords.
Grouped image data with PCOUNT=0.
As above but with GCOUNT treated as NAXIS(n+1).
Grouped image data with PCOUNT>0.
The data is returned as an array of structures. Each
structure has two elements. The first is a one-dimensional
array of the group parameters, the second is a multidimensional
array as given by the NAXIS2-n keywords.
ASCII and BINARY tables.
The data is returned as a structure with one column for
each field in the table. The names of the columns are
normally taken from the TTYPE keywords (but see USE_COLNUM).
Bit field columns
are stored in byte arrays of the minimum necessary
length. Spaces and invalid characters are replaced by
underscores, and other invalid tag names are converted using
the IDL_VALIDNAME(/CONVERT_ALL) function.
Columns specified as variable length columns are stored
with a dimension equal to the largest actual dimension
used. Extra values in rows are filled with 0's or blanks.
If the size of the variable length column is not
a constant, then an additional column is created giving the
size used in the current row. This additional column will
have a tag name of the form L#_"colname" where # is the column
number and colname is the column name of the variable length
column. If the length of each element of a variable length
column is 0 then the column is deleted.
OPTIONAL OUTPUT:
Header = String array containing the header from the FITS extension.
OPTIONAL INPUT KEYWORDS:
ALIAS The keyword allows the user to specify the column names
to be created when reading FITS data. The value of
this keyword should be a 2xn string array. The first
value of each pair of strings should be the desired
tag name for the IDL column. The second should be
the FITS TTYPE value. Note that there are restrictions
on valid tag names. The order of the ALIAS keyword
is compatible with MWRFITS.
COLUMNS - This keyword allows the user to specify that only a
subset of columns is to be returned. The columns
may be specified either as number 1,... n or by
name or some combination of these two.
If USE_COLNUM is specified names should be C1,...Cn.
The use of this keyword will not save time or internal
memory since the extraction of specified columns
is done after all columns have been retrieved from the
FITS file.
COMPRESS - This keyword allows the user to specify a
decompression program to use to decompress a file that
will not be automatically recognized based upon
the file name.
/DSCALE - As with FSCALE except that the resulting data is
stored in doubles.
ERROR_ACTION - Set the on_error action to this value (defaults
to 2).
/FIXED_VAR- Translate variable length columns into fixed length columns
and provide a length column for truly varying columns.
This was only behavior prior to V2.5 for MRDFITS and remains
the default (see /POINTER_VAR)
/FSCALE - If present and non-zero then scale data to float
numbers for arrays and columns which have either
non-zero offset or non-unity scale.
If scaling parameters are applied, then the corresponding
FITS scaling keywords will be modified.
NO_TDIM - Disable processing of TDIM keywords. If NO_TDIM
is specified MRDFITS will ignore TDIM keywords in
binary tables.
/POINTER_VAR- Use pointer arrays for variable length columns.
In addition to changing the format in which
variable length arrays are stored, if the pointer_var
keyword is set to any value other than 1 this also disables
the deletion of variable length columns. (See /FIXED_VAR)
Note that because pointers may be present in the output
structure, the user is responsible for memory management
when deleting or reassigning the structure (e.g. use HEAP_FREE
first).
RANGE - A scalar or two element vector giving the start
and end rows to be retrieved. For ASCII and BINARY
tables this specifies the row number. For GROUPed data
this will specify the groups. For array images, this
refers to the last non-unity index in the array. E.g.,
for a 3 D image with NAXIS* values = [100,100,1], the
range may be specified as 0:99, since the last axis
is suppressed. Note that the range uses IDL indexing
So that the first row is row 0.
If only a single value, x, is given in the range,
the range is assumed to be [0,x-1].
ROWS - A scalar or vector specifying a specific row or rows to read
(first row is 0). For example to read rows 0,
12 and 23 only, set ROWS=[0,12,23]. Valid for images, ASCII
and binary tables, but not GROUPed data. For images
the row numbers refer to the last non-unity index in the array.
Cannot be used at the same time as the RANGE keyword
/SILENT - Suppress informative messages.
STRUCTYP - The structyp keyword specifies the name to be used
for the structure defined when reading ASCII or binary
tables. Generally users will not be able to conveniently
combine data from multiple files unless the STRUCTYP
parameter is specified. An error will occur if the
user specifies the same value for the STRUCTYP keyword
in calls to MRDFITS in the same IDL session for extensions
which have different structures.
/UNSIGNED - For integer data with appropriate zero points and scales
read the data into unsigned integer arrays.
/USE_COLNUM - When creating column names for binary and ASCII tables
MRDFITS attempts to use the appropriate TTYPE keyword
values. If USE_COLNUM is specified and non-zero then
column names will be generated as 'C1, C2, ... 'Cn'
for the number of columns in the table.
/VERSION Print the current version number
OPTIONAL OUTPUT KEYWORDS:
EXTNUM - the number of the extension actually read. Useful if the
user specified the extension by name.
STATUS - A integer status indicating success or failure of
the request. A status of >=0 indicates a successful read.
Currently
0 -> successful completion
-1 -> error
-2 -> end of file
CALLED BY:
ATV, CH_READ_FITS, Energy_res [2], FITS CLASS DEFINITION, FITS2MAP [1]
FITS2MAP [2], FITSFILE__DEFINE [2], FITS__DEFINE, FLUX_NRH2, FOPEN_STD_SOHO
FOPEN_YOHKOH, GET_FITS_INSTR, GFITS_R, HESSI FRAMEWORK TEMPLATE CLASS [2]
HESSI FRAMEWORK TEMPLATE CLASS [3], HESSI Read lookup table, HFITS__DEFINE
HSI_DRM_MOD CLASS, HSI_DRM_MOD_CONTROL__DEFINE, HSI_FITS2MAP [1]
HSI_QLOOK_SUMMARY_PAGE__DEFINE, INTGCOMP_NRH2, NRHR, NRHRCAL, NRHR_CAL
NRH_FLUXASCI, NRH_HSI_FITS, NRH_PLOTF, NRH_PLOTI, NRH_SOURCEASCI, OCC_FROM_FITS
RD_STDFITS, READ_DISCLA_FITS, READ_FLUX, READ_HXRS_FITS [1], READ_HXRS_FITS [2]
READ_HXRS_FITS [3], READ_NRH, Radio Spectrogram FITS File reader
Radiospectrogram FITS File reader [2], Read_mat_xcom, SPEX_READ_FIT_RESULTS
SPEX__DEFINE, SUN_IMAGE, XSM_PREP, XSM_VALID, callisto_spg_recalibrate, fits2rm
fits2spectrum, fitsgen, hsi_break_srm, hsi_default_resolutions
hsi_default_tailfracs, hsi_filedb_read [1], hsi_filedb_read [2]
hsi_get_e_edges [1], hsi_image_fitsread, hsi_lambda_vs_t, hsi_qlook__define
hxrs_fits2drm [1], hxrs_fits2drm [2], hxrs_fits2drm [3], mrdfits_spectra
mxfread, phoenix_filedb_get, phoenix_spg_recalibrate, rd_fits_ext
rd_trace_i0 [1], rd_trace_i0 [2], read_hessi_4_ospex_params
spex_hessi_fits2drm, xsm_rd_fits_ext
EXAMPLES:
(1) Read a FITS primary array:
a = mrdfits('TEST.FITS') or
a = mrdfits('TEST.FITS', 0, header)
The second example also retrieves header information.
(2) Read rows 10-100 of the second extension of a FITS file.
a = mrdfits('TEST.FITS', 2, header, range=[10,100])
(3) Read a table and ask that any scalings be applied and the
scaled data be converted to doubles. Use simple column names,
suppress outputs.
a = mrdfits('TEST.FITS', 1, /dscale, /use_colnum, /silent)
(4) Read rows 3, 34 and 52 of a binary table and request that
variable length columns be stored as a pointer variable in the
output structure
a = mrdfits('TEST.FITS',1,rows=[3,34,52],/POINTER)
CALLS: ***
FXADDPAR [1], FXADDPAR [2], FXMOVE [1], FXMOVE [2], FXPAR [1], FXPAR [2]
FXPOSIT [1], FXPOSIT [2], GETTOK [1], GETTOK [2], GETTOK [3], GETTOK [4]
IEEE_TO_HOST [1], IEEE_TO_HOST [2], IEEE_TO_HOST [3], IEEE_TO_HOST [4]
IS_IEEE_BIG [1], IS_IEEE_BIG [2], MATCH [1], MATCH [2], MATCH [3], MRD_ASCII
MRD_ATYPE, MRD_AXES_TRUNC, MRD_CHKFN, MRD_CHKUNSIGNED, MRD_COLUMNS, MRD_DOFF
MRD_DOFN, MRD_FIXCOLUMN, MRD_FXPAR, MRD_HREAD [1], MRD_HREAD [2], MRD_IMAGE
MRD_PTRSCALE, MRD_READ_ASCII, MRD_READ_HEAP, MRD_READ_IMAGE, MRD_READ_TABLE
MRD_SCALE, MRD_SKIP [1], MRD_SKIP [2], MRD_STRUCT [1], MRD_STRUCT [2], MRD_TABLE
MRD_TDIM, MRD_UNSIGNEDTYPE, MRD_UNSIGNED_OFFSET, MRD_VARCOLUMN, MRD_VERSION
VALID_NUM [1], VALID_NUM [2], VALID_NUM [3]
RESTRICTIONS:
(1) Cannot handle data in non-standard FITS formats.
(2) Doesn't do anything with BLANK or NULL values or
NaN's. They are just read in. They may be scaled
if scaling is applied.
NOTES:
This multiple format FITS reader is designed to provide a
single, simple interface to reading all common types of FITS data.
MRDFITS DOES NOT scale data by default. The FSCALE or DSCALE
parameters must be used.
MRDFITS support 64 bit integer data types, which are tentatively
included in the FITS standard.
http://fits.gsfc.nasa.gov/fits_64bit.html
PROCEDURES USED:
The following procedures are contained in the main MRDFITS program.
MRD_IMAGE -- Generate array/structure for images.
MRD_READ_IMAGE -- Read image data.
MRD_ASCII -- Generate structure for ASCII tables.
MRD_READ_ASCII -- Read an ASCII table.
MRD_TABLE -- Generate structure for Binary tables.
MRD_READ_TABLE -- Read binary table info.
MRD_READ_HEAP -- Read variable length record info.
MRD_SCALE -- Apply scaling to data.
MRD_COLUMNS -- Extract columns.
Other ASTRON Library routines used
FXPAR(), FXADDPAR, IEEE_TO_HOST, FXPOSIT, FXMOVE(), IS_IEEE_BIG()
MRD_STRUCT(), MRD_SKIP
MODIfICATION HISTORY:
V1.0 November 9, 1994 ---- Initial release.
Creator: Thomas A. McGlynn
V1.1 January 20, 1995 T.A. McGlynn
Fixed bug in variable length records.
Added TDIM support -- new routine mrd_tdim in MRD_TABLE.
V1.2
Added support for dynamic decompression of files.
Fixed further bugs in variable length record handling.
V1.2a
Added NO_TDIM keyword to turn off TDIM processing for
those who don't want it.
Bug fixes: Handle one row tables correctly, use BZERO rather than
BOFFSET. Fix error in scaling of images.
V1.2b
Changed MRD_HREAD to handle null characters in headers.
V2.0 April 1, 1996
-Handles FITS tables with an arbitrary number of columns.
-Substantial changes to MRD_STRUCT to allow the use of
substructures when more than 127 columns are desired.
-All references to table columns are now made through the
functions MRD_GETC and MRD_PUTC. See description above.
-Use of SILENT will now eliminate compilation messages for
temporary functions.
-Bugs in handling of variable length columns with either
a single row in the table or a maximum of a single element
in the column fixed.
-Added support for DCOMPLEX numbers in binary tables (M formats) for
IDL versions above 4.0.
-Created regression test procedure to check in new versions.
-Added error_action parameter to allow user to specify
on_error action. This should allow better interaction with
new CHECK facility. ON_ERROR statements deleted from
most called routines.
- Modified MRDFITS to read in headers containing null characters
with a warning message printed.
V2.0a April 16, 1996
- Added IS_IEEE_BIG() checks (and routine) so that we don't
worry about IEEE to host conversions if the machine's native
format is IEEE Big-endian.
V2.1 August 24, 1996
- Use resolve_routine for dynamically defined functions
for versions > 4.0
- Fix some processing in random groups format.
- Handle cases where the data segment is--legally--null.
In this case MRDFITS returns a scalar 0.
- Fix bugs with the values for BSCALE and BZERO (and PSCAL and
PZERO) parameters set by MRDFITS.
V2.1a April 24, 1997 Handle binary tables with zero length columns
V2.1b May 13,1997 Remove whitespace from replicate structure definition
V2.1c May 28,1997 Less strict parsing of XTENSION keyword
V2.1d June 16, 1997 Fixed problem for >32767 entries introduced 24-Apr
V2.1e Aug 12, 1997 Fixed problem handling double complex arrays
V2.1f Oct 22, 1997 IDL reserved words can't be structure tag names
V2.1g Nov 24, 1997 Handle XTENSION keywords with extra blanks.
V2.1h Jul 26, 1998 More flexible parsing of TFORM characters
V2.2 Dec 14, 1998 Allow fields with longer names for
later versions of IDL.
Fix handling of arrays in scaling routines.
Allow >128 fields in structures for IDL >4.0
Use more efficient structure copying for
IDL>5.0
V2.2b June 17, 1999 Fix bug in handling case where
all variable length columns are deleted
because they are empty.
V2.3 March 7, 2000 Allow user to supply file handle rather
than file name.
Added status field.
Now needs FXMOVE routine
V2.3b April 4, 2000
Added compress option (from D. Palmer)
V2.4 July 4, 2000 Added STATUS=-1 for "File access error" (Zarro/GSFC)
V2.4a May 2, 2001 Trim binary format string (W. Landsman)
V2.5 December 5, 2001 Add unsigned, alias, 64 bit integers. version, $
/pointer_val, /fixed_var.
V2.5a Fix problem when both the first and the last character
in a TTYPEnn value are invalid structure tag characters
V2.6 February 15, 2002 Fix error in handling unsigned numbers, $
and 64 bit unsigneds. (Thanks to Stephane Beland)
V2.6a September 2, 2002 Fix possible conflicting data structure for
variable length arrays (W. Landsman)
V2.7 July, 2003 Added Rows keyword (W. Landsman)
V2.7a September 2003 Convert dimensions to long64 to handle huge files
V2.8 October 2003 Use IDL_VALIDNAME() function to ensure valid tag names
Removed OLD_STRUCT and TEMPDIR keywords W. Landsman
V2.9 February 2004 Added internal MRD_FXPAR procedure for faster
processing of binary table headers E. Sheldon
V2.9a March 2004 Restore ability to read empty binary table W. Landsman
Swallow binary tables with more columns than given in TFIELDS
V2.9b Fix to ensure order of TFORMn doesn't matter
V2.9c Check if extra degenerate NAXISn keyword are present W.L. Oct 2004
V2.9d Propagate /SILENT to MRD_HREAD, more LONG64 casting W. L. Dec 2004
V2.9e Add typarr[good] to fix a problem reading zero-length columns
A.Csillaghy, csillag@ssl.berkeley.edu (RHESSI)
V2.9f Fix problem with string variable binary tables, possible math
overflow on non-IEEE machines WL Feb. 2005
V2.9g Fix problem when setting /USE_COLNUM WL Feb. 2005
V2.10 Use faster keywords to BYTEORDER WL May 2006
V2.11 Add ON_IOERROR, CATCH, and STATUS keyword to MRD_READ_IMAGE to
trap EOF in compressed files DZ Also fix handling of unsigned
images when BSCALE not present K Chu/WL June 2006
V2.12 Allow extension to be specified by name, added EXTNUM keyword
WL December 2006
[Previous]
[Next]
NAME:
MRDFITS
PURPOSE:
Read all standard FITS data types into arrays or structures.
EXPLANATION:
Further information on MRDFITS is available at
http://idlastro.gsfc.nasa.gov/mrdfits.html
CALLING SEQUENCE:
Result = MRDFITS( Filename/FileUnit,[Exten_no/Exten_name, Header],
/FSCALE , /DSCALE , /UNSIGNED,
ALIAS=strarr[2,n], /USE_COLNUM,
/NO_TDIM, ROWS = [a,b,...], $
/POINTER_VAR, /FIXED_VAR, EXTNUM=
RANGE=[a,b], COLUMNS=[a,b,...]), ERROR_ACTION=x,
COMPRESS=comp_prog, STATUS=status, /VERSION )
INPUTS:
Filename = String containing the name of the file to be read or
file number of an open unit. If a unit is specified
if will be left open positioned to read the next HDU.
If the file name ends in .gz (or .Z on Unix systems)
the file will be dynamically decompressed.
FiluUnit = An integer file unit which has already been
opened for input. Data will be read from this
unit and the unit will be left pointing immediately
after the HDU that is read. Thus to read a compressed
file with many HDU's a user might do something like:
lun=fxposit(filename, 3) ; Skip the first three HDU's
repeat begin
thisHDU = mrdfits(lun, 0, hdr, status=status)
... process the HDU ...
endrep until status lt 0
Exten_no= Extension number to be read, 0 for primary array.
Assumed 0 if not specified.
If a unit rather than a filename
is specified in the first argument, this is
the number of HDU's to skip from the current position.
Exten_name - Name of the extension to read (as stored in the EXTNAME
keyword). This is a slightly slower method then specifying
the extension number.
OUTPUTS:
Result = FITS data array or structure constructed from
the designated extension. The format of result depends
upon the type of FITS data read.
Non-group primary array or IMAGE extension:
A simple multidimensional array is returned with the
dimensions given in the NAXISn keywords.
Grouped image data with PCOUNT=0.
As above but with GCOUNT treated as NAXIS(n+1).
Grouped image data with PCOUNT>0.
The data is returned as an array of structures. Each
structure has two elements. The first is a one-dimensional
array of the group parameters, the second is a multidimensional
array as given by the NAXIS2-n keywords.
ASCII and BINARY tables.
The data is returned as a structure with one column for
each field in the table. The names of the columns are
normally taken from the TTYPE keywords (but see USE_COLNUM).
Bit field columns
are stored in byte arrays of the minimum necessary
length. Spaces and invalid characters are replaced by
underscores, and other invalid tag names are converted using
the IDL_VALIDNAME(/CONVERT_ALL) function.
Columns specified as variable length columns are stored
with a dimension equal to the largest actual dimension
used. Extra values in rows are filled with 0's or blanks.
If the size of the variable length column is not
a constant, then an additional column is created giving the
size used in the current row. This additional column will
have a tag name of the form L#_"colname" where # is the column
number and colname is the column name of the variable length
column. If the length of each element of a variable length
column is 0 then the column is deleted.
OPTIONAL OUTPUT:
Header = String array containing the header from the FITS extension.
OPTIONAL INPUT KEYWORDS:
ALIAS The keyword allows the user to specify the column names
to be created when reading FITS data. The value of
this keyword should be a 2xn string array. The first
value of each pair of strings should be the desired
tag name for the IDL column. The second should be
the FITS TTYPE value. Note that there are restrictions
on valid tag names. The order of the ALIAS keyword
is compatible with MWRFITS.
COLUMNS - This keyword allows the user to specify that only a
subset of columns is to be returned. The columns
may be specified either as number 1,... n or by
name or some combination of these two.
If USE_COLNUM is specified names should be C1,...Cn.
The use of this keyword will not save time or internal
memory since the extraction of specified columns
is done after all columns have been retrieved from the
FITS file.
COMPRESS - This keyword allows the user to specify a
decompression program to use to decompress a file that
will not be automatically recognized based upon
the file name.
/DSCALE - As with FSCALE except that the resulting data is
stored in doubles.
ERROR_ACTION - Set the on_error action to this value (defaults
to 2).
/FIXED_VAR- Translate variable length columns into fixed length columns
and provide a length column for truly varying columns.
This was only behavior prior to V2.5 for MRDFITS and remains
the default (see /POINTER_VAR)
/FSCALE - If present and non-zero then scale data to float
numbers for arrays and columns which have either
non-zero offset or non-unity scale.
If scaling parameters are applied, then the corresponding
FITS scaling keywords will be modified.
NO_TDIM - Disable processing of TDIM keywords. If NO_TDIM
is specified MRDFITS will ignore TDIM keywords in
binary tables.
/POINTER_VAR- Use pointer arrays for variable length columns.
In addition to changing the format in which
variable length arrays are stored, if the pointer_var
keyword is set to any value other than 1 this also disables
the deletion of variable length columns. (See /FIXED_VAR)
Note that because pointers may be present in the output
structure, the user is responsible for memory management
when deleting or reassigning the structure (e.g. use HEAP_FREE
first).
RANGE - A scalar or two element vector giving the start
and end rows to be retrieved. For ASCII and BINARY
tables this specifies the row number. For GROUPed data
this will specify the groups. For array images, this
refers to the last non-unity index in the array. E.g.,
for a 3 D image with NAXIS* values = [100,100,1], the
range may be specified as 0:99, since the last axis
is suppressed. Note that the range uses IDL indexing
So that the first row is row 0.
If only a single value, x, is given in the range,
the range is assumed to be [0,x-1].
ROWS - A scalar or vector specifying a specific row or rows to read
(first row is 0). For example to read rows 0,
12 and 23 only, set ROWS=[0,12,23]. Valid for images, ASCII
and binary tables, but not GROUPed data. For images
the row numbers refer to the last non-unity index in the array.
Cannot be used at the same time as the RANGE keyword
/SILENT - Suppress informative messages.
STRUCTYP - The structyp keyword specifies the name to be used
for the structure defined when reading ASCII or binary
tables. Generally users will not be able to conveniently
combine data from multiple files unless the STRUCTYP
parameter is specified. An error will occur if the
user specifies the same value for the STRUCTYP keyword
in calls to MRDFITS in the same IDL session for extensions
which have different structures.
/UNSIGNED - For integer data with appropriate zero points and scales
read the data into unsigned integer arrays.
/USE_COLNUM - When creating column names for binary and ASCII tables
MRDFITS attempts to use the appropriate TTYPE keyword
values. If USE_COLNUM is specified and non-zero then
column names will be generated as 'C1, C2, ... 'Cn'
for the number of columns in the table.
/VERSION Print the current version number
OPTIONAL OUTPUT KEYWORDS:
EXTNUM - the number of the extension actually read. Useful if the
user specified the extension by name.
STATUS - A integer status indicating success or failure of
the request. A status of >=0 indicates a successful read.
Currently
0 -> successful completion
-1 -> error
-2 -> end of file
CALLED BY:
ATV, CH_READ_FITS, Energy_res [2], FITS CLASS DEFINITION, FITS2MAP [1]
FITS2MAP [2], FITSFILE__DEFINE [2], FITS__DEFINE, FLUX_NRH2, FOPEN_STD_SOHO
FOPEN_YOHKOH, GET_FITS_INSTR, GFITS_R, HESSI FRAMEWORK TEMPLATE CLASS [2]
HESSI FRAMEWORK TEMPLATE CLASS [3], HESSI Read lookup table, HFITS__DEFINE
HSI_DRM_MOD CLASS, HSI_DRM_MOD_CONTROL__DEFINE, HSI_FITS2MAP [1]
HSI_QLOOK_SUMMARY_PAGE__DEFINE, INTGCOMP_NRH2, NRHR, NRHRCAL, NRHR_CAL
NRH_FLUXASCI, NRH_HSI_FITS, NRH_PLOTF, NRH_PLOTI, NRH_SOURCEASCI, OCC_FROM_FITS
RD_STDFITS, READ_DISCLA_FITS, READ_FLUX, READ_HXRS_FITS [1], READ_HXRS_FITS [2]
READ_HXRS_FITS [3], READ_NRH, Radio Spectrogram FITS File reader
Radiospectrogram FITS File reader [2], Read_mat_xcom, SPEX_READ_FIT_RESULTS
SPEX__DEFINE, SUN_IMAGE, XSM_PREP, XSM_VALID, callisto_spg_recalibrate, fits2rm
fits2spectrum, fitsgen, hsi_break_srm, hsi_default_resolutions
hsi_default_tailfracs, hsi_filedb_read [1], hsi_filedb_read [2]
hsi_get_e_edges [1], hsi_image_fitsread, hsi_lambda_vs_t, hsi_qlook__define
hxrs_fits2drm [1], hxrs_fits2drm [2], hxrs_fits2drm [3], mrdfits_spectra
mxfread, phoenix_filedb_get, phoenix_spg_recalibrate, rd_fits_ext
rd_trace_i0 [1], rd_trace_i0 [2], read_hessi_4_ospex_params
spex_hessi_fits2drm, xsm_rd_fits_ext
EXAMPLES:
(1) Read a FITS primary array:
a = mrdfits('TEST.FITS') or
a = mrdfits('TEST.FITS', 0, header)
The second example also retrieves header information.
(2) Read rows 10-100 of the second extension of a FITS file.
a = mrdfits('TEST.FITS', 2, header, range=[10,100])
(3) Read a table and ask that any scalings be applied and the
scaled data be converted to doubles. Use simple column names,
suppress outputs.
a = mrdfits('TEST.FITS', 1, /dscale, /use_colnum, /silent)
(4) Read rows 3, 34 and 52 of a binary table and request that
variable length columns be stored as a pointer variable in the
output structure
a = mrdfits('TEST.FITS',1,rows=[3,34,52],/POINTER)
CALLS: ***
FXADDPAR [1], FXADDPAR [2], FXMOVE [1], FXMOVE [2], FXPAR [1], FXPAR [2]
FXPOSIT [1], FXPOSIT [2], GETTOK [1], GETTOK [2], GETTOK [3], GETTOK [4]
IEEE_TO_HOST [1], IEEE_TO_HOST [2], IEEE_TO_HOST [3], IEEE_TO_HOST [4]
IS_IEEE_BIG [1], IS_IEEE_BIG [2], MATCH [1], MATCH [2], MATCH [3], MRD_ASCII
MRD_ATYPE, MRD_AXES_TRUNC, MRD_CHKFN, MRD_CHKUNSIGNED, MRD_COLUMNS, MRD_DOFF
MRD_DOFN, MRD_FIXCOLUMN, MRD_FXPAR, MRD_HREAD [1], MRD_HREAD [2], MRD_IMAGE
MRD_PTRSCALE, MRD_READ_ASCII, MRD_READ_HEAP, MRD_READ_IMAGE, MRD_READ_TABLE
MRD_SCALE, MRD_SKIP [1], MRD_SKIP [2], MRD_STRUCT [1], MRD_STRUCT [2], MRD_TABLE
MRD_TDIM, MRD_UNSIGNEDTYPE, MRD_UNSIGNED_OFFSET, MRD_VARCOLUMN, MRD_VERSION
VALID_NUM [1], VALID_NUM [2], VALID_NUM [3]
RESTRICTIONS:
(1) Cannot handle data in non-standard FITS formats.
(2) Doesn't do anything with BLANK or NULL values or
NaN's. They are just read in. They may be scaled
if scaling is applied.
NOTES:
This multiple format FITS reader is designed to provide a
single, simple interface to reading all common types of FITS data.
MRDFITS DOES NOT scale data by default. The FSCALE or DSCALE
parameters must be used.
MRDFITS support 64 bit integer data types, which are tentatively
included in the FITS standard.
http://fits.gsfc.nasa.gov/fits_64bit.html
PROCEDURES USED:
The following procedures are contained in the main MRDFITS program.
MRD_IMAGE -- Generate array/structure for images.
MRD_READ_IMAGE -- Read image data.
MRD_ASCII -- Generate structure for ASCII tables.
MRD_READ_ASCII -- Read an ASCII table.
MRD_TABLE -- Generate structure for Binary tables.
MRD_READ_TABLE -- Read binary table info.
MRD_READ_HEAP -- Read variable length record info.
MRD_SCALE -- Apply scaling to data.
MRD_COLUMNS -- Extract columns.
Other ASTRON Library routines used
FXPAR(), FXADDPAR, IEEE_TO_HOST, FXPOSIT, FXMOVE(), IS_IEEE_BIG()
MRD_STRUCT(), MRD_SKIP
MODIfICATION HISTORY:
V1.0 November 9, 1994 ---- Initial release.
Creator: Thomas A. McGlynn
V1.1 January 20, 1995 T.A. McGlynn
Fixed bug in variable length records.
Added TDIM support -- new routine mrd_tdim in MRD_TABLE.
V1.2
Added support for dynamic decompression of files.
Fixed further bugs in variable length record handling.
V1.2a
Added NO_TDIM keyword to turn off TDIM processing for
those who don't want it.
Bug fixes: Handle one row tables correctly, use BZERO rather than
BOFFSET. Fix error in scaling of images.
V1.2b
Changed MRD_HREAD to handle null characters in headers.
V2.0 April 1, 1996
-Handles FITS tables with an arbitrary number of columns.
-Substantial changes to MRD_STRUCT to allow the use of
substructures when more than 127 columns are desired.
-All references to table columns are now made through the
functions MRD_GETC and MRD_PUTC. See description above.
-Use of SILENT will now eliminate compilation messages for
temporary functions.
-Bugs in handling of variable length columns with either
a single row in the table or a maximum of a single element
in the column fixed.
-Added support for DCOMPLEX numbers in binary tables (M formats) for
IDL versions above 4.0.
-Created regression test procedure to check in new versions.
-Added error_action parameter to allow user to specify
on_error action. This should allow better interaction with
new CHECK facility. ON_ERROR statements deleted from
most called routines.
- Modified MRDFITS to read in headers containing null characters
with a warning message printed.
V2.0a April 16, 1996
- Added IS_IEEE_BIG() checks (and routine) so that we don't
worry about IEEE to host conversions if the machine's native
format is IEEE Big-endian.
V2.1 August 24, 1996
- Use resolve_routine for dynamically defined functions
for versions > 4.0
- Fix some processing in random groups format.
- Handle cases where the data segment is--legally--null.
In this case MRDFITS returns a scalar 0.
- Fix bugs with the values for BSCALE and BZERO (and PSCAL and
PZERO) parameters set by MRDFITS.
V2.1a April 24, 1997 Handle binary tables with zero length columns
V2.1b May 13,1997 Remove whitespace from replicate structure definition
V2.1c May 28,1997 Less strict parsing of XTENSION keyword
V2.1d June 16, 1997 Fixed problem for >32767 entries introduced 24-Apr
V2.1e Aug 12, 1997 Fixed problem handling double complex arrays
V2.1f Oct 22, 1997 IDL reserved words can't be structure tag names
V2.1g Nov 24, 1997 Handle XTENSION keywords with extra blanks.
V2.1h Jul 26, 1998 More flexible parsing of TFORM characters
V2.2 Dec 14, 1998 Allow fields with longer names for
later versions of IDL.
Fix handling of arrays in scaling routines.
Allow >128 fields in structures for IDL >4.0
Use more efficient structure copying for
IDL>5.0
V2.2b June 17, 1999 Fix bug in handling case where
all variable length columns are deleted
because they are empty.
V2.3 March 7, 2000 Allow user to supply file handle rather
than file name.
Added status field.
Now needs FXMOVE routine
V2.3b April 4, 2000
Added compress option (from D. Palmer)
V2.4 July 4, 2000 Added STATUS=-1 for "File access error" (Zarro/GSFC)
V2.4a May 2, 2001 Trim binary format string (W. Landsman)
V2.5 December 5, 2001 Add unsigned, alias, 64 bit integers. version, $
/pointer_val, /fixed_var.
V2.5a Fix problem when both the first and the last character
in a TTYPEnn value are invalid structure tag characters
V2.6 February 15, 2002 Fix error in handling unsigned numbers, $
and 64 bit unsigneds. (Thanks to Stephane Beland)
V2.6a September 2, 2002 Fix possible conflicting data structure for
variable length arrays (W. Landsman)
V2.7 July, 2003 Added Rows keyword (W. Landsman)
V2.7a September 2003 Convert dimensions to long64 to handle huge files
V2.8 October 2003 Use IDL_VALIDNAME() function to ensure valid tag names
Removed OLD_STRUCT and TEMPDIR keywords W. Landsman
V2.9 February 2004 Added internal MRD_FXPAR procedure for faster
processing of binary table headers E. Sheldon
V2.9a March 2004 Restore ability to read empty binary table W. Landsman
Swallow binary tables with more columns than given in TFIELDS
V2.9b Fix to ensure order of TFORMn doesn't matter
V2.9c Check if extra degenerate NAXISn keyword are present W.L. Oct 2004
V2.9d Propagate /SILENT to MRD_HREAD, more LONG64 casting W. L. Dec 2004
V2.9e Add typarr[good] to fix a problem reading zero-length columns
A.Csillaghy, csillag@ssl.berkeley.edu (RHESSI)
V2.9f Fix problem with string variable binary tables, possible math
overflow on non-IEEE machines WL Feb. 2005
V2.9g Fix problem when setting /USE_COLNUM WL Feb. 2005
V2.10 Use faster keywords to BYTEORDER WL May 2006
V2.11 Add ON_IOERROR, CATCH, and STATUS keyword to MRD_READ_IMAGE to
trap EOF in compressed files DZ Also fix handling of unsigned
images when BSCALE not present K Chu/WL June 2006
V2.12 Allow extension to be specified by name, added EXTNUM keyword
WL December 2006
[Previous]
[Next]
Name: mreadfits
Purpose: read multiple FITs into data cube, header-> IDL structure array
Input Parameters:
files - fits files to read
Keyword Parameters:
strtemplate - template structure for read (reccommended, not required)
nodata - switch, if set, dont read the data (return only structures)
header (output) - last fits header as string array
outsize - 1 or 2 element array ([nx,ny]) specifying the output size
of data array - default is [max(NAXIS1),max(NAXIS2)]
add_standard - if set and NO template supplied, add some standard tags
comments (output) - concatentation of all COMMENT
ccnts (output) - counts (pointers) to map files -> COMMENT
history (output) - concatentation of all HISTORY
hcnts (output) - counts (pointers) to map files -> HISTORY
all_keywords (input) - if set, then go through all input file and get
the full list of unique keywords to build the template
structure (rather than from the first file)
silent/quiet(synonyms) - less verbose
Also takes any keywords accepted by FITSHEAD2WCS.
Calling Sequence:
mreadfits, filelist, index [,data , strtemplate=structure, $
outsize=xy, /nodata]
Calling Example:
mreadfits, spartan_files, index, data, strtemp=spartan_struct()
mreadfits, eit_files, index, data, strtemp=eit_struct()
mreadfits,your_files, index, data, strtemp=your_template
mreadfits, files, index, data, outsize=128 ; rebin "on the fly"
mreadfits, eit_files, index [,/nodata] ; Fast (header only)
mreadfits, files, index, /add_standard ; add "SSW standards"
[note: xxx_struct.pro are functions which return template structures
for instrument XXX]
Serving Suggestions:
Leaving off DATA parameter (OR using /nodata keyword) results in
HEADER-ONLY processing for speed.
A useful sequence is:
--------------------------------------------------------------------
IDL> mreadfits, files, index ; headers only->struct
IDL> ss=where(index.xxx ... AND index.yyy... ) ; vector filter
IDL> mreadfits,files(ss),index,data [outsize=xy] ; read desired->3D
--------------------------------------------------------------------
--------------------------------------------------------------------
CALLED BY:
CALC_LOI_ROLL, FITS__DEFINE, Radiospectrogram FITS File reader [1]
fix_decon_pits, fixinate_lasco, mreadfits_header, mreadfits_sxig12, mxf_dset_map
mxf_read_data, mxf_read_header, mxfdset_map, mxfread, rd_mdi [1], rd_mdi [2]
read_eit, read_soon, read_spartan, read_sxt, read_trace, ssw_fs_cat2db
Example:
Mixture of 1024^2 512^2 256^2 128^2 can be read and displayed via:
IDL> mreadfits, files, index, data, outsize=256 ; read 3D (256x256xNN)
IDL> xstepper, data [,get_infox(index) ] ; view 3D cube
--------------------------------------------------------------------
History:
21-Mar-1996 (S.L.Freeland) PROTOTYPE For EIT/SPARTAN originally
23-Mar-1996 (S.L.Freeland) no 'data' parameter implies /nodata
28-apr-1996 (S.L.Freeland) fix doc, add header keyword
21-oct-1996 (S.L.Freeland) allow naxis3 (3D) (see restrictions)
16-jan-1997 (S.L.Freeland) add OUTSIZE keyword and function
27-jan-1997 (S.L.Freeland) avoid problem with 3D introduced on 16-jan
28-jan-1997 (S.L.Freeland) remove restrictions on 2D/3D data combination
24-feb-1997 (S.L.Freeland) use <fitshead2struct> if no template passed
27-feb-1997 (S.L.Freeland) add ADD_STANDARD keyword, documentation
10-apr-1997 (S.L.Freeland) add COMMENTS, CCNTS, HISTORY, HCNTS
(see <mreadfits_info> to map file# -> COMMENT
4-jun-1997 (S.L.Freeland) call <mreadfits_fixup> if required
(adjust some tags for rebinned images)
29-Jul-1997 (C.E.DeForest) Accept one-dimensional data products
(patched call to make_array for the
case where NAXIS2 is 0)
4-Aug-1997 (C.E.DeForest) -Added nocom, nohist, and noscale options.
-fixed repeating-"mreadfits temporary"
bug (removed "mreadfits temporary" lines
-Used "temporary" to dispose of initial-
image array
12-Aug-1997 (C.E.DeForest) -Fixed 1-D array reading (switched
make_array NAXIS2 check from "eq 0"
to "le 0" to handle NAXIS=1 case).
30-Jul-1998 (M.D.Morrison) - Added /ALL_KEYWORDS
18-Aug-1998 S.L.Freeland - add /NOFILL keyword
(pass to fitshead2struct)
04-Aug-1999 J.S.Newmark - change loops indices from INT -> LONG
19-may-2005 S.L.Freeland - add SILENT synonym for QUIET -> readfits
10-Jan-2006 A.Vourlidas - Force reading of headers in
readfits calls for proper treatment
of UINT types (SECCHI images).
17-Feb-2006 W.T.Thompson - Support WCS_STRUCT
CALLS: ***
CONGRID [1], CONGRID [2], CONGRID [3], FITSHEAD2WCS, FXADDPAR [1], FXADDPAR [2]
HEADFITS [1], HEADFITS [2], HEADFITS [3], READFITS [1], READFITS [2], READFITS [3]
TAG_EXIST [1], TAG_EXIST [2], data_chk [1], data_chk [2], fits_interp
fitshead2struct, gt_tagval [1], gt_tagval [2], mreadfits_fixup, totvect
where_arr [1], where_arr [2]
Restrictions:
use of <strtemplate> is STRONGLY RECOMMENDED for consistent output
(and to facilitate downline structure concatenation operations)
Most of the problem is due to non-conforming FITS headers
Improvements to <fitshead2struc> is ongoing which will help to
relieve this "restriction"
[Previous]
[Next]
Name: mreadfits_fixup
Purpose: adjust some standard fields after mreadfits rebinning
Input Parameters:
index (input/output) - structure array (see mreadfits.pro)
data - corresponding data array (post-rebinning)
Output Parameters:
index - fields adjusted for previous rebinning
Calling Sequence:
mreadfits_fixup, index, data [,/loud]
(by the time you read this, it may be called WITHIN mreadfits)
CALLS: ***
STR2ARR [1], STR2ARR [2], TAG_EXIST [1], TAG_EXIST [2], gt_tagval [1]
gt_tagval [2], prstr [1], prstr [2], strjustify, tag_index [1], tag_index [2]
CALLED BY:
eit_proton_summary, mreadfits
History:
4-Jun-1997 - S.L.Freeland
5-Jun-1997 - S.L.Freeland - fix an 'off-by-1' error
5-may-2004 - S.L.Freeladn - relax constraint on all or nothing
[Previous]
[Next]
Name: mreadfits_header
Purpose: 3D FITS -> header structures - mreadfits helper for speed
Input Paramters:
fitsfiles - FITS file list
Output Parameters:
index - vector of header-structures
Keyword Parameters:
only_tags - optional tag list desired subset (for speed!)
Calling Sequence:
IDL> mreadfits_header, fitsfiles, index [,only_tags=taglist]
Calling Examples:
IDL> mreadfits_header,fitsfiles, index ; all FITS -> index.TAGS
IDL> mreadfits_header,fitsfiles, index, $
only_tags='naxis1,naxis2,xcen,ycen,cdelt1,wavelen' ; much faster
IDL> help,index,/str ; show output of above
History:
11-July-2006 - S.L.Freeland - speed up the 3D FITS->structure process
17-July-2006 - S.L.Freeland - add ONLY_TAGS, online beta version
31-July-2006 - S.L.Freeland - in line comment protection...
Notes:
Preliminary tests indicate factor of at least 4 faster
Use of ONLY_TAGS may give another order of magnitude improvement
CALLS: ***
BOX_MESSAGE, DELVARX [1], DELVARX [2], DELVARX [3], DELVARX [4], FILE_EXIST [2]
HEADFITS [1], HEADFITS [2], HEADFITS [3], data_chk [1], data_chk [2], delvarx [5]
file_exist [1], file_exist [3], mreadfits, ssw_strsplit, str_replace [1]
str_replace [2], str_subset, strmids [1], strmids [2]
Restrictions:
escaped tags not yet implemented (DATE-OBS vs DATE_OBS for example)
(coming soon, I'm sure)
COMMENT and HISTORY not yet implemented - check tommorrow
Assumes that all files have same set of FITS keywords (1:1)
After testing, plan to integrate this ~transparently -> mreadfits.pro
[Previous]
[Next]
Name: mreadfits_info
Purpose: extract COMMENT and HISTORY info from mreadfits output variables
Input Parameters:
mrftext - text array (COMMENT or HISTORY) output from mreadfits
counts - corresponding count vector output from mreadfits
which - file number desired
Calling Sequence:
info=mreadfits_info(mfrtest, counts, which)
Calling Example:
mreadfits,files,index,comments=comm, history=hist, ccnts=ccnts, hcnts=hcnts
commentsx=mreadfits_info(comm,ccnts,10) ; comments from file#10
CALLS: ***
MESSASGE, totvect
CALLED BY:
read_eit
History:
11-apr-1997 - S.L.Freeland
[Previous]
[Next]
Name: mreadfits_sxig12
Purpose: read multi sxig12 2D -> 3D index,data w/opt. composite/registration
Input Parameters:
sxifiles - file list - composite option assumes Level One
Keyword Parameters:
composite - (switch) - if set -and- L1 data includes satpix binary
extension, then make the composite
register - (switch) - if set, register,de-roll
column_fix (switch) - if set, apply an (adhoc) column fix algorithm
hotpix_fix (switch) - if set, apply 'ssw_hot_pix' correction
ref_index - optional reference image 'index' for registration
Calling Sequence:
mreadfits_sxig12,sxifiles,index,data[,/reg] [,/composite] [,/column_fix]
[,/hotpix_fix]
History:
9-Apr-2003 - S.L.Freeland - combine a few common functions
30-Nov-2004 - S.L.Freeland - add column_fix keyword+function
6-Jan-2005 - S.L.Freeland - added hotpix_fix keyword+function
30-may-2006 - S.L.Freeland - add REF_INDEX -> ssw_register
Calls: ***
BOX_MESSAGE, CONCAT_STRUCT, SSW_HOT_PIX, SSW_REGISTER, SXIG12_READ_ONE [1]
SXIG12_READ_ONE [2], data_chk [1], data_chk [2], get_infox, get_logenv [1]
get_logenv [2], gt_tagval [1], gt_tagval [2], mreadfits, update_history
Restrictions: - currently assumes sxig12 in $SSW_INSTR
[Previous]
[Next]
Name: mreadfits_urls
Purpose: read one/multiple FITS urls -> "index,data" via sockets
Input Parameters:
fitsurls - list of one or more fits file urls
Output Parameters:
index [,data] - ssw standards: index->FITS header as structure vector
data ->2D or 3D data
Keyword Parameters:
server - desired server (default derived from FITSURLs input)
gateway - (switch) if server/fitsurls are via gateway
status (output) - boolean vector of read success (1:1 w/fitsurls) - read ok?
success (output) - boolean scalar - 1 if all reads ok, 0 if at least one problem
Calling Examples:
mreadfits_urls,fitsurls, index [,server=server] [,/gateway] ; header only->index
mreadfits_urls,fitsurls, index, data ; headers+data
Calling Context/Example : (sxi multi image example )
IDL> sxiurls=sxi_files('1-dec-2001 02:20','1-dec-2001 02:50',/ngdc,/full) ; time->urls
IDL> mreadfits_urls,sxiurls,index,server=sxi_server(),/GATEWAY,/VERBOSE ; headers ->index
IDL> help,sxiurls,index ; show what I got
SXIURLS STRING = Array[32]
INDEX STRUCT = -> MS_097097004001 Array[32] ; header/struct vector
IDL> more,get_infox(index,'date_obs,exptime,wavelnth,crpix1,crpix2') ; index summaries
2001-12-01T02:19:14.004 3.0005 OPEN 224.0391 260.5744 ; (get_infox.pro)
2001-12-01T02:20:00.865 0.0155 OPEN 222.9005 259.9301
2001-12-01T02:21:15.507 3.0005 P_MED_A 221.9841 260.8560
2001-12-01T02:22:02.352 0.0255 P_MED_A 221.6006 261.2311
(...etc)
; filter on above index, and read 3D subset
IDL> ss=where(index.exptime gt 2 and index.wavelnth eq 'OPEN') ; desired subset
IDL> mreadfits_urls,sxiurls(ss),index,data,server=sxi_server(),/GATE ; now read data
=========== ; (only subset)
IDL> help,index,data ; filtered subset -> 3D
INDEX STRUCT = -> MS_097107956001 Array[8]
DATA FLOAT = Array[512, 512, 8]
IDL> more,get_infox(index,'date_obs,exptime,wavelnth,img_mean,img_med') ; check filtered output
2001-12-01T02:19:14.004 3.0005 OPEN 19.0213 9.4895
2001-12-01T02:23:13.629 3.0005 OPEN 18.9202 9.4304
2001-12-01T02:27:13.254 3.0005 OPEN 18.9639 9.4521
2001-12-01T02:31:12.879 3.0005 OPEN 18.9814 9.4751
2001-12-01T02:35:12.503 3.0005 OPEN 18.9521 9.4481
2001-12-01T02:39:15.495 3.0005 OPEN 18.9335 9.4547
2001-12-01T02:43:15.121 3.0005 OPEN 18.9578 9.4715
2001-12-01T02:47:14.746 3.0005 OPEN 18.9019 9.4565
Calls: ***
BOX_MESSAGE, DELVARX [1], DELVARX [2], DELVARX [3], DELVARX [4], GET_TEMP_DIR
SINCE_VERSION [1], SINCE_VERSION [2], data_chk [1], data_chk [2], delvarx [5]
fitshead2struct, ssw_strsplit
History:
14-Jan-2003 - S.L.Freeland ; socket/url analog of 'mreadfits.pro'
21-Jan-2003 - S.L.Freeland header-only socket reads & copy->local options
22-Jan-2003 - S.L.Freeland added STATUS and SUCCESS output indicators
;
Restrictions:
At least for today, assumes all files same naxis1&naxis2
OUTSIZE not yet implemented
Assumes same server for a given call
Use of underlying RSI <socket> implies only Versions >= 5.4
[Previous]
[Next]
PROJECT:
SOHO - CDS
NAME:
MRQCOF
PURPOSE:
Internal routine called by MRQMIN
EXPLANATION:
Used by MRQMIN to evaluate the linearized fitting matrix
ALPHA, and vector ZETA.
CALLING SEQUENCE:
MRQCOF,
INPUTS:
X -- A matrix with M x N elements containing the observation points,
where M is the number of independent variables, and N is the
number of observing points.
Y -- N element vector, value of the fitted function.
SIG -- Measurement error (standard deviation, N elements); If the
measurement errors are not know, they can all be set to 1.
A -- M element vector, initial and final parameters to be solved.
FUNCS -- Name of the user-supplied procedure that returns values of
the model function and its first derivative. Its calling
sequence must be:
FUNCS, x0, a, ymod, dyda
OPTIONAL INPUTS:
None.
OUTPUTS:
ALPHA -- M x M array, curvature matrix
ZETA -- M-element vector, solution of the linear equation associated
with the curvature matrix
CHISQ -- Value of the merit function
OPTIONAL OUTPUTS:
None.
KEYWORD PARAMETERS:
None.
CALLS:
FUNCS, the user-supplied procedure.
CALLED BY:
NL_MRQMIN
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
CATEGORY:
Utility, numerical calculation
PREVIOUS HISTORY:
Written November 10, 1994, by Liyun Wang, GSFC/ARC
MODIFICATION HISTORY:
VERSION:
Version 1, November 10, 1994
[Previous]
[Next]
NAME:
msplot
PURPOSE:
plot multiple data sets on a single set of axes
CALLING SEQUENCE:
msplot, x, a, xsp, ysp, noaxe=noaxe
INPUTS:
x = x array
y = set of n y arrays (*, n)
xsp = x spacing between plots
ysp = y spacing between plots
KEYWORD PARAMETERS:
/norm plot data with each array normalized to unity
/noax don't plot axes
CALLED BY:
map_bsc
MODIFICATION HISTORY:
JTM, Jan 1984 as routine pseudo
JTM, Sep 1992 renamed mplot and added /norm
DMZ, Mar 1993 - beefed up
[Previous]
[Next]
NAME: Multi_draw
PURPOSE:
create multiple draw widgets for display
size of draw areas are variable
INPUT PARAMETERS (positional):
XSIZE - vector of draw widget X dimensions
YSIZE - [optional] - if present, vector of draw widget Y
dimenstion - if absent, all widgets are square
of size = (Xsize x Xsize)
OPTIONAL INPUT PARAMETERS (keyword):
Labels - string array containing label names
Title - title for top level widget - ignored if embedded
OUTPUT:
Function returns structure of type Multi_Draw
contains widget IDs of created widgets for control
CALLS: ***
FMT_TAG [1], FMT_TAG [2], MAKE_STR [1], MAKE_STR [2], XMENU [1], XMENU [2]
CALLED BY:
make_views, xspr [1], xspr [2]
History: slf, 7/91
[Previous]
[Next]
NAME:
MULTI_RESTORE
PURPOSE:
To read the file multiple records created by MULTI_SAVE
CATEGORY:
Data readers
CALLING SEQUENCE:
TO READ AN OPTIONAL HEADER AND THE FIRST RECORD:
record=(MULTI_RESTORE,lun,file=file,/new [,header=header][,/close])
the above calling sequence returns the LUN parameter
associated with the new open file, which is ready for reading more records.
TO READ THE NEXT RECORD FROM A FILE OPEN AS INDICATED ABOVE,
AND TO OPTIONALLY CLOSE THE FILE:
record=MULTI_RESTORE(lun,[,/close])
INPUTS:
LUN A named variable to hold the logical file unit
OUTPUTS: RECORD the current record
KEYWORD PARAMETERS:
NEW Set this keyword to read the optional header and the first record
FILE The name of the file to be open for reading.
Must be present when a new file is open for reading.
It is quitely ignored if NEW=0
HEADER Set this keyword to retrieve the optional header, if any.
It is quitely ignored if NEW=0
CLOSE Use this keyword to force closing the file after the record is retrieved.
REFERENCE:
CALLED BY:
MULTI_SAVE
RESTRICTIONS:
First call this routine with NEW keyword set.
DISCLAIMER: This routine is provided as is without any express or implied warranties whatsoever.
COMMENTS:
The user is responsible for closing the file after the records are restore.
You may simply use RESTORE if you only want to restore the self describing header record.
MODIFICATION HISTORY:
Written by: Gelu M. Nita (gnita@njit.edu), October 27, 2006.
[Previous]
[Next]
NAME:
MULTI_SAVE
PURPOSE:
This procedure saves any number of IDL same length records
in a binary file having a self describing XDR header.
CATEGORY:
Data writers
CALLING SEQUENCE:
TO OPEN/REPLACE A FILE AND WRITE AN OPTIONAL HEADER AND THE FIRST RECORD:
MULTI_SAVE,lun,record,file=file,/new [,header=header][,/close]
the above calling sequence returns the LUN parameter
associated with the new open file, which is ready for appending.
TO WRITE A NEW RECORD TO A FILE OPEN AS INDICATED ABOVE,
AND TO OPTIONALLY CLOSE THE FILE:
MULTI_SAVE,lun,record,[,/close]
INPUTS:
LUN A name variable to hold the logical file unit
RECORD The template (first record) or the record to be appended
OUTPUTS:
KEYWORD PARAMETERS:
NEW Set this keyword to create a new file
FILE The name of the file to be created/replaced.
Must be present when creating/replacing a new file.
If the FILE already exists, the file is QUITELY replaced.
The FILE argument is quitely ignored if NEW=0
HEADER Set this keyword to a named structure to be written as a file header
The HEADER argument is quitely ignored if NEW=0
CLOSE Use this keyword to force closing the file after the record is written
XDR Set this keyword to append the extra records in portable XDR format
REFERENCE:
CALLS: ***
MULTI_RESTORE, MULTI_TEST
RESTRICTIONS:
First call this routine with NEW keyword set.
The template record CANNOT contain POINTERS or STRINGS.
However, the optional HEADER argument has no data type restriction.
DISCLAIMER: This routine is provided as is without any express or implied warranties whatsoever.
COMMENTS:
ALL RECORDS MUST HAVE THE SAME LENGTH
The user is responsible for checking if an already existing file would be replaced.
The user is responsible for closing the file after all records are written.
Use MULTI_RESTORE to read all records saved by this routine
You may simply use RESTORE if you only want to restore the self describing header record.
MODIFICATION HISTORY:
Written by: Gelu M. Nita (gnita@njit.edu), October 27, 2006.
[Previous]
[Next]
NAME:
MULTIPLOT
PURPOSE:
Create multiple plots with shared axes.
EXPLANATION:
This procedure makes a matrix of plots with *SHARED AXES*, either using
parameters passed to multiplot or !p.multi in a non-standard way.
It is good for data with one or two shared axes and retains all the
versatility of the plot commands (e.g. all keywords and log scaling).
The plots are connected with the shared axes, which saves space by
omitting redundant ticklabels and titles. Multiplot does this by
setting !p.position, !x.tickname and !y.tickname automatically.
A call (multiplot,/reset) restores original values.
Note: This method may be superseded by future improvements in !p.multi
by RSI. For now, it's a good way to gang plots together.
CALLING SEQUENCE:
multiplot[pmulti][,/help][,/initialize][,/reset][,/rowmajor]
EXAMPLES:
multiplot,/help ; print this header.
; Then copy & paste, from your xterm, the following lines to test:
x = findgen(100) ; MULTIPLOT
t=exp(-(x-50)^2/300) ; -------------------------
erase ; | | |
u=exp(-x/30) ; | | |
y = sin(x) ; | UL plot | UR plot |
r = reverse(y*u) ; | | |
!p.multi=[0,2,2,0,0] ; | | |
multiplot ; y-------------------------
plot,x,y*u,title='MULTIPLOT' ; l| | |
multiplot & plot,x,r ; a| | |
multiplot ; b| LL plot | LR plot |
plot,x,y*t,ytit='ylabels' ; e| | |
multiplot ; l| | |
plot,x,y*t,xtit='xlabels' ; s-------------------------
multiplot,/reset ; xlabels
wait,2 & erase ; TEST
multiplot,[1,3] ; H------------------------
plot,x,y*u,title='TEST' ; E| plot #1 |
multiplot ; I------------------------
plot,x,y*t,ytit='HEIGHT' ; G| plot #2 |
multiplot ; H------------------------
plot,x,r,xtit='PHASE' ; T| plot #3 |
multiplot,/reset ; ------------------------
; PHASE
multiplot,[1,1],/init,/verbose ; one way to return to single plot
% MULTIPLOT: Initialized for 1x1, plotted across then down (column major).
OPTIONAL INPUTS:
pmulti = 2-element or 5-element vector giving number of plots, e.g.,
multiplot,[1,6] ; 6 plots vertically
multiplot,[0,4,2,0,0] ; 4 plots along x and 2 along y
multiplot,[0,4,2,0,1] ; ditto, except rowmajor (down 1st)
multiplot,[4,2],/rowmajor ; identical to previous line
OPTIONAL KEYWORDS:
help = flag to print header
initialize = flag to begin only---no plotting, just setup,
e.g., multiplot,[4,2],/init,/verbose & multiplot & plot,x,y
reset = flag to reset system variables to values prior to /init
default = flag to restore IDL's default value for system variables
rowmajor = flag to number plots down column first (D=columnmajor)
verbose = flag to output informational messages
Outputs:
!p.position = 4-element vector to place a plot
!x.tickname = either '' or else 30 ' ' to suppress ticknames
!y.tickname = either '' or else 30 ' ' to suppress ticknames
!p.noerase = 1
CALLS: ***
DOC_LIBRARY
Common blocks:
multiplot---to hold saved variables and plot counter. See code.
Side Effects:
Multiplot sets a number of system variables: !p.position, !p.multi,
!x.tickname, !y.tickname, !P.noerase---but all can be reset with
the call: multiplot,/reset
RESTRICTIONS:
1. If you use !p.multi as the method of telling how many plots
are present, you have to set !p.multi at the beginning each time you
use multiplot or call multiplot with the /reset keyword.
2. There's no way to make an xtitle or ytitle span more than one plot,
except by adding spaces to shift it or to add it manually with xyouts.
3. There is no way to make plots of different sizes; each plot
covers the same area on the screen or paper.
PROCEDURE:
This routine makes a matrix of plots with common axes, as opposed to
the method of !p.multi where axes are separated to allow labels.
Here the plots are joined and labels are suppressed, except at the
left edge and the bottom. You tell multiplot how many plots to make
using either !p.multi (which is then reset) or the parameter pmulti.
However, multiplot keeps track of the position by itself because
!p.multi interacts poorly with !p.position.
MODIFICATION HISTORY:
write, 21-23 Mar 94, Fred Knight (knight@ll.mit.edu)
alter plot command that sets !x.window, etc. per suggestion of
Mark Hadfield (hadfield@storm.greta.cri.nz), 7 Apr 94, FKK
add a /default keyword restore IDL's default values of system vars,
7 Apr 94, FKK
modify two more sys vars !x(y).tickformat to suppress user-formatted
ticknames, per suggestion of Mark Hadfield (qv), 8 Apr 94, FKK
Converted to IDL V5.0 W. Landsman September 1997
[Previous]
[Next]
Project : YOHKOH-BCS
Name : MVOIGT
Purpose : Compute multiple voigt functions with quadratic background
Explanation : Program checks no. of elements in a, of which there must
at least 7. First three elements define background. Remaining
elements define voigt function(s) which must come in
multiples of 4.
Category : fitting
Syntax : v=mvoigt(x,a,pder)
Inputs : x =dependent variable
a(0,1,2)=coefficients of quadratic background
a(3)= line intensity
a(4)= line center
a(5)= 1/e doppler width
a(6)= rocking width (1/e units)
Outputs : v = n voigt functions + quadratic background
Opt Outputs : PDER = partial derivatives wrt 'a'
Keywords : EXTRA = extra optional variable in which user can return
miscellaneous information.
CALLED BY:
voigt_refl
Restrictions: None.
CALLS: ***
PVOIGT
Side effects: None.
History : Version 1, 17-July-1993, D M Zarro. Written
Contact : DZARRO@SOLAR.STANFORD.EDU
[Previous]
[Next]
Project: YOHKOH-BCS
Name: MVOIGT_FIT
Purpose: multiple voigt function fit to line profile
Explanation :
There must be at least 7 elements in the variable 'a'. First three elements
define background. Remaining elements define voigt function(s)
which must come in multiples of 4 with:
a(3) = total wavelength integrated line strength
a(4) = line center
a(5) = doppler width (1/e width)
a(6) = damping width (Lorentzian broadening parameter
expressed as a 1/e value in the same units as the doppler width.
Syntax: v=mvoigt_fit(x,y,a,sigmaa)
Category: Fitting
Inputs:
y = data to fit
x = bin or wavelength
Outputs:
background=a(0)+a(1)*x+a(2)*x^2
a(3) = total intensity
a(4) = center
a(5) = doppler width
a(6) = damping width
Opt. Outputs:
sigmaa = sigma errors
Keywords:
fixp = vector of parameters to keep fixed
(e.g. fixp=[0,1,3] to fix parameters 1,2 and 4)
weights = data weights
nfree = number of free parameters
chi2 = chi^2
same_damp = keep damping width the same for all profiles
CALLS: ***
FUNCT_FIT
History: Written 12-Dec-1998, Zarro (SMA/GSFC)
Contact: DZARRO@SOLAR.STANFORD.EDU
[Previous]
[Next]
NAME:
MWRFITS
PURPOSE:
Write all standard FITS data types from input arrays or structures.
CALLING SEQUENCE:
MWRFITS, Input, Filename, [Header],
/LSCALE , /ISCALE, /BSCALE,
/USE_COLNUM, /Silent, /Create, /No_comment, /Version, $
Alias=, /ASCII, Separator=, Terminator=, Null=,
/Logical_cols, /Bit_cols, /Nbit_cols,
Group=, Pscale=, Pzero=
INPUTS:
Input = Array or structure to be written to FITS file.
-When writing FITS primary data or image extensions
input should be an array.
--If data is to be grouped
the Group keyword should be specified to point to
a two dimensional array. The first dimension of the
Group array will be PCOUNT while the second dimension
should be the same as the last dimension of Input.
--If Input is undefined, then a dummy primary dataset
or Image extension is created [This might be done, e.g.,
to put appropriate keywords in a dummy primary
HDU].
-When writing an ASCII table extension, Input should
be a structure array where no element of the structure
is a structure or array (except see below).
--A byte array will be written as A field. No checking
is done to ensure that the values in the byte field
are valid ASCII.
--Complex numbers are written to two columns with '_R' and
'_I' appended to the TTYPE fields (if present). The
complex number is enclosed in square brackets in the output.
--Strings are written to fields with the length adjusted
to accommodate the largest string. Shorter strings are
blank padded to the right.
-When writing a binary table extension, the input should
be a structure array with no element of the structure
being a substructure.
If a structure is specified on input and the output
file does not exist or the /CREATE keyword is specified
a dummy primary HDU is created.
Filename = String containing the name of the file to be written.
By default MWRFITS appends a new extension to existing
files which are assumed to be valid FITS. The /CREATE
keyword can be used to ensure that a new FITS file
is created even if the file already exists.
OUTPUTS:
OPTIONAL INPUTS:
Header = Header should be a string array. Each element of the
array is added as a row in the FITS header. No
parsing is done of this data. MWRFITS will prepend
required structural (and, if specified, scaling)
keywords before the rows specified in Header.
Rows describing columns in the table will be appended
to the contents of Header.
Header lines will be extended or truncated to
80 characters as necessary.
If Header is specified then on return Header will have
the header generated for the specified extension.
OPTIONAL INPUT KEYWORDS:
ALias= Set up aliases to convert from the IDL structure
to the FITS column name. The value should be
a STRARR(2,*) value where the first element of
each pair of values corresponds to a column
in the structure and the second is the name
to be used in the FITS file.
The order of the alias keyword is compatible with
use in MRDFITS.
ASCII - Creates an ASCII table rather than a binary table.
This keyword may be specified as:
/ASCII - Use default formats for columns.
ASCII='format_string' allows the user to specify
the format of various data types such using the following
syntax 'column_type:format, column_type:format'. E.g.,
ASCII='A:A1,I:I6,L:I10,B:I4,F:G15.9,D:G23.17,C:G15.9,M:G23.17'
gives the default formats used for each type. The TFORM
fields for the real and complex types indicate will use corresponding
E and D formats when a G format is specified.
Note that the length of the field for ASCII strings and
byte arrays is automatically determined for each column.
BIT_COLS= An array of indices of the bit columns. The data should
comprise a byte array with the appropriate dimensions.
If the number of bits per row (see NBIT_COLS)
is greater than 8, then the first dimension of the array
should match the number of input bytes per row.
BSCALE Scale floats, longs, or shorts to unsigned bytes (see LSCALE)
CREATE If this keyword is non-zero, then a new FITS file will
be created regardless of whether the file currently
exists. Otherwise when the file already exists,
a FITS extension will be appended to the existing file
which is assumed to be a valid FITS file.
GROUP= This keyword indicates that GROUPed FITS data is to
be generated.
Group should be a 2-D array of the appropriate output type.
The first dimension will set the number of group parameters.
The second dimension must agree with the last dimension
of the Input array.
ISCALE Scale floats or longs to short integer (see LSCALE)
LOGICAL_COLS= An array of indices of the logical column numbers.
These should start with the first column having index 0.
The structure element should either be an array of characters
with the values 'T' or 'F', or an array of bytes having the
values byte('T'), byte('F') or 0b. The use of bytes allows
the specification of undefined values (0b).
LSCALE Scale floating point numbers to long integers.
This keyword may be specified in three ways.
/LSCALE (or LSCALE=1) asks for scaling to be automatically
determined. LSCALE=value divides the input by value.
I.e., BSCALE=value, BZERO=0. Numbers out of range are
given the value of NULL if specified, otherwise they are given
the appropriate extremum value. LSCALE=(value,value)
uses the first value as BSCALE and the second as BZERO
(or TSCALE and TZERO for tables).
NBIT_COLS= The number of bits actually used in the bit array.
This argument must point to an array of the same dimension
as BIT_COLS.
NO_TYPES If the NO_TYPES keyword is specified, then no TTYPE
keywords will be created for ASCII and BINARY tables.
No_comment Do not write comment keywords in the header
NULL= Value to be written for integers/strings which are
undefined or unwritable.
PSCALE= An array giving scaling parameters for the group keywords.
It should have the same dimension as the first dimension
of Group.
PZERO= An array giving offset parameters for the group keywords.
It should have the same dimension as the first dimension
of Group.
Separator= This keyword can be specified as a string which will
be used to separate fields in ASCII tables. By default
fields are separated by a blank.
SILENT Suppress informative messages. Errors will still
be reported.
Terminator= This keyword can be specified to provide a string which
will be placed at the end of each row of an ASCII table.
No terminator is used when not specified.
If a non-string terminator is specified (including
when the /terminator form is used), a new line terminator
is appended.
USE_COLNUM When creating column names for binary and ASCII tables
MWRFITS attempts to use structure field name
values. If USE_COLNUM is specified and non-zero then
column names will be generated as 'C1, C2, ... 'Cn'
for the number of columns in the table.
Version Print the version number of MWRFITS.
CALLED BY:
FITS WRITER CLASS, FITSFILE__DEFINE [3], HSI_PACKET2FITS, XSM_VALID
hsi_break_srm, hsi_qlook__define, hsi_remake_gains, hsi_remake_lambda
hsi_remake_resol, hsi_remake_tailfrac, hsi_spectrum__filewrite
hsi_spectrum__fitswrite, rm2fits, wrt_ebounds_ext, wrt_eneband_ext
EXAMPLE:
Write a simple array:
a=fltarr(20,20)
mwrfits,a,'test.fits'
Append a 3 column, 2 row, binary table extension to file just created.
a={name:'M31', coords:(30., 20.), distance:2}
a=replicate(a, 2);
mwrfits,a,'test.fits'
Now add on an image extension:
a=lonarr(10,10,10)
hdr=("COMMENT This is a comment line to put in the header", $
"MYKEY = "Some desired keyword value")
mwrfits,a,'test.fits',hdr
CALLS: ***
CHK_AND_UPD, FXADDPAR [1], FXADDPAR [2], FXPAR [1], FXPAR [2], MWR_ASCII
MWR_CHECKTYPE, MWR_DUMMY, MWR_FINDSCALE, MWR_GROUPINFIX, MWR_GROUPSCALE
MWR_HEADER, MWR_IMAGE, MWR_PSCALE, MWR_RETABLE, MWR_SCALE, MWR_TABLEDAT
MWR_TABLEHDR, MWR_UNSIGNED_OFFSET, MWR_VALIDPTR, MWR_VERSION, MWR_WRITEHEAP
RESTRICTIONS:
(1) Variable length columns are not supported for anything
other than simple types (byte, int, long, float, double).
(2) Empty strings are converted to 1 element blank strings (because
IDL refuses to write an emptry string (0b) from a structure)
NOTES:
This multiple format FITS writer is designed to provide a
single, simple interface to writing all common types of FITS data.
Given the number of options within the program and the
variety of IDL systems available it is likely that a number
of bugs are yet to be uncovered. If you find an anomaly
please send a report to:
Tom McGlynn
NASA/GSFC Code 660.2
tam@silk.gsfc.nasa.gov (or 301-286-7743)
PROCEDURES USED:
FXPAR(), FXADDPAR
MODIfICATION HISTORY:
Version 0.9: By T. McGlynn 1997-07-23
Initial beta release.
Dec 1, 1997, Lindler, Modified to work under VMS.
Version 0.91: T. McGlynn 1998-03-09
Fixed problem in handling null primary arrays.
Reconverted to IDL 5.0 format using IDLv4_to_v5
Version 0.92: T. McGlynn 1998-09-09
Add no_comment flag and keep user comments on fields.
Fix handling of bit fields.
Version 0.93: T. McGlynn 1999-03-10
Fix table appends on VMS.
Version 0.93a W. Landsman/D. Schlegel
Update keyword values in chk_and_upd if data type has changed
Version 0.94: T. McGlynn 2000-02-02
Efficient processing of ASCII tables.
Use G rather than E formats as defaults for ASCII tables
and make the default precision long enough that transformations
binary to/from ASCII are invertible.
Some loop indices made long.
Fixed some ends to match block beginnings.
Version 0.95: T. McGlynn 2000-11-06
Several fixes to scaling. Thanks to David Sahnow for
documenting the problems.
Added PCOUNT,GCOUNT keywords to Image extensions.
Version numbers shown in SIMPLE/XTENSION comments
Version 0.96: T. McGlynn 2001-04-06
Changed how files are opened to handle ~ consistently
Version 1.0: T. McGlynn 2001-12-04
Unsigned integers,
64 bit integers.
Aliases
Variable length arrays
Some code cleanup
Version 1.1: T. McGlynn 2002-2-18
Fixed major bug in processing of unsigned integers.
(Thanks to Stephane Beland)
Version 1.2: Stephane Beland 2003-03-17
Fixed problem in creating dummy dataset when passing undefined
data, caused by an update to FXADDPAR routine.
Version 1.2.1 Stephane Beland 2003-09-10
Exit gracefully if write priveleges unavailable
Version 1.3 Wayne Landsman 2003-10-24
Don't use EXECUTE() statement if on a virtual machine
Version 1.3a Wayne Landsman 2004-5-21
Fix for variable type arrays
Version 1.4 Wayne Landsman 2004-07-16
Use STRUCT_ASSIGN when modifying structure with pointer tags
Version 1.4a Wayne Landsman 2005-01-03
Fix writing of empty strings in binary tables
Version 1.4b Wayne Landsman 2006-02-23
Propagate /SILENT keyword to mwr_tablehdr
Version 1.5 Wayne Landsman 2006-05-24
Open file using /SWAP_IF_LITTLE_ENDIAN keyword
Convert empty strings to 1 element blank strings before writing
Version 1.5a Wayne Landsman 2006-06-29
Fix problem introduced 2006-05-24 with multidimensional strings
Version 1.5b K. Tolbert 2006-06-29
Make V1.5a fix work pre-V6.0
Version 1.5c I.Evans/W.Landsman 2006-08-08
Allow logical columns to be specified as bytes
Version 1,5d K. Tolbert 2006-08-11
Make V1.5a fix work for scalar empty string
Version 1.6 W. Landsman 2006-09-22
Assume since V5.5, remove VMS support
[Previous]
[Next]
Name: mwritefits
Purpose: index/data to specified type of FITS file
Input Parameters:
index - index structures
data - corresponding 2d/3d data array
Keyword Parameters:
NaNvalue - passed through to writefits
outfile - if supplied, use this/these file names (including outdir/path)
if not supplied, files are auto-named based on DATE_OBS
outdir - if supplied, direct files to this directory (names derived)
prefix - if supplied, 'PREFIX' prepended to autonamed files (def='mwf')
extension - if supplied, appended to auto-named files (def='.fits')
fitstype - type of file; 0=>mxf (trace-like) 1=>2D FITS (1/image)
nocomment - switch, if set, dont add comment from this routine
flat_fits - switch, if set, fitstype=1 (2D FITS, 1/image)
CALLED BY:
sxt_ssc2file, sxt_ssn2fits [1], sxt_ssn2fits [2], yo_xda2legacy
History:
24-Jun-1998 - S.L.Freeland - from write_trace
19-Nov-1998 - S.L.Freeland - include SECONDs in auto named files
(via time2file(/sec)
strip nested structure tags
Calling Sequence:
mwritefits, index, data ; 1 image per index/data pair
mwritefits, index, data [,outfile=outfile, outdir=outdir, $
prefix=prefix, extension=extension]
Calls: ***
ARR2STR [1], Arr2Str [2], BOX_MESSAGE, CONCAT_DIR [1], CONCAT_DIR [2]
CONCAT_DIR [3], FILE_EXIST [2], FXHMAKE [1], FXHMAKE [2], TIME2FILE, WRITEFITS [1]
WRITEFITS [2], concat_dir [4], curdir [1], curdir [2], data_chk [1], data_chk [2]
file_exist [1], file_exist [3], required_tags, str_subset, str_taginfo
struct2fitshead
[Previous]
[Next]
Name: mxf_decomp_data
Purpose: convert fits extension header and byte stream to image
Input Parameters:
structure - mxf style structure
stream - compressed stream
CALLS: ***
HOST_TO_IEEE [1], HOST_TO_IEEE [2], HOST_TO_IEEE [3], HOST_TO_IEEE [4]
data_chk [1], data_chk [2], gt_tagval [1], gt_tagval [2], prstr [1], prstr [2]
strjustify, trace_jpeg_decomp
CALLED BY:
mxf_read_data
History:
1-Nov-1997 - S.L.Freeland - originally for TRACE, but ~generic
2-Mar-1998 - S.L.Freeland - enable standard 12 bit jpeg decoder
4-Mar-1998 - S.L.Freeland - eliminate some debug, documentation...
5-Jan-2000 - S.L.Freeland - fix bug pointed out by Harry Warren
TODO - allow comp_code as keyword (dont require structure?)
Codes Allowed (append as new features added):
0 - no compression
1 - 12 bit JPEG (per TRACE implementation)
[2] - [hcompress] - [not yet implemented]
[Previous]
[Next]
Name: mxf_dset_map
Purpose: map Multi-Fits-Extension user SS -> "dset array"
Input Parameters:
phead - primary header structures - assume tag "EXT_NROW"
ss - subscripts of desired elements
Output Paramters:
function returns dset structure array {dset:xx, ifile:}
Calling Sequence:
dsetarr=mxf_dset_map(pheaders, ss)
dsetarr=mxf_dset_map(files, ss)
CALLED BY:
TRACE_PREP, mxf_read_data, mxf_read_header, read_soon, read_trace
History:
20-Oct-1997 - S.L.Freeland , prototype - originally for TRACE, but...
11-Mar-1998 - S.L.Freeland, scalarize dsetmap/filemap if only one record
3-Mar-1999 - S.L.Freeland - permit FILE_D$LEN in addition to EXT_NROW
CALLS: ***
data_chk [1], data_chk [2], gt_tagval [1], gt_tagval [2], mreadfits, prstr [1]
prstr [2], strjustify, totvect
Restrictions:
not much error checking
[Previous]
[Next]
Name: mxf_read_data
Purpose: Multi-Xtension-Fits data reader
Input Parameters:
infiles - filelist
dset_arr - subset of data sets to read (-1 implies all)
Output Parameters:
oustruct - output structure (extended headers as IDL structures)
outdata - optional output data cube - padded/embedded to largest
image and optionally rebinned by OUTSIZE or MAG_FACTOR
Keyword Parameters:
outsize - optional rebinned output array
mag_factor - another way to specify output size
Keyword Parameters:
loud (input) - if set, print some diagnostics
Calling Sequence:
mxf_read_data, infiles, dset_arr, eheaders ; binary headers only
mxf_read_data, infiles, dset_arr, ehead, dcube ; also data cube
CALLED BY:
read_trace
History:
4-Nov-1997 - S.L.Freeland - 4-November-1997 - originally for TRACE, but generic
12-Feb-1998 - MDM - Put in protection for data not fitting in the
output data cube
2-mar-1998 - SLF - dont rebin to max unless outsize or mag_fact
explicitly set
10-mar-1998 - SLF - add ROTATE keyword & logic for .ROT_OUT field
15-mar-1998 - SLF - add DTYPE (override structure.DATA_TYPE
(for recovery from bad values only - careful)
25-mar-1998 - SLF - add PHEAD output keyword
22-aug-2001 - TDT - fix bug for nonsquare, non-compressed images
Calls: ***
BOX_MESSAGE, CONGRID [1], CONGRID [2], CONGRID [3], DELVARX [1], DELVARX [2]
DELVARX [3], DELVARX [4], UNIQ [1], UNIQ [2], UNIQ [3], data_chk [1], data_chk [2]
delvarx [5], gt_tagval [1], gt_tagval [2], mreadfits, mxf_decomp_data
mxf_dset_map, mxf_read_header, prstr [1], prstr [2], strjustify
[Previous]
[Next]
Name: mxf_read_header
Purpose: read headers from mxf files
Input Parameters:
infiles - list of mxf files
Output Paramters:
outstruct - output structure (primary or extension IDL structures)
dset_arr - output full dset array (via mxfdset_map)
Keyword Parameters:
extension - if set, outstruct are extented headers
primary - if set, outstruct are primary headers (1:1 with infiles)
Calling Sequence:
mxfread, infiles, pheaders [,dset_arr] ; primary struct
mxfread, infiles, eheaders,[,dset_arr], /extension ; extension struct
CALLED BY:
READ_ANALIST, TRACE_PREP, mxf_read_data, read_trace, tr_rd_index, trace_cat2data
trace_write_genxcat, wrt_fits_bin_exten [2]
History:
28-oct-1997 - S.L. Freeland (written)
4-Dec-1997 - MDM Corrected reading primary header and passing it out
25-Mar-1998 - S.L. Freeland (add PHEAD output keyword)
Calls: ***
BOX_MESSAGE, mreadfits, mxf_dset_map, mxfread
[Previous]
[Next]
Name: mxfdset_map
Purpose: map Multi-Fits-Extension user SS -> "dset array"
Input Parameters:
phead - primary header structures - assume tag "EXT_NROW"
ss - subscripts of desired elements
Output Paramters:
function returns dset structure array {dset:xx, ifile:}
Calling Sequence:
dsetarr=mxfdset_map(pheaders, ss)
dsetarr=mxfdset_map(files, ss)
History:
20-Oct-1997 - prototype - originally for TRACE, but...
CALLS: ***
data_chk [1], data_chk [2], gt_tagval [1], gt_tagval [2], mreadfits, prstr [1]
prstr [2], strjustify, totvect
Restrictions:
not much error checking
[Previous]
[Next]
Name: mxfread
Purpose: Multi-Fits-Extension READer
Input Parameters:
infiles - filelist
Output Paramters:
oustruct - output structure (primary or extension IDL structures)
outdata - optional output data array
Keyword Parameters:
ss (input) - subset indices to read (data only)
loud (input) - if set, print some diagnostics
filemap (output) - lonarr map - maps files:outstruct
Calling Sequence:
mxfread, infiles, pheaders ; return primary struct
mxfread, infiles, eheaders, /extension ; return extension struct
CALLED BY:
mxf_read_header
History:
17-Oct-1997 - S.L.Freeland - originally for TRACE, but...
12-Mar-1998 - S.L.Freeland - protect against different structure
10-dec-2003 - S.L.Freeland - change mrdfits2 reference -> mrdfits
(ancient requirement for mrdfits2
has passed)
Calls: ***
MRDFITS [1], MRDFITS [2], gt_tagval [1], gt_tagval [2], mreadfits, prstr [1]
prstr [2], str_concat [1], str_concat [2], strjustify, totvect