Skip to content

Commit de67fef

Browse files
MichaelHuthMichaelHuth
committed
Docu: Add rst documentation for operation getmeta, preparefit and fit2
1 parent 6e45a98 commit de67fef

1 file changed

Lines changed: 237 additions & 0 deletions

File tree

‎Packages/doc/SweepFormula.rst‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2133,6 +2133,243 @@ Useful for testing SweepFormula itself mainly.
21332133
21342134
dataset(1, [2, 3], "abcd") == [1], [2, 3], ["abcd]
21352135
2136+
getmeta
2137+
"""""""
2138+
2139+
Some SweepFormula operations return additional metadata that can be retrieved with
2140+
the `getmeta` operation.
2141+
2142+
.. code-block:: bash
2143+
2144+
getmeta(array keys, data, [datasetNumber])
2145+
2146+
The meta data can be referenced by keys that are strings. It is possible to specify an array of key strings, and keys may include wildcards.
2147+
If one of the keys is `"*"` then `getmeta` returns meta information from all keys that data has.
2148+
If none of the provided keys match any available meta data key then `getmeta` reports this as an error.
2149+
The argument `data` can be any output from another operation. The operation retrieves meta information only from one dataset, by default dataset 0.
2150+
The optional argument `datasetNumber` allows to select a different dataset from data. If the dataset does not exist, `getmeta` returns an error.
2151+
2152+
Available meta keys are documented at the specific operation returning meta information.
2153+
2154+
.. code-block:: bash
2155+
2156+
getmeta([key1, key2], data, 0)
2157+
2158+
Results from multiple keys are returned in separate datasets. When displayed as `table` each result is shown in its own columns.
2159+
2160+
.. code-block:: bash
2161+
2162+
table(getmeta([key1, key2], data))
2163+
2164+
preparefit
2165+
""""""""""
2166+
2167+
The operation `preparefit` creates a configuration for a later call of the `fit2` operation.
2168+
2169+
.. code-block:: bash
2170+
2171+
preparefit([string fitfuncName, length, errorbarType, errorbarStyle, confLevel, array coefs, string holdStr, array range, array constraints])
2172+
2173+
All arguments of `preparefit` are optional. When called without arguments the fit configuration is set to `disabled`.
2174+
This means that `fit2` returns an empty result with this configuration.
2175+
2176+
The argument `fitfuncName` names an Igor Pro integrated fit function or a user defined fit function that is called for the fit.
2177+
The following table lists the names of the supported Igor Pro integrated fit functions and the number of coefficients.
2178+
2179+
+-------------------+------------------------+
2180+
| Fit Function Name | Number of Coefficients |
2181+
+===================+========================+
2182+
| gauss | 4 |
2183+
+-------------------+------------------------+
2184+
| lor | 4 |
2185+
+-------------------+------------------------+
2186+
| Voigt | 5 |
2187+
+-------------------+------------------------+
2188+
| exp | 3 |
2189+
+-------------------+------------------------+
2190+
| dblexp | 5 |
2191+
+-------------------+------------------------+
2192+
| exp_XOffset | 3 |
2193+
+-------------------+------------------------+
2194+
| dblexp_XOffset | 5 |
2195+
+-------------------+------------------------+
2196+
| dblexp_peak | 5 |
2197+
+-------------------+------------------------+
2198+
| sin | 4 |
2199+
+-------------------+------------------------+
2200+
| line | 2 |
2201+
+-------------------+------------------------+
2202+
| poly 1 | 1 |
2203+
+-------------------+------------------------+
2204+
| poly 2 | 2 |
2205+
+-------------------+------------------------+
2206+
| poly 3 | 3 |
2207+
+-------------------+------------------------+
2208+
| poly 4 | 4 |
2209+
+-------------------+------------------------+
2210+
| poly_XOffset 1 | 1 |
2211+
+-------------------+------------------------+
2212+
| poly_XOffset 2 | 2 |
2213+
+-------------------+------------------------+
2214+
| poly_XOffset 3 | 3 |
2215+
+-------------------+------------------------+
2216+
| poly_XOffset 4 | 4 |
2217+
+-------------------+------------------------+
2218+
| hillequation | 4 |
2219+
+-------------------+------------------------+
2220+
| sigmoid | 4 |
2221+
+-------------------+------------------------+
2222+
| power | 3 |
2223+
+-------------------+------------------------+
2224+
| lognormal | 4 |
2225+
+-------------------+------------------------+
2226+
| log | 2 |
2227+
+-------------------+------------------------+
2228+
| gauss2D | 7 |
2229+
+-------------------+------------------------+
2230+
| poly2D 1 | 3 |
2231+
+-------------------+------------------------+
2232+
| poly2D 2 | 6 |
2233+
+-------------------+------------------------+
2234+
| poly2D 3 | 10 |
2235+
+-------------------+------------------------+
2236+
| poly2D 4 | 15 |
2237+
+-------------------+------------------------+
2238+
2239+
Any other fit function name is treated as user defined fit function name. A user defined fit function must be implemented by the user.
2240+
The function must have the same syntax as an Igor Pro user fit function:
2241+
2242+
.. code-block:: igorpro
2243+
2244+
Function MyOwnFitFunction(WAVE w, variable x)
2245+
2246+
// Calculate fit
2247+
// result = myFitModelFormula
2248+
2249+
return result
2250+
End
2251+
2252+
If the given user fit function does not exist, `preparefit` returns an error.
2253+
2254+
The argument `length` sets the number of points in the fit output. The default length is 200. The `length` can be set to 0 or 2+.
2255+
When set to 2 or more then the output will have the given number of points. A special case is `length` zero. When set to zero the output
2256+
has the same number of points as the y-wave input.
2257+
2258+
The argument `errorbarType` sets which fit output is used for the error bars of the fit output wave.
2259+
Possible options are `standard`, `conf` and `pred`.
2260+
The option `standard` calculates the Standard Normalized Error and works only in combination with `length` zero,
2261+
such that the fit output has the same number of points as the fit input.
2262+
The option `conf` calculates the confidence interval and `pred` the prediction interval. `conf` and `pred` work only in combination with
2263+
not zero `length`. For details see `DisplayHelpTopic "Confidence Bands and Coefficient Confidence Intervals"`.
2264+
2265+
The argument `errorbarStyle` sets a hint in which style the errorbars should be displayed.
2266+
Possible options are `normal` and `shaded`. With `normal` Igor Pros default style for error bars is used (distance lines).
2267+
With `shaded` the error distance is displayed as transparent shaded area with a different colors for positive and negative errors.
2268+
2269+
The argument `confLevel` sets the confidence level in percent. The value must be between 0 and 100. The default value is 85.
2270+
The value is unused for the Standard Normalized Error calculation.
2271+
For details see `DisplayHelpTopic "Confidence Bands and Coefficient Confidence Intervals"`.
2272+
2273+
The argument `coefs` is a numeric array that allows to set initial fit coefficients. It must have the correct size.
2274+
For internal fit functions the required size is shown in the above table. The default coefficient values are zero.
2275+
For user defined fit functions `coefs` must be provided explicitly, as the number of required coefficients can not be inferred.
2276+
2277+
The argument `holdStr` is a string that allows to hold certain coefficients.
2278+
The string must have the correct length that equals the number of coefficients.
2279+
The character `X` holds a coefficient and the character `O` leaves the coefficient free.
2280+
e.g. for three coefficient where the last one is held the string would be `OOX`.
2281+
2282+
The argument `range` is a two element numeric array in the form `[x-start, x-end]` that allows to limit the fit range. This array uses x-axis values.
2283+
Points outside the given range are masked out. The start must be smaller than the end. By default all points are included in the fit.
2284+
2285+
The argument `constraints` is a string array that allows to set fit constraints. Constraints are set by simple rules like `"K1 > 0"`.
2286+
Note that dependencies between coefficients must be linear. See also `DisplayHelpTopic "Fitting with Constraints"`.
2287+
2288+
.. code-block:: bash
2289+
2290+
preparefit(exp, 500, pred, shaded, 10, [2, 5, 2], OXO, [5, 15], ["K0 > 0", "K1 > 0"])
2291+
2292+
fit2
2293+
""""
2294+
2295+
The operation `fit2` fits the input datasets with the given fit configuration created with `preparefit`.
2296+
The operation can be called in two variants, either with or without `xWave` specification.
2297+
2298+
.. code-block:: bash
2299+
2300+
# Variant 1
2301+
fit2(yWave, fitConfiguration)
2302+
2303+
# Variant 2
2304+
fit2(yWave, xWave, fitConfiguration)
2305+
2306+
When an `xWave` argument is specified then it must have the same number of datasets as the `yWave` argument. Also for each dataset the
2307+
number of points in the x-wave and y-wave must be the same. Errorbar information (ErrorY± and ErrorX±) is read from the y-wave's wave note and
2308+
interpreted as standard deviation and used for weighting the input points of the fit.
2309+
When x-errorbar information is present then as fitting method Trust-region Levenberg-Marquardt least orthogonal distance is used.
2310+
This method is appropriate for fitting when there are measurement errors in the independent variables, sometimes called "errors in variables fitting", "random regressor models," or "measurement error models".
2311+
2312+
After the fit the following keys are created as meta data in the output. This information can be retrieved with the `getmeta` operation.
2313+
2314+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2315+
| key | type | description |
2316+
+===========================+==============+=================================================================================================================+
2317+
| FitError | number | Fit Error code, zero is no error |
2318+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2319+
| FitStatusMessage | string | Fit status as text message |
2320+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2321+
| FitQuitReason | number | Fit Quit Reason code |
2322+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2323+
| FitNumIters | number | Number of iterations run |
2324+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2325+
| FitFunc | string | Fit function name |
2326+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2327+
| FitCoefs | numeric wave | Fit coefficients |
2328+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2329+
| FitWSigma | numeric wave | estimates of error for the coefficients |
2330+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2331+
| FitMCovar | numeric wave | Covariance Matrix See also DisplayHelpTopic "Covariance Matrix" |
2332+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2333+
| FitMFitConstraint | numeric wave | Constraint Matrix (only when fitting with constraints) See also DisplayHelpTopic "Constraint Matrix and Vector" |
2334+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2335+
| FitWFitConstraint | numeric wave | Constraint Vector (only when fitting with constraints) See also DisplayHelpTopic "Constraint Matrix and Vector" |
2336+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2337+
| FitConstant | numeric wave | Fit Constant, e.g. from the “*XOffset*” fit functions See also DisplayHelpTopic "Fits with Constants" |
2338+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2339+
| FitChiSquare | number | Chi Square |
2340+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2341+
| FitXResiduals | numeric wave | X-residuals (only after ODR / Trust-region Levenberg-Marquardt method fit) |
2342+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2343+
| FitYResiduals | numeric wave | Y-residuals |
2344+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2345+
| FitUConfidence | numeric wave | Upper confidence band |
2346+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2347+
| FitLConfidence | numeric wave | Lower confidence band |
2348+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2349+
| FitUPrediction | numeric wave | Upper prediction band |
2350+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2351+
| FitLPrediction | numeric wave | Lower prediction band |
2352+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2353+
| FitCoefConfidenceInterval | numeric wave | Fit coefficient confidence interval See DisplayHelpTopic "Errors in Variables: Orthogonal Distance Regression" |
2354+
+---------------------------+--------------+-----------------------------------------------------------------------------------------------------------------+
2355+
2356+
Note that depending on the fit configuration and the resulting fit type not every meta information results may be available.
2357+
2358+
If `length` is zero in the fit configuration then a separate x-wave is stored in the fit output.
2359+
Otherwise the row dimension of the fit output wave is scaled.
2360+
2361+
If the fit results in a fit error, `FitError` is not zero. The fit output wave has zero size and only the following meta information is set:
2362+
`FitError`, `FitStatusMessage`, `FitFunc`, `FitQuitReason` and `FitNumIters`.
2363+
2364+
The trace style of the fit is set to be a black line. The error bar style is set depending on the fit configuration.
2365+
The `shaded` style is 75% transparent with red for positive errors and blue for negative errors.
2366+
2367+
.. code-block:: bash
2368+
2369+
fit2([1, 2, 4], preparefit(line))
2370+
and
2371+
fit2([1, 2, 4], [0, 3, 7], preparefit(log, 500, pred, shaded, 1.5, [0.1, 0.2], OO, [-1, 8], [""]))
2372+
21362373
table
21372374
"""""
21382375

0 commit comments

Comments
 (0)