README.TXT CREDITS: First off, STEPIT was written by J.P. Chandler as (I believe) his Ph.D. thesis. I did not write it, but I did attempt to port it from Fortran77 to Matlab, which is why you are reading this file. PLEASE NOTE that this is a work in progress!! I have run this program on data sets and compared the results to the original STEPIT program in Fortran, and the results line up exactly. However, I am sure there are bugs I am not aware of, simply because it is difficult for one soul to explore all the areas where something can go wrong. This was written as an ancillary part of another project, so for that reason I have been unable to do the debugging and optimization myself. Please contact me at hoffa@uab.edu with any suggestions, bug reports, bug fixes, improvements, expletives, etc. PART I. MODIFYING FOR YOUR NEEDS: First, I suggest taking a look at the original code by Chandler; he has provided extensive comments on variables and the general working of the program, to which I have adhered as closely as posssible. The actual code structure itself has changed, due to the translation of numerous GOTO statements in the original code to FOR and WHILE LOOPS. This is the reason for the numerous private routines included in this program. STEPITDRIVER2.m--The driver file for this program. There are four sections in the actual code that must be modified for any particular model as defined by private_FUNK.m. NPTS-User input; specifies the number of data points under consideration The first section specifies the number of actual parameters for the model/function as specified by FUNK, and the max number of parameters (vestigal variable left over from the FORTRAN CODE; there are, unfortunately, a number of instances of this sort of thing) The second section specifes a data matrices T, Y, and YSIG, from which data values are read in line by line in section 3. Notice that these matrices are specified according to the model I have picked in private_FUNK.m They must be modified according to whatever function you are interested in. The third section reads in data specified by the second section. The fourth section sets the initial guesses for the (in this case) 3 parameters specified in private_FUNK.m private_FUNK.m--The main file where you enter whatever model/function you are interested in. Depending on your needs, you will have to specify particular data matrices in STEPITDRIVER2.m above. In this case I have specified a 3 parameter model, in which the 2 independent variables are stored in data matrix T(i,1) and T(i,2) respectively, where the length of T is specified by NPTS. The independent data is stored in Y and the variance at each point is stored in YSIG. Again, these matrices have been created specifically for this model in STEPITDRIVER2.m as described above. DATA FILES--x1.txt, x2.txt, y.txt, ysig.txt -For the model specified in funk, the above 4 data files have been included. Notice that in STEPITDRIVER2 there are several input lines in the third section from which data is read from these matrices and used to fill T(i,1), T(i,2), Y(i), and YSIG(i) respectively, where the length of each matrix must match exactly with NPTS. PART II-- OTHER FILES The other files necessary for the proper operation of STEPIT include the following: private_110_ROUTINE.m private_140_ROUTINE.m private_210_ROUTINE.m private_290_ROUTINE.m private_380_ROUTINE.m private_390_ROUTINE.m private_530_ROUTINE.m private_570_ROUTINE.m private_90_ROUTINE.m private_FORLOOP_ROUTINE1.m private_STBEG2.m private_STSET.m private_KFLAG_EXIT.m STEPIT10.m Each of the private_##_ROUTINE.m files corresponds to a particular GOTO statement found at the same line ## in Chandler's original STEPIT FORTRAN77 code. (the ## in private_##_ROUTINE.m is the same ## as line number ## in Chandler's code--this makes sense if you read it enough). Because there are many nasty GOTO's nested within other GOTO's, each of these files makes use of horrible while-for-else-loops that may be somewhat hard to debug, but which are much clearer than the original GOTO statements in the code. Beyond that, I refer you to Chandler's code to see what is going on... it is simply too much to go into here. private_FORLOOP_ROUTINE1.m--this is the main workhorse file. Bugs will likely creep up here, as this is where all of the private_##_ROUTINE.m files are called from. It is called from the smaller but meta-important STEPIT10.m file. private_STBEG2.m--this sets some initial parameter values for STEPITDRIVER2.m and STEPIT10.m It corresponds directly to the STBEG routine as found in the original Chandler Fortran 77 code. private_STSET.m--this sets some other initial parameters, and corresponds directly to a subroutine of the same name in the Chandler's Fortran77 program. private_KFLAG_EXIT.m--This file determines the exit status for STEPIT10.m, i.e. how the program terminates. See Chandler's code for the possible exit statuses, or examine this file more closely. Notice for successful exits, a line will appear--'STERR CALLED.' Unfortunately, I have yet to port STERR.f to Matlab, so this is all you get! STERR is not part of Chandler's STEPIT per say, it simply calculates some statistical estimates of the accuracy of the values that STEPIT produces. Its absence in this particular port does nothing to affect the validity of STEPIT's calculations. PART III-- YOUR HELP! Please, try this program out. See how well it works. Try it on several models. For those of you have experience with Chandler's original Fortran 77 program, compare the results from the two programs. I know that many people would like the convenience of using STEPIT in Matlab, and that is what this program aims to do. Please report any bugs you may have to me at hoffa@uab.edu. Even better, please try to improve this program yourself. I know there are many people out there with much more experience with STEPIT than me, and I both welcome and encourage any suggestions you may have, and certainly welcome any help I can get. Thanks!!!! Jason P. Lott University of Alabama at Birmingham hoffa@uab.edu July 2001