# Formula Validation Python Module
This Python module contains a `Formula` class for working with chemical formulas, as well as methods for creating, manipulating, and analyzing formulas. It also includes functionality for dealing with adducts and calculating monoisotopic masses.
## Table of Contents
- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [Creating Formula Objects](#creating-formula-objects)
- [Basic Operations](#basic-operations)
- [Calculating Mass](#calculating-mass)
- [Fragment Analysis](#fragment-analysis)
- [Examples](#examples)
- [License](#license)
## Introduction
This Python module provides a `Formula` class that allows you to work with chemical formulas. It includes the following features:
- Create Formula objects from Hill notation, SMILES, and InChI.
- Perform basic mathematical operations on formulas (addition, subtraction, multiplication).
- Calculate the monoisotopic mass of a formula.
- Check if a given mass is within a specified tolerance of the formula's mass.
- Analyze possible fragment masses explained by a formula and adduct.
## Installation
To use this module, you'll need Python 3.x and the required dependencies. You can install the dependencies using pip:
```bash
pip install rdkit urllib3 rpy2
```
You should have R installed with the package devtools and
```R
install.packages("devtools")
devtools::install_github("mjhelf/MassTools")
library(MassTools)
```
## Usage
### Creating Formula Objects
You can create a Formula object using various methods:
- `Formula.formula_from_str_hill(formula_str: str, adduct: str) -> 'Formula'`: Create a Formula object from a chemical formula string in Hill notation.
- `Formula.formula_from_str(formula_str: str, adduct: str, no_api: bool = False) -> 'Formula'`: Create a Formula object from a chemical formula string. You can disable API calls for formula resolution by setting `no_api` to `True`.
- `Formula.formula_from_smiles(smiles: str, adduct: str, no_api: bool = False) -> 'Formula'`: Create a Formula object from a SMILES string representing a molecular structure.
- `Formula.formula_from_inchi(inchi: str, adduct: str, no_api: bool = False) -> 'Formula'`: Create a Formula object from an InChI string representing a molecular structure.
### Basic Operations
You can perform various operations on Formula objects:
- Addition: `formula1 + formula2`
- Subtraction: `formula1 - formula2`
- Multiplication: `formula * num`
### Calculating Mass
You can calculate the monoisotopic mass of a formula and check if it matches an external mass:
- `get_monoisotopic_mass() -> float`: Get the monoisotopic mass of the formula.
- `get_monoisotopic_mass_with_adduct() -> float`: Get the monoisotopic mass of the formula, considering the adduct.
- `check_monoisotopic_mass(external_mass: Union[float, int], mass_tolerance_in_ppm: Union[int, float] = __default_ppm) -> bool`: Check if the monoisotopic mass is within a specified tolerance of an external mass.
- `check_monoisotopic_mass_with_adduct(external_mass: Union[float, int], mass_tolerance_in_ppm: Union[int, float] = __default_ppm) -> bool`: Check if the monoisotopic mass, considering the adduct, is within a specified tolerance of an external mass.
### Fragment Analysis
You can analyze potential fragment masses explained by a formula and adduct:
- `check_possible_fragment_mz(fragment_mz: Union[float, int], ppm: Union[float, int] = __default_ppm) -> bool`: Check if a fragment mass can be explained by the formula and adduct.
- `percentage_intensity_fragments_explained_by_formula(fragments_mz_intensities: Dict[Union[float, int], Union[float, int]], ppm: Union[float, int] = __default_ppm) -> float`: Calculate the percentage of intensity of fragments explained by the formula and adduct.
## Examples
Here are some examples of how to use the Formula class:
```python
# Create Formula objects
formula1 = Formula.formula_from_str_hill("C5H5O4", "[M+H]+")
formula2 = Formula.formula_from_smiles("CCO", "[M+NH4]+")
formula3 = formula1 + formula2
# Calculate monoisotopic mass
mass1 = formula1.get_monoisotopic_mass()
mass2 = formula2.get_monoisotopic_mass_with_adduct()
print(f"Mass of formula1: {mass1}")
print(f"Mass of formula2 with adduct: {mass2}")
# Check mass against an external mass with a tolerance of 5 ppm
check_monoisotopic_mass = formula1.check_monoisotopic_mass(121.05142,5)
check_monoisotopic_mass_with_adduct = formula1.check_monoisotopic_mass_with_adduct(122.05862,5)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Wang-Bioinformatics-Lab/formula_validation",
"name": "formula-validation",
"maintainer": "Alberto Gil de la Fuente",
"docs_url": null,
"requires_python": ">3.8",
"maintainer_email": "alberto.gilf@gmail.com",
"keywords": "ms,chemistry",
"author": "Alberto Gil de la Fuente",
"author_email": "alberto.gilf@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/76/43/334fe069780063597c46e18735e3c8ad1d09aa73582c253938972349b5b0/formula_validation-1.0.3.tar.gz",
"platform": null,
"description": "# Formula Validation Python Module\n\nThis Python module contains a `Formula` class for working with chemical formulas, as well as methods for creating, manipulating, and analyzing formulas. It also includes functionality for dealing with adducts and calculating monoisotopic masses.\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Creating Formula Objects](#creating-formula-objects)\n - [Basic Operations](#basic-operations)\n - [Calculating Mass](#calculating-mass)\n - [Fragment Analysis](#fragment-analysis)\n- [Examples](#examples)\n- [License](#license)\n\n## Introduction\n\nThis Python module provides a `Formula` class that allows you to work with chemical formulas. It includes the following features:\n\n- Create Formula objects from Hill notation, SMILES, and InChI.\n- Perform basic mathematical operations on formulas (addition, subtraction, multiplication).\n- Calculate the monoisotopic mass of a formula.\n- Check if a given mass is within a specified tolerance of the formula's mass.\n- Analyze possible fragment masses explained by a formula and adduct.\n\n## Installation\n\nTo use this module, you'll need Python 3.x and the required dependencies. You can install the dependencies using pip:\n\n```bash\npip install rdkit urllib3 rpy2\n```\nYou should have R installed with the package devtools and \n```R\ninstall.packages(\"devtools\")\ndevtools::install_github(\"mjhelf/MassTools\")\n\nlibrary(MassTools)\n```\n## Usage\n\n### Creating Formula Objects\n\nYou can create a Formula object using various methods:\n\n- `Formula.formula_from_str_hill(formula_str: str, adduct: str) -> 'Formula'`: Create a Formula object from a chemical formula string in Hill notation.\n\n- `Formula.formula_from_str(formula_str: str, adduct: str, no_api: bool = False) -> 'Formula'`: Create a Formula object from a chemical formula string. You can disable API calls for formula resolution by setting `no_api` to `True`.\n\n- `Formula.formula_from_smiles(smiles: str, adduct: str, no_api: bool = False) -> 'Formula'`: Create a Formula object from a SMILES string representing a molecular structure.\n\n- `Formula.formula_from_inchi(inchi: str, adduct: str, no_api: bool = False) -> 'Formula'`: Create a Formula object from an InChI string representing a molecular structure.\n\n### Basic Operations\n\nYou can perform various operations on Formula objects:\n\n- Addition: `formula1 + formula2`\n- Subtraction: `formula1 - formula2`\n- Multiplication: `formula * num`\n\n### Calculating Mass\n\nYou can calculate the monoisotopic mass of a formula and check if it matches an external mass:\n\n- `get_monoisotopic_mass() -> float`: Get the monoisotopic mass of the formula.\n- `get_monoisotopic_mass_with_adduct() -> float`: Get the monoisotopic mass of the formula, considering the adduct.\n- `check_monoisotopic_mass(external_mass: Union[float, int], mass_tolerance_in_ppm: Union[int, float] = __default_ppm) -> bool`: Check if the monoisotopic mass is within a specified tolerance of an external mass.\n- `check_monoisotopic_mass_with_adduct(external_mass: Union[float, int], mass_tolerance_in_ppm: Union[int, float] = __default_ppm) -> bool`: Check if the monoisotopic mass, considering the adduct, is within a specified tolerance of an external mass.\n\n### Fragment Analysis\n\nYou can analyze potential fragment masses explained by a formula and adduct:\n\n- `check_possible_fragment_mz(fragment_mz: Union[float, int], ppm: Union[float, int] = __default_ppm) -> bool`: Check if a fragment mass can be explained by the formula and adduct.\n\n- `percentage_intensity_fragments_explained_by_formula(fragments_mz_intensities: Dict[Union[float, int], Union[float, int]], ppm: Union[float, int] = __default_ppm) -> float`: Calculate the percentage of intensity of fragments explained by the formula and adduct.\n\n## Examples\n\nHere are some examples of how to use the Formula class:\n\n```python\n# Create Formula objects\nformula1 = Formula.formula_from_str_hill(\"C5H5O4\", \"[M+H]+\")\nformula2 = Formula.formula_from_smiles(\"CCO\", \"[M+NH4]+\")\nformula3 = formula1 + formula2\n\n# Calculate monoisotopic mass\nmass1 = formula1.get_monoisotopic_mass()\nmass2 = formula2.get_monoisotopic_mass_with_adduct()\nprint(f\"Mass of formula1: {mass1}\")\nprint(f\"Mass of formula2 with adduct: {mass2}\")\n\n# Check mass against an external mass with a tolerance of 5 ppm\ncheck_monoisotopic_mass = formula1.check_monoisotopic_mass(121.05142,5)\ncheck_monoisotopic_mass_with_adduct = formula1.check_monoisotopic_mass_with_adduct(122.05862,5)\n```\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "Package to represent formulas with adducts and process ms data from it.",
"version": "1.0.3",
"project_urls": {
"Homepage": "https://github.com/Wang-Bioinformatics-Lab/formula_validation",
"Repository": "https://github.com/Wang-Bioinformatics-Lab/formula_validation"
},
"split_keywords": [
"ms",
"chemistry"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c894ed569302eb6cac8476a48dfc8ba2a62006fe34cf16936615c8a6ccf26b41",
"md5": "3f090fa0a5d9afaa29a9edf0d7ad5184",
"sha256": "fd2e8d35aa109a62d79114a24c8846089d28530496067582c54843637bb0714b"
},
"downloads": -1,
"filename": "formula_validation-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3f090fa0a5d9afaa29a9edf0d7ad5184",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.8",
"size": 30164,
"upload_time": "2023-10-10T20:18:16",
"upload_time_iso_8601": "2023-10-10T20:18:16.205663Z",
"url": "https://files.pythonhosted.org/packages/c8/94/ed569302eb6cac8476a48dfc8ba2a62006fe34cf16936615c8a6ccf26b41/formula_validation-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7643334fe069780063597c46e18735e3c8ad1d09aa73582c253938972349b5b0",
"md5": "0f892215f7ea0aa61168ed5b76191c5f",
"sha256": "3daa4c541fd10599372fef2cf92e75fe864e695cad01f928c5e4208f2b043333"
},
"downloads": -1,
"filename": "formula_validation-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "0f892215f7ea0aa61168ed5b76191c5f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.8",
"size": 26816,
"upload_time": "2023-10-10T20:18:32",
"upload_time_iso_8601": "2023-10-10T20:18:32.137301Z",
"url": "https://files.pythonhosted.org/packages/76/43/334fe069780063597c46e18735e3c8ad1d09aa73582c253938972349b5b0/formula_validation-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-10 20:18:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Wang-Bioinformatics-Lab",
"github_project": "formula_validation",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "formula-validation"
}
JSON
