Clean up variable vs parameter language.

[jagerber48]

I'm working with the Model class but I think my comments apply more broadly other classes like minimizers etc. in lmfit.

The model is very centered around the idea of Parameters which carry information about initial guess values, vary flags, bounds etc. to configure the minimizer. The documentation seems to focus on Parameters as well. However, in a few cases there seem to be references to "variables" which. I think variable is synonymous with parameter but it's not clear and can lead to confusion.

The most striking example is that when model results are displayed there is a major heading titled "Variables" which appears over the table displaying information about all of the "parameters". This might lead new users to look for an attribute on the model results class like results.variables instead of result.params. Likewise, there is an attribute on the results class call var_names which returns the names of the parameters.

The idea here is to remove all references to "variables" and replace them with "parameters". At least wherever appropriate.

One point where variables and parameters are distinct is when it comes to independent variables. But here the two phrases actually refer to separate concepts, so using variables synonymously with parameters elsewhere servers only to further confuse the distinction between independent variables and parameters.

[newville]

@jagerber48 I can see the room for confusion here, and the docs could probably be clearer.

First, as you say "independent variables" are completely separate. These are really "extra user-specified data that the user wants to use to calculate the model or residual function". In many (most?) curve-fitting problems, one is modeling (and likely plotting) y(x), represented as arrays y -- the data to be modeled, and x-- the independent variable that the user will use to calculate the model (but that is not used elsewhere in the fitting process).

In lmfit, Parameters can be set to be fixed (vary=False) or defined by constraints -- mathematical expressions using the names of other Parameters. Parameters that are fixed or are defined as constraints are not varied by the fitting process: they are not variables. For constraint expressions, their values may change during the fit if they depend on fitting variables, but they are not themselves directly varied. To be completer, parameters that vary but have bounds are still variables. In the mathematics of fitting, the number of variable parameters does matter, while the fixed or constrained parameters do not. In lmfit, we hold and/or update these values as appropriate so that they can be used in the model or objective function.

When we say "variables" we usually try to mean "the truly variable parameters". So, nvarys really will be the number of varying parameters, and var_names will be the names of the variable parameters. All the underlying algorithms use an array of values for the variables (yes, not parameters), so var_names is used to map the nvarys values in the array of "current variable values" to the corresponding parameters variables.

That's all to say: there is a distinction between variable and Parameter. The docs might be better ;)

[jagerber48]

That's a nice explanation, but look at this printout:

This table (titled "Variables") includes all parameters, including ones with vary=False. I think the title of this table should be "Parameters", not "Variables".

edit: result.var_names correctly returns the list of "variable parameters".

[newville]

Okay, changing the title there and similar places seems okay to me.

I hope no one is parsing the report text, but this would be a good way to find out ;).

[jagerber48]

Ok, if I get time I will
(1) make a PR changing that title
(2) look through code to see if there other cases where "variables" can be confused with "parameters". result.var_names is ok. especially given that the documentation says "Ordered list of variable parameter names used in optimization..."