Help for package namedropR

Type:

Package

Title:

Create Visual Citations for Presentations and Posters

Version:

2.4.1

Description:

Provides 'visual citations' containing the metadata of a scientific paper and a 'QR' code. A 'visual citation' is a banner containing title, authors, journal and year of a publication. This package can create such banners based on 'BibTeX' and 'BibLaTeX' references or call the reference metadata from 'Crossref'-API. The banners include a QR code pointing to the 'DOI'. The resulting HTML object or PNG image can be included in a presentation to point the audience to good resources for further reading. Styling is possible via predefined designs or via custom 'CSS'. This package is not intended as replacement for proper reference manager packages, but a tool to enrich scientific presentation slides and conference posters.

License:

MIT + file LICENSE

URL:

https://github.com/nucleic-acid/namedropR

BugReports:

https://github.com/nucleic-acid/namedropR/issues

Imports:

bib2df, dplyr, htmltools, lubridate, qrcode (≥ 0.1.4), R.utils, readr, stringr, webshot

Suggests:

knitr, rcrossref, rmarkdown, testthat (≥ 3.0.0), withr

VignetteBuilder:

knitr

Config/testthat/edition:

Encoding:

UTF-8

RoxygenNote:

7.2.1

NeedsCompilation:

Packaged:

2022-08-28 10:35:27 UTC; christian

Author:

Christian A. Gebhard

[aut, cre], Lukas Wallrich

[ctb], Matthew T. Warkentin

[ctb]

Maintainer:

Christian A. Gebhard <christian.gebhard@posteo.de>

Repository:

CRAN

Date/Publication:

2022-08-28 10:50:02 UTC

namedropR: Create Visual Citations for Presentations and Posters

Description

Author(s)

Maintainer: Christian A. Gebhard christian.gebhard@posteo.de (ORCID)

Other contributors:

Lukas Wallrich l.wallrich@bbk.ac.uk (ORCID) [contributor]
Matthew T. Warkentin warkentin@lunenfeld.ca (ORCID) [contributor]

drop_html

Description

Accepts bibliographic information and returns a htmltools tagList for printing/display.

Usage

drop_html(
  work_item,
  include_qr,
  qr_size = 250,
  qr_color = "#000000",
  qr_hyperlink = FALSE,
  vc_width = 600,
  output_dir,
  style,
  use_xaringan = FALSE,
  style_args = list()
)

Arguments

work_item

A data.frame or tibble with nrow(work_item) == 1 containing the data for one reference to create the visual citation.

include_qr

Character string specifying the way the QR code should be included or if no QR code should be included. 'embed' results in a stand alone <img> tag within the HTML object, other options are ignored for the time being. 'link' (default) creates a PNG of the QR code and stores it in a subfolder of the HTML file's location. The HTML <img> tag links to this file then. 'link_svg' creates a SVG of the QR code and stores it in a subfolder of the HTML file's location. The HTML <img> tag links to this file then. 'none' creates no QR code.

qr_size

Specifies the height/width of the rendered QR code in px. Default: 250px, minimum: 150px. Ignored for SVG output.

qr_color

Specifies the foreground color of the QR code as hex-string, e.g. "#00FF00".

qr_hyperlink

Logical. Should the QR code be a hyperlink?

vc_width

Specifies the width of the text part of the visual citation in px. This can be adjusted to accommodate e.g. untypically long or short titles. Default: 600px

output_dir

A string specifying the relative path, where the rendered output files should be stored.

style

A string specifying the desired style for the visual citation. Possible values are: "modern", "classic", "clean", "none". If "none" is given, the returned html can use a custom css file provided by the user. This custom CSS file must specify styles for <div> classes "top-row", "title-row" and "author-row".

use_xaringan

Boolean to specify if an HTML output is intended to be included in an HTML presentation (like e.g. xaringan) or not. When including the visual citation via htmltools::includeHTML(), the QR code needs to be in a subfolder relative to the rendered presentation, not relative to the visual citation.

style_args

Custom style arguments can be passed by drop_name for individual styles. These are passed on to get_css_styles(). Style arguments are combinations of 'author_', 'title_', 'journal_' with either one of: 'font', 'size', 'weight' and 'color'. E.g. 'author_weight = "bold"'.

Value

A htmltools taglist containing the visual citation as HTML representation including style.

drop_name

Description

Extracts metadata from a .bib file and exports the visual citation in the specified format.

Usage

drop_name(
  bib,
  cite_key,
  output_dir = "visual_citations",
  export_as = "html",
  max_authors = 3,
  include_qr = "link",
  qr_size = 250,
  qr_color = "#000000",
  qr_hyperlink = FALSE,
  vc_width = 600,
  style = "modern",
  path_absolute = FALSE,
  use_xaringan = FALSE,
  clean_strings = TRUE,
  ...
)

Arguments

bib

Accepts one of the following: 1) A data.frame or tibble containing the columns YEAR, JOURNAL, AUTHOR, TITLE, BIBTEXKEY (all mandatory) and DOI, URL (optional). 2) A file path to a bibliography file in BibTeX/BibLaTeX format (usually *.bib file).

cite_key

If given, either a character string or a vector of strings are accepted. Specifies the reference items within the bibliography for which visual citations should be created. If no key is specified, a visual citation is created for ALL reference items within the bibliography. In other words, either one, many or no BibTeX citation keys can be specified.

output_dir

A string specifying the relative path, where the rendered output files should be stored.

export_as

A string specifying the desired output format. For now supports PNG and HTML. Use "html" to include the 'bare' taglist (recommended for inclusion in Rmarkdown documents) or "html_full" to write a standalone .html file including <head> etc. The PNG is a screenshot of the rendered HTML via the 'webshot' package. The filename represents this two step approach on purpose. For webshot you need to install phantomJS once (see 'webshot' documentation).

max_authors

Integer number of maximum authors to print. If the number of authors exceeds this, the list is cropped accordingly.

include_qr

qr_size

Specifies the height/width of the rendered QR code in px. Default: 250px, minimum: 150px. Ignored for SVG output.

qr_color

Specifies the foreground color of the QR code as hex-string, e.g. "#00FF00"; default is black: "#000000".

qr_hyperlink

Logical. Should the QR code be a hyperlink?

vc_width

Specifies the width of the text part of the visual citation in px. This can be adjusted to accommodate e.g. untypically long or short titles. Default: 600px

style

A string specifying the desired style for the visual citation. Possible values are: "modern", "classic", "clean", "fancy", "newspaper", "compact" and "none". If "compact" is given, the rendered VC contains only the last name of the first author and the publication year, next to the QR code. If "none" is given, the returned html can use a custom css file provided by the user. This custom CSS file must specify styles for <div> classes "top-row", "title-row" and "author-row". (see vignette)

path_absolute

Boolean to specify, whether the returned output path is a relative path or an absolute path.

use_xaringan

clean_strings

Removes curly braces from titles and journal names, as they are often present in BibTeX strings, but not needed for the rendering. TRUE by default, but can be set to FALSE, if the are needed.

...

Allows for custom style arguments to override predefined styles. Supported are: author_size, author_font, author_weight, author_color, title_size, title_font, title_weight, title_color, journal_size, journal_font, journal_weight, journal_color. Fonts need to be installed on the system.

Value

A character string with the file path to the created visual citation in the specified output format.

Examples


# create sample data
## Not run: 
bib_tbl <- dplyr::tribble(
  ~TITLE, ~AUTHOR, ~JOURNAL, ~BIBTEXKEY, ~YEAR,
  "Some title", c("Alice", "Bob", "Charlie"),
  "Journal of Unnecessary R Packages",
  "Alice2022", "2022"
)

# create visual citation
drop_name(
  bib = bib_tbl,
  cite_key = "Alice2022",
  export_as = "png",
  max_authors = 2,
  style = "clean",
  output_dir = "visual_citations",
  author_color = "#FF0000",
  author_weight = "normal",
  author_size = "12pt",
  author_font = "Roboto",
  title_color = "#00FF00",
  title_weight = "bold",
  title_size = "2.5rem",
  title_font = "Playfair Display",
  journal_color = "#0000FF",
  journal_weight = "bold",
  journal_size = "8pt",
  journal_font = "Fira Sans",
  qr_size = 150,
  qr_color = "#AAAAAA"
)

## End(Not run)

Create visual citation from Crossref data

Description

Takes one or several dois and extracts information from Crossref, then processes them into visual citations with drop_name. Requires rcrossref > v1.1, see README for further details.

Usage

drop_name_crossref(dois, ...)

Arguments

dois

One or several dois to create visual citations for. If they are named, these names are used as filenames; otherwise they are generated based on authors and years.

...

Arguments passed on to drop_name

export_as: A string specifying the desired output format. For now supports PNG and HTML. Use "html" to include the 'bare' taglist (recommended for inclusion in Rmarkdown documents) or "html_full" to write a standalone .html file including <head> etc. The PNG is a screenshot of the rendered HTML via the 'webshot' package. The filename represents this two step approach on purpose. For webshot you need to install phantomJS once (see 'webshot' documentation).
output_dir: A string specifying the relative path, where the rendered output files should be stored.
max_authors: Integer number of maximum authors to print. If the number of authors exceeds this, the list is cropped accordingly.
include_qr: Character string specifying the way the QR code should be included or if no QR code should be included. 'embed' results in a stand alone <img> tag within the HTML object, other options are ignored for the time being. 'link' (default) creates a PNG of the QR code and stores it in a subfolder of the HTML file's location. The HTML <img> tag links to this file then. 'link_svg' creates a SVG of the QR code and stores it in a subfolder of the HTML file's location. The HTML <img> tag links to this file then. 'none' creates no QR code.
style: A string specifying the desired style for the visual citation. Possible values are: "modern", "classic", "clean", "fancy", "newspaper", "compact" and "none". If "compact" is given, the rendered VC contains only the last name of the first author and the publication year, next to the QR code. If "none" is given, the returned html can use a custom css file provided by the user. This custom CSS file must specify styles for <div> classes "top-row", "title-row" and "author-row". (see vignette)
path_absolute: Boolean to specify, whether the returned output path is a relative path or an absolute path.
use_xaringan: Boolean to specify if an HTML output is intended to be included in an HTML presentation (like e.g. xaringan) or not. When including the visual citation via htmltools::includeHTML(), the QR code needs to be in a subfolder relative to the rendered presentation, not relative to the visual citation.
clean_strings: Removes curly braces from titles and journal names, as they are often present in BibTeX strings, but not needed for the rendering. TRUE by default, but can be set to FALSE, if the are needed.
qr_size: Specifies the height/width of the rendered QR code in px. Default: 250px, minimum: 150px. Ignored for SVG output.
qr_color: Specifies the foreground color of the QR code as hex-string, e.g. "#00FF00"; default is black: "#000000".
qr_hyperlink: Logical. Should the QR code be a hyperlink?
vc_width: Specifies the width of the text part of the visual citation in px. This can be adjusted to accommodate e.g. untypically long or short titles. Default: 600px

Value

A character string with the file path to the created visual citation in the specified output format.

Examples

## Not run: 
drop_name_crossref(c(cite1 = "10.1126/science.169.3946.635", cite2 = "10.1111/joms.12670"))

## End(Not run)

generate_qr

Description

Generates a QR code from a supplied string and return as a plot object. This is a wrapper function around qrcode::qr_code().

Usage

generate_qr(url)

Arguments

url

A string to encode as QR code.

Value

The encoded QR code as matrix.

get_css_style

Description

Provides inline CSS code for three distinct visual citation styles. If "none" is given, the returned styles are empty strings.

Usage

get_css_styles(style, custom_style = list())

Arguments

style

custom_style

Style arguments passed by drop_html(). Can be specified in function call of drop_name().

Value

A list of inline css styles for each element of the visual citation: top row, title row and author row.

manage_authors

Description

Returns a cleaned and cropped string of authors for the visual citation.

Usage

manage_authors(authors, max_authors, style = "any")

Arguments

authors

Can be a single string or a list of authors.

max_authors

Maximum number of authors to be returned from the list.

style

Takes the user specified style. Only relevant for "compact" mode. Ignored otherwise.

Value

A single string with the desired maximum number of authors.

write_vc

Description

Takes the data from drop_name and writes the actual outputs to the output directory.

Usage

write_vc(work_item, path_absolute, output_dir, export_as)

Arguments

work_item

A data.frame or tibble with a single row, passed by drop_name()

path_absolute

A logical parameter specifying, whether eventually a relative or absolute path should be returned.

output_dir

A relative path (in regard to the working directory) where the visual citations should be 'dropped'. (type: character)

export_as

Defines the file format of the returned visual citation (see drop_name() for more).

Value

The path to the written file as character.

Examples

## Not run: 
# not intended for direct call. Please refer to the documentation
# of drop_name() for further assistance.

## End(Not run)

namedropR: Create Visual Citations for Presentations and Posters

Description

Author(s)

See Also

drop_html

Description

Usage

Arguments

Value

drop_name

Description

Usage

Arguments

Value

Examples

Create visual citation from Crossref data

Description

Usage

Arguments

Value

Examples

generate_qr

Description

Usage

Arguments

Value

get_css_style

Description

Usage

Arguments

Value

manage_authors

Description

Usage

Arguments

Value

write_vc

Description

Usage

Arguments

Value

Examples