In jotsetung/atc: Data package providing ATC codes

Introduction

This package provides the Anatomical Therapeutical Chemical (ATC) Classification data and functions that facilitate working with these. The ATC data is defined by the WHO Collaborating Centre (WHOCC) for Drug Statistics Methodology (Oslo, Norway), which holds also the copyright for the data and dos not allow distribution for commercial purposes.

This packages provides two ATC databases, bound to the variables atc and atc_wido. The AtcDb object bound to the atc variable access a database containing the official ATC data from the WHOCC web page. The AtcDb object bound to atc_wido provides access to a database that was compiled manually from data files from the Wissenschaftliches Institut der AOK (http://www.wido.de), and from the online resources http://atccodes.com and Wikipedia. The two databases might differ partially in their content (e.g. the atc_wido contains also homeopathic compounds).

The ATC Classification system is used for the classification of active ingredients of drugs according to the organ or system on which they act and their therapeutic, pharmacological and chemical properties. In this system, drugs are classified into groups at 5 different levels:

First level: indicates the anatomical main group and consists of one letter.
Second level: indicates the therapeutic main group and consists of two digits.
Third level: indicates the therapeutic/pharmacological subgroup and consists of one letter.
Fourth level: indicates the chemical/therapeutic/pharmacological subgroup and consists of one letter.
Fifth level: indicates the chemical substance and consists of two digits. For the 5th level entries also defined daily dosages (ddd) may be provided.

Note that national versions of the ATC classification exist with eventual additional codes and ddds.

Basic usage

The data structure of the database is very simple, and it is thus straight forward to retrieve data from it.

The columns (or listColumns) or the listTables methods can be used to get some information of the available values (see Database layout section below for a more detailed description of the individual columns).

library(atc)

## First of all print some basic information
atc

## What tables are available?
listTables(atc)

## All available columns.
listColumns(atc)

The keys method can be used to retrieve the ATC codes in the database, with the additional argument level we can restrict to ATC codes from a certain level or levels.

## All ATC codes
head(keys(atc))

## Only ATC codes from level 1 and 3
head(keys(atc, level=c(1, 3)))

The atcs method can be used to extract additional information from the database.

## Get the full data
head(atcs(atc))

## To retrive the full data we could also use the as.data.frame method
head(as.data.frame(atc))

The arguments columns and filters allow to define which columns respectively entries (rows) should be retrieved from the database. The atc package supports the filtering framework of Bioconductor's AnnotationFilter package, i.e. supports filtering using a single filter object or a list thereof that can be passed to the atcs method to retrieve specific data.

The filters that are presently supported by the atc package are:

AdminrouteFilter: filter results based on the administration route (e.g. O for oral).
KeyFilter: filter results using their key values.
LevelFilter: filter results based on the ATC level.
NameFilter: filter results based on the entries' names.

In the code example below we simply query the database to get all level 1 entries from the database.

## Get all level 1 entries and restrict to some columns
atcs(atc, filter=LevelFilter(1), columns=c("key", "name", "level"))

In the example below we combine filters to retrieve all orally taken glucocorticoids.

## Use a KeyFilter to search for all entries that start with H02AB
## and combine that with administration route being 'O'
atcs(atc, filter=list(KeyFilter("H02AB", condition = "startsWith"),
              AdminrouteFilter("O")))

Extract ATC codes from the official WHOCC web page

The official WHOCC web page provides a simple search functionality to retrieve data for a user specified ATC code. The crunchWHOCC function we use below recursively retrieves ATC data from this web page starting from either a user-specified ATC code, or if not provided, for all level 1 codes and above.

## Retrieve all data from the WHOCC web page.
whoccAtc <- crunchWHOCC()

The function returns 3 data.frames that can be used to build a RSQLite database such as provided by the atc package.

library(RSQLite)

## Connect to the database.
con <- dbConnect(dbDriver("SQLite"), dbname="atc.sqlite")
## Store the 3 tables.
dbWriteTable(con, name="atc", whoccAtc$atc, row.names=FALSE)
dbWriteTable(con, name="ddd", whoccAtc$ddd, row.names=FALSE)
dbWriteTable(con, name="metadata", whoccAtc$metadata, row.names=FALSE)

## Create indices for faster access.
dbExecute(con, "create index key_idx on atc (key);")
dbExecute(con, "create index level_idx on atc (level);")
dbExecute(con, "create index ddd_key_idx on ddd (key);")
dbDisconnect(con)

A AtcDb object can then be created using.

atcDb <- AtcDb("atc.sqlite")
atcDb

Database layout

The database consists of 3 tables, atc, ddd and metadata. The columns for the individual tables are listed below.

atc: the main table providing the mapping between the ATC codes (also called keys) and their names.
- key: column containing the ATC codes. The KeyFilter can be used to filter on this column.
- name: column with the name associated with the key. The NameFilter can be used to filter on this column.
- level: the level of the ATC code (from 1 to 5). The LevelFilter can be used to filter on this column.
ddd: the table providing the defined daily dosage (ddd) for the ATC entries of level 5. Thus, this table contains only values for codes of level 5, but not for all of them. Note also, that this table can contain multiple dosages for the same ATC code.
- key: the ATC code.
- ddd: the defined daily dose.
- unit: the unit of the dose.
- administration_route: the route of administration of the drug. The AdminrouteFilter can be used to filter on this column.
- note: optional additional information.
metadata: table providing additional information (creation time, source etc). Values are stored as key-value pairs.
- name: the name of the key.
- value: its value.