updated documentation in fit functions

src/juobs_tools.jl

@@ -1240,34 +1240,54 @@ function get_chi(model::Function,x,par,data,W::Vector{Float64})
   return sum((data.-model(x,par)).^2 .* W)
 end
 
-@doc """
-    fit_routine(model::Function, xdata::Array{<:Real}, ydata::Array{uwreal}, npar::Int64; 
-    wpm::Union{Dict{Int64,Vector{Float64}},Dict{String,Vector{Float64}}}=Dict{Int64,Vector{Float64}}(),
-    corr::Bool = true, 
-    W::VecOrMat{Float64}=Vector{Float64}(),
-    guess::Vector{Float64} = fill(0.5,npar),
-    logfile,
-    C::AbstractMatrix{Float64} = Matrix{Float64}());
+@doc raw"""
+        fit_routine(model::Function,xdata::AbstractArray{<:Real},ydata::AbstractArray{ADerrors.uwreal},npar; kwargs...)
+        fit_routine(model::Function,xdata::AbstractArray{uwreal},ydata::AbstractArray{ADerrors.uwreal},npar; kwargs...)
 
 It executes a fit of the `ydata` with the fit function `model`. 
 
-# parameters
-  - `npar::Int64`: number of fit parameters.
-  - `wpm`: Windows parameter that ADerrors uses to computes the errors. 
+# Arguments:
+
+  - `model`: Fit function used to fit the data. the function assumes that its called as `model(xdata,parameters)`.
+  - `xdata`: indipendent variable in the fit. It can be an `AbstractArray{<:Real}`, that is the "default" method, or 
+             a `AbstractArray{uwreal}`. In the latter case, the method builds the function
+``math
+F(q_i) = \begin{cases}
+         model(q_{npar+i},q[1:npar])  \quad \text{if} i<= length(xdata)\\
+         q_i \quad \text{elsewhere}
+       \end{cases}
+``
+             and then call the default method with dummy `xdata` and `vcat(ydata,xdata)` as new `ydata`
+  - `ydata`: Data variable that carries the error 
+  - `npar`: number of parameters used in the fit.
+
+# Keyword parameters:
+
+  - `wpm`: window parameter used by ADerrors to computes the errors. Default to `Dict{Int64,Vector{Float64}}()`.
            This is used both when computing the error of the data and when computing the covariance matrix through `ADerrors.cov`
-  - `corr::Bool`: if `true` (default) it exectues the correlated fit, this flag is overridden if `W` is passed as a `Vector`. 
-    When `corr=true`, and `W` is not given, it computes the covarinace matrix through `ADerrors.cov`, then it is inverted and symmetrized. 
-  - `W::AbstractVecOrMat{Float64}`: Weight matrix/vector. When given, the flag `corr` is overridden. 
-     If `W` is a `Vector` the fit is perfomed uncorrelated,otherwise is correlated. 
-  - `guess::Vector{Float64}`: Initial guess used in the fit routine.
-  - `logfile`: handle to a logfile. If `nothing`, no log will be written. 
-     It can be `IO` file or a custom log structure that has an overloading for `print()` and `println()`.
-  - `C::AbstractMatrix`: covariance matrix used to compute W. 
-     If W is computed by using a different covariance matrix that what given by ADerrors, it is advised to pass it to the function
-     to have a better chiexp and pvalue. If W and C are not given but the fit is correlated, then C is computed using ADerrors
+           It accept a dictionary with ensemble id as keys (either `String` or `Int64`) and `Vector{Float64}` as value.
+           See also ADerrors documentation.
+
+  - `W::AbstractVecOrMat{Float64}`: Weight matrix/vector. If `W` is a `Vector` the fit is perfomed uncorrelated ,otherwise is correlated.
+                                    default to `Vector{Float64}()`
+
+  - `corr::Bool`: flag used to generated `W` when not given. Default to `true`. If `false`, `W = [1/y.err^2 for y in ydata]`.
+                  If `true` the covariance matrix of the data is used to compute `W` as `W = C^{-1}`.
+
+  - `C::AbstractMatrix`: covariance matrix used to compute W. Default to `Matrix{Float64}(undef, 0, 0)`.
+                         If `W` is not given, and `corr` is `true`, then it is used to compute `W`.
+                         If need to computed `W` but not given,  then `C = ADerrors.cov(ydata,wpm)`. See also ADerrors documentation.
+                         If available, it will be used to better estimate the fit pvalue and the expected chi-square,
+                         but it will not be computed if not available at this point. 
+
+  - `guess::Vector{Float64}`: Initial guess for the parameter used in the fit routine. If not given, default to `fill(0.5,npar)`.
+                              If `xdata isa Vector{uwreal}`, the mean value of `xdata` are used as guess for the relevant `q_i` parameters.
+  
+  - `logfile`: handle to a logfile. If `nothing`, no log will be written. It can be `IO` file or a custom log structure that has
+               an overloading for `print()` and `println()`.
 
 # Returns
-It returns a NamedTuple with names:
+It returns a `NamedTuple` with names:
   - `:par`:    fit parameter as `Vector{uwreal}`
   - `:chi2`:   chisquare,
   - `:chiexp`: chisquare expected 
@@ -1331,7 +1351,7 @@ end
 """
         check_size(M,n)
 
-Check if `M` has sizes all equal to n or, if is empty
+Check if `M` has sizes all equal to n or if is empty
 """
 function check_sizes(M,n)
     if length(M) ==0 || all(size(M) .== n)
@@ -1398,10 +1418,27 @@ function fit_routine(model::Function,
     return fit
 end
 
+
+@doc raw"""
+        fit_routine(model::AbstractArray{Function},
+                    xdata::AbstractArray{<:AbstractArray},
+                    ydata::AbstractArray{<:AbstractArray{ADerrors.uwreal}},npar; kwargs...)
+       
+
+It executes a combined fit of the `ydata` with the fit functions in `model`. The method define the general model `F(X_{mi},p) = model[m](xdata[i],p)`
+and call `fit_routine(F,vcat(xdata),vcat(ydata),npar;kwargs....)`. The `kwargs` parameters are accordingly updated to reflect the new function.
+
+# Returns
+It returns a `NamedTuple` with names:
+  - `:par`:    fit parameter as `Vector{uwreal}`
+  - `:chi2`:   chisquare,
+  - `:chiexp`: chisquare expected 
+  - `:pval`:   pvalue 
+"""
 function fit_routine(models::AbstractArray{Function},
                      xdata::AbstractArray{<:AbstractArray},
                      ydata::AbstractArray{<:AbstractArray{ADerrors.uwreal}},
-                     npar::AbstractArray{Int64};
+                     npar::Int64;
                      W::AbstractArray = Float64[],
                      C::AbstractArray = Float64[],
                      wpm::AbstractDict = Dict{Int64,Vector{Float64}}(),
@@ -1419,9 +1456,6 @@ function fit_routine(models::AbstractArray{Function},
     if !(length(C) == 0 || length(C)==Nmodel)
         error("[juobs] Error: You need to pass a C matrix for model or none")
     end
-    if length(npar) != Nmodel
-        error("[juobs] Error: You need to specify the number of parameter for every model")
-    end
     if length(guess)!=Nmodel
         error("[juobs] Error: You need to specify the inital guess for all model or for none")
     end
@@ -1449,16 +1483,16 @@ function fit_routine(models::AbstractArray{Function},
 
     function Model(x,p)
         res = zeros(Nmodel)
-        res[1] = models[1](x[1:ndata[1]],p[1:npar[1]])
+        res[1] = models[1](x[1:ndata[1]],p)
         for i in 2:Nmodel
             rd = (ndata[i-1]+1):ndata[i]
             rp = (npar[i-1]+1):npar[i]
-            res[i] = models[i](x[rd],p[rp])
+            res[i] = models[i](x[rd],p)
         end
         return res
     end
     Guess = vcat(guess...)
-    fit = fit_routine(Model,X,Y,sum(npar),guess = Guess,W=WW,C=CC,corr=corr,logfile=nothing,wpm=wpm)
+    fit = fit_routine(Model,X,Y,npar,guess = Guess,W=WW,C=CC,corr=corr,logfile=nothing,wpm=wpm)
 
     if !isnothing(logfile) 
         uwerr.(fit.par)
@@ -1471,19 +1505,22 @@ function fit_routine(models::AbstractArray{Function},
         for nm in 1:Nmodel
             println(logfile,"---Model $(nm)---")
             println(logfile, "\t\tFit routine in [$(xdata[nm][1].mean),...,$(xdata[nm][end].mean)]")
-            println(logfile, "\t\tFit parameters:")
-            for i in 1:npar[nm]
-                off = nm ==1 ? 0 : npar[nm-1]
-                println(logfile,"\t\t\t",fit.par[off+i])
         end
+        println(logfile, "\t\tFit parameters:")
+        for i in 1:npar
+            println(logfile,"\t\t\t",fit.par[i])
         end
         if flag
+            off = npar
             pritnln(logfile, "\t\tauxiliary fit parameter:")
+            for nm in 1:Nmodel
+                println(logfile,"---Model $(nm)---")
                 println(logfile, "\t\t\txdata[m][i] \t q[i]")
-            for nm in 1:Nmodel, i in 1:npar[nm]
-                off = nm==1 ? 0 : npar[end]+npar[i-1]
+                for i in eachindex(xdata[nm])
                     println(logfile, "\t\t\t",xdata[nm][i]," \t ", fit.par[off+i])
                 end
+                off += npar+length(xdata[nm])
+            end
         end
         println(logfile, "\t\tchi2:       ", chi2)
         println(logfile, "\t\tchiexp:     ", chiexp)