library(namedropR)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.
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.
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).1
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)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"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"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.
There are two sizes of VCs: the regular-size and a compact size.
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
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
)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"
)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.
output_dir specifies the output path (relative to the
working directory)max_authors specifies how many authors should be
printedinclude_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 codeIn version v1.x you could pass BibEntry
objects (e.g. as generated by the great {RefManageR}
package) to the drop_name() function. This option was
removed in v2.0 to remove the dependency on the {bibtex}
package.)↩︎