# ChemInformant *A Robust Data Acquisition Engine for the Modern Scientific Workflow*
[](https://pepy.tech/project/cheminformant)

ChemInformant is a robust data acquisition engine for the PubChem database, engineered for the modern scientific workflow. It intelligently manages network requests, performs rigorous runtime data validation, and delivers analysis-ready results, providing a dependable foundation for any computational chemistry project in Python.

✨ Key Features

• Analysis-Ready Pandas/SQL Output: The core API (get_properties) returns either a clean Pandas DataFrame or a direct SQL output, eliminating data wrangling boilerplate and enabling immediate integration with both the Python data science ecosystem and modern database workflows.

• Automated Network Reliability: Ensures your workflows run flawlessly with built-in persistent caching, smart rate-limiting, and automatic retries. It also transparently handles API pagination (ListKey) for large-scale queries, delivering complete result sets without any manual intervention.

• Flexible & Fault-Tolerant Input: Natively accepts mixed lists of identifiers (names, CIDs, SMILES) and intelligently handles any invalid inputs by flagging them with a clear status in the output, ensuring a single bad entry never fails an entire batch operation.

• A Dual API for Simplicity and Power: Offers a clear get_<property>() convenience layer for quick lookups, backed by a powerful get_properties engine for high-performance batch operations.

• Guaranteed Data Integrity: Employs Pydantic v2 models for rigorous, runtime data validation when using the object-based API, preventing malformed or unexpected data from corrupting your analysis pipeline.

• Terminal-Ready CLI Tools: Includes chemfetch and chemdraw for rapid data retrieval and 2D structure visualization directly from your terminal, perfect for quick lookups without writing a script.

• Modern and Actively Maintained: Built on a contemporary tech stack for long-term consistency and compatibility, providing a reliable alternative to older or less frequently updated libraries.

📦 Installation

Install the library from PyPI:

bash pip install ChemInformant

To include plotting capabilities for use with the tutorial, install the [plot] extra:

bash pip install "ChemInformant[plot]"

🚀 Quick Start

Retrieve multiple properties for multiple compounds, directly into a Pandas DataFrame, in a single function call:

```python import ChemInformant as ci

1. Define your identifiers

identifiers = ["aspirin", "caffeine", 1983] # 1983 is paracetamol's CID

2. Specify the properties you need

properties = ["molecular_weight", "xlogp", "cas"]

3. Call the core function

df = ci.get_properties(identifiers, properties)

4. Save the results to an SQL database

ci.dftosql(df, "sqlite:///chemdata.db", "results", ifexists="replace")

5. Analyze your results!

print(df) ```

Output:

input_identifier cid status molecular_weight xlogp cas 0 aspirin 2244 OK 180.16 1.2 50-78-2 1 caffeine 2519 OK 194.19 -0.1 58-08-2 2 1983 1983 OK 151.16 0.5 103-90-2

ChemInformant also includes handy command-line tools for quick lookups directly from your terminal:

• chemfetch: Fetches properties for one or more compounds.

  bash chemfetch aspirin --props "cas,molecular_weight,iupac_name"

• chemdraw: Renders the 2D structure of a compound.

  bash chemdraw aspirin

📚 Documentation & Examples

For a deep dive, please see our detailed guides:

• ➡️ Online Documentation: The official documentation site contains complete API references, guides, and usage examples. This is the most comprehensive resource.
• ➡️ Interactive User Manual: Our Jupyter Notebook Tutorial provides a complete, end-to-end walkthrough. This is the best place to start for a hands-on experience.
• ➡️ Performance Benchmarks: You can review and run our Benchmark Script to see the performance advantages of batching and caching.

🤔 Why ChemInformant?

ChemInformant's core mission is to serve as a high-performance data backbone for the Python cheminformatics ecosystem. By delivering clean, validated, and analysis-ready Pandas DataFrames, it enables researchers to effortlessly pipe PubChem data into powerful toolkits like RDKit, Scikit-learn, or custom machine learning models, transforming multi-step data acquisition and wrangling tasks into single, elegant lines of code.

A detailed comparison with other existing tools is provided in our JOSS paper.

🤝 Contributing

Contributions are welcome! For guidelines on how to get started, please read our contributing guide. You can open an issue to report bugs or suggest features, or submit a pull request to contribute code.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📑 Citation

```bibtex @article{He2025, doi = {10.21105/joss.08341}, url = {https://doi.org/10.21105/joss.08341}, year = {2025}, publisher = {The Open Journal}, volume = {10}, number = {112}, pages = {8341}, author = {He, Zhiang}, title = {ChemInformant: A Robust and Workflow-Centric Python Client for High-Throughput PubChem Access}, journal = {Journal of Open Source Software} }