CommonChemistry Ruby Library

A Ruby client library for the Common Chemistry API, providing easy access to chemical substance data including search functionality, detailed substance information, and data export capabilities.

Table of Contents

• Features
• Installation
• Getting Started
  • Initialization
  • Search Substances
  • Get Substance Details
  • Export Substance Data
• Classes and Data Models
• Error Handling

Features

• Search Substances: Find substances by name, CAS Registry Number, or other identifiers.
• Detailed Information: Retrieve comprehensive data about a substance, including molecular properties and synonyms.
• Data Export: Export substance data in plain text format.
• Error Handling: Custom exceptions for graceful error management.
• Easy Integration: Designed to be simple and idiomatic for Ruby developers.

Installation

Add this line to your application's Gemfile:

gem 'commonchemistry'

Or install it yourself with:

gem install commonchemistry

Note: Depends on httparty:

gem install httparty

Getting Started

Initialization

Begin by requiring the library and initializing a new client:

require 'commonchemistry'

client = CommonChemistry::Client.new

Search Substances

Search for substances using the search method:

search_results = client.search(q: 'water', offset: 0, size: 10)

puts "Total Results: #{search_results.count}"
search_results.results.each do |result|
  puts "Name: #{result.name}, RN: #{result.rn}"
  # Optionally save the SVG image
  # result.save_image("#{result.rn}.svg")
end

Parameters:

• q (String): The search query.
• offset (Integer, optional): The offset for pagination.
• size (Integer, optional): The number of results to return.

Get Substance Details

Retrieve detailed information about a substance:

detail = client.detail(cas_rn: '7732-18-5')

puts "Name: #{detail.name}"
puts "Molecular Formula: #{detail.molecular_formula}"
puts "Molecular Mass: #{detail.molecular_mass}"

# Experimental Properties
detail.experimental_properties.each do |prop|
  puts "#{prop.name}: #{prop.property} (Source #{prop.source_number})"
end

# Synonyms
puts "Synonyms: #{detail.synonyms.join(', ')}"

# Save the SVG image
# detail.save_image("#{detail.rn}.svg")

Parameters:

• cas_rn (String, optional): The CAS Registry Number of the substance.
• uri (String, optional): The URI of the substance.

Export Substance Data

Export substance data in plain text format:

export_data = client.export(uri: detail.uri)
puts export_data

Parameters:

• uri (String): The URI of the substance.
• return_as_attachment (Boolean, optional): Whether to return the data as an attachment.

Classes and Data Models

Client

The main class for interacting with the API.

• search(q:, offset: nil, size: nil): Searches for substances.
• detail(cas_rn: nil, uri: nil): Retrieves detailed substance information.
• export(uri:, return_as_attachment: false): Exports substance data.

SearchResponse

Represents the response from a search query.

• count (Integer): Total number of results.
• results (Array of SearchResult): List of search results.

SearchResult

Represents an individual search result.

• rn (String): CAS Registry Number.
• name (String): Substance name.
• image (String): SVG image data.

DetailResult

Contains detailed information about a substance.

• uri (String)
• rn (String)
• name (String)
• image (String)
• inchi (String)
• inchi_key (String)
• smile (String)
• canonical_smile (String)
• molecular_formula (String)
• molecular_mass (Float)
• experimental_properties (Array of ExperimentalProperty)
• property_citations (Array of PropertyCitation)
• synonyms (Array of String)
• replaced_rns (Array of String)

ExperimentalProperty

Represents an experimental property of a substance.

• name (String)
• property (String)
• source_number (Integer)

PropertyCitation

Represents a citation for a property.

• doc_uri (String)
• source_number (Integer)
• source (String)

Error Handling

The library defines custom exceptions for better error management:

• CommonChemistry::InvalidRequestError: Raised for invalid requests (HTTP 400, 404).
• CommonChemistry::ServerError: Raised when the server returns an internal error (HTTP 500).
• CommonChemistry::UnexpectedResponseError: Raised for any other unexpected HTTP responses.

Example:

begin
  detail = client.detail(cas_rn: 'invalid-cas-rn')
rescue CommonChemistry::InvalidRequestError => e
  puts "Request Error: #{e.message}"
rescue CommonChemistry::ServerError => e
  puts "Server Error: #{e.message}"
rescue CommonChemistry::Error => e
  puts "An error occurred: #{e.message}"
end

---

Disclaimer: This library is not affiliated with or endorsed by its upstream. Use responsibly.