DOCUMENTATION FOR KURODA'S ALGORITHM Peter J. Wilcoxen Departments of Economics and Public Administration The Maxwell School, Syracuse University wilcoxen@maxwell.syr.edu This note describes the FORTRAN source code used to implement Kuroda's method of adjusting a bi-proportional matrix. The method itself is described in a separate document titled "Kuroda's Method for Constructing Consistent Input-Output Data Sets." An Adobe Acrobat version of the paper is contained in the accompanying file called kuroda.pdf. You should print out and read kuroda.pdf before trying to use these programs. The code is divided into four files, each of which is described below. The most important part, the algorithm itself, is contained in a subroutine called "kuroda" in file KURODA.FOR. It was written as a subroutine to allow it to be incorporated into other programs easily. FIT.FOR is a sample main program which asks the user several questions and then calls KURODA. It demonstrates how KURODA can be used, but it is not suitable for all applications. Usually, it will be necessary to rewrite FIT for the particular application at hand. Two other files are needed: LUDCMP.FOR, a library of numerical subroutines required by KURODA, and LIBRARY.FOR, a library of miscellaneous required by FIT and KURODA. FIT.FOR is a typical main program for use with KURODA. Generally, it should be modified or rewritten entirely to fit the needs of a particular application. As it stands, however, it works in the following way. First, FIT prompts for the following information: (1) the name of an input file to process, (2) the name of an output file to be written, (3) the name of a summary file to be written, (4) the weighting method to be used. Each of these should be an ordinary string of text, as shown in the sample answers below: INPUT.DAT (input file) OUTPUT.DAT (output file) SUMMARY.DAT (summary file) kuroda (weighting method, see below) Next, it reads the input file. The input file must be ordinary text which can be read by FORTRAN free-format read statements, and should contain the following information: (1) the dimensions of the array, (2) the array's original contents, (3) the row targets, (4) the column targets. The format of the input file is best described by an example. Suppose the original array to be adjusted was 3x4 and had the elements shown below: 0 0 0 0 1 2 1 0 0 1 1 0 The rows sum to (0,4,2)', while the columns sum to (1,3,2,0). Next, suppose that the desired row and column sums were (0,4,3)' and (2,3,2,0). Given this problem, the input file would look as follows: 3 4 <-- number of rows and columns in the array 3 <-- number of rows in column 1 0 } 1 } contents of column one 0 } 3 <-- number of rows in column 2 0 } 2 } contents of column two 1 } 3 <-- number of rows in column 3 0 } 1 } contents of column three 1 } 3 <-- number of rows in column 4 0 } 0 } contents of column four 0 } 3 <-- number of row targets 0 } 4 } targets for rows 3 } 4 <-- number of column targets 2 3 2 0 } targets for columns Needless to say, the explanatory information to the right of each line would not be included in the input file. Also, the seemingly redundant specification of the number of rows in each column (and columns in the target row) is deliberate. It helps ensure that the input file does not become corrupted. For many applications, this input file format will not be convenient, so the corresponding part of FIT may have to be rewritten. After reading the input file, FIT calls KURODA to do the actual adjustment. The arguments to KURODA are the following: weight (i,c) indicates weighting method (see below) x (i,a) original matrix np (i,i) number of rows of x and xn as dimensioned n (i,i) number of logical rows in x and xn m (i,i) number of logical columns in x and xn r_tar (i,a) vector of row targets c_tar (i,a) vector of column targets xn (o,a) new, adjusted matrix pfile (i,c) name of optional output file The first letter in parentheses shows whether the variable is input (i) or output (o). The second letter shows whether it is character (c), integer (i), or array of double precision (a). The original matrix should be in array x, with targets in vectors r_tar and c_tar. The adjusted array will be in xn. If pfile is not blank, it gives the name of a file to be used to write summary information. Kuroda's algorithm can be used with several different weight methods. As written, KURODA offers five choices of weighting (NOTE: THESE MUST BE WRITTEN IN LOWER CASE LETTERS): kuroda > as described in the accompanying paper sumsq > use squares of row and column targets equal > weight rows and columns equally rows > only rows relevant, columns ignored columns > only columns relevant, rows ignored Generally, "kuroda", "sumsq" or "equal" are most useful, and produce fairly similar adjusted matricies. "kuroda" tends to be the most reluctant to generate negative entries in the finished matrix, so it is often the best one to use. The final two methods are used in special circumstances. For example, "columns" might be used if the initial column shares are thought to be reliable while the row shares are unreliable. This is sometimes the case with input-output data. None of these schemes is guaranteed not to produce negative entries, so always check the results. Finally, FIT produces an output file which has the same structure as the input file, but excludes the row and column targets. LIST OF FILES ------------- README.TXT This file KURODA.PDF Adobe Acrobat file describing the mathematical structure of the algorithm FIT.FOR Main program KURODA.FOR Subroutine KURODA LUDCMP.FOR Miscellaneous numerical routines LIBRARY.FOR Miscellaneous library routines FIT.EXE Compiled version for use under DOS; requires the DOS extender DOS4GW.EXE DOS4GW.EXE DOS extender used by FIT.EXE TESTINP.DAT Sample input file TESTOUT.DAT Output file for TESTINP.DAT using kuroda weighting TESTSUM.DAT Summary file for TESTINP.DAT HOW TO USE THE SOURCE CODE -------------------------- (1) Under Windows you can use the executable provided (fit.exe). Make sure that fit.exe is in the current directory or is in your path and then skip to step 3. (2) For operating systems other than Windows you'll need to recompile the source files. Here's how it would be done under Unix: f77 -o fit fit.for kuroda.for ludcmp.for library.for (3) Run the program on the test file. Here's how it would look under Windows: c:> fit Input file: testinp.dat Output file: testout.new Summary file: testsum.new Weighting method: kuroda (4) Check whether the results are correct. TESTOUT.NEW should be the same as TESTOUT.DAT up to 10 digits or so. TESTSUM.NEW should be identical to TESTSUM.DAT.