Skip to content

Commit

Permalink
Merge pull request #170 from FAIRmat-NFDI/158-xps-peak-fitting-in-nexus
Browse files Browse the repository at this point in the history 
Description of peak fitting (e.g., in XPS)
  • Loading branch information
@lukaspie
lukaspie authored Sep 11, 2024
2 parents 6054ae7 + fb0be54 commit 5a3e07d
Show file tree
Hide file tree
Showing 12 changed files with 1,643 additions and 71 deletions.
199 changes: 199 additions & 0 deletions contributed_definitions/NXfit.nxdl.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,199 @@
<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl"?>
<!--
# NeXus - Neutron and X-ray Common Data Format
#
# Copyright (C) 2014-2024 NeXus International Advisory Committee (NIAC)
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 3 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# For further information, see http://www.nexusformat.org
-->
<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXfit" extends="NXprocess" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
<symbols>
<doc>
The symbols used in the schema to specify e.g. dimensions of arrays.
</doc>
<symbol name="dimRank">
<doc>
Rank of the dependent and independent data arrays (for
multidimensional/multivariate fit.)
</doc>
</symbol>
</symbols>
<doc>
Description of a fit procedure.
</doc>
<field name="label">
<doc>
Human-readable label for this fit procedure.
</doc>
</field>
<group name="data" type="NXdata">
<doc>
Input data and results of the fit.
</doc>
<field name="input_dependent" type="NX_NUMBER" units="NX_ANY">
<doc>
Position values along one or more data dimensions (to hold the
values for the independent variable for this fit procedure).
</doc>
<dimensions rank="dimRank">
<doc>
The ``input_dependent`` field must have the same rank (``dimRank``)
as the ``input_independent`` field. Each individual dimension of ``input_dependent``
must have the same number of points as the corresponding dimension in
the ``input_independent`` field.
</doc>
</dimensions>
</field>
<field name="input_independent" type="NX_NUMBER" units="NX_ANY">
<doc>
Independent input axis for this fit procedure.
</doc>
<dimensions rank="dimRank">
<doc>
The ``input_independent`` field must have the same rank (``dimRank``)
as the ``input_dependent`` field. Each individual dimension of ``input_independent``
must have the same number of points as the corresponding dimension in
the ``input_dependent`` field.
</doc>
</dimensions>
</field>
<field name="envelope" type="NX_NUMBER" units="NX_ANY">
<doc>
Resulting envelope of applying the `global_fit_function` with its parameter to the data stored
in `input_independent`.
</doc>
<dimensions rank="dimRank">
<doc>
The ``envelope`` field must have the same rank (``dimRank``)
as the ``input_independent`` field. Each individual dimension of ``envelope``
must have the same number of points as the corresponding dimension in
the ``input_independent`` field.
</doc>
</dimensions>
</field>
<field name="residual" type="NX_NUMBER" units="NX_ANY">
<doc>
Difference between the envelope and the `input_independent` data to be fitted.
</doc>
<dimensions rank="dimRank">
<doc>
The ``residual`` field must have the same rank (``dimRank``)
as the ``input_independent`` field. Each individual dimension of ``residual``
must have the same number of points as the corresponding dimension in
the ``input_independent`` field.
</doc>
</dimensions>
</field>
</group>
<group name="peakPEAK" type="NXpeak">
<doc>
One peak of the peak model.
If there is no characteristic name for each peak component, is envisioned that peaks
are labeled as peak_0, peak_1, and so on.
</doc>
<field name="total_area" type="NX_NUMBER" units="NX_ANY">
<doc>
Total area under the curve (can also be used for the total area minus any
background values).
</doc>
</field>
<field name="relative_sensitivity_factor" type="NX_NUMBER" units="NX_UNITLESS">
<doc>
Relative sensitivity for this peak, to be used for quantification in
an NXprocess.

As an example, in X-ray spectroscopy could depend on the energy scale
(see position), the ionization cross section, and the element probed.
</doc>
</field>
<field name="relative_area" type="NX_NUMBER" units="NX_ANY">
<doc>
Relative area of this peak compared to other peaks.

The relative area can simply be derived by dividing the total_area by the
total area of all peaks or by a more complicated method (e.g., by
additionally dividing by the relative sensitivity factors). Details shall
be given in `global_fit_function`.
</doc>
</field>
</group>
<group name="backgroundBACKGROUND" type="NXfit_background">
<doc>
One fitted background (functional form, position, and intensities) of the peak fit.
If there is no characteristic name for each peak component, it is envisioned that backgrounds are labeled
as background_0, background_1, and so on.
</doc>
</group>
<group name="global_fit_function" type="NXfit_function">
<doc>
Function used to describe the overall fit to the data, taking into account the parameters of the
individual `NXpeak` and `NXfit_background` components.
</doc>
<field name="formula">
<doc>
Oftentimes, if the peaks and fit backgrounds are defined independently (i.e, with their own
parameter sets), the resulting global fit is a function of the form
:math:`model = peak_1(p_1) + peak2(p_2) + backgr(p_3).`, where each :math:`p_x` describes the
set of parameters for one peak/background.
</doc>
</field>
</group>
<group name="error_function" type="NXfit_function">
<doc>
Function used to optimize the parameters during peak fitting.
</doc>
<field name="description">
<doc>
Description of the method used to optimize the parameters during peak fitting.
Examples:
- least squares
- non-linear least squares
- Levenberg-Marquardt algorithm (damped least-squares)
- linear regression
- Bayesian linear regression
</doc>
</field>
<field name="formula">
<doc>
For the optimization, the formula is any optimization process on the `global_fit_function` given above.
As an example, for a linear least squared algorithm on independent components, the formula of the error_function
would be :math:`LLS(peak_1(p_1) + peak2(p_2) + backgr(p_3))`, where each :math:`p_x` describes the set
of parameters for one peak/background.

It is however also possible to supply more involved formulas (e.g., in the case of constrained fits).
</doc>
</field>
</group>
<field name="figure_of_meritMETRIC" type="NX_NUMBER" units="NX_UNITLESS">
<doc>
Figure-of-merit to determine the goodness of fit, i.e., how well the peak model
fits the measured observations.

This value (which is a single number) is oftenused to guide adjustments to the
fitting parameters in the peak fitting process.
</doc>
<attribute name="metric">
<doc>
Metric used to determine the goodness of fit. Examples include:
- :math:`\chi^2`, the squared sum of the sigma-weighted residuals
- reduced :math:`\chi^2`:, :math:`\chi^2`: per degree of freedom
- :math:`R^2`, the coefficient of determination
</doc>
</attribute>
</field>
</definition>
80 changes: 80 additions & 0 deletions contributed_definitions/NXfit_background.nxdl.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl"?>
<!--
# NeXus - Neutron and X-ray Common Data Format
#
# Copyright (C) 2014-2024 NeXus International Advisory Committee (NIAC)
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 3 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# For further information, see http://www.nexusformat.org
-->
<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXfit_background" extends="NXobject" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
<symbols>
<doc>
The symbols used in the schema to specify e.g. dimensions of arrays.
</doc>
<symbol name="dimRank">
<doc>
Rank of the dependent and independent data arrays (for
multidimensional/multivariate fit.)
</doc>
</symbol>
</symbols>
<doc>
Description of the background for an NXfit model.
</doc>
<field name="label" type="NX_CHAR">
<doc>
Human-readable label which specifies which concept/entity
the background represents/identifies.
</doc>
</field>
<group name="data" type="NXdata">
<field name="position" type="NX_NUMBER" units="NX_ANY">
<doc>
Position values along one or more data dimensions (to hold the
values for the independent variable).
</doc>
<dimensions rank="dimRank">
<doc>
The ``position`` field must have the same rank (``dimRank``)
as the ``intensity`` field. Each individual dimension of ``position``
must have the same number of points as the corresponding dimension in
the ``intensity`` field.
</doc>
</dimensions>
</field>
<field name="intensity" type="NX_NUMBER" units="NX_ANY">
<doc>
This array holds the intensity/count values of the fitted background
at each position.
</doc>
<dimensions rank="dimRank">
<doc>
The ``intensity`` field must have the same rank (``dimRank``)
as the ``intensity`` field. Each individual dimension of ``position``
must have the same number of points as the corresponding dimension in
the ``position`` field.
</doc>
</dimensions>
</field>
</group>
<group name="function" type="NXfit_function">
<doc>
The functional form of the background.
</doc>
</group>
</definition>
47 changes: 47 additions & 0 deletions contributed_definitions/NXfit_function.nxdl.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl"?>
<!--
# NeXus - Neutron and X-ray Common Data Format
#
# Copyright (C) 2014-2024 NeXus International Advisory Committee (NIAC)
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 3 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# For further information, see http://www.nexusformat.org
-->
<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXfit_function" extends="NXobject" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
<doc>
This describes a fit function that is used to fit data to any functional form.

A fit function is used to describe a set of data :math:`y_k, k = 1 ... M`, which are collected as a function
of one or more independent variables :math:`x` at the points :math:`x_k`. The fit function :math:`f` describes
these data in an approximative way as :math:`y_k \approx f(a_0, . . . a_n, x_k)`,
where :math:`a_i, i = 0 . . . n` are the *fit parameters* (which are stored the instances of ``NXfit_parameter``).
</doc>
<field name="description">
<doc>
Human-readable description of this fit function.
</doc>
</field>
<field name="formula">
<doc>
Mathematical formula of the function, taking into account the instances of ``NXfit_parameter``.

This should be a python parsable function. Here we should provide which keywords are available
and a BNF of valid grammar.
</doc>
</field>
<group type="NXfit_parameter"/>
</definition>
56 changes: 56 additions & 0 deletions contributed_definitions/NXfit_parameter.nxdl.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl"?>
<!--
# NeXus - Neutron and X-ray Common Data Format
#
# Copyright (C) 2014-2024 NeXus International Advisory Committee (NIAC)
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 3 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# For further information, see http://www.nexusformat.org
-->
<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXfit_parameter" extends="NXobject" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
<doc>
A parameter for a fit function.
This would typically be a variable that
is optimized in a fit.
</doc>
<field name="name" type="NX_CHAR">
<doc>
The name of the parameter.
</doc>
</field>
<field name="description" type="NX_CHAR">
<doc>
A description of what this parameter represents.
</doc>
</field>
<field name="value" type="NX_NUMBER" units="NX_ANY">
<doc>
The value of the parameter. After fitting, this would store the
optimized value.
</doc>
</field>
<field name="min_value" type="NX_NUMBER" units="NX_ANY">
<doc>
The minimal value of the parameter, to be used as a constraint during fitting.
</doc>
</field>
<field name="max_value" type="NX_NUMBER" units="NX_ANY">
<doc>
The maximal value of the parameter, to be used as a constraint during fitting.
</doc>
</field>
</definition>
Loading

0 comments on commit 5a3e07d

Please sign in to comment.