# `find-mfs`: Accurate mass ➜ Molecular Formulae
[](https://github.com/mhagar/find-mfs/actions/workflows/ci.yml)
[](https://pypi.org/project/find-mfs/)
[](https://www.python.org/downloads/)
[](https://www.gnu.org/licenses/gpl-3.0)
`find-mfs` is a simple Python package for finding
molecular formulae candidates which fit some given mass (+/- an error window).
It implements Böcker & Lipták's algorithm for efficient formula finding, as
implemented in SIRIUS.
`find-mfs` also implements other methods
for filtering the MF candidate lists:
- **Octet rule**
- **Ring/double bond equivalents (RDBE's)**
- **Predicted isotope envelopes**, generated using using Łącki and Startek's algorithm
as implemented in `IsoSpecPy`
## Motivation:
I needed to perform mass decomposition and, shockingly, I could not find a Python library for it
(despite being a routine process). `find-mfs` is intended to be used by anyone looking to incorporate
molecular formula finding into their Python project.
## Installation
```commandline
pip install find-mfs
```
## Example Usage:
```python
# For simple queries, one can use this convenience function
from find_mfs import find_chnops
find_chnops(
mass=613.2391, # Novobiocin [M+H]+ ion; C31H37N2O11+
charge=1, # Charge should be specified - electron mass matters
error_ppm=5.0, # Can also specify error_da instead
# --- FORMULA FILTERS ----
check_octet=True, # Candidates must obey the octet rule
filter_rdbe=(0, 20), # Candidates must have 0 to 20 ring/double-bond equivalents
max_counts='C*H*N*O*P0S2' # Element constraints: unlimited C/H/N/O,
# No phosphorous atoms, up to two sulfurs.
)
```
Output:
```
FormulaSearchResults(query_mass=613.2391, n_results=38)
Formula Error (ppm) Error (Da) RDBE
----------------------------------------------------------------------
[C6H25N30O4S]+ -0.12 0.000073 9.5
[C31H37N2O11]+ 0.14 0.000086 14.5
[C14H29N24OS2]+ 0.18 0.000110 12.5
[C16H41N10O11S2]+ 0.20 0.000121 1.5
[C29H33N12S2]+ -0.64 0.000392 19.5
... and 33 more
```
```python
# If processing many masses, it's better to instantiate a FormulaFinder object
from find_mfs import FormulaFinder
finder = FormulaFinder()
finder.find_formulae(
mass=613.2391, # Novobiocin [M+H]+ ion; C31H37N2O11+
charge=1,
error_ppm=5.0,
# ... etc
)
```
### Jupyter Notebook:
See [this Jupyter notebook](docs/basic_usage.ipynb) for more thorough examples/demonstrations
---
**If you use this package, make sure to cite:**
- [Böcker & Lipták, 2007](https://link.springer.com/article/10.1007/s00453-007-0162-8) - this package uses their algorithm for formula finding...
- ...as implemented in SIRIUS: [Böcker et. al., 2008](https://academic.oup.com/bioinformatics/article/25/2/218/218950)
- [Łącki, Valkenborg & Startek 2020](https://pubs.acs.org/doi/10.1021/acs.analchem.0c00959) - this package uses IsoSpecPy to quickly simulate isotope envelopes
- [Gohlke, 2025](https://zenodo.org/records/17059777) - this package uses `molmass`, which provides very convenient methods for handling chemical formulae
## Contributing
Contributions are welcome. Here's a list of features I feel should be implemented eventually:
- Statistics-based isotope envelope fitting
- Fragmentation constraints
- Element ratio constraints
- GUI app
## License
This project is distributed under the GPL-3 license.
Raw data
{
"_id": null,
"home_page": null,
"name": "find-mfs",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": "mass spectrometry, molecular formula, accurate mass, chemistry, proteomics, metabolomics",
"author": null,
"author_email": "Mostafa Hagar <mostafa@150mL.com>",
"download_url": "https://files.pythonhosted.org/packages/1a/85/5902aa27a03fcb7646aea587b2d31ed1fd6e7fdef8d03b598b1b3545e4a1/find_mfs-0.2.1.tar.gz",
"platform": null,
"description": "# `find-mfs`: Accurate mass \u279c Molecular Formulae\n\n[](https://github.com/mhagar/find-mfs/actions/workflows/ci.yml)\n[](https://pypi.org/project/find-mfs/)\n[](https://www.python.org/downloads/)\n[](https://www.gnu.org/licenses/gpl-3.0)\n\n`find-mfs` is a simple Python package for finding \nmolecular formulae candidates which fit some given mass (+/- an error window).\nIt implements B\u00f6cker & Lipt\u00e1k's algorithm for efficient formula finding, as \nimplemented in SIRIUS. \n\n`find-mfs` also implements other methods \nfor filtering the MF candidate lists:\n- **Octet rule**\n- **Ring/double bond equivalents (RDBE's)**\n- **Predicted isotope envelopes**, generated using using \u0141\u0105cki and Startek's algorithm\n as implemented in `IsoSpecPy`\n\n## Motivation:\nI needed to perform mass decomposition and, shockingly, I could not find a Python library for it \n(despite being a routine process). `find-mfs` is intended to be used by anyone looking to incorporate\nmolecular formula finding into their Python project.\n\n## Installation\n```commandline\npip install find-mfs\n```\n\n## Example Usage:\n\n```python\n# For simple queries, one can use this convenience function\nfrom find_mfs import find_chnops\n\nfind_chnops(\n mass=613.2391, # Novobiocin [M+H]+ ion; C31H37N2O11+\n charge=1, # Charge should be specified - electron mass matters\n error_ppm=5.0, # Can also specify error_da instead\n # --- FORMULA FILTERS ----\n check_octet=True, # Candidates must obey the octet rule\n filter_rdbe=(0, 20), # Candidates must have 0 to 20 ring/double-bond equivalents\n max_counts='C*H*N*O*P0S2' # Element constraints: unlimited C/H/N/O,\n # No phosphorous atoms, up to two sulfurs.\n)\n```\nOutput:\n```\nFormulaSearchResults(query_mass=613.2391, n_results=38)\n\nFormula Error (ppm) Error (Da) RDBE\n----------------------------------------------------------------------\n[C6H25N30O4S]+ -0.12 0.000073 9.5\n[C31H37N2O11]+ 0.14 0.000086 14.5\n[C14H29N24OS2]+ 0.18 0.000110 12.5\n[C16H41N10O11S2]+ 0.20 0.000121 1.5\n[C29H33N12S2]+ -0.64 0.000392 19.5\n... and 33 more\n```\n\n```python\n# If processing many masses, it's better to instantiate a FormulaFinder object\nfrom find_mfs import FormulaFinder\n\nfinder = FormulaFinder()\nfinder.find_formulae(\n mass=613.2391, # Novobiocin [M+H]+ ion; C31H37N2O11+\n charge=1, \n error_ppm=5.0, \n # ... etc\n)\n```\n\n### Jupyter Notebook:\nSee [this Jupyter notebook](docs/basic_usage.ipynb) for more thorough examples/demonstrations\n\n---\n**If you use this package, make sure to cite:**\n- [B\u00f6cker & Lipt\u00e1k, 2007](https://link.springer.com/article/10.1007/s00453-007-0162-8) - this package uses their algorithm for formula finding...\n - ...as implemented in SIRIUS: [B\u00f6cker et. al., 2008](https://academic.oup.com/bioinformatics/article/25/2/218/218950)\n- [\u0141\u0105cki, Valkenborg & Startek 2020](https://pubs.acs.org/doi/10.1021/acs.analchem.0c00959) - this package uses IsoSpecPy to quickly simulate isotope envelopes\n- [Gohlke, 2025](https://zenodo.org/records/17059777) - this package uses `molmass`, which provides very convenient methods for handling chemical formulae\n\n\n## Contributing\n\nContributions are welcome. Here's a list of features I feel should be implemented eventually:\n- Statistics-based isotope envelope fitting\n- Fragmentation constraints\n- Element ratio constraints\n- GUI app\n\n## License\n\nThis project is distributed under the GPL-3 license.\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A Python package for finding molecular formula candidates from a mass and error window",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://github.com/mhagar/find-mfs#readme",
"Homepage": "https://github.com/mhagar/find-mfs",
"Issues": "https://github.com/mhagar/find-mfs/issues",
"Repository": "https://github.com/mhagar/find-mfs"
},
"split_keywords": [
"mass spectrometry",
" molecular formula",
" accurate mass",
" chemistry",
" proteomics",
" metabolomics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b4789cef9b7112e01b427aae74694e38127db55feed106a542280c31dcabe473",
"md5": "6f48d7322897848965a4057dfa4339c4",
"sha256": "0c07c742aee1b49e38aee65e10726dbb37700385b86dea797401779ec090a856"
},
"downloads": -1,
"filename": "find_mfs-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6f48d7322897848965a4057dfa4339c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 220745,
"upload_time": "2025-10-27T19:07:18",
"upload_time_iso_8601": "2025-10-27T19:07:18.338811Z",
"url": "https://files.pythonhosted.org/packages/b4/78/9cef9b7112e01b427aae74694e38127db55feed106a542280c31dcabe473/find_mfs-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1a855902aa27a03fcb7646aea587b2d31ed1fd6e7fdef8d03b598b1b3545e4a1",
"md5": "c0e450ef1e2a0b147aaffbd7452660ea",
"sha256": "f85e2566094dbdb53e5458bdd5909a24beedbbaa3c83f5dd55bae7d95b1b9e21"
},
"downloads": -1,
"filename": "find_mfs-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "c0e450ef1e2a0b147aaffbd7452660ea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 219608,
"upload_time": "2025-10-27T19:07:19",
"upload_time_iso_8601": "2025-10-27T19:07:19.755895Z",
"url": "https://files.pythonhosted.org/packages/1a/85/5902aa27a03fcb7646aea587b2d31ed1fd6e7fdef8d03b598b1b3545e4a1/find_mfs-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 19:07:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mhagar",
"github_project": "find-mfs#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "find-mfs"
}
JSON
