Merge pull request #27 from HzaCode/feat/enhance-get-properties

🚀 ChemInformant v2.4.0 - Core `get_properties()` Enhancement

Author: HzaCode

CITATION.cff

@@ -5,7 +5,7 @@ authors:
     given-names: "Zhiang"
     orcid: "https://orcid.org/0009-0009-0171-4578"
 title: "ChemInformant"
-version: 2.2.2
+version: 2.4.0
 date-released: 2025
 url: "https://github.com/HzaCode/ChemInformant"
 license: MIT

README.md

@@ -99,11 +99,12 @@ print(df)
 | `get_cas(id)`              | CAS Registry Number *(str)*                   |
 | `get_iupac_name(id)`       | IUPAC name *(str)*                            |
 | `get_canonical_smiles(id)` | Canonical SMILES with Canonical→Connectivity fallback *(str)* |
-| `get_isomeric_smiles(id)`  | Isomeric SMILES *(str)*                       |
+| `get_isomeric_smiles(id)`  | Isomeric SMILES with Isomeric→SMILES fallback *(str)* |
 | `get_xlogp(id)`            | XLogP (calculated hydrophobicity) *(float)*   |
 | `get_synonyms(id)`         | List of synonyms *(List[str])*                |
 | `get_compound(id)`         | Full, validated **`Compound`** object (Pydantic v2 model) |
 
+*Note: This table shows key convenience functions for demonstration. ChemInformant provides **22 convenience functions** in total, covering molecular descriptors, mass properties, stereochemistry, and more.*
 
 *All functions accept a **CID, name, or SMILES** and return `None`/`[]` on failure.*
 

benchmark.py

@@ -1,7 +1,7 @@
 
 """
 ChemInformant vs. PubChemPy
-(285 unique drugs × 6 properties)
+(285 unique drugs x 6 properties)
 
 Output:
   • PubChemPy bulk time

docs/source/advanced_usage.rst

@@ -4,6 +4,9 @@ Application in Real-World Scientific Workflows
 
 The core value of ChemInformant lies in its role as a starting point for data science workflows, seamlessly injecting chemical data into Python's powerful scientific computing ecosystem. This page will demonstrate through three cases that more closely resemble real-world research scenarios how ChemInformant can be combined with advanced libraries like **RDKit**, **Scikit-learn**, and **NetworkX** to accomplish diverse tasks ranging from data preprocessing and multi-class classification to community detection.
 
+.. note::
+   All examples use ChemInformant's standardized **snake_case** property names for consistent data handling across workflows.
+
 .. note::
    The examples on this page depend on additional specialized libraries.
 
@@ -100,12 +103,14 @@ We can use the **data obtained from ChemInformant** as features to train a machi
        ids.extend(drugs)
        labels.extend([cls] * len(drugs))
 
-   # 2. Use ci to get feature data and calculate TPSA with RDKit
-   df_feat = ci.get_properties(ids, ['molecular_weight', 'xlogp', 'isomeric_smiles'])
+   # 2. Use ci to get comprehensive feature data efficiently
+   # NEW: Using all_properties for comprehensive dataset
+   df_feat = ci.get_properties(ids, all_properties=True)
    df_feat_clean = df_feat[df_feat['status'] == 'OK'].copy()
-   df_feat_clean['tpsa'] = df_feat_clean['isomeric_smiles'].apply(
-       lambda s: rdMolDescriptors.CalcTPSA(Chem.MolFromSmiles(s))
-   )
+   
+   # Extract key features already available from ChemInformant
+   features = ['molecular_weight', 'xlogp', 'tpsa', 'h_bond_donor_count', 
+              'h_bond_acceptor_count', 'rotatable_bond_count']
 
    # 3. Prepare training data and perform cross-validation
    features = ['molecular_weight', 'xlogp', 'tpsa']

docs/source/api/api_helpers.rst

@@ -1,6 +1,6 @@
-================================
+=====================================
 Internal API Helpers (`api_helpers`)
-================================
+=====================================
 
 .. module:: ChemInformant.api_helpers
 

docs/source/api/cheminfo_api.rst

@@ -1,6 +1,6 @@
-=============================
+====================================
 Main API Interface (`cheminfo_api`)
-=============================
+====================================
 
 .. module:: ChemInformant.cheminfo_api
 
@@ -21,13 +21,47 @@ This module is the main entry point for all user interactions. It is designed ar
 
 .. rubric:: Convenience Lookups
 
+**Basic Properties**
+
 .. autofunction:: get_weight
 .. autofunction:: get_formula
 .. autofunction:: get_cas
 .. autofunction:: get_iupac_name
+
+**SMILES and Identifiers**
+
 .. autofunction:: get_canonical_smiles
 .. autofunction:: get_isomeric_smiles
+.. autofunction:: get_inchi
+.. autofunction:: get_inchi_key
+
+**Molecular Descriptors**
+
 .. autofunction:: get_xlogp
+.. autofunction:: get_tpsa
+.. autofunction:: get_complexity
+
+**Mass Properties**
+
+.. autofunction:: get_exact_mass
+.. autofunction:: get_monoisotopic_mass
+
+**Molecular Counts**
+
+.. autofunction:: get_h_bond_donor_count
+.. autofunction:: get_h_bond_acceptor_count
+.. autofunction:: get_rotatable_bond_count
+.. autofunction:: get_heavy_atom_count
+.. autofunction:: get_charge
+
+**Stereochemistry**
+
+.. autofunction:: get_atom_stereo_count
+.. autofunction:: get_bond_stereo_count
+.. autofunction:: get_covalent_unit_count
+
+**Synonyms and Names**
+
 .. autofunction:: get_synonyms
 
 .. rubric:: Visualization Functions

docs/source/api/models.rst

@@ -1,6 +1,6 @@
-==================================
+=======================================
 Data Models and Exceptions (`models`)
-==================================
+=======================================
 
 .. module:: ChemInformant.models
 
@@ -16,7 +16,6 @@ By defining clear data models, this module ensures that all data consumed by the
    :show-inheritance:
    :member-order: bysource
    :exclude-members: __init__
-   :no-value:
 
 .. rubric:: Custom Exceptions
 

docs/source/api_reference.rst

@@ -1,19 +1,22 @@
-==========
+===========
 Basic Usage
-==========
+===========
 
 This guide covers the fundamental features of the ChemInformant library, designed to help users quickly get started with common chemical information query tasks.
 
 .. contents:: Contents
     :local:
 
-----------------------------------------------------
+-----------------------------------------------------
 Core Functionality: Bulk Fetching of Multiple Properties
-----------------------------------------------------
+-----------------------------------------------------
 
 The most central feature of ChemInformant is :func:`~ChemInformant.get_properties`. This function is designed for batch processing, allowing users to query multiple chemical properties for a group of compounds in a single call. This approach is significantly more efficient than querying each compound individually in a loop because it effectively consolidates network requests.
 
-The function accepts a list of various identifiers (such as common names, PubChem CIDs, or SMILES strings) and returns a structured Pandas DataFrame, ready for direct use in subsequent data analysis.
+The function accepts a list of various identifiers (such as common names, PubChem CIDs, or SMILES strings) and returns a structured Pandas DataFrame with **standardized snake_case column names**, ready for direct use in subsequent data analysis.
+
+.. note::
+   **Snake_case Property Names**: ChemInformant uses consistent snake_case naming (e.g., ``molecular_weight``, ``h_bond_donor_count``) for all returned data. Both snake_case and CamelCase inputs are accepted, but output is always standardized.
 
 .. code-block:: python
 
@@ -24,7 +27,7 @@ The function accepts a list of various identifiers (such as common names, PubChe
     #    (Aspirin, Caffeine, Acetaminophen)
     identifiers = ['aspirin', 'caffeine', 1983] 
 
-    # 2. Specify the properties you want to fetch
+    # 2. Specify the properties you want to fetch (using snake_case names)
     properties_to_fetch = ['molecular_weight', 'xlogp', 'cas', 'iupac_name']
 
     # 3. Call the core function to perform the query
@@ -43,6 +46,24 @@ Output:
   caffeine            2519.0   OK    194.19            -0.07     58-08-2    1,3,7-trimethylpurine-2,6-dione
   1983                1983.0   OK    151.16            0.51      103-90-2   N-(4-hydroxyphenyl)acetamide
 
+---------------------------------------------------------
+Getting All Properties or Including 3D Descriptors
+---------------------------------------------------------
+
+ChemInformant offers convenient options to retrieve comprehensive data sets:
+
+.. code-block:: python
+
+    # Get all ~40 available properties for a compound
+    complete_data = ci.get_properties(['aspirin'], all_properties=True)
+    print(f"Retrieved {len(complete_data.columns)} columns of data")
+
+    # Get core properties plus 3D molecular descriptors
+    data_with_3d = ci.get_properties(['aspirin'], include_3d=True)
+    
+    # Both approaches are much more efficient than multiple API calls
+
+The ``all_properties=True`` option retrieves every available property from PubChem, including core properties, 3D descriptors, and special properties like CAS numbers and synonyms. The ``include_3d=True`` option adds 3D molecular descriptors to the default core property set.
 
 ------------------------------------------------
 Getting Complete Information for a Single Compound
@@ -109,6 +130,8 @@ Output:
     CAS number for water: 7732-18-5
     Molecular formula of ethanol: C2H6O
 
+ChemInformant provides **22 convenience functions** for individual properties, covering molecular descriptors, structural features, mass properties, and identifiers. All functions return None for compounds that cannot be found, making error handling straightforward.
+
 -----------------------------
 Visualizing Compound Structures
 -----------------------------

docs/source/basic_usage.rst

@@ -33,18 +33,38 @@ ChemInformant provides a suite of command-line interface (CLI) tools, designed t
 
 .. option:: --props <property_list>
 
-   A comma-separated list of properties to precisely specify which data to retrieve for each identifier. If the user does not provide this option, `chemfetch` will use a default set of properties: ``cas,molecular_weight,iupac_name``.
+   A comma-separated list of properties to precisely specify which data to retrieve for each identifier. If the user does not provide this option, `chemfetch` will use the default core property set (20+ essential properties including molecular_weight, formula, smiles, etc.).
 
-   The complete list of available properties includes:
+   .. note::
+      **Property Names Use snake_case Format**
+
+      ChemInformant uses standardized snake_case property names (e.g., ``molecular_weight``, ``h_bond_donor_count``). 
+      Both snake_case and CamelCase inputs are accepted, but output is always in snake_case for consistency.
+
+   The complete list of available properties includes **Core Properties** (default set):
 
-   * ``cas``: CAS Registry Number, a common chemical identifier.
    * ``molecular_weight``: Molecular weight, in g/mol.
-   * ``molecular_formula``: Molecular formula, indicating the number of atoms of each element in the compound.
-   * ``canonical_smiles``: Canonical SMILES string.
-   * ``isomeric_smiles``: Isomeric SMILES string.
+   * ``molecular_formula``: Molecular formula.
+   * ``canonical_smiles``, ``isomeric_smiles``: SMILES representations.
    * ``iupac_name``: The systematic name established by IUPAC.
    * ``xlogp``: Calculated octanol-water partition coefficient.
-   * ``synonyms``: A list of all known synonyms.
+   * ``tpsa``: Topological polar surface area.
+   * ``complexity``: Molecular complexity score.
+   * ``h_bond_donor_count``, ``h_bond_acceptor_count``: Hydrogen bonding properties.
+   * ``rotatable_bond_count``, ``heavy_atom_count``: Molecular structure counts.
+   * ``charge``: Formal molecular charge.
+   * ``atom_stereo_count``, ``bond_stereo_count``: Stereochemistry information.
+   * ``covalent_unit_count``: Number of covalent units.
+   * ``in_ch_i``, ``in_ch_i_key``: InChI identifiers.
+   * ``cas``: CAS Registry Number.
+   * ``synonyms``: List of all known synonyms.
+
+   **3D Properties** (available with ``--include-3d``):
+
+   * ``volume_3d``: 3D molecular volume.
+   * ``feature_count_3d``, ``feature_acceptor_count_3d``, etc.: 3D pharmacophore features.
+   * ``conformer_count_3d``: Number of conformers.
+   * And more spatial descriptors...
 
 .. option:: -f, --format <format_type>
 
@@ -55,6 +75,14 @@ ChemInformant provides a suite of command-line interface (CLI) tools, designed t
    * ``json``: JSON array output.
    * ``sql``: Writes to a SQLite database (requires ``--output``).
 
+.. option:: --include-3d
+
+   Include 3D molecular descriptors in addition to the default core properties. This option is ignored when ``--props`` is specified. The 3D properties include volume_3d, feature_count_3d, conformer_count_3d, and other spatial descriptors.
+
+.. option:: --all-properties
+
+   Retrieve all ~40 available properties from PubChem, including core properties, 3D descriptors, and special properties like CAS and synonyms. This option is mutually exclusive with ``--props`` and ``--include-3d``.
+
 .. option:: -o, --output <file_path>
 
    Specifies the path for the output file. Required for ``--format sql`` and ignored otherwise.
@@ -75,7 +103,29 @@ ChemInformant provides a suite of command-line interface (CLI) tools, designed t
       aspirin            2244     OK      50-78-2   180.16           2-(acetyloxy)benzoic acid
       caffeine           2519     OK      58-08-2   194.19           1,3,7-trimethylpurine-2,6-dione
 
-2. **Valid and Invalid Identifiers**
+2. **Get All Properties**
+
+   .. code-block:: bash
+
+      chemfetch aspirin --all-properties --format csv -o aspirin_complete.csv
+
+   This retrieves all ~40 available properties for aspirin and saves to CSV.
+
+3. **Include 3D Descriptors**
+
+   .. code-block:: bash
+
+      chemfetch aspirin --include-3d
+
+   This includes 3D molecular descriptors in addition to the core property set.
+
+4. **Custom Property Selection**
+
+   .. code-block:: bash
+
+      chemfetch aspirin caffeine --props "molecular_weight,xlogp,tpsa,h_bond_donor_count"
+
+5. **Valid and Invalid Identifiers**
 
    .. code-block:: bash
 
@@ -85,10 +135,10 @@ ChemInformant provides a suite of command-line interface (CLI) tools, designed t
 
    .. code-block:: text
 
-      input_identifier         cid   status         cas     molecular_weight  iupac_name
-      caffeine                 2519  OK             58-08-2 194.19            1,3,7-trimethylpurine-2,6-dione
-      ThisIsA_FakeCompound     <NA>  NotFoundError  <NA>    NaN               <NA>
-      999999999                <NA>  NotFoundError  <NA>    NaN               <NA>
+      input_identifier         cid   status         molecular_weight  xlogp  cas     
+      caffeine                 2519  OK             194.19            -0.07  58-08-2 
+      ThisIsA_FakeCompound     <NA>  NotFoundError  <NA>              <NA>   <NA>    
+      999999999                <NA>  NotFoundError  <NA>              <NA>   <NA>
 
 **Using `chemfetch` in Data Processing Pipelines**