cholla-chem 0.2.0__tar.gz

cholla_chem-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 De Novo Chem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cholla_chem-0.2.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: cholla_chem
+Version: 0.2.0
+Summary: Name-to-SMILES conversion
+Author-email: De Novo Chem Team <carson.britt@denovochem.com>
+Project-URL: Homepage, https://github.com/denovochem/cholla_chem
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru~=0.7.0
+Requires-Dist: cirpy~=1.0.0
+Requires-Dist: chemspipy~=2.0.0
+Requires-Dist: rdkit>=2025.9.3
+Requires-Dist: levenshtein
+Requires-Dist: flashtext
+Dynamic: license-file
+
+# cholla_chem
+[![version](https://img.shields.io/github/v/release/denovochem/cholla_chem)](https://github.com/denovochem/cholla_chem/releases)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://gitHub.com/denovochem/cholla_chem/graphs/commit-activity)
+[![License](https://img.shields.io/pypi/l/PubChemPy)](https://github.com/denovochem/cholla_chem/blob/main/LICENSE)
+[![Run Tests](https://github.com/denovochem/cholla_chem/actions/workflows/tests.yml/badge.svg)](https://github.com/denovochem/cholla_chem/actions/workflows/tests.yml)
+[![Build Docs](https://github.com/denovochem/cholla_chem/actions/workflows/docs.yml/badge.svg)](https://github.com/denovochem/cholla_chem/actions/workflows/docs.yml)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/denovochem/cholla_chem/blob/main/examples/example_notebook.ipynb)
+
+This library is used for performant, comprehensive, and customizable name-to-SMILES conversions. 
+
+This library can use the following existing name-to-SMILES resolvers:
+- [OPSIN](https://github.com/dan2097/opsin) using code adapted from [py2opsin](https://github.com/JacksonBurns/py2opsin)
+- [PubChem](https://pubchem.ncbi.nlm.nih.gov/) using code adapted from [PubChemPy](https://github.com/mcs07/PubChemPy)
+- [CIRpy](https://github.com/mcs07/CIRpy)
+- [ChemSpiPy](https://github.com/mcs07/ChemSpiPy)
+
+This library also implements the following new resolvers:
+- Manually curated dataset of common names not correctly resolved by other resolvers (e.g. 'NaH')
+- Structural formula resolver (e.g. 'CH3CH2CH2COOH')
+- Inorganic shorthand resolver (e.g. '[Cp*RhCl2]2')
+
+
+The following string editing/manipulation strategies may be applied to compounds to assist with name-to-SMILES resolution:
+- String sanitization for special characters and mojibake encoding errors
+- Name correction for OCR errors, typos, pagination errors, etc. 
+- Splitting compounds on common delimiters (useful for mixtures of compounds, e.g. 'BH3•THF')
+- Peptide shorthand expansion (e.g. 'cyclo(Asp-Arg-Val-Tyr-Ile-His-Pro-Phe)' -> 'cyclo(l-aspartyl-l-arginyl-l-valyl-l-tyrosyl-l-isoleucyl-l-histidyl-l-prolyl-l-phenylalanyl)')
+
+
+When resolvers disagree on the SMILES for a given compound, a variety of SMILES selection methods can be employed to determine the "best" SMILES for a given compound name. See the documentation for more details.
+
+## Installation
+
+Install cholla_chem with pip directly from this repo:
+
+```shell
+pip install git+https://github.com/denovochem/cholla_chem.git
+```
+
+## Basic usage
+Resolve chemical names to SMILES by passing a string or a list of strings:
+```pycon
+from cholla_chem import resolve_compounds_to_smiles
+
+resolved_smiles = resolve_compounds_to_smiles(compounds_list=['aspirin'])
+
+"{'aspirin': 'CC(=O)Oc1ccccc1C(=O)O'}"
+```
+
+See detailed information including which resolver returned which SMILES with detailed_name_dict=True:
+```pycon
+from cholla_chem import resolve_compounds_to_smiles
+
+resolved_smiles = resolve_compounds_to_smiles(
+    compounds_list=['2-acetyloxybenzoic acid'], 
+    detailed_name_dict=True
+)
+
+"{'2-acetyloxybenzoic acid': {
+    'SMILES': 'CC(=O)Oc1ccccc1C(=O)O',
+    'SMILES_source': ['pubchem_default', 'opsin_default'],
+    'SMILES_dict': {
+        'CC(=O)Oc1ccccc1C(=O)O': ['pubchem_default', 'opsin_default']
+    },
+    'additional_info': {}
+}}"
+```
+
+## Advanced usage
+Many aspects of the name-to-SMILES resolution process can be customized, including the resolvers that are used, the configuration of those resolvers, and the strategy used to pick the best SMILES.
+
+In this example, we resolve chemical names with OPSIN, PubChem, and CIRPy, and use a custom consensus weighting approach to pick the best SMILES:
+```pycon
+from cholla_chem import (
+    OpsinNameResolver,
+    PubChemNameResolver,
+    CIRpyNameResolver,
+    resolve_compounds_to_smiles,
+)
+
+opsin_resolver = OpsinNameResolver(
+    resolver_name='opsin', 
+    resolver_weight=4
+)
+pubchem_resolver =  PubChemNameResolver(
+    resolver_name='pubchem', 
+    resolver_weight=3
+)
+cirpy_resolver = CIRpyNameResolver(
+    resolver_name='cirpy', 
+    resolver_weight=2
+)
+
+resolved_smiles = resolve_compounds_to_smiles(
+    compounds_list=['2-acetyloxybenzoic acid'],
+    resolvers_list=[opsin_resolver, pubchem_resolver, cirpy_resolver],
+    smiles_selection_mode='weighted',
+    detailed_name_dict=True
+)
+
+"{'2-acetyloxybenzoic acid': {
+    'SMILES': 'CC(=O)Oc1ccccc1C(=O)O',
+    'SMILES_source': ['opsin', 'pubchem', 'cirpy'],
+    'SMILES_dict': {
+        'CC(=O)Oc1ccccc1C(=O)O': ['opsin', 'pubchem', 'cirpy']
+    },
+    'additional_info': {}
+}}"
+```
+
+## Command line interface
+
+cholla_chem can be used as a command line tool. The command line interface can resolve single chemical names directly from the command line or read from a file.
+
+Resolve compounds directly from the command line:
+```bash
+cholla-chem "aspirin"
+```
+
+Resolve compounds from a file:
+```bash
+cholla-chem --input names.txt --output results.tsv
+```
+
+See help for more options:
+```bash
+cholla-chem --help
+```
+
+See documentation for more details. 
+
+## Documentation
+Full documentation is available [here](https://denovochem.github.io/cholla_chem/)
+
+## Contributing
+
+- Feature ideas and bug reports are welcome on the Issue Tracker.
+- Fork the [source code](https://github.com/denovochem/cholla_chem) on GitHub, make changes and file a pull request.
+
+## License
+
+cholla_chem is licensed under the [MIT license](https://github.com/denovochem/cholla_chem/blob/main/LICENSE).

cholla_chem-0.2.0/README.md

@@ -0,0 +1,142 @@
+# cholla_chem
+[![version](https://img.shields.io/github/v/release/denovochem/cholla_chem)](https://github.com/denovochem/cholla_chem/releases)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://gitHub.com/denovochem/cholla_chem/graphs/commit-activity)
+[![License](https://img.shields.io/pypi/l/PubChemPy)](https://github.com/denovochem/cholla_chem/blob/main/LICENSE)
+[![Run Tests](https://github.com/denovochem/cholla_chem/actions/workflows/tests.yml/badge.svg)](https://github.com/denovochem/cholla_chem/actions/workflows/tests.yml)
+[![Build Docs](https://github.com/denovochem/cholla_chem/actions/workflows/docs.yml/badge.svg)](https://github.com/denovochem/cholla_chem/actions/workflows/docs.yml)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/denovochem/cholla_chem/blob/main/examples/example_notebook.ipynb)
+
+This library is used for performant, comprehensive, and customizable name-to-SMILES conversions. 
+
+This library can use the following existing name-to-SMILES resolvers:
+- [OPSIN](https://github.com/dan2097/opsin) using code adapted from [py2opsin](https://github.com/JacksonBurns/py2opsin)
+- [PubChem](https://pubchem.ncbi.nlm.nih.gov/) using code adapted from [PubChemPy](https://github.com/mcs07/PubChemPy)
+- [CIRpy](https://github.com/mcs07/CIRpy)
+- [ChemSpiPy](https://github.com/mcs07/ChemSpiPy)
+
+This library also implements the following new resolvers:
+- Manually curated dataset of common names not correctly resolved by other resolvers (e.g. 'NaH')
+- Structural formula resolver (e.g. 'CH3CH2CH2COOH')
+- Inorganic shorthand resolver (e.g. '[Cp*RhCl2]2')
+
+
+The following string editing/manipulation strategies may be applied to compounds to assist with name-to-SMILES resolution:
+- String sanitization for special characters and mojibake encoding errors
+- Name correction for OCR errors, typos, pagination errors, etc. 
+- Splitting compounds on common delimiters (useful for mixtures of compounds, e.g. 'BH3•THF')
+- Peptide shorthand expansion (e.g. 'cyclo(Asp-Arg-Val-Tyr-Ile-His-Pro-Phe)' -> 'cyclo(l-aspartyl-l-arginyl-l-valyl-l-tyrosyl-l-isoleucyl-l-histidyl-l-prolyl-l-phenylalanyl)')
+
+
+When resolvers disagree on the SMILES for a given compound, a variety of SMILES selection methods can be employed to determine the "best" SMILES for a given compound name. See the documentation for more details.
+
+## Installation
+
+Install cholla_chem with pip directly from this repo:
+
+```shell
+pip install git+https://github.com/denovochem/cholla_chem.git
+```
+
+## Basic usage
+Resolve chemical names to SMILES by passing a string or a list of strings:
+```pycon
+from cholla_chem import resolve_compounds_to_smiles
+
+resolved_smiles = resolve_compounds_to_smiles(compounds_list=['aspirin'])
+
+"{'aspirin': 'CC(=O)Oc1ccccc1C(=O)O'}"
+```
+
+See detailed information including which resolver returned which SMILES with detailed_name_dict=True:
+```pycon
+from cholla_chem import resolve_compounds_to_smiles
+
+resolved_smiles = resolve_compounds_to_smiles(
+    compounds_list=['2-acetyloxybenzoic acid'], 
+    detailed_name_dict=True
+)
+
+"{'2-acetyloxybenzoic acid': {
+    'SMILES': 'CC(=O)Oc1ccccc1C(=O)O',
+    'SMILES_source': ['pubchem_default', 'opsin_default'],
+    'SMILES_dict': {
+        'CC(=O)Oc1ccccc1C(=O)O': ['pubchem_default', 'opsin_default']
+    },
+    'additional_info': {}
+}}"
+```
+
+## Advanced usage
+Many aspects of the name-to-SMILES resolution process can be customized, including the resolvers that are used, the configuration of those resolvers, and the strategy used to pick the best SMILES.
+
+In this example, we resolve chemical names with OPSIN, PubChem, and CIRPy, and use a custom consensus weighting approach to pick the best SMILES:
+```pycon
+from cholla_chem import (
+    OpsinNameResolver,
+    PubChemNameResolver,
+    CIRpyNameResolver,
+    resolve_compounds_to_smiles,
+)
+
+opsin_resolver = OpsinNameResolver(
+    resolver_name='opsin', 
+    resolver_weight=4
+)
+pubchem_resolver =  PubChemNameResolver(
+    resolver_name='pubchem', 
+    resolver_weight=3
+)
+cirpy_resolver = CIRpyNameResolver(
+    resolver_name='cirpy', 
+    resolver_weight=2
+)
+
+resolved_smiles = resolve_compounds_to_smiles(
+    compounds_list=['2-acetyloxybenzoic acid'],
+    resolvers_list=[opsin_resolver, pubchem_resolver, cirpy_resolver],
+    smiles_selection_mode='weighted',
+    detailed_name_dict=True
+)
+
+"{'2-acetyloxybenzoic acid': {
+    'SMILES': 'CC(=O)Oc1ccccc1C(=O)O',
+    'SMILES_source': ['opsin', 'pubchem', 'cirpy'],
+    'SMILES_dict': {
+        'CC(=O)Oc1ccccc1C(=O)O': ['opsin', 'pubchem', 'cirpy']
+    },
+    'additional_info': {}
+}}"
+```
+
+## Command line interface
+
+cholla_chem can be used as a command line tool. The command line interface can resolve single chemical names directly from the command line or read from a file.
+
+Resolve compounds directly from the command line:
+```bash
+cholla-chem "aspirin"
+```
+
+Resolve compounds from a file:
+```bash
+cholla-chem --input names.txt --output results.tsv
+```
+
+See help for more options:
+```bash
+cholla-chem --help
+```
+
+See documentation for more details. 
+
+## Documentation
+Full documentation is available [here](https://denovochem.github.io/cholla_chem/)
+
+## Contributing
+
+- Feature ideas and bug reports are welcome on the Issue Tracker.
+- Fork the [source code](https://github.com/denovochem/cholla_chem) on GitHub, make changes and file a pull request.
+
+## License
+
+cholla_chem is licensed under the [MIT license](https://github.com/denovochem/cholla_chem/blob/main/LICENSE).

cholla_chem-0.2.0/cholla_chem/__init__.py

@@ -0,0 +1,31 @@
+"""cholla_chem initialization."""
+
+from cholla_chem.main import (
+    ChemicalNameResolver,
+    ChemSpiPyResolver,
+    CIRpyNameResolver,
+    InorganicShorthandNameResolver,
+    ManualNameResolver,
+    OpsinNameResolver,
+    PubChemNameResolver,
+    StructuralFormulaNameResolver,
+    resolve_compounds_to_smiles,
+)
+from cholla_chem.name_manipulation.name_correction.dataclasses import CorrectorConfig
+from cholla_chem.name_manipulation.name_correction.name_corrector import (
+    ChemNameCorrector,
+)
+
+__all__ = [
+    "resolve_compounds_to_smiles",
+    "ChemSpiPyResolver",
+    "ChemicalNameResolver",
+    "ManualNameResolver",
+    "OpsinNameResolver",
+    "PubChemNameResolver",
+    "StructuralFormulaNameResolver",
+    "CIRpyNameResolver",
+    "InorganicShorthandNameResolver",
+    "ChemNameCorrector",
+    "CorrectorConfig",
+]

cholla_chem-0.2.0/cholla_chem/cli.py

@@ -0,0 +1,136 @@
+import argparse
+from typing import Optional, Sequence
+
+from cholla_chem.main import resolve_compounds_to_smiles
+from cholla_chem.utils.file_utils import read_names_from_file, write_results
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """
+    Build a parser for the CLI.
+
+    Returns:
+        argparse.ArgumentParser: A parser object
+    """
+    p = argparse.ArgumentParser(prog="cholla-chem")
+    p.add_argument("names", nargs="*", type=str, help="Chemical names to resolve")
+    p.add_argument("--input", "-i", type=str, help="Text file with one name per line")
+    p.add_argument(
+        "--input-format",
+        type=str,
+        default=None,
+        choices=["txt", "csv", "tsv"],
+        help="Optional override for input format (otherwise inferred from file extension)",
+    )
+    p.add_argument(
+        "--input-column",
+        type=str,
+        default="name",
+        help="Column name to read from CSV/TSV inputs (default: name)",
+    )
+    p.add_argument(
+        "--output", "-o", type=str, help="Write results to a file (default: stdout)"
+    )
+    p.add_argument(
+        "--output-format",
+        type=str,
+        default=None,
+        choices=["json", "csv", "tsv", "smi", "txt"],
+        help="Optional override for output format (otherwise inferred from output file extension)",
+    )
+    p.add_argument(
+        "--smiles-selection-mode",
+        default="weighted",
+        type=str,
+        help="Smiles selection mode",
+    )
+    p.add_argument(
+        "--detailed-name-dict",
+        default=False,
+        type=bool,
+        help="Whether to return a detailed name dictionary",
+    )
+    p.add_argument("--batch-size", default=500, type=int, help="Batch size")
+    p.add_argument(
+        "--normalize-unicode",
+        default=True,
+        type=bool,
+        help="Whether to normalize unicode",
+    )
+    p.add_argument(
+        "--split-names-to-solve",
+        default=True,
+        type=bool,
+        help="Whether to split names to solve",
+    )
+    p.add_argument(
+        "--resolve-peptide-shorthand",
+        default=True,
+        type=bool,
+        help="Whether to resolve peptide shorthand",
+    )
+    p.add_argument(
+        "--attempt-name-correction",
+        default=True,
+        type=bool,
+        help="Whether to attempt name correction",
+    )
+    p.add_argument(
+        "--internet-connection-available",
+        default=True,
+        type=bool,
+        help="Whether an internet connection is available",
+    )
+    return p
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """
+    Main entry point for the CLI.
+
+    Resolve compound names to SMILES strings.
+
+    Args:
+        argv: Optional sequence of command-line arguments
+
+    Returns:
+        int: Exit code (0 for success, non-zero for failure)
+    """
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    names = list(args.names)
+    if args.input:
+        names.extend(
+            read_names_from_file(
+                args.input,
+                input_format=args.input_format,
+                input_column=args.input_column,
+            )
+        )
+
+    if not names:
+        parser.error("Provide names as arguments or via --input")
+
+    if args.output_format != "json" and args.detailed_name_dict:
+        parser.error("--detailed-name-dict can only be used with JSON output format")
+
+    results = resolve_compounds_to_smiles(
+        names,
+        smiles_selection_mode=args.smiles_selection_mode,
+        detailed_name_dict=args.detailed_name_dict,
+        batch_size=args.batch_size,
+        normalize_unicode=args.normalize_unicode,
+        split_names_to_solve=args.split_names_to_solve,
+        resolve_peptide_shorthand=args.resolve_peptide_shorthand,
+        attempt_name_correction=args.attempt_name_correction,
+        internet_connection_available=args.internet_connection_available,
+    )
+
+    write_results(
+        results,
+        output_path=args.output,
+        output_format=args.output_format,
+    )
+
+    return 0