CTG
CTG
is a Ruby client library for interacting with the ClinicalTrials.gov API. It allows you to fetch and query clinical study data, including study metadata, search areas, study sizes, field values, and more. The library supports both JSON and CSV response formats, with built-in support for pagination and advanced querying.
Installation
Add this line to your application's Gemfile:
gem 'ctg'
And then execute:
bundle install
Or install it yourself as:
gem install ctg
Usage
Initializing the Client
To start using the CTG
, first create a new client instance:
require 'ctg'
client = CTG.new
Fetching Studies
You can fetch studies using the studies
method. This will return a CTG::Response
object that you can query.
response = client.studies('query.term' => 'cancer')
studies = response.query('studies')
puts studies
Fetching a Single Study by NCT Number
You can fetch a single study by its NCT number:
response = client.number('NCT04050163')
study = response.query('nctId')
puts study
Fetching Study Metadata
To fetch metadata information about study fields:
response = client.metadata
metadata = response.data
puts metadata
Handling Pagination
If your query returns multiple pages of results, you can fetch the next page using the next_page
method:
response = client.studies('query.term' => 'cancer', 'pageSize' => 5)
puts response.query('studies')
next_page_response = response.next_page
puts next_page_response.query('studies') if next_page_response
Querying the Response
You can query JSON responses using keys or XPath expressions:
response = client.number('NCT04050163')
nct_id = response.query('nctId')
puts nct_id
For CSV responses, query by column name:
response = client.number('NCT04050163', format: 'csv')
nct_ids = response.query('NCT Number')
puts nct_ids
Finding a Specific Key in JSON Data
You can find the first occurrence of a specific key within the JSON data using the find
method:
response = client.number('NCT04050163')
nct_id = response.find('nctId')
puts nct_id
CTG::Query Object
The CTG::Query
class is designed to help you build complex queries for searching clinical studies on ClinicalTrials.gov. It provides a convenient way to add different query parameters and filters, allowing for advanced search capabilities.
Creating a Query
To start building a query, you first need to create an instance of the CTG::Query
class:
query = CTG::Query.new
Adding Query Parameters
The CTG::Query
object allows you to add various search parameters using method chaining. Below are the available methods:
condition(condition)
Adds a condition or disease to the query.
- Parameter:
condition
(String) - The condition or disease to search for. - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.condition('diabetes')
term(term)
Adds additional search terms to the query.
- Parameter:
term
(String) - Additional search terms. - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.term('lung cancer')
location(location)
Adds a location filter to the query.
- Parameter:
location
(String) - The location term to filter results by. - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.location('New York')
title(title)
Adds a title or acronym to the query.
- Parameter:
title
(String) - The title or acronym to search for. - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.title('COVID-19 Vaccine')
intervention(intervention)
Adds an intervention or treatment to the query.
- Parameter:
intervention
(String) - The intervention or treatment to search for. - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.intervention('remdesivir')
outcome(outcome)
Adds an outcome measure to the query.
- Parameter:
outcome
(String) - The outcome measure to search for. - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.outcome('survival rate')
collaborator(collaborator)
Adds a sponsor or collaborator to the query.
- Parameter:
collaborator
(String) - The sponsor or collaborator to search for. - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.collaborator('IQVIA')
Adds a lead sponsor to the query.
- Parameter:
sponsor
(String) - The lead sponsor to search for. - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.sponsor('National Institutes of Health')
study_id(study_id)
Adds a study ID filter to the query.
- Parameter:
study_id
(String) - The study ID or IDs to search for (comma- or space-separated). - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.study_id('NCT01234567')
status(*statuses)
Adds an overall status filter to the query.
- Parameter:
statuses
(Array) - The list of statuses to filter by (e.g., ['RECRUITING', 'COMPLETED']
). - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.status('RECRUITING', 'COMPLETED')
page_size(size)
Specifies the number of results per page.
- Parameter:
size
(Integer) - The number of results to return per page (max 1000). - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.page_size(50)
format(format)
Specifies the format of the response.
- Parameter:
format
(String) - The format of the response ('json'
or 'csv'
). - Returns: The updated
CTG::Query
object.
query = CTG::Query.new.format('json')
Retrieving Query Parameters
Once you’ve built your query, you can retrieve the complete set of query parameters as a hash:
query_params = query.params
This params
method returns a hash of all the query parameters that have been set.
Example: Building a Complex Query
Here’s an example of how you might build a more complex query using method chaining:
query = CTG::Query.new
.condition('diabetes')
.term('insulin')
.location('California')
.status('RECRUITING')
.page_size(10)
.format('json')
response = client.studies(query)
puts response.query('studies', 'protocolSection', 'outcomesModule', 'secondaryOutcomes' )
In this example, the query is set to search for recruiting studies related to diabetes and insulin in California, returning results in JSON format with a page size of 10.
Finding All Occurrences of a Key in JSON Data
If you need to find all occurrences of a specific key within the JSON data, use the find_all
method:
references = response.find_all('references')
puts references
Running Tests
To run the tests, use RSpec:
rspec
This will run all the tests located in the spec/
directory and report on their success.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/trialize/ctg.
License
This library is available as open source under the terms of the MIT License.
Copyright 2024 Leonid Stoianov. Copyright 2024 Trialize.