Matlab documentation

The matlab package contains three functions:

derfit:

computes the derivatives of the parameters w.r.t. the input observable Y at the minimum

chiexp:

computes the expected \(\chi^2\)

qfit:

computes the quality of fit

derfit

At the minimum of the \(\chi^2\), the parameters depend on the input observables Y. This function computes their derivatives w.r.t. Y:

der = derfit(X,Y,W,p,'field',value);
Parameters:

  • X, Y - arrays with N entries; Y is assumed to contain the central values of the observable

  • W - weight matrix, N-by-N, used in the fit

  • p - array with the values of the parameters at the minimum

  • field - a string whose admitted values as 'f' and 'df'

  • value - the value corresponding to one of the two strings above

    • df - the gradient of the function f. An array of functions is expected df = @(x,p) [df/dp1 df/dp2 ...]

    • f - fitted function. It must be passed in the form f=@(x,p) f(x,p); if passed together with df it is used to check numerically the provided gradient; if passed without df it is used to numerically compute the gradient

Additional arguments:

  • c (optional): array of length N used as additional argument for f and df, which in this case must obey the syntax f = @(x,p,c) f(x,p,c) (same for df); it can be useful for global fits

Returns:

  • der: a N-by-NA matrix, with NA the number of parameters; contains the derivatives of the parameters der(i,a) = dp(a)/dy(i)

Examples:

 1% derfit can be used in two ways:
 2% either by passing the function (numerical gradient)
 3func = @(x,p) p(1) + p(2)*x;
 4der = derfit(X,Y,W,p,'f',func);
 5
 6% or by passing the gradient (analytical)
 7grad = @(x,p) [1, x];
 8der = derfit(X,Y,W,p,'df',grad);
 9
10% if both are passed, the function is used to check the
11% gradient
12der = derfit(X,Y,W,p,'f',func,'df',grad);
13
14% additional argumemts
15der = derfit(X,Y,W,p,'f',func,'df',grad,'c',c);

chiexp

This function computes the expected \(\chi^2\). The covariance matrix is automatically estimated from the fluctuations of Y, but the user can also provide it independently:

[ce,dce,nu,covest] = chiexp(X,Y,W,p,cov,'field',value)
Parameters:

  • X, Y - arrays with N entries

  • W - weight matrix. It can be an array of dimensions N or a matrix of dimension NxN. In the first case a diagonal weight matrix is automatically created

  • p - array with the values of the parameters at the minimum

  • cov - if cov is a N-by-N matrix, the programs takes it as the covariance matrix, assuming the user has previously computed it; if cov is a M-by-N matrix, the program assumes that it contains the values of the N observables Y on M different configurations.

  • field - a string whose admitted values as 'f' and 'df'

  • value - the value corresponding to one of the two strings above

    • f - fitted function. It must be passed in the form f = @(x,p) f(x,p); this argument is ignored if df is passed

    • df: the gradient of the function f. An array of functions is expected df = @(x,p) [df/dp1 df/dp2 ...]. If empty, the gradient is computed numerically and f must be passed

Additional parameters can be passed using the syntax:

1[ce,dce] = chiexp(X,Y,W,p,cov,'df',df,'field1',value1,'field2',value2...)
2% or
3[ce,dce] = chiexp(X,Y,W,p,cov,'f',f,'field1',value1,'field2',value2...)
Additional arguments:

  • c (optional): array of length N used as additional argument for f and df, which in this case must obey the syntax f = @(x,p,c) f(x,p,c) (same for df); it can be useful for global fits

  • Nrep (optional): array with the number of configurations belonging to each replica, e.g. [N1 N2 N3 ...]. If not given, the number of replica is assumed to be 1.

  • Stau (optional): value of the parameter Stau. Default is 1.5.

  • plot (optional): flag to produce a plot of the expected \(\chi^2\) as a function of the window. Default is 'off'. Accepted values are 'on' and 'off'.

Returns:

  • ce, dce - the values of \(\langle \chi^2 \rangle\) and its error

  • nu: the matrix \(\big[ C^{1/2} W^{1/2} (1-P) W^{1/2} C^{1/2} \big]\)

  • covest: the estimated covariance matrix using the window obtained from the expected \(\chi^2\) (which may not be adeguate for general purposes)

Examples:

 1% chiexp can be used in two ways:
 2% either by passing the function (numerical gradient)
 3func = @(x,p) p(1) + p(2)*x;
 4[ce,dce] = chiexp(X,Y,W,p,cov,'f',func);
 5
 6% or by passing the gradient (analytical)
 7grad = @(x,p) [1, x];
 8[ce,dce] = chiexp(X,Y,W,p,cov,'df',grad);
 9
10% if cov is M-by-N and has 2 replica
11Nrep=[N1, N2]; % M=N1+N2
12[ce,dce] = chiexp(X,Y,W,p,cov,'df',grad,'Nrep',Nrep,'Stau',2.5);
13
14% full output
15[ce,dce,nu,covest] = chiexp(X,Y,W,p,cov,'df',grad);
16
17% for W^-1 = diag(C)
18[ce,dce,nu,covest,ce2,dce2] = chiexp(X,Y,W,f,p)

Note

If W is an array of length N corresponding to the diagonal entries of the covariance matrix, the expected \(\chi^2\) can be obtained with a second formula. To have both results the user must request two additional output arguments, that will contain \(\langle \chi^2 \rangle = N - \mathrm{tr}\big[C W^{1/2} P W^{1/2}\big]\) and its error

qfit

The quality of fit and its error are estimated from a Monte Carlo integration.:

[Q,dQ] = qfit(nmc,nu,c2,plot)

Input arguments:

  • nmc: the size of the Monte Carlo chain

  • nu: the matrix returned from the function chiexp

  • c2: the value of the \(\chi^2\) obtained from the fitting procedure

  • plot (optional): is passed a histogram with normalized distribution

    probability obtained from the Monte Carlo process is plotted

Returns:

  • Q,dQ: the quality of fit and its error