next up previous contents
Next: Astronomical Stuff Up: Commands currently recognized Previous: 3D Data

Data Analysis Commands

The data analysis commands which fold data or subtract a fitted function result in the plot area being rescaled. Folding data overwrites the internal ROBOT data arrays. Arithmetic operations and functions of the x and y arrays don't rescale the plot area. To rescale the area manually use the command RESCALE.
SORT - sorts the data into ascending x values. Sorts x , y and associated error arrays but not z array.
SORTY - as SORT but sorts by y value.
SMOOTH - smooth data by convolving with a triangle. Replaces each point with half its original value plus a quarter of the points on either side.
SMOOTHN - as smooth but repeat the smoothing several times. Argument: no. of times to smooth data.
REBIN - sum together bins to create new arrays. Argument: no. of old bins to make one new one. The SMOOTH and REBIN commands are obviously best suited to evenly spaced data with no gaps.
LOGX - take log10 of x values.
LOGY - take log10 of y values.
LOGXY - take log10 of both x and y values.
XFITLIMITS - restricts the data range to be used when making fits to the data. Argument: low x, high x fitting limits.
YFITLIMITS - restrict fitting limits based on y values. Argument: low y, high y fitting limits.
XYFITLIMITS - restrict fitting limits using both x and y values. Argument: low x, low y, high x, high y.
DFLIMITS - restrict both plotting area and fit limits. Equivalent to a combination of DATALIMITS and XYFITLIMITS. Argument: low x, low y, high x, high y. DFLIMITS is the most frequently used method of selecting a portion of data for display/analysis. ROBOT will try and adjust your plotting limits to make them ``nicer''. If you don't want this enclose fixed values in (brackets). This method is also used to obtain ``upside-down'' plots. e.g. for plotting astronomical magnitudes.
MOMENTS - calculate sum, mean, standard deviation, standard error, skewness and kurtosis of x and y arrays.
MEDIAN - median value of y array.
MEDIANX - median value of x array.
SUMDATA - calculate sum of y values in the range specified by e.g. XFITLIMITS.
INTEGRATE - integrate the area under the curve defined by the data points.
XARITH - perform arithmetic on the x values. Arguments: 1) arithmetic operation, i.e. +, -, /, * or **; 2) operand; either a number or x, y, xerr, yerr or z to operate using the numbers in these arrays. N.B. only the * and / operations also change the error arrays if an operation is made on a data array.
YARITH, ZARITH, XERRARITH, YERRARITH - as XARITH but on the y, z, x error and y error arrays respectively.
XFUNCTION - replace the x array with a function of x. Argument: the type of function; e.g. SQUARE, SQRT, CUBERT, INVERSE, FACTORIAL, SINE, COS, TAN, ASINE, ACOS, ATAN, LOG (base 10), LOGE and LOG2 (base 2). The trigonometric functions all assume degrees.
YFUNCTION, ZFUNCTION - as XFUNCTION but for the y and z arrays respectively.
ZRESET - sets the z array to zero.
LINFIT - make a straight line fit to the data and calculate the linear correlation coefficient and its significance.
PLOTFIT - plot the straight line fit.
KENDALL - non-parametric test of correlation between x and y values.
POLFIT - fit a polynomial to the data. Argument: order of the polynomial to be fitted.
PLOTPOLY - plot the results of the polynomial fit.
SUBPOLY - subtract the polynomial fit from the data.
FOLD - fold the data on specified period. Argument: period and phase zero.
BINFOLD - fold the data into bins. Also calculates the [tex2html_wrap_inline277] value for the hypothesis of source constancy. Argument: period, phase zero and the no. of bins to fold the data into.
FINDPERIOD - period search using the BINFOLD routine. Argument: start period, end period, period step and the number of bins to fold the data into.
BINFOLDBEST - fold and bin the data on the best period found by FINDPERIOD.
FOLDBEST - fold the data on the best period found by FINDPERIOD but don't bin it.
PERIODOGRAM - like FINDPERIOD but plots the periodogram. Argument: as in FINDPERIOD. N.B. you can also search for periods by fitting sine waves to your data and looking for [tex2html_wrap_inline279] minima. Use GRID followed by CURFIT and grid the period.
POWER - Calculates power spectrum of data using a Fourier transform. The power spectrum is plotted against frequency. The strongest peak is found and the ``FOLDBEST" routine will take the corresponding period automatically. If ``OVERWRITE'' is true then the data is overwritten with the power spectrum. If ``WEIGHTFT'' is set then data points are weighted by the inverse square of their errors.
FFT - for evenly spaced data the Fast Fourier Transform can be used. If the number of data points is not an integer power of two the default is to truncate the data. Alternatively the data can be padded with the mean of the data.
FFTMODE - takes a value of either TRUNCATE (the default), PAD, or NEAREST. NEAREST uses the logarithmically closest value to either pad or truncate.
OVERWRITE - enables the FFT and POWER routines to overwrite the data with the power spectrum. By default this is FALSE.
NOOVERWRITE - stops the FFT and POWER routines overwriting data. This is the default.
WEIGHTFT - For the POWER routine only the power spectrum is weighted by the inverse square of each data point. This is not used by the FFT routine. While this appears to be formally correct, it should be used with caution. Sometimes it appears to improve the results, other times it doesn't.
NOWEIGHTFT - don't weight points for the POWER routine. This is the default.
RANDOMISE/RANDOMIZE - replaces y values with Gaussian distributed random numbers having the same mean and standard deviation as the original data set. If MOMENTS has not already been called it calls this to evaluate the mean and standard deviation of the current data.
GRANDOMISE/GRANDOMIZE - same as the regular randomize command except that, instead of taking the standard deviation of the input data, the standard deviation is the square root of the mean of the input data.
FITMODE - determines the weighting of data points in the fit. Argument: 1 for weighting by errors in the y error array, 0 for no weighting and --1 for weighting by inverse of y array (e.g. Poisson errors). Default is weight by errors in y error array.
CURFIT - generalized fitting routine using the famous Bevington routine. You can add many models together. The following models are currently supported: POLYNOMIAL, TRIANGLE, LORENTZ, GAUSS, POWERLAW, EXPONENTIAL, SINE, BLACKBODY, TOPHAT, ORBIT and USER. End of models is signaled by ENDMODELS. After each function give initial guesses for each parameter. Polynomial: initial guesses for coefficients (all on one line). The order of the polynomial is automatically determined from the number of parameters. Triangle: height, start of function, half width at zero. Lorentz: normalization, mean and width. Gauss: normalization, mean and width. Powerlaw: normalization and power. Exponential: normalization, start time and decay time. Sine: amplitude, phase and period. Blackbody: normalization and kT in units of the x axis. Top hat: height, start of function and width. Orbit: amplitude, phase period, mean value, eccentricity and omega. The TOPHAT function is almost impossible to fit without CURFIT crashing! It is very easy to add new models so please tell me if there are any others you want included. Currently up to 10 models can be added together. The same model type may be specified as many times as you want (e.g. 5 Gaussians plus a polynomial is O.K.).

To write your own model to fit with CURFIT you need to write a FORTRAN subroutine called USER. An example of the type of function you can write is:
C Function User.
C An example of a user supplied function for use with the ``CURFIT" command in
C ROBOT. This routine is for a straight line fit; much more complicated
C functions can be used as long as the basic format is retained.
FUNCTION USER(A,X)
REAL A(*), X
USER = A(1)+A(2)*X
END
The equivalent in C is:
float user_(a, x)
float *a, *x;
{
float ret_value;
--a;
ret_value = a[1] + a[2]* *x;
return ret_value;
}

For the X windows and Fujitsu versions you will need to relink ROBOT, for the Mac program you just need to compile your subroutine as the Mac FORTRAN compiler can link your subroutine during run time order that your subroutine uses them. You can combine your model together with the other models already available with ROBOT.

If you want to fix a parameter in the list of input parameters to any model enclose that parameter in (brackets). Any number of parameters (including all of them) may be fixed. If you want to produce a grid of [tex2html_wrap_inline281] square against the value of a particular parameter enclose it in <this type of bracket>. The default is to produce the grid using values of the parameter ranging from + to - 3 times the error found by the curfit (before doing the grid a fit is done with the parameter free) with steps of one fifth the supposed error. If you don't want to use these defaults use the command:
GRID - to specify the grid range. Argument: start value for grid, end value, step size. In this case no fit with the parameter free is done. Currently only one parameter at a time can be gridded.
PLOTCUR - plots the fitted function.
SUBCUR - subtracts the fitted function from the data.
ADDCUR - adds the fitted function to the data.
CURMODELPLOT - plots individual fitted models. Argument: either ALL for all models, a single number (e.g. 2) to just plot that model number or e.g. 3:6 to plot individual model numbers 3 to 6. The model number is its sequence in the list you gave to CURFIT.
CONVERGENCE - changes convergence conditions. Argument: fractional change of [tex2html_wrap_inline287] at which to stop and maximum number of times to call CURFIT. Default is fractional change in [tex2html_wrap_inline289] = 0.01, call CURFIT 10 times.
FITDELTA - changes step values used in calculating derivatives of parameters of fit. The steps are parameter value divided by the FITDELTA value.
PREDICT - once a fit has been made ``PREDICT" gives the expected ``y" value from the fit for a given ``x" value.
WRITEDATA - write data to specified file. Argument: output file name. Only data inside the region defined for plotting (e.g. via DFLIMITS) is written to the output file.
CCF - calculates the cross correlation coefficient of the data already inside ROBOT with a specified input file as a function of shift in X. This input file must have a ``DATAFILE" format with three lines of text at the top. This command can be used for doing pulse arrival time analysis where you fold data using the BINFOLD command and then use CCF to get the relative phase vs. a template. The CCF is calculated simply by shifting bins and multiplying, however it centroids the cross-correlation function and so can give results more accurate than one bin width.



next up previous contents
Next: Astronomical Stuff Up: Commands currently recognized Previous: 3D Data



Robin Corbet
Sat May 3 16:56:08 EDT 1997