corems.molecular_formula

 1"""Molecular formula objects and related calculations.
 2
 3This package defines molecular formula types used throughout CoreMS
 4(for example after molecular formula search) and calculations such as
 5exact mass, double-bond equivalent, and assignment confidence.
 6
 7**Confidence score**
 8
 9When a formula is attached to a mass spectral peak (and isotopologues have
10been evaluated during search), CoreMS provides a composite **confidence
11score** that ranks candidates. Public properties on
12``MolecularFormula``
13(:class:`~corems.molecular_formula.factory.MolecularFormulaFactory.MolecularFormula`)
14are:
15
16- ``mz_error_score`` — mass accuracy of the monoisotopic peak (Gaussian
17  score from the ppm error).
18- ``average_mz_error_score`` — mean mass-accuracy score over the mono peak
19  and expected isotopologue peaks (missing expected isotopologues score 0).
20- ``isotopologue_similarity`` — agreement between expected and observed
21  isotopologue abundance patterns (Manhattan-based similarity).
22- ``confidence_score`` — weighted sum of the formula-level mass-error term
23  and the isotopologue similarity term.
24
25**Composite score**
26
27```
28CS = (w_err * m_err) + (w_iso * m_iso)
29```
30
31where:
32
33- ``m_err`` is ``average_mz_error_score``
34- ``m_iso`` is ``isotopologue_similarity``
35- ``w_err`` is ``molecular_search_settings.mz_error_score_weight``
36  (default **0.6**)
37- ``w_iso`` is ``molecular_search_settings.isotopologue_score_weight``
38  (default **0.4**)
39
40**Mass-error term (per peak)**
41
42For a single peak, ``mz_error_score`` is a Gaussian score of the assignment
43error ``delta`` (ppm) about a mean of zero (calibrated spectrum assumed):
44
45```
46m = exp( -(delta ** 2) / (2 * (sigma ** 2)) )
47```
48
49The width ``sigma`` is the peak's ``predicted_std`` when set (for example from
50resolving-power / mass-error prediction). If unset, CoreMS uses a fallback
51of **1.66** ppm. Formula-level ``average_mz_error_score`` averages this score
52over the monoisotopic assignment and each expected isotopologue peak.
53
54**Isotopologue term**
55
56``isotopologue_similarity`` compares sum-normalized theoretical and
57observed abundances for the mono peak plus expected isotopologues. Missing
58expected partners are treated as near-zero abundance. If no isotopologues
59are expected (or none were computed), the similarity is **0**.
60
61**Interpretation**
62
63Scores are typically in about [0, 1], with higher values preferred.
64When ``score_method`` is ``"prob_score"``, ranking uses this composite
65confidence score. Isotopologue detection during search
66(``find_isotopologues=True``) is required for a meaningful
67``isotopologue_similarity`` contribution.
68
69**Literature**
70
71The confidence score formulation and its use for ranking formula
72candidates are described in Dewey, Corilo, Kew, and Boiteau,
73*Analytical Chemistry* **2025**, *97*, 13031–13039
74(https://doi.org/10.1021/acs.analchem.4c06826).
75
76**See also**
77
78- ``MolecularFormula.confidence_score``
79- ``MolecularFormula.mz_error_score``
80- ``MolecularFormula.average_mz_error_score``
81- ``MolecularFormula.isotopologue_similarity``
82- Settings: ``mz_error_score_weight``, ``isotopologue_score_weight``
83"""