Skip to content

Commit 141579d

Browse files
coderobecoderobe
committed
import
0 parents commit 141579d

File tree

6 files changed

+569
-0
lines changed

6 files changed

+569
-0
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
*.gem

‎LICENSE.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Copyright 2024 coderobe
2+
3+
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:
4+
5+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6+
7+
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.

‎README.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# PubChemAPI Ruby Library
2+
3+
A comprehensive Ruby library for interacting with the [PubChem PUG REST API](https://pubchem.ncbi.nlm.nih.gov/docs/pug-rest). This library provides a user-friendly interface to access PubChem data and services, mapping API responses onto Ruby classes for seamless integration into your applications.
4+
5+
## Table of Contents
6+
7+
- [Features](#features)
8+
- [Installation](#installation)
9+
- [Getting Started](#getting-started)
10+
- [Initialization](#initialization)
11+
- [Usage Examples](#usage-examples)
12+
- [Retrieve Compound Data by CID](#retrieve-compound-data-by-cid)
13+
- [Retrieve Compound Data by Name](#retrieve-compound-data-by-name)
14+
- [Perform a Similarity Search](#perform-a-similarity-search)
15+
- [Retrieve Taxonomy Summary by TaxID](#retrieve-taxonomy-summary-by-taxid)
16+
- [Available Methods](#available-methods)
17+
- [Error Handling](#error-handling)
18+
- [License](#license)
19+
20+
## Features
21+
22+
- **Comprehensive Endpoint Coverage**: Access various PubChem resources such as compounds, substances, assays, genes, proteins, and more.
23+
- **Object Mapping**: API responses are mapped to Ruby classes, allowing easy access to data without handling raw JSON or XML.
24+
- **HTTP Requests with HTTParty**: Efficient and clean HTTP requests using the `httparty` gem.
25+
- **XML Parsing with Nokogiri**: Parse XML responses when necessary using `nokogiri`.
26+
- **Error Handling**: Custom `APIError` class provides detailed error messages and codes.
27+
- **Parameter Validation**: Ensures that only valid parameters are sent to the API.
28+
- **Extensible Design**: Easily extend the library for additional endpoints or complex data mapping.
29+
30+
## Installation
31+
32+
Add this line to your application's `Gemfile`:
33+
34+
```ruby
35+
gem 'pubchem_api'
36+
```
37+
38+
Or install it yourself as:
39+
40+
```bash
41+
$ gem install pubchem_api
42+
```
43+
44+
**Note**: This gem depends on httparty and nokogiri
45+
46+
```bash
47+
$ gem install httparty nokogiri
48+
```
49+
50+
## Getting Started
51+
52+
### Initialization
53+
54+
Require the library in your Ruby script:
55+
56+
```ruby
57+
require 'pubchem_api'
58+
```
59+
60+
Initialize the client:
61+
62+
```ruby
63+
client = PubChemAPI::Client.new
64+
```
65+
66+
### Usage Examples
67+
68+
#### Retrieve Compound Data by CID
69+
70+
```ruby
71+
begin
72+
compound = client.get_compound_by_cid(2244, 'record')
73+
puts "CID: #{compound.cid}"
74+
puts "Molecular Formula: #{compound.molecular_formula}"
75+
puts "Molecular Weight: #{compound.molecular_weight}"
76+
puts "Canonical SMILES: #{compound.canonical_smiles}"
77+
puts "InChIKey: #{compound.inchi_key}"
78+
rescue PubChemAPI::APIError => e
79+
puts "API Error (#{e.code}): #{e.message}"
80+
end
81+
```
82+
83+
#### Retrieve Compound Data by Name
84+
85+
```ruby
86+
begin
87+
compound = client.get_compound_by_name('aspirin', 'record')
88+
puts "CID: #{compound.cid}"
89+
puts "Molecular Formula: #{compound.molecular_formula}"
90+
puts "Molecular Weight: #{compound.molecular_weight}"
91+
rescue PubChemAPI::APIError => e
92+
puts "API Error (#{e.code}): #{e.message}"
93+
end
94+
```
95+
96+
#### Perform a Similarity Search
97+
98+
```ruby
99+
begin
100+
options = {}
101+
options['Threshold'] = 90
102+
results = client.compound_structure_search(
103+
'fastsimilarity_2d',
104+
'smiles',
105+
'CC(=O)OC1=CC=CC=C1C(=O)O',
106+
'JSON',
107+
options
108+
)
109+
cids = results['IdentifierList']['CID']
110+
puts "Found CIDs: #{cids.join(', ')}"
111+
rescue PubChemAPI::APIError => e
112+
puts "API Error (#{e.code}): #{e.message}"
113+
end
114+
```
115+
116+
#### Retrieve Taxonomy Summary by TaxID
117+
118+
```ruby
119+
begin
120+
taxonomy = client.get_taxonomy_summary_by_taxid(9606)
121+
puts "Scientific Name: #{taxonomy.scientific_name}"
122+
puts "Common Name: #{taxonomy.common_name}"
123+
puts "Rank: #{taxonomy.rank}"
124+
rescue PubChemAPI::APIError => e
125+
puts "API Error (#{e.code}): #{e.message}"
126+
end
127+
```
128+
129+
## Available Methods
130+
131+
### Compounds
132+
133+
- `get_compound_by_cid(cid, operation, output = DEFAULT_OUTPUT, options = {})`
134+
- `get_compound_by_name(name, operation, output = DEFAULT_OUTPUT, options = {})`
135+
- `get_compound_conformers(cid, output = DEFAULT_OUTPUT, options = {})`
136+
- `compound_structure_search(search_type, namespace, identifier, output = DEFAULT_OUTPUT, options = {})`
137+
138+
### Substances
139+
140+
- `get_substance_by_sid(sid, operation, output = DEFAULT_OUTPUT, options = {})`
141+
142+
### Assays
143+
144+
- `get_assay_by_aid(aid, operation, output = DEFAULT_OUTPUT, options = {})`
145+
- `get_assay_doseresponse(aid, output = DEFAULT_OUTPUT, options = {})`
146+
- `get_assay_targets(aid, target_type, output = DEFAULT_OUTPUT, options = {})`
147+
148+
### Genes
149+
150+
- `get_gene_summary_by_geneid(geneid, output = DEFAULT_OUTPUT, options = {})`
151+
- `get_gene_summary_by_synonym(synonym, output = DEFAULT_OUTPUT, options = {})`
152+
153+
### Proteins
154+
155+
- `get_protein_summary_by_synonym(synonym, output = DEFAULT_OUTPUT, options = {})`
156+
157+
### Taxonomy
158+
159+
- `get_taxonomy_summary_by_taxid(taxid, output = DEFAULT_OUTPUT, options = {})`
160+
161+
### Pathways
162+
163+
- `get_pathway_summary_by_pwacc(pwacc, output = DEFAULT_OUTPUT, options = {})`
164+
165+
### Classification
166+
167+
- `get_classification_nodes(hnid, idtype, output = DEFAULT_OUTPUT, list_return, options = {})`
168+
169+
### Lists and Pagination
170+
171+
- `get_compounds_by_listkey(listkey, output = DEFAULT_OUTPUT, options = {})`
172+
173+
## Error Handling
174+
175+
The library raises a `PubChemAPI::APIError` exception for API errors:
176+
177+
```ruby
178+
begin
179+
# API call
180+
rescue PubChemAPI::APIError => e
181+
puts "API Error (#{e.code}): #{e.message}"
182+
end
183+
```
184+
185+
The `APIError` includes:
186+
187+
- `e.code`: HTTP status code
188+
- `e.message`: Error message from the API
189+
190+
191+
## License
192+
193+
This project is licensed under the [MIT License](LICENSE).
194+
195+
---
196+
197+
*Disclaimer: This library is not affiliated with or endorsed by PubChem. Use responsibly.*

0 commit comments

Comments
 (0)