namedropR

library(namedropR)

Introduction

When you’re preparing a talk for a scientific conference, you might want to point the audience to good literature resources for further reading.

namedropR helps to generate what I call ‘visual citations’ (VC): a banner containing the article’s title, publication year, authors and journal name. The package can also attach a QR code for the audience to scan and thus quickly follow your reference for further reading.

The package can be used to create and include these banners “on the fly” e.g. while knitting a xaringan presentation or Rmarkdown documents in general. If you’re using other presentation software and want to include a VC in the *.pptx file, the package can save the banners as PNG so you can drag-and-drop it onto the slide easily.

Basic Usage

This package accepts bibliographic information as data.frames or tibbles and adds a QR code pointing to the ‘DOI’ included in the reference. If the ‘DOI’ is not available in the bibliography entry, but a ‘URL’ field instead, this is used. If neither is given, the QR code points to a search call at https://scholar.google.com with the available data as search terms.

Read the Bibliography file

The package allows for two input options: a data.frame/tibble containing the citation data in appropriate columns or bibliographies stored in the ‘BibTeX’/‘BibLaTeX’ format (usually *.bib).¹

You can pass the path to your *.bib file to drop_name(). The function will read the bibliography, select the needed columns and create the visual citation:

bib_path <- system.file("testdata", "sample.bib", package = "namedropR")
namedropR::drop_name(bib_path)

When repeatedly “dropping” single citations from the same bibliography, it is recommended to read the bibliography once and pass the generated data.frame to drop_name() function:

library(bib2df)
bib_path <- system.file("testdata", "sample.bib", package = "namedropR")
bib <- bib2df::bib2df(bib_path)

namedropR::drop_name(bib)

Create a VC and save to disk

The default output folder (relative to the working directory) is visual_citations/. However, you can also specify a custom output folder (see below).

The QR codes are additionally stored in the subdirectory visual_citations/qr/ and kept, in case one wants to use them separately.

By default, the function returns the relative filepath.

# create a visual citation as HTML (default, equivalent to export_as = "html")
drop_name(bib, cite_key = "Hawking1974")
#> [1] "visual_citations/Hawking1974.html"

# create a visual citation as PNG
drop_name(bib, cite_key = "Hawking1974", export_as = "png")
#> [1] "visual_citations/Hawking1974.html.png"

To save the output to a custom location there are a few options:

# using the temporary directory tempdir()
drop_name(bib,
  output_dir = tempdir(),
  export_as = "png",
  cite_key = "Hawking1974"
)

# by passing a relative path
drop_name(bib,
  output_dir = "my_custom_folder",
  export_as = "png",
  cite_key = "Hawking1974"
)

# by passing an absolute path
drop_name(bib,
  output_dir = "/home/user_name/some/project/path",
  export_as = "png",
  cite_key = "Hawking1974"
)

# (note: if passing an absolute path, the path must already exist!)

It is also possible to obtain the absolute file path as returned string, by passing path_absolute = TRUE:

drop_name(bib,
  export_as = "png",
  path_absolute = TRUE,
  cite_key = "Hawking1974"
)
#> [1] ""/home/user_name/some/project/path/Hawking1974.html.png"

Bulk-dropping

If no cite_key is specified, all bibliography entries are being dropped:

drop_name(bib)

#> No cite_key specified. Working through all possible 5 entries in the bibliography.
#> [1] "visual_citations/Eschrich1983.html"
#> [2] "visual_citations/collaboration_2019_ApJL.html"
#> [3] "visual_citations/Hawking1974.html"
#> [4] "visual_citations/Hawking1975.html"
#> [5] "visual_citations/Hawking1976.html"

To select just some of the references in a larger bibliography, you can pass a vector containing some cite_keys as well:

drop_name(bib,
  cite_key = c(
    "Hawking1974",
    "Eschrich1983",
    "collaboration_2019_ApJL"
  )
)

#> 3 cite_key(s) specified. Working through all of them.
#> [1] "visual_citations/Hawking1974.html"
#> [2] "visual_citations/Eschrich1983.html"
#> [3] "visual_citations/collaboration_2019_ApJL.html"

Including VCs in Rmarkdown

drop_name() by default returns the file path (where the VC was stored) as character string. By default this is a relative path, except the option path_absolute = TRUE is passed.

Within an Rmarkdown/HTML presentation the VC can be conveniently included like so:

# PNG
knitr::include_graphics(
  drop_name(bib,
    cite_key = "Hawking1974",
    export_as = "png",
    style = "clean"
  )
)

# HTML
htmltools::includeHTML(
  drop_name(bib,
    cite_key = "Hawking1974",
    export_as = "hmtl",
    style = "clean",
    use_xaringan = TRUE
  )
)

In both cases, the VC is crated by drop_name() and the returned file path is used by htmltools or knitr to find the VC.

For details of all options and ways to drop names, please see the detailed vignette for using namedropR in an Rmarkdown environment.

Styling

There are two sizes of VCs: the regular-size and a compact size.

Predefined Styles

There are three predefined styles for the standard size VC: ‘modern’ (default), ‘classic’ and ‘clean’. You can easily try them out by setting the style argument accordingly:

drop_name(bib,
  cite_key = "Hawking1974",
  export_as = "png",
  style = "modern"
)

drop_name(bib,
  cite_key = "Hawking1974",
  export_as = "png",
  style = "classic"
)

drop_name(bib,
  cite_key = "Hawking1974",
  export_as = "png",
  style = "clean"
)

drop_name(bib,
  cite_key = "Hawking1974",
  export_as = "png",
  style = "fancy"
)

drop_name(bib,
  cite_key = "Hawking1974",
  export_as = "png",
  style = "newspaper"
)

More styles might be added / contributed in the future. For a list of all styles, see the packages styles.csv

Changing the size of the elements

It is possible to adapt the width of the text area and the size of the QR code to one’s needs. To achieve this you simply specify the size of each in pixels:

drop_name(bib,
  cite_key = "Hawking1974",
  export_as = "png",
  style = "newspaper",
  # default size is 250, minimum is 150:
  qr_size = 150,
  # default width of the text area is 600
  vc_width = 1100
)

Compact-Size VC

The compact style is intended for less intrusive visual citations. They only contain the first author’s last name and the year next to the QR code.

To render a compact VC pass style = 'compact' to drop_name():

drop_name(bib,
  cite_key = "Hawking1974",
  export_as = "png",
  style = "compact"
)

Custom Styling via CSS

If the VC is intended to be included as HTML in a presentation, custom styling via CSS is possible by styling the respective elements.

If you are not already using a document-wide CSS style-sheet via the YAML header, you can put a CSS chunk before the first VC, where you style the following HTML classes:

<!-- Background color -->
table.visual-citation tr {
  background: #EEEEEE;
}

<!-- Journal name and Publication Year -->
table.visual-citation tr td div.top-row span {
  font-size: 16px;
  color: #00CC00;
  font-family: monospace;
}

<!-- Title of the Article -->
table.visual-citation tr td div.title-row span {
  font-size: 32px;
  color: #DD00AA;
  font-style: italic;
  font-family: serif;
}

<!-- Authors -->
table.visual-citation tr td div.author-row span {
  font-size: 20px;
  color: #0000DD;
  font-style: bold;
  font-family: monospace;
}

NOTE: Custom styling is only available for HTML output in the regular size. For PNG only the predefined styles are available. Custom PNG might be planned for future releases.

Further Options

• output_dir specifies the output path (relative to the working directory)
• max_authors specifies how many authors should be printed
• include_qr specifies the creation/implementation of the QR code
  • 'link' (default) creates a PNG and links to that in the composed HTML
  • 'link_svg' creates a SVG and links to that in the composed HTML
  • 'embed' encodes the QR code as base64 and includes it within the HTML document (use with caution, this caused severe performance issues in Rmarkdown knitting)
  • 'none' produces no QR code