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