Doxygen Source Code Documentation
NLfit.h
Go to the documentation of this file.00001 /***************************************************************************** 00002 Major portions of this software are copyrighted by the Medical College 00003 of Wisconsin, 1994-2000, and are released under the Gnu General Public 00004 License, Version 2. See the file README.Copyright for details. 00005 ******************************************************************************/ 00006 00007 /* 00008 This is the header file for NLfit.c. 00009 00010 File: NLfit.h 00011 Author: B. Douglas Ward 00012 Date: 3 June 1997 00013 00014 Mod: Added options for percent signal change above baseline, and 00015 calculation of area under the signal above baseline. 00016 Date: 26 November 1997 00017 00018 Mod: Added novar flag to eliminate unnecessary calculations. 00019 Date: 13 July 1999 00020 00021 Mod: Changes for output of R^2 (coefficient of multiple determination), 00022 and standard deviation of residuals from full model fit. 00023 Added global variable calc_tstats. 00024 Also, added screen display of p-values. 00025 Date: 10 May 2000 00026 00027 */ 00028 00029 /*---------------------------------------------------------------------------*/ 00030 00031 #ifndef _NLFIT_HEADER_ 00032 #define _NLFIT_HEADER_ 00033 00034 #include "NLfit_model.h" 00035 00036 00037 /*---------------- global data -------------------*/ 00038 static char lbuf[4096] ; 00039 static char sbuf[256] ; 00040 00041 static int calc_tstats = 0; /* set to 1 for calculating t-stats */ 00042 00043 00044 /*---------------------------------------------------------------------------*/ 00045 /* 00046 Routine to print error message and stop. 00047 */ 00048 00049 void NLfit_error 00050 ( 00051 char * message /* message to be displayed */ 00052 ); 00053 00054 00055 /*---------------------------------------------------------------------------*/ 00056 /* 00057 Routine to initialize the signal model by defining the number of parameters 00058 in the signal model, the default values for the minimum and maximum 00059 parameter constraints, and setting the pointer to the function which 00060 implements the signal model. 00061 */ 00062 00063 void initialize_signal_model 00064 ( 00065 NLFIT_MODEL_array * model_array, /* the array of SO models */ 00066 char * sname, /* name of signal model (user input) */ 00067 vfp * smodel, /* pointer to signal model */ 00068 int * p, /* number of parameters in the signal model */ 00069 char ** spname, /* signal parameter names */ 00070 float * min_sconstr, /* minimum parameter constraints for signal model */ 00071 float * max_sconstr /* maximum parameter constraints for signal model */ 00072 ); 00073 00074 00075 /*---------------------------------------------------------------------------*/ 00076 /* 00077 Routine to initialize the noise0 model by defining the number of parameters 00078 in the noise model, the default values for the minimum and maximum 00079 parameter constraints, and setting the pointer to the function which 00080 implements the noise model. 00081 */ 00082 00083 void initialize_noise_model 00084 ( 00085 NLFIT_MODEL_array * model_array, /* the array of SO models */ 00086 char * nname, /* name of noise model (user input) */ 00087 vfp * nmodel, /* pointer to noise model */ 00088 int * r, /* number of parameters in the noise model */ 00089 char ** npname, /* noise parameter names */ 00090 float * min_nconstr, /* minimum parameter constraints for noise model */ 00091 float * max_nconstr /* maximum parameter constraints for noise model */ 00092 ); 00093 00094 00095 /*---------------------------------------------------------------------------*/ 00096 /* 00097 Routine to calculate the least squares linear regression. 00098 */ 00099 00100 void calc_linear_regression 00101 ( 00102 matrix x, /* matrix of constants */ 00103 vector y, /* observation vector */ 00104 vector * b, /* estimated regression coefficients */ 00105 float * sse /* error sum of squares */ 00106 ); 00107 00108 00109 /*---------------------------------------------------------------------------*/ 00110 00111 void calc_reduced_model 00112 ( 00113 int n, /* number of observations */ 00114 int r, /* number of parameters in reduced model */ 00115 float ** x_array, /* data matrix */ 00116 float * y_array, /* observed time series */ 00117 float * b_array, /* estimated parameters for reduced model */ 00118 float * sse /* error sum of squares */ 00119 ); 00120 00121 00122 /*---------------------------------------------------------------------------*/ 00123 /* 00124 Routine to allocate memory required for calculation of the full model. 00125 */ 00126 00127 void initialize_full_model 00128 ( 00129 int dimension, /* number of parameters in full model */ 00130 int nbest, /* keep nbest vectors from random search */ 00131 float *** parameters, /* array of parameter vectors */ 00132 float ** sse /* array of error sum of squares */ 00133 ); 00134 00135 00136 /*---------------------------------------------------------------------------*/ 00137 /* 00138 Routine to determine if the parameter vector violates the constraints. 00139 */ 00140 00141 int calc_constraints 00142 ( 00143 int r, /* number of parameters in the noise model */ 00144 int p, /* number of parameters in the signal model */ 00145 int nabs, /* use absolute constraints for noise parameters */ 00146 float * b_array, /* estimated parameters for the reduced model */ 00147 float * min_nconstr, /* minimum parameter constraints for noise model */ 00148 float * max_nconstr, /* maximum parameter constraints for noise model */ 00149 float * min_sconstr, /* minimum parameter constraints for signal model */ 00150 float * max_sconstr, /* maximum parameter constraints for signal model */ 00151 float * vertex /* test parameter vector */ 00152 ); 00153 00154 00155 /*---------------------------------------------------------------------------*/ 00156 /* 00157 Calculate the estimated time series using the full model. 00158 */ 00159 00160 void full_model 00161 ( 00162 vfp nmodel, /* pointer to noise model */ 00163 vfp smodel, /* pointer to signal model */ 00164 float * gn, /* parameters for noise model */ 00165 float * gs, /* parameters for signal model */ 00166 int ts_length, /* length of time series data */ 00167 float ** x_array, /* independent variable matrix */ 00168 float * yhat_array /* output estimated time series */ 00169 ); 00170 00171 00172 /*---------------------------------------------------------------------------*/ 00173 /* 00174 This routine calculates the error sum of squares corresponding to 00175 the given vector of parameters for the full model. 00176 */ 00177 00178 float calc_sse 00179 ( 00180 vfp nmodel, /* pointer to noise model */ 00181 vfp smodel, /* pointer to signal model */ 00182 int r, /* number of parameters in the noise model */ 00183 int p, /* number of parameters in the signal model */ 00184 int nabs, /* use absolute constraints for noise parameters */ 00185 float * min_nconstr, /* minimum parameter constraints for noise model */ 00186 float * max_nconstr, /* maximum parameter constraints for noise model */ 00187 float * min_sconstr, /* minimum parameter constraints for signal model */ 00188 float * max_sconstr, /* maximum parameter constraints for signal model */ 00189 float * b_array, /* estimated parameters for the reduced model */ 00190 float * vertex, /* test parameter vector */ 00191 int ts_length, /* length of time series array */ 00192 float ** x_array, /* independent variable matrix */ 00193 float * ts_array /* observed time series */ 00194 ); 00195 00196 00197 /*---------------------------------------------------------------------------*/ 00198 /* 00199 Select and evaluate randomly chosen vectors in the parameter space. 00200 */ 00201 00202 void random_search 00203 ( 00204 vfp nmodel, /* pointer to noise model */ 00205 vfp smodel, /* pointer to signal model */ 00206 int r, /* number of parameters in the noise model */ 00207 int p, /* number of parameters in the signal model */ 00208 int nabs, /* use absolute constraints for noise parameters */ 00209 float * min_nconstr, /* minimum parameter constraints for noise model */ 00210 float * max_nconstr, /* maximum parameter constraints for noise model */ 00211 float * min_sconstr, /* minimum parameter constraints for signal model */ 00212 float * max_sconstr, /* maximum parameter constraints for signal model */ 00213 int ts_length, /* length of time series array */ 00214 float ** x_array, /* independent variable matrix */ 00215 float * ts_array, /* observed time series */ 00216 float * par_rdcd, /* estimated parameters for the reduced model */ 00217 int nrand, /* number of random vectors to generate */ 00218 int nbest, /* number of random vectors to keep */ 00219 float ** parameters, /* array of best random vectors */ 00220 float * response /* array of best sse's */ 00221 ); 00222 00223 00224 /*---------------------------------------------------------------------------*/ 00225 /* 00226 Estimate the parameters for the full model. 00227 */ 00228 00229 void calc_full_model 00230 ( 00231 vfp nmodel, /* pointer to noise model */ 00232 vfp smodel, /* pointer to signal model */ 00233 int r, /* number of parameters in the noise model */ 00234 int p, /* number of parameters in the signal model */ 00235 float * min_nconstr, /* minimum parameter constraints for noise model */ 00236 float * max_nconstr, /* maximum parameter constraints for noise model */ 00237 float * min_sconstr, /* minimum parameter constraints for signal model */ 00238 float * max_sconstr, /* maximum parameter constraints for signal model */ 00239 int ts_length, /* length of time series array */ 00240 float ** x_array, /* independent variable matrix */ 00241 float * ts_array, /* observed time series */ 00242 float * par_rdcd, /* estimated parameters for the reduced model */ 00243 float sse_rdcd, /* error sum of squares for the reduced model */ 00244 int nabs, /* use absolute constraints for noise parameters */ 00245 int nrand, /* number of random vectors to generate */ 00246 int nbest, /* number of random vectors to keep */ 00247 float rms_min, /* minimum rms error required to reject rdcd model */ 00248 float * par_full, /* estimated parameters for the full model */ 00249 float * sse_full, /* error sum of squares for the full model */ 00250 int * novar /* flag for insufficient variation in data */ 00251 ); 00252 00253 00254 /*---------------------------------------------------------------------------*/ 00255 /* 00256 Routine to calculate the partial derivative matrix, evaluated at the 00257 estimated parameter location. 00258 */ 00259 00260 void calc_partial_derivatives 00261 ( 00262 vfp nmodel, /* pointer to noise model */ 00263 vfp smodel, /* pointer to signal model */ 00264 int r, /* number of parameters in the noise model */ 00265 int p, /* number of parameters in the signal model */ 00266 float * min_nconstr, /* minimum parameter constraints for noise model */ 00267 float * max_nconstr, /* maximum parameter constraints for noise model */ 00268 float * min_sconstr, /* minimum parameter constraints for signal model */ 00269 float * max_sconstr, /* maximum parameter constraints for signal model */ 00270 int ts_length, /* length of time series data */ 00271 float ** x_array, /* independent variable matrix */ 00272 float * par_full, /* estimated parameters for the full model */ 00273 matrix d /* matrix of estimated partial derivatives */ 00274 ); 00275 00276 00277 /*---------------------------------------------------------------------------*/ 00278 00279 void analyze_results 00280 ( 00281 vfp nmodel, /* pointer to noise model */ 00282 vfp smodel, /* pointer to signal model */ 00283 int r, /* number of parameters in the noise model */ 00284 int p, /* number of parameters in the signal model */ 00285 int novar, /* flag for insufficient variation in the data */ 00286 float * min_nconstr, /* minimum parameter constraints for noise model */ 00287 float * max_nconstr, /* maximum parameter constraints for noise model */ 00288 float * min_sconstr, /* minimum parameter constraints for signal model */ 00289 float * max_sconstr, /* maximum parameter constraints for signal model */ 00290 int ts_length, /* length of time series data */ 00291 float ** x_array, /* independent variable matrix */ 00292 float * par_rdcd, /* estimated parameters for the reduced model */ 00293 float sse_rdcd, /* error sum of squares for the reduced model */ 00294 float * par_full, /* estimated parameters for the full model */ 00295 float sse_full, /* error sum of squares for the full model */ 00296 float * rmsreg, /* root-mean-square for the full regression model */ 00297 float * freg, /* f-statistic for the full regression model */ 00298 float * rsqr, /* R^2 (coef. of multiple determination) */ 00299 float * smax, /* signed maximum of signal */ 00300 float * tmax, /* epoch of signed maximum of signal */ 00301 float * pmax, /* percentage change due to signal */ 00302 float * area, /* area between signal and baseline */ 00303 float * parea, /* percentage area between signal and baseline */ 00304 float * tpar_full /* t-statistic of the parameters in the full model */ 00305 ); 00306 00307 00308 /*---------------------------------------------------------------------------*/ 00309 /* 00310 Report results for this voxel. 00311 */ 00312 00313 void report_results 00314 ( 00315 char * nname, /* name of noise model */ 00316 char * sname, /* name of signal model */ 00317 int r, /* number of parameters in the noise model */ 00318 int p, /* number of parameters in the signal model */ 00319 char ** npname, /* noise parameter names */ 00320 char ** spname, /* signal parameter names */ 00321 int ts_length, /* length of time series array */ 00322 float * par_rdcd, /* estimated parameters for the reduced model */ 00323 float sse_rdcd, /* error sum of squares for the reduced model */ 00324 float * par_full, /* estimated parameters for the full model */ 00325 float sse_full, /* error sum of squares for the full model */ 00326 float * tpar_full, /* t-statistic of the parameters in full model */ 00327 float rmsreg, /* root-mean-square for the full regression model */ 00328 float freg, /* f-statistic for the full regression model */ 00329 float rsqr, /* R^2 (coef. of multiple determination) */ 00330 float smax, /* signed maximum of signal */ 00331 float tmax, /* epoch of signed maximum of signal */ 00332 float pmax, /* percentage change due to signal */ 00333 float area, /* area between signal and baseline */ 00334 float parea, /* percentage area between signal and baseline */ 00335 char ** label /* label output for this voxel */ 00336 ); 00337 00338 00339 /*---------------------------------------------------------------------------*/ 00340 00341 00342 #endif /* _NLFIT__HEADER_ */ 00343
