## all functions - f

f2z

z = f2z(x) convert 2-by-dims float or double X to complex. Interpreted function, defined at i/idlsave.i line 306

f_inverse

f_inverse(f_and_dfdx, y, x0, x1, xerr) or f_inverse(f_and_dfdx, y, x0, x1, xerr) Find values of an inverse function by Newton-Raphson iteration, backed up by bisection if the convergence seems poor. The subroutine F_AND_DFDX must be defined as: func F_AND_DFDX (x, &f, &dfdx) returning both the function value f(x) and derivative dfdx(x). If the input x is an array, the returned f and dfdx must have the same shape as the input x. If F_AND_DFDX always returns zero dfdx, f_inverse will use bisection. The result x will have the same shape as the input Y values. The values of x are constrained to lie within the interval from X0 to X1; the function value must be on opposite sides of the required Y at these interval endpoints. The iteration stops when the root is known to within XERR, or to machine precision if XERR is nil or zero. X0, X1, and XERR may be arrays conformable with Y. f_inverse takes the same number of iterations for every Y value; it does not notice that some may have converged before others. Interpreted function, defined at i/roots.i line 102SEE ALSO: nraphson

factorize

factorize(x) return list of prime factors of X and their powers as an n-by-2 array. May include a large non-prime factor if X exceeds 3e9. In any event, product(result(,1)^result(,2)) will equal abs(X). X must be a scalar integer type. Interpreted function, defined at i/gcd.i line 83SEE ALSO: gcd, lcm, is_prime

fd12

fd12(x) return Fermi-Dirac integral of order 1/2, fd12(x) = integral[0 to inf]{ dt * t^0.5 / (exp(t-x)+1) } accurate to about 1e-12 Interpreted function, defined at i/fermi.i line 56SEE ALSO: fdm12, fd32, fd52, ifdm12, ifd12, ifd32, ifd52

fd32

fd32(x) return Fermi-Dirac integral of order 3/2, fd32(x) = integral[0 to inf]{ dt * t^1.5 / (exp(t-x)+1) } accurate to about 1e-12 Interpreted function, defined at i/fermi.i line 96SEE ALSO: fdm12, fd12, fd52, ifdm12, ifd12, ifd32, ifd52

fd52

fd52(x) return Fermi-Dirac integral of order 5/2, fd52(x) = integral[0 to inf]{ dt * t^2.5 / (exp(t-x)+1) } accurate to about 1e-12 Interpreted function, defined at i/fermi.i line 135SEE ALSO: fdm12, fd12, fd32, ifdm12, ifd12, ifd32, ifd52

fdi12

fdi12(x, b) return incomplete Fermi-Dirac integral of order 1/2, fdi12(x, b) = integral[b to inf]{ dt * t^0.5 / (exp(t-x)+1) } default accuracy to about 1e-10 Interpreted function, defined at i/fermii.i line 44SEE ALSO: fdim12, fdi32, fdi52

fdi32

fdi32(x, b) return incomplete Fermi-Dirac integral of order 1/2, fdi32(x, b) = integral[b to inf]{ dt * t^1.5 / (exp(t-x)+1) } default accuracy to about 1e-10 Interpreted function, defined at i/fermii.i line 70SEE ALSO: fdim12, fdi12, fdi52

fdi52

fdi52(x, b) return incomplete Fermi-Dirac integral of order 1/2, fdi32(x, b) = integral[b to inf]{ dt * t^2.5 / (exp(t-x)+1) } default accuracy to about 1e-10 Interpreted function, defined at i/fermii.i line 96SEE ALSO: fdim12, fdi12, fdi32

fdim12

fdim12(x, b) return incomplete Fermi-Dirac integral of order -1/2, fdim12(x, b) = integral[b to inf]{ dt * t^-0.5 / (exp(t-x)+1) } default accuracy to about 1e-10 Interpreted function, defined at i/fermii.i line 18SEE ALSO: fdi12, fdi32, fdi52

fdm12

fdm12(x) return Fermi-Dirac integral of order -1/2, fdm12(x) = integral[0 to inf]{ dt * t^-0.5 / (exp(t-x)+1) } accurate to about 1e-12 Interpreted function, defined at i/fermi.i line 15SEE ALSO: fd12, fd32, fd52, ifdm12, ifd12, ifd32, ifd52

fflush

fflush, file flush the I/O buffers for the text file FILE. (Binary files are flushed at the proper times automatically.) You should only need this after a write, especially to a pipe. Builtin function, documented at i0/std.i line 1956SEE ALSO: write, popen

fft

fft(x, direction) fft(x, ljdir, rjdir) or fft(x, ljdir, rjdir, setup=workspace) returns the complex Fast Fourier Transform of array X. The DIRECTION determines which direction the transform is in -- e.g.- from time to frequency or vice-versa -- as follows: DIRECTION meaning --------- ------- 1 "forward" transform (coefficients of exp(+i * 2*pi*kl/N)) on every dimension of X -1 "backward" transform (coefficients of exp(-i * 2*pi*kl/N)) on every dimension of X [1,-1,1] forward transform on first and third dimensions of X, backward transform on second dimension of X (any other dimensions remain untransformed) [-1,0,0,1] backward transform on first dimension of X, forward transform on fourth dimension of X etc. The third positional argument, if present, allows the direction of dimensions of X to be specified relative to the final dimension of X, instead of relative to the first dimension of X. In this case, both LJDIR and RJDIR must be vectors of integers -- the scalar form is illegal: LJDIR RJDIR meaning ----- ----- ------- [] [1] forward transform last dimension of X [1] [] forward transform first dimension of X [] [-1,-1] backward transform last two dimensions of X, leaving any other dimensions untransformed [-1,0,0,1] [] backward transform on first dimension of X, forward transform on fourth dimension of X [] [-1,0,0,1] backward transform on 4th to last dimension of X, forward transform on last dimension of X etc. Note that the final element of RJDIR corresponds to the last dimension of X, while the initial element of LJDIR corresponds to the first dimension of X. The explicit meaning of "forward" transform -- the coefficients of exp(+i * 2*pi*kl/N) -- is: result for j=1,...,n result(j)=the sum from k=1,...,n of x(k)*exp(-i*(j-1)*(k-1)*2*pi/n) where i=sqrt(-1) Note that the result is unnormalized. Applying the "backward" transform to the result of a "forward" transform returns N times the original vector of length N. Equivalently, applying either the "forward" or "backward" transform four times in succession yields N^2 times the original vector of length N. Performing the transform requires some WORKSPACE, which can be set up beforehand by calling fft_setup, if fft is to be called more than once with arrays X of the same shape. If no setup keyword argument is supplied, the workspace allocation and setup must be repeated for each call. Interpreted function, defined at i0/fft.i line 20SEE ALSO: roll, fft_setup, fft_inplace

fft_braw

fft_braw, n, c, wsave Swarztrauber's cfftb. You can use this to avoid the additional 2*N storage incurred by fft_setup. Builtin function, documented at i0/fft.i line 237

fft_dirs

fft_dirs Interpreted function, defined at i0/fft.i line 192

fft_fraw

fft_fraw, n, c, wsave Swarztrauber's cfftf. You can use this to avoid the additional 2*N storage incurred by fft_setup. Builtin function, documented at i0/fft.i line 228

fft_good

fft_good(n) returns the smallest number of the form 2^x*3^y*5^z greater than or equal to n. An fft of this length will be much faster than a number with larger prime factors; the speed difference can be an order of magnitude or more. For n>100, the worst cases result in a little over a 11% increase in n; for n>1000, the worst are a bit over 6%; still larger n are better yet. The median increase for n<=10000 is about 1.5%.SEE ALSO: fft, fft_setup, convol

fft_good

fft_good(n) returns the smallest number of the form 2^x*3^y*5^z greater than or equal to n. An fft of this length will be much faster than a number with larger prime factors; the speed difference can be an order of magnitude or more. For n>100, the worst cases result in a little over a 11% increase in n; for n>1000, the worst are a bit over 6%; still larger n are better yet. The median increase for n<=10000 is about 1.5%.SEE ALSO: fft, fft_setup, convol

fft_init

fft_init, n, wsave Swarztrauber's cffti. This actually requires wsave=array(0.0, 4*n+15), instead of the 6*n+15 doubles of storage used by fft_raw to handle the possibility of multidimensional arrays. If the storage matters, you can call cfftf and/or cfftb as the Yorick functions fft_fraw and/or fft_braw. Builtin function, documented at i0/fft.i line 216

fft_inplace

fft_inplace, x, direction or fft_inplace, x, ljdir, rjdir or fft_inplace, x, ljdir, rjdir, setup=workspace is the same as the fft function, except that the transform is performed "in_place" on the array X, which must be of type complex. Interpreted function, defined at i0/fft.i line 94SEE ALSO: fft, fft_setup

fft_raw

fft_raw Builtin function, documented at i0/fft.i line 246

fft_setup

workspace= fft_setup(dimsof(x)) or workspace= fft_setup(dimsof(x), direction) or workspace= fft_setup(dimsof(x), ljdir, rjdir) allocates and sets up the workspace for a subsequent call to fft(X, DIRECTION, setup=WORKSPACE) or fft(X, LJDIR, RJDIR, setup=WORKSPACE) The DIRECTION or LJDIR, RJDIR arguments compute WORKSPACE only for the dimensions which will actually be transformed. If only the dimsof(x) argument is supplied, then WORKSPACE will be enough to transform any or all dimensions of X. With DIRECTION or LJDIR, RJDIR supplied, WORKSPACE will only be enough to compute the dimensions which are actually to be transformed. The WORKSPACE does not depend on the sign of any element in the DIRECTION (or LJDIR, RJDIR), so you can use the same WORKSPACE for both "forward" and "backward" transforms. Furthermore, as long as the length of any dimensions of the array X to be transformed are present in WORKSPACE, it may be used in a call to fft with the array. Thus, if X were a 25-by-64 array, and Y were a 64-vector, the following sequence is legal: ws= fft_setup(dimsof(x)); xf= fft(x, 1, setup=ws); yf= fft(y, -1, setup=ws); The WORKSPACE required for a dimension of length N is 6*N+15 doubles. Interpreted function, defined at i0/fft.i line 137SEE ALSO: fft, dimsof, fft_inplace

fil_analyze

fil_analyze, filt, poles, zeroes given a FILT, return the complex POLES and ZEROES, sorted in order of increasing imaginary part. The real parts of POLES will all be negative if the FILT is stable. Interpreted function, defined at i/filter.i line 160SEE ALSO: filter, fil_make

fil_bessel

filt= fil_bessel(np, wc, db) returns the lowpass Bessel filter with NP poles, normalized such that at angular frequency WC, the attenuation is DB decibels. (That is, the attenuation factor is 10^(.05*DB) at WC, so that to_db(response(filt,WC))==DB.) A Bessel filter has the most nearly constant group delay time d(phase)/dw of any filter of the same order. It minimizes pulse distortion, but does not cut off very rapidly in frequency. If WC is nil or zero, it defaults to 1.0. If DB is nil, the filter is normalized such that both the s^0 and s^NP terms are 1, unless the natural= keyword is non-zero, in which case the filter is normalized such that the group delay d(phase)/dw is -1 at w=0. Interpreted function, defined at i/filter.i line 178SEE ALSO: filter, fil_analyze

fil_butter

filt= fil_butter(np, wc, db) returns the lowpass Butterworth filter with NP poles, normalized such that at angular frequency WC, the attenuation is DB decibels. (That is, the attenuation factor is 10^(.05*DB) at WC, so that to_db(response(filt,WC))==DB.) A Butterworth filter is the best Taylor series approximation to the ideal lowpass filter (a step in frequency) response at both w=0 and w=infinity. For wc=1 and db=10*log10(2), the square of the Butterworth frequency response is 1/(1+w^(2*np)). If WC is nil or zero, it defaults to 1.0. If DB is nil, the filter is normalized "naturally", which is the same as DB=10*log10(2). Interpreted function, defined at i/filter.i line 226SEE ALSO: filter, fil_analyze, butter

fil_cauer

filt= fil_cauer(np, ripple, atten, wc, db) or filt= fil_cauer(np, ripple, -skirt, wc, db) returns the lowpass Cauer (elliptic) filter with NP poles, passband ripple RIPPLE and stopband attenuation ATTEN decibels, normalized such that at angular frequency WC, the attenuation is DB decibels. (That is, the attenuation factor is 10^(.05*DB) at WC, so that to_db(response(filter,WC))==DB.) If the third parameter is negative, its absolute value is SKIRT, the ratio of the frequency at which the stopband attenuation is first reached to the frequency at which the passband ends (where the attenuation is RIPPLE). The closer to 1.0 SKIRT is, the smaller the equivalent ATTEN would be. The external variable cauer_other is set to ATTEN if you provide SKIRT, and to SKIRT if you provide ATTEN. The Cauer filter has NP zeroes as well as NP poles. Consider the four parameters: (1) filter order, (2) transition ("skirt") bandwidth, (3) passband ripple, and (4) stopband ripple. Given any three of these, the Cauer filter minimizes the fourth. If WC is nil or zero, it defaults to 1.0. If DB is nil, the filter is normalized "naturally", which is the same as DB=RIPPLE. Interpreted function, defined at i/filter.i line 357SEE ALSO: filter, fil_analyze, cauer

fil_cheby1

filt= fil_cheby1(np, ripple, wc, db) returns the lowpass Chebyshev type I filter with NP poles, and passband ripple RIPPLE decibels, normalized such that at angular frequency WC, the attenuation is DB decibels. (That is, the attenuation factor is 10^(.05*DB) at WC, so that to_db(response(filter,WC))==DB.) A Chebyshev type I filter gives the smallest maximum error over the passband for any filter that is a Taylor series approximation to the ideal lowpass filter (a step in frequency) response at w=infinity. It has NP/2 ripples of amplitude RIPPLE in its passband, and a smooth stopband. For wc=1 and db=ripple, the square of the Chebyshev frequency response is 1/(1+eps2*Tnp(w)), where eps2 = 10^(ripple/10)-1, and Tnp is the np-th Chebyshev polynomial, cosh(np*acosh(x)) or cos(np*acos(x)). If WC is nil or zero, it defaults to 1.0. If DB is nil, the filter is normalized "naturally", which is the same as DB=RIPPLE. Interpreted function, defined at i/filter.i line 263SEE ALSO: filter, fil_analyze, cheby1

fil_cheby2

filt= fil_cheby2(np, atten, wc, db) returns the lowpass Chebyshev type II filter with NP poles, and stopband attenuation ATTEN decibels, normalized such that at angular frequency WC, the attenuation is DB decibels. (That is, the attenuation factor is 10^(.05*DB) at WC, so that to_db(response(filter,WC))==DB.) This is also called an inverse Chebyshev filter, since its poles are the reciprocals of a Chebyshev type I filter. It has NP zeroes as well as NP poles. A Chebyshev type II filter gives the smallest maximum leakage over the stopband for any filter that is a Taylor series approximation to the ideal lowpass filter (a step in frequency) response at w=0. It has NP/2 ripples of amplitude ATTEN in its stopband, and a smooth passband. For wc=1 and db=ripple, the square of the inverse Chebyshev frequency response is 1 - 1/(1+eps2*Tnp(1/w)), where eps2 = 10^(ripple/10)-1 = 1/(10^(atten/10)-1) and Tnp is the np-th Chebyshev polynomial, cosh(np*acosh(x)) or cos(np*acos(x)). If WC is nil or zero, it defaults to 1.0. If DB is nil, the filter is normalized "naturally", which is the same as DB=ATTEN. Interpreted function, defined at i/filter.i line 305SEE ALSO: filter, fil_analyze, cheby2

fil_delay

fil_delay(filt) or fil_delay(filt, 1) return the group delay d(phase)/dw at w=0 (zero frequency) for filter FILT. By default, FILT is assumed to be normalized to an angular frequency (e.g.- radians per second), but if the 2nd parameter is non-nil and non-0 FILT is assumed to be normalized to a circular frequency (e.g.- Hz or GHz). Interpreted function, defined at i/filter.i line 93SEE ALSO: filter, fil_butter, fil_bessel, fil_cheby1, fil_cheby2, fil_response,

to_db, to_phase

fil_make

filt= fil_make(poles, zeroes) given the complex POLES and ZEROES, return a FILT. The real parts of POLES must all be negative to make a stable FILT. Both POLES and ZEROES must occur in conjugate pairs in order to make a real filter (the returned filter is always real). The returned filter always has a0=1 (its DC gain is 1). Interpreted function, defined at i/filter.i line 126SEE ALSO: filter, fil_analyze

fil_normalize

fil_normalize Interpreted function, defined at i/filter.i line 473

fil_poly

fil_poly(c, x) return c(1) + c(2)*x + c(3)*x^2 + c(4)*x^3 + ... Interpreted function, defined at i/filter.i line 115

fil_response

fil_response(filt, w) return the complex response of FILT at the frequencies W. The frequency scale for W depends on how FILT has been scaled; filters are rational functions in W. The to_db and to_phase functions may be useful for extracting the attenuation and phase parts of the complex response. Interpreted function, defined at i/filter.i line 72SEE ALSO: filter, fil_butter, fil_bessel, fil_cheby1, fil_cheby2, fil_delay,

to_db, to_phase

filter

filter(filt, dt, signal) apply the filter FILT to the input SIGNAL, which is sampled at times spaced by DT. The filter is assumed to be normalized to an angular frequency (e.g.- radians per second), unless DT<0, in which case FILT is assumed to be normalized to a circular frequency (e.g.- Hz or GHz). The result will have the same length as SIGNAL; be sure to pad SIGNAL if you need the response to go beyond that time, or you can use the pad=n keyword to force the returned result to have N samples more than SIGNAL. If the shift= keyword is non-nil and non-0, then the result is shifted backward in time by the filter group delay at zero frequency. The impulse response of the FILT is also assumed to be shorter than the duration of signal, and SIGNAL is assumed to be sampled finely enough to resolve the FILT impulse response. FILT is an array of double, which represents a filter with a particular finite list of zeroes and poles. See the specific functions to construct filters from poles and zeroes (fil_make), or classic Bessel, Butterworth, Chebyshev, inverse Chebyshev, or Cauer (elliptic) designs. With fil_analyze, you can find the poles and zeroes of a FILT. The format for FILT is: FILT is an array of double with the following meanings: FILT(1) = np = number of poles (integer >= 0) FILT(2) = nz = number of zeroes (integer >= 0) FILT(3) = reserved FILT(4:4+nz) = coefficients for numerator = [a0, a1, a2, a3, ..., anz] FILT(5+nz:4+nz+np) = coefficents for denominator (if np>0) = [b1, b2, b3, ..., bnp] The Laplace transform (s-transform) of the filter response is L[FILT] = (a0 + a1*s + a2*s^2 + a3*s^3 + ...) / ( 1 + b1*s + b2*s^2 + b3*s^3 + ...) Interpreted function, defined at i/filter.i line 8SEE ALSO: filter, fil_bessel, fil_butter, fil_cheby1, fil_cheby2, fil_cauer,

fil_response, fil_make, fil_analyze, to_db, to_phase

find_boundary

boundary= find_boundary(mesh) or boundary= find_boundary(mesh, region, sense) returns an array of 4 pointers representing the boundary of the MESH, or of a particular REGION of the MESH, with a particular SENSE -- 0 for counterclockwise in the (r,z)-plane, 1 for clockwise. The returned arrays are: *boundary(1) zone index list -- always 1-origin values *boundary(2) side list 0, 1, 2, or 3 side 0 is from point zone to zone-1, side 1 is from zone-1 to zone-imax-1 *boundary(3) z values of boundary points *boundary(4) r values of boundary points Builtin function, documented at i0/drat.i line 1095SEE ALSO: form_mesh, update_mesh

fitlsq

yp= fitlsq(y, x, xp) ... yfit= interp(yp, xp, xfit) performs a least squares fit to the data points (X, Y). The input XP are the abcissas of the piecewise linear function passing through (XP, YP) which is the best fit to the data (X,Y) in a least squares sense. The XP must be strictly monotone, either increasing or decreasing. As for interp, the piecewise linear fit is taken to be constant outside the limits of the XP. The result YP is linearly interpolated through any consecutive intervals of XP which contain no data points X, and linearly extrapolated beyond the extreme values of X (if any of the intervals of XP lie outside these extremes). A WEIGHT keyword of the same length as X and Y may be supplied in order to weight the various data points differently; a typical WEIGHT function is 1/sigma^2 where sigma are the standard deviations associated with the Y values. Interpreted function, defined at i/fitlsq.i line 10SEE ALSO: interp

fitpol

yp= fitpol(y, x, xp) -or- yp= fitpol(y, x, xp, keep=1) is an interpolation routine similar to interp, except that fitpol returns the polynomial of degree numberof(X)-1 which passes through the given points (X,Y), evaluated at the requested points XP. The X must either increase or decrease monotonically. If the KEEP keyword is present and non-zero, the external variable yperr will contain a list of error estimates for the returned values yp on exit. The algorithm is taken from Numerical Recipes (Press, et. al., Cambridge University Press, 1988); it is called Neville's algorithm. The rational function interpolator fitrat is better for "typical" functions. The Yorick implementaion requires numberof(X)*numberof(XP) temporary arrays, so the X and Y arrays should be reasonably small. Interpreted function, defined at i/fitrat.i line 10SEE ALSO: fitrat, interp

fitrat

yp= fitrat(y, x, xp) -or- yp= fitrat(y, x, xp, keep=1) is an interpolation routine similar to interp, except that fitpol returns the diagonal rational function of degree numberof(X)-1 which passes through the given points (X,Y), evaluated at the requested points XP. (The numerator and denominator polynomials have equal degree, or the denominator has one larger degree.) The X must either increase or decrease monotonically. Also, this algorithm works by recursion, fitting successively to consecutive pairs of points, then consecutive triples, and so forth. If there is a pole in any of these fits to subsets, the algorithm fails even though the rational function for the final fit is non- singular. In particular, if any of the Y values is zero, the algorithm fails, and you should be very wary of lists for which Y changes sign. Note that if numberof(X) is even, the rational function is Y-translation invariant, while numberof(X) odd generally results in a non-translatable fit (because it decays to y=0). If the KEEP keyword is present and non-zero, the external variable yperr will contain a list of error estimates for the returned values yp on exit. The algorithm is taken from Numerical Recipes (Press, et. al., Cambridge University Press, 1988); it is called the Bulirsch-Stoer algorithm. The Yorick implementaion requires numberof(X)*numberof(XP) temporary arrays, so the X and Y arrays should be reasonably small. Interpreted function, defined at i/fitrat.i line 72SEE ALSO: fitpol, interp

fitsAddComment

fitsAddCommentSEE fitsHeader

fitsAddHistory

fitsAddHistorySEE fitsHeader

fitsFixHeader

fitsFixHeaderSEE fitsHeader

fitsHeader

fitsHeader

fitsRead

fitsReadSEE fitsHeader

fitsRead

a= fitsRead(filename, header) *** WARNING: Obsolete fits routine (see fits_read) *** Returns the data of the FITS file FILENAME. If present, the optional argument HEADER will be used to store the contents of the FITS header file (a FitsHeader structure). Keyword WHICH may be used to indicate which sub-array should be returned. For instance, if the array DATA with dimensions (235,453,7) is stored in the FITS file "data.fits", the sub-array DATA(,,4) can be read by: SUB_DATA= fitsRead("data.fits", which= 4); Keyword PACK, if non-nil and non-zero, indicates that axis whith unit dimension should be ignored. The default is to ignore only zero length axis. Keyword RESCALE, if non-nil and zero, indicates that read data values should not be rescaled according to FITS keywords BSCALE and BZERO. The default is to rescale data values if BSCALE is not 1. or BZERO is not 0.SEE ALSO: fits, fits_read, fitsObsolete

fitsRescale

fitsRescaleSEE fitsHeader

fitsWrite

fitsWriteSEE fitsHeader

fits_best_scale

fits_best_scale(bitpix, data) -or- fits_best_scale(bitpix, cmin, cmax) Returns [BSCALE,BZERO] where BSCALE and BZERO are optimal values for rescaling to BITPIX file type. BITPIX must correspond to an integer type (BITPIX = 8, 16 or 32). The array DATA contains all the physical values to save to the file; alternatively, CMIN and CMAX give the minimal and maximal values in physical data. Interpreted function, defined at i/fits.i line 517SEE ALSO: fits, fits_write

fits_bitpix_info

fits_bitpix_info(bitpix) Return string information about FITS bits-per-pixel value. Interpreted function, defined at i/fits.i line 2721SEE ALSO: fits, fits_bitpix_of, fits_bitpix_type, fits_check_bitpix

fits_bitpix_of

fits_bitpix_of(x) -or- fits_bitpix_of(x, native=1) Return FITS bits-per-pixel value BITPIX for binary data X which can be an array or a data type (structure definition). If keyword NATIVE is true, the routine assumes that binary data will be read/write to/from FITS file using native machine data representation. The default is to conform to FITS standard and to assume that XDR binary format will be used in FITS file. Interpreted function, defined at i/fits.i line 2765SEE ALSO: fits, fits_bitpix_type, fits_check_bitpix

fits_bitpix_type

fits_bitpix_type(bitpix) -or- fits_bitpix_type(bitpix, native=1) Returns Yorick data type given by FITS bits-per-pixel value BITPIX. If keyword NATIVE is true, return the native data type matching BITPIX. Interpreted function, defined at i/fits.i line 2735SEE ALSO: fits, fits_bitpix_of, fits_bitpix_info, fits_check_bitpix

fits_check_bitpix

fits_check_bitpix(bitpix) Test if FITS bits-per-pixel value BITPIX is valid. Interpreted function, defined at i/fits.i line 2711SEE ALSO: fits, fits_bitpix_of, fits_bitpix_type, fits_bitpix_info

fits_check_file

fits_check_file(filename) -or- fits_check_file(filename, errmode) Returns 1/0 depending whether FILENAME is a valid FITS file or not. If ERRMODE is true (non-nil and non-zero), unreadable file results in false result otherwise it is a runtime error. Note that the checking is very simple: it is sufficient that the first FITS card in the first 2880 bytes has keyword "SIMPLE" with logical value 'T' (true). Interpreted function, defined at i/fits.i line 750SEE ALSO: fits

fits_close

fits_close(fh) Closes stream in FITS handle FH. The header information stored in FH remain unchanged (e.g. you can keep editing the header in FH). The returned value is FH. Note that if you destroy all references to handle FH, the associated file (if any) gets automatically closed by Yorick. Interpreted function, defined at i/fits.i line 627SEE ALSO: fits, fits_pad_hdu, fits_open, close

fits_coordinate

fits_coordinate struct fits_coordinate { long axis, length; string ctype; double crpix, crval, cdelt, crota; }

fits_create

fits_create(filename) Creates a new FITS file FILENAME and returns a FITS handle with mandatory cards (i.e. SIMPLE, BITPIX, NAXIS, NAXISn) and some optional cards (i.e. EXTEND, BSCALE and BZERO) already initialized. Keyword BITPIX can be used to set FITS "bits-per-pixel" (default is BITPIX=8, i.e. byte data). Keyword DIMLIST should be used to specify the dimension list of the array data that is intended to be written in primary HDU. The value of DIMLIST is similar to the result returned by dimsof. Keyword EXTEND can be used to indicate whether the file may contains FITS extensions. It is probably a good idea to always use EXTEND=1. Keyword TEMPLATE can be set with an existing FITS handle to copy some FITS cards of the template into the new header. The FITS card that are _never_ copied are: "SIMPLE", "XTENSION", "BITPIX", "NAXIS", "NAXIS#" (with # an integer), "BSCALE" and "BZERO"; the other cards get copied. See keywords BSCALE and BZERO if you specifically want to set these values. Keywords BSCALE and BZERO can be used to specify physical value scale and offset. See fits_write_array to figure out how keywords BITPIX, BSCALE and BZERO are used to convert data values into file values. Keywords HISTORY and COMMENT can be set to add some comments in the new handle. The values of these keywords may be array of strings. Keywords ENCODING and OVERWRITE have the same meaning as in fits_open routine (to see). Interpreted function, defined at i/fits.i line 651SEE ALSO: fits, fits_open, fits_set, fits_set_dims

fits_current_hdu

fits_current_hdu(fh); Return number of current Header Data Unit in FITS handle FH. Interpreted function, defined at i/fits.i line 938SEE ALSO: fits, fits_read_header, fits_rewind, fits_next_hdu

fits_date

fits_date() Returns current Universal Time date as a string conforming to FITS standard: "DD/MM/YY" Interpreted function, defined at i/fits.i line 1013SEE ALSO: fits, rdline, popen

fits_delete

fits_delete, fh, pattern; Delete all cards matching PATTERN from current header of FITS handle FH (see fits_match for the syntax of PATTERN). Interpreted function, defined at i/fits.i line 3029SEE ALSO: fits, fits_match

fits_eof

fits_eof(fh) Returns non-zero if FITS handle FH is at end of file. Interpreted function, defined at i/fits.i line 928SEE ALSO: fits, fits_open, fits_next_hdu

fits_filename

fits_filename(fh) Return path name of file associated with FITS handle FH (in fact the argument may also be any Yorick open stream). Interpreted function, defined at i/fits.i line 2648SEE ALSO: fits

fits_get

fits_get(fh, pattern, comment) Get (array of) value(s) for FITS cards matching PATTERN (see fits_match) in current header of FITS handle FH. If present, argument COMMENT is an output symbol where the corresponding comment part of selected card(s) will be stored. In order to avoid namespace clash due to Yorick's scoping rules, COMMENT should be declared as a local symbol in the calling function, e.g.: local comment; value = fits_get(fh, pattern, comment); If no cards match PATTERN, the value of keyword DEFAULT is returned and COMMENT is set to the null string. If multiple cards match PATTERN, they must have the same value type unless keyword PROMOTE is true, in which case the routine promotes all card values to a suitable "highest" type. Request fo commentary cards (i.e. PATTERN is "HISTORY", "COMMENT", or "") may returns several cards. Interpreted function, defined at i/fits.i line 2906SEE ALSO: fits, fits_match, fits_parse

fits_get_bitpix

fits_get_bitpix(fh) -or- fits_get_bitpix(fh, fix) Get BITPIX value from current HDU in FITS handle FH. See fits_get_special for the meaning of FIX. Interpreted function, defined at i/fits.i line 1020SEE ALSO: fits, fits_check_bitpix, fits_get_special, fits_get_naxis,

fits_get_dims

fits_get_bscale

fits_get_bscale(fh) -or- fits_get_bzero(fh) Get BSCALE and BZERO values for FITS handle FH. These parameters are used to convert file values into physical values according to: physical_value = BZERO + BSCALE * file_value if the corresponding card is missing, BSCALE and BZERO default to 1.0 and 0.0 respectively. Interpreted function, defined at i/fits.i line 3149SEE ALSO: fits, fits_get, fits_read_array, fits_write_array

fits_get_cards

fits_get_cards(fh, pattern); Return cards from FITS handle FH which match PATTERN (see fits_match for the syntax of PATTERN). Interpreted function, defined at i/fits.i line 3017SEE ALSO: fits, fits_match

fits_get_data_size

fits_get_data_size(fh) -or- fits_get_data_size(fh, fix) Computes the number of bytes in data part of current HDU of FITS handle FH. This value is computed according to the header part of FH and may be different from the number of bytes actually written in the data part of the current HDU. Interpreted function, defined at i/fits.i line 1306SEE ALSO: fits, fits_read_header

fits_get_dims

fits_get_dims(fh) -or- fits_get_dims(fh, fix) Get all NAXIS* values from current HDU in FITS handle FH and return vector [NAXIS, NAXIS1, NAXIS2, ...]. If the value of any of the "NAXIS#" card is zero, then there is no data in the current unit and fits_get_dims returns [] (nil) in this case. See fits_get_special for the meaning of FIX. Interpreted function, defined at i/fits.i line 1048SEE ALSO: fits, fits_get_special, fits_get_bitpix, fits_get_naxis

fits_get_gcount

fits_get_gcount(fh) -or- fits_get_pcount(fh) Get PCOUNT and GCOUNT values for FITS handle FH. PCOUNT shall be an integer equal to the number of parameters preceding each group (default value 0). GCOUNT shall be an integer equal to the number of random groups present (default value 1). The total number of bits in the data array (exclusive of fill that is needed after the data to complete the last record) is given by the following expression: NBITS = abs(BITPIX)*GCOUNT*(PCOUNT + NAXIS1*NAXIS2*...*NAXISm) Interpreted function, defined at i/fits.i line 3167SEE ALSO: fits, fits_get, fits_get_bitpix, fits_read_array, fits_write_array

fits_get_history

fits_get_history(fh) -or- fits_get_comment(fh) Get COMMENT and HISTORY values for FITS handle FH. The result is an array of string(s) or nil if no such cards exists in the header of the current unit. Interpreted function, defined at i/fits.i line 3190SEE ALSO: fits, fits_get, fits_read_array, fits_write_array

fits_get_keywords

fits_get_keywords(fh) -or- fits_get_keywords(fh, ordered) Get list of FITS keywords defined in current HDU of FITS handle HF. The returned value is an array of strings. If ORDERED is true (non-nil and non-zero), the keywords get sorted. Note: the "END" keyword is always missing in a (non-corrupted) FITS handle. Interpreted function, defined at i/fits.i line 1182SEE ALSO: fits, sort, strtok

fits_get_naxis

fits_get_naxis(fh) -or- fits_get_naxis(fh, fix) Get NAXIS value from current HDU in FITS handle FH. See fits_get_special for the meaning of FIX. Interpreted function, defined at i/fits.i line 1035SEE ALSO: fits, fits_get_special, fits_get_bitpix, fits_get_dims

fits_get_special

fits_get_special(fh, key, id, location, fix) Get value of a special FITS card given its key string, numerical identifier and absolute LOCATION (1 for first FITS card). If FIX is true, various further verifications are made and, if FITS strict checking mode is off, the header may be fixed in case of unambiguous error. Interpreted function, defined at i/fits.i line 1097SEE ALSO: fits, fits_get_bitpix, fits_get_naxis, fits_get_dims, fits_parse

fits_get_xtension

fits_get_xtension(fh) Get XTENSION value from current HDU in FITS handle FH. The returned value is a scalar string with the name of the extension; "IMAGE" is returned for the primary HDU. Interpreted function, defined at i/fits.i line 1073SEE ALSO: fits, fits_get, fits_parse

fits_goto_hdu

fits_goto_hdu(fh, hdu) Move FITS handle FH to Header Data Unit number HDU (starting at 1 for the primary HDU) and parse the header part of the new unit. Contents of FH is updated with header part of new HDU. To allow for linked calls, the returned value is FH. Interpreted function, defined at i/fits.i line 875SEE ALSO: fits, fits_next_hdu, fits_read_header, fits_rewind

fits_id

fits_id Interpreted function, defined at i/fits.i line 3044SEE fits_ids

fits_ids

fits_id(card) -or- fits_ids(cards) Convert FITS card(s) or FITS card name(s) into unique numerical identifier. CARD is a scalar string and CARDS (with an S) is an array of string(s) (including a scalar). Only the keyword part (characters 1:8) of CARD(S) is relevant; cards shorter than 8 characters yield the same identifier as if they were padded (right filled) with spaces. In other words, all the values returned by the following expressions are identical: fits_id("SIMPLE = T / conforming FITS file"); fits_id("SIMPLE "); fits_id("SIMPLE"); Interpreted function, defined at i/fits.i line 3044SEE ALSO: fits, fits_key, fits_rehash

fits_info

fits_info, fh; -or- fits_info, fh, hdu -or- fits_info, filename; -or- fits_info, filename, hdu; Prints header contents of current HDU in FITS handle FH or all HDU's in FITS file FILENAME. If argument HDU is given, only this header unit get printed out (HDU may be an array). Interpreted function, defined at i/fits.i line 386SEE ALSO: fits, fits_open

fits_init

fits_init; (Re)initializes FITS private data. Normally you do not have to call this routine because this routine is automatically called when "fits2.i" is parsed by Yorick. You may however need to explicitely call fits_init if you suspect that some FITS private data get corrupted or if you want to tune FITS strict/sloopy behaviour. If keyword SLOOPY is true (non-nil and non-zero) some discrepancy is allowed (for reading FITS file only); otherwise strict FITS compliance is applied. If SLOOPY is true, lower case Latin letters have the same meaning as their upper case counterparts, most control characters become identical to regular spaces. According to FITS standard, the only characters permitted for keywords are upper case (capital) Latin alphabetic, numbers, hyphen, and underscore. Leading and embedded blanks are forbidden. If you cannot read a FITS file because it does not confrom to this rule, you can use keyword ALLOW (a string or an array of characters) to allow additional characters for FITS keywords. For instance: fits_init, allow="/."; // fix for invalid headers made by IRAF make characters '/' and '.' acceptable in FITS keywords. Note that you must apply fits_rehash (to see) to _every_ FITS handle in use whenever you change the set of allowed characters (because this will probably corrupt the values of numerical identifiers of FITS card) ... It is therefore a good idea to change the set of allowed characters before using any FITS routines. Keyword BLANK can be used to add more characters that should be considered as blanks (spaces) when parsing FITS header/keywords. The value of BLANK must be a string or an array of characters, for instance: BLANK="\t\r\v\n". Note that this break strict compliance to FITS standard. Interpreted function, defined at i/fits.i line 3260SEE ALSO: fits, fits_rehash

fits_is_integer

fits_is_integer(x) Returns true if array X is of integer type. Interpreted function, defined at i/fits.i line 2617SEE ALSO: fits_is_scalar

fits_is_integer_scalar

fits_is_integer_scalar(x) Returns true if array X is a scalar of integer type. Interpreted function, defined at i/fits.i line 2624SEE ALSO: fits_is_real_scalar, fits_is_scalar, fits_is_string_scalar

fits_is_real_scalar

fits_is_real_scalar(x) Returns true if array X if of real type (i.e. double or float). Interpreted function, defined at i/fits.i line 2634SEE ALSO: fits_is_integer_scalar, fits_is_scalar, fits_is_string_scalar

fits_is_scalar

fits_is_scalar(x) Returns true if X is a scalar. Interpreted function, defined at i/fits.i line 2610SEE ALSO: fits_is_integer_scalar, fits_is_real_scalar, fits_is_string_scalar

fits_is_string_scalar

fits_is_string_scalar(x) Returns true if array X is a scalar of string type. Interpreted function, defined at i/fits.i line 2641SEE ALSO: fits_is_integer_scalar, fits_is_real_scalar, fits_is_scalar

fits_key

fits_key(id) Convert (array of) FITS numerical identifier(s) ID into the corresponding string FITS keyword(s) without trailing spaces. Interpreted function, defined at i/fits.i line 3108SEE ALSO: fits, fits_id

fits_list

fits_list, fh; -or- fits_list(fh) Get the names of the FITS extensions in FH. FH can be the name of a FITS file or a FITS handle FH (the input handle is left unchanged). When called as a subroutine, the list is printed to terminal; when called as a function, the returned value is a string array with the names of the FITS extensions in FH. Interpreted function, defined at i/fits.i line 944SEE ALSO: fits, fits_read_header, fits_next_hdu

fits_map

fits_map(op, src) Map scalar function OP onto array argument SRC to mimics element-wise unary operation. Interpreted function, defined at i/fits.i line 2595SEE ALSO: fits

fits_match

fits_match(fh, pattern) Return array of int's which are non-zero where FITS card names in FITS handle FH match PATTERN. PATTERN must be a scalar string or a numerical identifier. As a special case, if PATTERN is of the form "KEYWORD#" (i.e. last character of PATTERN is a '#'), then any human readable integer will match the '#', e.g. "NAXIS#" will match "NAXIS3" and "NAXIS11" but not "NAXIS" nor "QNAXIS4. Global/extern variable _fits_match_id is set with the numerical identifier of PATTERN (without last '#' if any). Interpreted function, defined at i/fits.i line 2972SEE ALSO: fits, fits_get_cards, fits_rehash

fits_move

fits_move, a, i, j; Move I-th element of array A in place of J-th element. The operation is done in-place. Interpreted function, defined at i/fits.i line 1212SEE ALSO: fits, fits_move_card

fits_move_card

fits_move_card(fh, from, to); Change location of FROM-th card to index TO into FITS handle FH. The operation is made in place. Interpreted function, defined at i/fits.i line 1201SEE ALSO: fits, fits_move

fits_new_bintable

fits_new_bintable(fh) -or- fits_new_bintable(fh, comment) Starts a new binary table FITS extension. This routine starts a new FITS extension with name "BINTABLE" and pre-set FITS cards needed to describe the table with fake values (the correct values will be set when fits_write_bintable is called to actually write the table). After calling this routine, the user can add new FITS cards (but not XTENSION, BITPIX, NAXIS, NAXIS1, NAXIS2, GCOUNT, nor PCOUNT). Optional argument COMMENT is the comment string for the XTENSION card. The returned value is FH. Interpreted function, defined at i/fits.i line 1984SEE ALSO: fits, fits_write_bintable

fits_new_hdu

fits_new_hdu(fh, xtension) -or- fits_new_hdu(fh, xtension, comment) Starts a new extension in FITS file open for writing. FH is the FITS handle, XTENSION is the name of the FITS extension and COMMENT is an optional string comment. After calling fits_new_hdu, there is no need to call: fits_set, FH, "XTENSION", XTENSION, COMMENT; since this is already done by this routine. However, beware that FITS standard requires that, if any extension is present in the file, that the keyword "EXTEND" with logical value 'T' (true) must appear in the primary header. Interpreted function, defined at i/fits.i line 1374SEE ALSO: fits, fits_pad_hdu, fits_set, fits_write_header, fits_write_array

fits_new_image

fits_new_image(fh, data) -or- fits_new_image(fh, bitpix=..., dimlist=...) Starts a new image (array) FITS extension in handle FH and returns FH. This routine starts a new FITS extension with name "IMAGE" and pre-set FITS cards needed to describe the array data according to keywords: BITPIX, DIMLIST, BZERO, and BSCALE. If argument DATA is given, it is used to guess the bits per pixel and the dimension list if not specified by the keywords BITPIX and DIMSLIST respectively. Interpreted function, defined at i/fits.i line 1955SEE ALSO: fits, fits_write_array

fits_next_hdu

fits_next_hdu(fh) Move FITS handle FH to next Header Data Unit and parse the header part of the new unit. Contents of FH is updated with header part of new HDU. To allow for linked calls, the returned value is FH. Interpreted function, defined at i/fits.i line 898SEE ALSO: fits, fits_goto_hdu, fits_read_header, fits_rewind

fits_nth

fits_nth(n) Returns a string in the form "1st", "2nd", "3rd" or "#th" where # is the human readable value of integer N. Interpreted function, defined at i/fits.i line 1000SEE ALSO: fits, fits_set_dims

fits_open

fits_open(filename) -or- fits_open(filename, filemode) Opens the FITS file FILENAME according to FILEMODE. The returned value is a FITS handle used in most other FITS routines. FILEMODE is one of: "r" or 'r' - read mode, the header of the primary HDU get read and is parsed. "w" or 'w' - write mode, new file is created (unless keyword OVERWRITE is true, FILENAME must not already exists). "a" or 'a' - append mode, stream get positionned at last HDU, the header of the last HDU get read and parsed. The default FILEMODE is "r" -- open an existing FITS file for reading. Keyword ENCODING can be used to change the data encoding of the FITS file which is "xdr" for a regular FITS file (XDR means eXternal Data Representation, which is natively used by all IEEE compliant big endian machine). The value of the keyword is a string like: "xdr", "sun" - eXternal Data Representation (the default) "native" - native data representation (i.e. no conversion) "i86", "pc" - IEEE little endian machines ... see documentation for "__sun" for a list of supported encodings. Note that using an encoding different from IEEE big endian (or XDR) violates FITS standard. Keyword OVERWRITE can be used to force overwriting of an existing file (otherwise it is an error to create a file that already exists). Interpreted function, defined at i/fits.i line 561SEE ALSO: fits, fits_read_header, fits_write_header, fits_get, fits_set,

fits_read_array, fits_write_array, fits_next_hdu, fits_new_hdu,

fits_rewind, __sun

fits_pack_bintable

fits_pack_bintable(ptr) -or- fits_pack_bintable(ptr(list)) Packs binary table PTR into a single array; PTR must be a pointer array (e.g. as the one returned by fits_read_bintable which see). The argument can be PTR(LIST) to select or re-order some fields: LIST is a vector of indices of selected and re-ordered fields. The returned array is NROWS-by-NCOLS where NROWS is the first dimension of all fields (which must be the same) and NCOLS is the sum of the second dimension of all fields. Interpreted function, defined at i/fits.i line 2417SEE ALSO: fits_read_bintable

fits_pad_hdu

fits_pad_hdu(fh) Fix file size in handle FH to a multiple of FITS blocking factor (2880 bytes) by writting null or space characters at the end of the file and update FH offsets accordingly. FH must be open for writing. Interpreted function, defined at i/fits.i line 1339SEE ALSO: fits, fits_close, fits_new_hdu

fits_parse

fits_parse(card); -or- fits_parse(card, id); Return value of a single FITS card (CARD is a scalar string). The type of the scalar result is as follow: - string for a string or a commentary FITS card - char ('T' for true or 'F' for false) for a logical FITS card - long for an integer FITS card - double for a real FITS card - complex for a complex FITS card In order to save a call to fits_id, if ID is non-nil it is assumed to be the numerical identifier of the card, i.e. fits_id(CARD). The comment part of CARD is stored into external symbol _fits_parse_comment which is a string (possibly nil) for a valued card and void (i.e. []) for a commentary card. If the SAFE keyword is true, the routine returns an empty result in case of error. Interpreted function, defined at i/fits.i line 2807SEE ALSO: fits, fits_get, fits_id

fits_read

fits_read(filename) -or- local fh; a = fits_read(filename, fh) Open FITS file FILENAME and read data. FH is an optional output symbol where the FITS handle will be stored for future use such as moving to a FITS extension in the same file and reading its header/data. (Note: a FITS handle is a Yorick list that contains a file handle and all header information from the current HDU.) By default, the data get read from the first HDU but this can be changed with the HDU keyword (default HDU=1, i.e. primary HDU). Keyword ENCODING has the same meaning as in fits_open (which see). Keywords WHICH and RESCALE have the same meaning as in fits_read_array (which see). These keywords are ignored if HDU to read is not primary HDU nor an "image" extension. Keywords PACK and SELECT have the same meaning as in fits_read_bintable (which see). Interpreted function, defined at i/fits.i line 438SEE ALSO: fits, fits_write, fits_open, fits_read_array, fits_read_bintable

fits_read_array

fits_read_array(fh) Gets "image" (actually a Yorick array) from current HDU of FITS handle FH. Note that the result may be [] (nil) if the current unit contains no data. Keyword WHICH may be used to indicate which sub-array should be returned. WHICH always applies to the last dimension of the "image" data stored in current HDU. For instance, if the array DATA with dimensions (235,453,7) is stored in the current FITS HDU, the sub-array DATA(,,4) can be obtained by: fits_read_array(FH, which=4); If keyword RESCALE is true, returned values get rescaled according to FITS keywords BSCALE and BZERO. If RESCALE=2 and one of BSCALE and/or BZERO exists in the FITS header and BITPIX was 8, 16, 32, or -32, a single precision array (float) is returned. If RESCALE is not set (nil), the default is to rescale data values if BSCALE is not 1 or BZERO is not 0 (i.e. the default is RESCALE=1). In order to get raw data (i.e. as written in the file), use RESCALE=0. Interpreted function, defined at i/fits.i line 1712SEE ALSO: fits, fits_open

fits_read_bintable

fits_read_bintable(fh) Reads a binary table in current HDU of FITS handle FH and returns the fields of the table as a pointer array (i-th field of the table is pointed by i-th pointer element). Empty fields and fields for unsupported data types (bit array and array descriptor) result in a null pointer (&[]). The geometry of the arrays pointed by the result will be NROWS-by-NCOLS(i) where NROWS is the number of rows in the table and NCOLS(i) is the repeat count of the i-th field in the table (see fits_write_bintable). If NCOLS(i) = 1, the i-th pointer element is the address of a NROWS vector, i.e. not a NROWS-by-1 array. Keyword SELECT can be used to retain only some fields (or re-order them) of the table. For instance, use SELECT=[2,5,3] to return only 2nd, 5th and 3rd fields (in that order) of the table. The fields can also be selected by their names, e.g. SELECT=["flux","distance"] (note that trailing spaces and case is not significant for the field names). If keyword PACK is true, fits_pack_bintable (which see) is used to pack the columns of the binary table into a single array (possibly after selection/re-ordering by SELECT). If keyword TRIM is true, then trailing spaces get removed from string fields (this has no effect if RAW_STRING is true). If keyword RAW_STRING is true, fields made of char's ('A' format) are returned as arrays of char's. The default is to convert 'A' format fields into 1-by-NROWS array of strings. If keyword RAW_LOGICAL is true, logical fields ('L' format) are returned as arrays of char's. The default is to convert 'L' format fields into array of int's as follows: 'T' -> 1 (true), 'F' -> 0 (false), and any other character -> -1 (bad). The 'bad' value can be set by keyword BAD (default is -1). Interpreted function, defined at i/fits.i line 2178SEE ALSO: fits, fits_write_bintable, fits_pack_bintable

fits_read_bintable_as_hashtable

fits_read_bintable_as_hashtable(fh) -or- fits_read_bintable_as_hashtable(fh, h) Read binary table in current HDU (see fits_read_bintable) of FITS handle FH and make it into a hash table. If optional argument H is given, it must be an existing hash table to be augmented with the contents of the binary table. The (augmented) hash table is returned. This function can only be used with the hash table extension. The members of the hash table get named after the value of the 'TTYPEn' card converted to lowercase (where n is the field number). For missing 'TTYPEn' cards, the value of keyword FORMAT is used to define the member name as swrite(format=FORMAT,n). The default value for FORMAT is "_%d". If FORMAT is specified, it must contain exactly one directive to write an integer and no other format directives. If a card 'TUNITn' exists, its value is stored into member with "_units" appended to the corresponding field name. Keywords SELECT, RAW_STRING, RAW_LOGICAL and BAD have the same meaning as in fits_read_bintable. Interpreted function, defined at i/fits.i line 2500SEE ALSO: fits_read_bintable, swrite, h_new

fits_read_header

fits_read_header(fh) (Re)read and parse header of current HDU of FITS handle FH. Contents of FH is updated with header part of new HDU. To allow for linked calls, the returned value is FH. If the current HDU is empty (i.e. last HDU in the file), the header will be empty. Interpreted function, defined at i/fits.i line 774SEE ALSO: fits, fits_open, fits_read_array, fits_next_hdu

fits_rehash

fits_rehash(fh); (Re)compute array of numerical identifier for FITS handle FH (operation is done in-place) and return FH. Interpreted function, defined at i/fits.i line 3136SEE ALSO: fits, fits_id

fits_rewind

fits_rewind(fh) Move FITS handle FH to primary Header Data Unit and parse the header part of the unit. FH is returned when called as a function. Interpreted function, defined at i/fits.i line 913SEE ALSO: fits, fits_read_header, fits_next_hdu

fits_set

fits_set, fh, key, value; -or- fits_set, fh, key, value, comment; Set (or adds) FITS card in header of FITS handle FH. KEY is the card name (FITS keyword) and must be a scalar string, VALUE is the scalar value of the card and COMMENT is an optional string comment. Commentary cards -- for which KEY is one of "COMMENT, "HISTORY" or "" (blank) -- get appended to the existing cards in the header of FH (if the VALUE of a commentary card is too long, it may occupy several FITS cards). For any other kind of cards, the new card replaces the existing one, if any; or get appended to the existing cards. Special cards that must appear in a precise order ("SIMPLE", "BITPIX", "NAXIS" and "NAXIS#") must be added in the correct order (their value can be modified afterward). The "END" card is not needed since it will be automatically written when required. Interpreted function, defined at i/fits.i line 1417SEE ALSO: fits, fits_open

fits_set_dims

fits_set_dims(fh, dimlist) Set NAXIS and NAXIS1, NAXIS2, ... values into current HDU of FITS handle FH according to dimension list DIMLIST. DIMLIST may be empty. Interpreted function, defined at i/fits.i line 1925SEE ALSO: fits, fits_get_dims

fits_tolower

fits_tolower(s) -or- fits_toupper(s) Converts a string or an array of strings S to lower/upper case letters. Interpreted function, defined at i/fits.i line 2569SEE ALSO: fits, fits_trim

fits_toupper

fits_toupper Interpreted function, defined at i/fits.i line 2569SEE fits_tolower

fits_trim

fits_trim(s) Removes trailing spaces (character 0x20) from scalar string S (note: trailing spaces are not significant in FITS). Interpreted function, defined at i/fits.i line 2583SEE ALSO: fits, fits_tolower, fits_toupper

fits_write

fits_write, filename, data; -or- fits_write(filename, data) Creates a new FITS file FILENAME and write array DATA in primary HDU. When called as a function, the result is a FITS handle that can be used to append extensions to the file. FITS "bits-per-pixel" can be specified by keyword BITPIX; otherwise, BITPIX is automatically guessed from the data type (see fits_bitpix_of). Keywords EXTEND, TEMPLATE, HISTORY COMMENT, BSCALE, BZERO, ENCODING and OVERWRITE have the same meaning as in fits_create (to see). If BITPIX is explicitely specified and corresponds to an integer file type (8, 16 or 32) and neither BSCALE nor BZERO are specified, optimal BSCALE and BZERO values will be automatically computed thanks to fits_best_scale (which see). Interpreted function, defined at i/fits.i line 475SEE ALSO: fits, fits_best_scale, fits_bitpix_of, fits_create,

fits_write_header, fits_write_array

fits_write_array

fits_write_array, fh, data; Write array DATA into curent HDU of FITS handle FH. DATA is a so-called "image" in FITS jargon but it can be a numerical array of any-dimension. FITS cards BITPIX, BSCALE and BZERO are taken into account to convert data values into file values. The file values are: (DATA - BZERO)/BSCALE with BZERO=0 and BSCALE=1 by default (i.e. if not found in FH) or if keyword RESCALE is explicitely set to zero. The values are further subject to rounding to the nearest integer and clipping for positive BITPIX. If keyword RESCALE is explicitely set to false (zero), the file values get written without BSCALE/BZERO scale conversion. The N dimensions of DATA must match the values of the NAXIS1, NAXIS2, ..., NAXISn cards of the FITS file (it is assumed that the header information stored in FH are synchronized to the header actually written) extra dimensions in the FITS file are considered as possible data slices. By default, the first data slice get written. Keyword WHICH may be used to write a given slice of data. The value WHICH may be less or equal zero to choose a slice with respect to the last one. EXAMPLE: The following example creates a FITS file with a 100-by-45-by-4-by-7 "image" data made of random values computed and written one 100-by-45 slice at a time: fh = fits_create("newfile.fits", bitpix=16, dimlist=[4,100,45,4,7], bscale=1e-4, bzero=0.0); fits_write_header, fh; nslices = 4*7; // product of last FITS dimensions for (i=1 ; i<=nslices ; ++i) fits_write_array, fh, random(100, 45), which=i; fits_close, fh; Interpreted function, defined at i/fits.i line 1789SEE ALSO: fits, fits_write, fits_write_header

fits_write_bintable

fits_write_bintable(fh, ptr) Writes contents of pointer PTR in a binary table in FITS handle FH. Arrays pointed by PTR become the fields of the table (in the same order as in PTR) and must all have 1 or 2 dimensions with the same first dimension (i.e. the number of rows in the table), second dimensions can have any values and may all be different: they count as the number of 'columns' of the field. In other words: *PTR(i) = i-th field in the table, is an NROWS-by-NCOLS(i) array where NROWS is the number of rows in the table and NCOLS(i) is the repeat count of the i-th field; it can also be simply a NROWS element vector if NCOLS(i) = 1. In the current version of the routine, only arrays of numbers (char, short, int, long, float, double or complex) and vectors of strings (you can use several vectors to circumvent this limitation) are supported. Before writing the data part of a binary table, you must creates proper header: fits_new_bintable, fh; // starts a new binary table fits_set, fh, "...", ...; // (optional) set more info. in header fits_set, ...; fits_write_bintable, fh, ptr; // write binary table fits_write_bintable automatically guess the format of the fields in the binary table and accordingly set FITS cards "TFORM#" (with # equal to the field number) in the header of the binary table. If keyword LOGICAL is true (non nil and non-zero) then arrays of int's in PTR are considered as logical arrays and saved as arrays of characters: 'F' for false, 'T' for true or '\0' for bad/invalid value. Following Yorick's convention, a "false" value is integer zero in the arrays of int's and a "true" is any non-zero integer. However, if LOGICAL has the special value 2, then strictly positive integers are treated as "true" values and strictly negative integers are treated as invlaid values. Note that this only affect arrays of int's (not long's nor short's nor char's). The default is to save arrays of int's as array of 32 bits integers. The returned value is FH. Interpreted function, defined at i/fits.i line 2007SEE ALSO: fits, fits_new_bintable, fits_read_bintable

fits_write_header

fits_write_header(fh) Write header information of FITS handle FH into current HDU of associated file. It is possible to re-write header as long as this would not overwrite existing written data if any (i.e. the new header, rounded up to a multiple of 2880 bytes, must not be longer than the old one or there must be no data written. Interpreted function, defined at i/fits.i line 1235SEE ALSO: fits, fits_open, fits_write, fits_write_array

floor

floor(x) returns the largest integer not greater than x (no-op on integers). Builtin function, documented at i0/std.i line 715SEE ALSO: ceil

fma

fma frame advance the current graphics window. The current picture remains displayed in the associated X window until the next element is actually plotted. Builtin function, documented at i0/graph.i line 310SEE ALSO: window, hcp, animate, plg

form_mesh

form_mesh(zsym, khold, lhold) returns an opaque "mesh" object, which will hold rt, zt, ireg, and a boundary edge list. This opaque mesh object is required as an input to the integ_flat and integ_linear routines. ZSYM is 2 for spherical symmetry, 1 for z=0 reflection symmetry, or 0 for no symmetry KHOLD and LHOLD are the 1-origin indices of "hold" lines in the mesh, or 0 if none. This information is used only during the pcen_source operation before integ_linear is called. Builtin function, documented at i0/drat.i line 1071SEE ALSO: update_mesh, integ_flat, integ_linear

form_rays

best= form_rays( [x, y, z, theta, phi] ) or dirt= form_rays( [x, y, theta] ) or internal= form_rays( [cos, sin, y, z, x, r] ) forms 5-by-nrays, 3-by-nrays, or 6-by-nrays ray representation given individual lists of array coordinates. The [...] operator builds an nrays-by-5, nrays-by-3, or nrays-by-6 array, which form_rays transposes. The "nrays" may represent zero or more actual dimensions. Interpreted function, defined at i/rays.i line 27SEE ALSO: best_rays, dirt_rays, internal_rays, picture_rays