Keeping up with new nucleosome structures

In this post, I will show how I made the bar graph in Box 3 of the review I co-authored recently (Zhou et al, 2019). This involves collecting metadata from the PDB, which I explained in the first post in this series. Having an automated way to regenerate this graph was invaluable during the writing of this review, because new nucleosome structures were published at a very rapid rate over the last few months.

Required packages

We will need the following packages:

library(magrittr)
library(here)
library(purrr)
library(forcats)
library(jsonlite)
library(readr)
library(tibble)
library(dplyr)
library(ggplot2)
library(plotly)

Getting and cleaning data

This bar graph will present the number of PDB entries containing a nucleosome by year of publication since 1997. We need to request a dataset containing all released structures (status:REL) with the word “nucleosome” in their title, and with the following columns (corresponding PDBe API fields):

  • database accession code (pdb_id),
  • publication year (citation_year),
  • structure title (title),
  • experimental method (experimental_method).

We need to take into account the fact that older entries in the PDB have their titles in all capitals, while newer entries have normal case titles. The PDBe API search is case sensitive, and I haven’t found how to make it case-insensitive (or even whether it is possible at all), so we will need two queries.

This translates as follows:

# We need two queries: one for uppercase titles, the other for lowercase ones
pdb_queries <- c(
    uppercase = 'https://www.ebi.ac.uk/pdbe/search/pdb/select?q=title:*UCLEOSOM*%20AND%20status:REL&fl=pdb_id,citation_year,title,experimental_method&rows=1000000&wt=json',
    lowercase = 'https://www.ebi.ac.uk/pdbe/search/pdb/select?q=title:*ucleosom*%20AND%20status:REL&fl=pdb_id,citation_year,title,experimental_method&rows=1000000&wt=json'
)

Some PDB entries have the word “nucleosome” in their title, but do not actually contain a nucleosome. This is the case for structures of Nap1 (nucleosome assembly protein 1), for instance. I could not find a more accurate way than combing through the dataset one entry at a time and building a list of such irrelevant entries to filter them out.

# The following PDB entries do not contain a nucleosome
non_nucleosome_structures <- c(
    "1hst",
    "2z2r",
    "5x7v",
    "3uv2",
    "3fs3",
    "1wg3",
    "1nw3",
    "5ikf",
    "3gyw",
    "3gyv",
    "1ofc",
    "2ayu",
    "2iw5",
    "3hfd"
)

We can then retrieve and clean up the dataset as follows. Having to perform two case-sensitive queries complicates the procedure a little bit; the key parts are to keep only one occurrence of each PDB accession code (remember that a query will return all molecules that match, and that a structure often contains several molecules, as explained in the first post in this series) and to filter out the above list of PDB entries that don’t contain a nucleosome.

nucleosome_structures_dataset <- here("static", "datasets", "nucleosome-structures.csv")

dig_up_data <- . %>%
    .$response %>%
    .$docs %>%
    as_tibble()

if (!file.exists(nucleosome_structures_dataset)) {
    pdb_data <- pdb_queries %>%
        map(fromJSON) %>%
        map(dig_up_data) %>% 
        bind_rows() %>%
        distinct(pdb_id, .keep_all = TRUE) %>% 
        filter(!(pdb_id %in% non_nucleosome_structures)) %>%
        mutate(experimental_method = as.character(experimental_method))
    write_csv(pdb_data, path = nucleosome_structures_dataset)
} else {
    pdb_data <- read_csv(nucleosome_structures_dataset)
}

pdb_data %<>%
    mutate(experimental_method = as_factor(experimental_method),
           citation_year       = as.integer(citation_year))

pdb_data
## # A tibble: 194 x 4
##    citation_year experimental_meth… pdb_id title                           
##            <int> <fct>              <chr>  <chr>                           
##  1          2003 X-ray diffraction  1m18   LIGAND BINDING ALTERS THE STRUC…
##  2          2001 X-ray diffraction  1id3   CRYSTAL STRUCTURE OF THE YEAST …
##  3          1997 X-ray diffraction  1aoi   COMPLEX BETWEEN NUCLEOSOME CORE…
##  4          2003 X-ray diffraction  1m1a   LIGAND BINDING ALTERS THE STRUC…
##  5          2000 X-ray diffraction  1eqz   X-RAY STRUCTURE OF THE NUCLEOSO…
##  6          2000 X-ray diffraction  1f66   2.6 A CRYSTAL STRUCTURE OF A NU…
##  7          2013 X-ray diffraction  4x23   CRYSTAL STRUCTURE OF CENP-C IN …
##  8          2003 X-ray diffraction  1m19   LIGAND BINDING ALTERS THE STRUC…
##  9          2010 X-ray diffraction  3lja   Using Soft X-Rays for a Detaile…
## 10          2018 Electron Microsco… 6a5r   RNA polymerase II elongation co…
## # … with 184 more rows

Here is the resulting dataset for download.

Making a bar graph

From this table, we can now easily construct a bar graph. This is the same graph I made for the review article, except this one is also interactive (you can zoom in and out, and hovering over the bars will indicate the years and counts).

figure <- ggplot(data = pdb_data) +
    geom_bar(mapping = aes(x = citation_year, fill = experimental_method)) +
    guides(fill = guide_legend(title = "Experimental method")) +
    ggtitle("Nucleosome structures") +
    xlab("Publication year") +
    ylab("Number of PDB entries") +
    theme_bw()
ggplotly(figure)

Going further

To generate this graph, only the following fields are absolutely necessary:

  • database accession code (pdb_id),
  • publication year (citation_year),
  • experimental method (experimental_method).

I also included the title field in this post to show in the table, but it was not required to build the graph. Now, when writing the review, I also downloaded two additional fields:

  • resolution (resolution),
  • article DOI (citation_doi).

Knowing the resolution was somewhat useful, because we tended to focus on high-resolution structures in the review. Being able to get each entry’s DOI was very helpful to easily access the corresponding article. The citation_doi field only contains a DOI, not a full URL, but with stringr::str_c it’s very easy to prepend all DOIs with https://doi.org/ or the URL of your favorite DOI resolver. Then, by saving the table as an Excel spreadsheet with readr::write_excel_csv (and converting to XLSX with Excel), the DOI links can be made clickable.

Replicate this post

You can replicate this post by running the Rmd source with RStudio and R. The easiest way to replicate this post is to clone the entire git repository.

sessioninfo::session_info()
## ─ Session info ──────────────────────────────────────────────────────────
##  setting  value                       
##  version  R version 3.5.2 (2018-12-20)
##  os       macOS Mojave 10.14.3        
##  system   x86_64, darwin15.6.0        
##  ui       X11                         
##  language (EN)                        
##  collate  en_US.UTF-8                 
##  ctype    en_US.UTF-8                 
##  tz       America/Denver              
##  date     2019-02-28                  
## 
## ─ Packages ──────────────────────────────────────────────────────────────
##  package     * version date       lib source        
##  assertthat    0.2.0   2017-04-11 [1] CRAN (R 3.5.0)
##  backports     1.1.3   2018-12-14 [1] CRAN (R 3.5.0)
##  blogdown    * 0.10    2019-01-09 [1] CRAN (R 3.5.2)
##  bookdown      0.9     2018-12-21 [1] CRAN (R 3.5.0)
##  cli           1.0.1   2018-09-25 [1] CRAN (R 3.5.0)
##  codetools     0.2-16  2018-12-24 [2] CRAN (R 3.5.2)
##  colorspace    1.4-0   2019-01-13 [1] CRAN (R 3.5.2)
##  crayon        1.3.4   2017-09-16 [1] CRAN (R 3.5.0)
##  crosstalk     1.0.0   2016-12-21 [1] CRAN (R 3.5.0)
##  data.table    1.12.0  2019-01-13 [1] CRAN (R 3.5.2)
##  digest        0.6.18  2018-10-10 [1] CRAN (R 3.5.0)
##  dplyr       * 0.8.0.1 2019-02-15 [1] CRAN (R 3.5.2)
##  ellipsis      0.1.0   2019-02-19 [1] CRAN (R 3.5.2)
##  evaluate      0.13    2019-02-12 [1] CRAN (R 3.5.2)
##  fansi         0.4.0   2018-10-05 [1] CRAN (R 3.5.0)
##  forcats     * 0.4.0   2019-02-17 [1] CRAN (R 3.5.2)
##  ggplot2     * 3.1.0   2018-10-25 [1] CRAN (R 3.5.0)
##  glue          1.3.0   2018-07-17 [1] CRAN (R 3.5.0)
##  gtable        0.2.0   2016-02-26 [1] CRAN (R 3.5.0)
##  here        * 0.1     2017-05-28 [1] CRAN (R 3.5.0)
##  hms           0.4.2   2018-03-10 [1] CRAN (R 3.5.0)
##  htmltools     0.3.6   2017-04-28 [1] CRAN (R 3.5.0)
##  htmlwidgets   1.3     2018-09-30 [1] CRAN (R 3.5.0)
##  httpuv        1.4.5.1 2018-12-18 [1] CRAN (R 3.5.0)
##  httr          1.4.0   2018-12-11 [1] CRAN (R 3.5.0)
##  jsonlite    * 1.6     2018-12-07 [1] CRAN (R 3.5.0)
##  knitr         1.21    2018-12-10 [1] CRAN (R 3.5.2)
##  labeling      0.3     2014-08-23 [1] CRAN (R 3.5.0)
##  later         0.8.0   2019-02-11 [1] CRAN (R 3.5.2)
##  lazyeval      0.2.1   2017-10-29 [1] CRAN (R 3.5.0)
##  magrittr    * 1.5     2014-11-22 [1] CRAN (R 3.5.0)
##  mime          0.6     2018-10-05 [1] CRAN (R 3.5.0)
##  munsell       0.5.0   2018-06-12 [1] CRAN (R 3.5.0)
##  pillar        1.3.1   2018-12-15 [1] CRAN (R 3.5.0)
##  pkgconfig     2.0.2   2018-08-16 [1] CRAN (R 3.5.0)
##  plotly      * 4.8.0   2018-07-20 [1] CRAN (R 3.5.2)
##  plyr          1.8.4   2016-06-08 [1] CRAN (R 3.5.0)
##  promises      1.0.1   2018-04-13 [1] CRAN (R 3.5.0)
##  purrr       * 0.3.0   2019-01-27 [1] CRAN (R 3.5.2)
##  R6            2.4.0   2019-02-14 [1] CRAN (R 3.5.2)
##  Rcpp          1.0.0   2018-11-07 [1] CRAN (R 3.5.0)
##  readr       * 1.3.1   2018-12-21 [1] CRAN (R 3.5.0)
##  rlang         0.3.1   2019-01-08 [1] CRAN (R 3.5.2)
##  rmarkdown     1.11    2018-12-08 [1] CRAN (R 3.5.0)
##  rprojroot     1.3-2   2018-01-03 [1] CRAN (R 3.5.0)
##  scales        1.0.0   2018-08-09 [1] CRAN (R 3.5.0)
##  sessioninfo   1.1.1   2018-11-05 [1] CRAN (R 3.5.0)
##  shiny         1.2.0   2018-11-02 [1] CRAN (R 3.5.0)
##  stringi       1.3.1   2019-02-13 [1] CRAN (R 3.5.2)
##  stringr       1.4.0   2019-02-10 [1] CRAN (R 3.5.2)
##  tibble      * 2.0.1   2019-01-12 [1] CRAN (R 3.5.2)
##  tidyr         0.8.2   2018-10-28 [1] CRAN (R 3.5.0)
##  tidyselect    0.2.5   2018-10-11 [1] CRAN (R 3.5.0)
##  utf8          1.1.4   2018-05-24 [1] CRAN (R 3.5.0)
##  viridisLite   0.3.0   2018-02-01 [1] CRAN (R 3.5.0)
##  withr         2.1.2   2018-03-15 [1] CRAN (R 3.5.0)
##  xfun          0.5     2019-02-20 [1] CRAN (R 3.5.2)
##  xtable        1.8-3   2018-08-29 [1] CRAN (R 3.5.0)
##  yaml          2.2.0   2018-07-25 [1] CRAN (R 3.5.0)
## 
## [1] /Users/guillaume/Library/R/3.5/library
## [2] /Library/Frameworks/R.framework/Versions/3.5/Resources/library

References

Zhou K, Gaullier G & Luger K (2019) Nucleosome structure and dynamics are coming of age. Nature Structural & Molecular Biology 26: 3–13 https://doi.org/10.1038/s41594-018-0166-x