Version: 0.0.10
Encoding: UTF-8
Title: Interacting with BibTeX Databases
Depends: R(≥ 4.1)
Imports: methods, rcrossref, stringr, tools, utils, yamlme
Suggests: covr, devtools, rmarkdown, testthat
LazyData: true
SystemRequirements: pandoc (>= 1.14) - http://pandoc.org
Description: Reading and writing BibTeX files using data frames in R sessions.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL: https://kamapu.github.io/biblio/
BugReports: https://github.com/kamapu/biblio/issues
RoxygenNote: 7.3.1
NeedsCompilation: no
Packaged: 2024-06-07 10:42:44 UTC; miguel
Author: Miguel Alvarez ORCID iD [aut, cre]
Maintainer: Miguel Alvarez <kamapu78@gmail.com>
Repository: CRAN
Date/Publication: 2024-06-07 11:20:07 UTC

Coerce 'lib_df' objects

Description

Coercion 'lib_df' objects.

Arguments

x

An object to be coerced.

Examples

## Read installed library
Refs <- read_bib(x = file.path(path.package("biblio"),
        "LuebertPliscoff.bib"))

# Convert lib_df to data frame
as(Refs[1:5, ], "data.frame")

# Convert lib_df to bibentry
as(Refs[1:5, ], "bibentry")

Convert lib_df to bibentry

Description

Conversion method for lib_df objects into bibentry.

Usage

bib2bibentry(x, ...)

## S3 method for class 'lib_df'
bib2bibentry(x, ...)

Arguments

x

A lib_df object to be converted.

...

Further arguments passed among methods (not yet in use).

Value

An bibentry object.

Examples

## Read installed electronic library
Bib <- read_bib(x = file.path(path.package("biblio"),
        "LuebertPliscoff.bib"))

## Convert the first five entries
bib2bibentry(Bib[1:5, ])

Compared libraries

Description

An S3 class for compared data frames. A list containing added, deleted entries on the regarding a key column and cells that are modified.

Compare data frames and libraries

Description

Report on differences between two versions of the same data frame or electronic library. When used for data frames, you need to indicate the variable containing IDs for each entry, while applied to lib_df objects, the variable 'bibtexkey' will be considered as ID per default.

The output printed in the console will advice about added and deleted entries in 'y' as well as any change in the entries common to both versions.

Usage

compare_df(x, y, key, ...)

## S4 method for signature 'data.frame,data.frame,character'
compare_df(x, y, key, ...)

## S4 method for signature 'lib_df,lib_df,missing'
compare_df(x, y, key, ...)

Arguments

x

The (old) reference data frame.

y

The updated (new) data frame.

key

A character value with the name of the variable used as primary key in the tables.

...

Further arguments passed among methods.

Value

A S3 object of class comp_df, which can be printed in the console by print().

See Also

update(), lib_df, comp_df

Examples

# Partially matching libraries
Refs1 <- synopsis[1:10, ]
Refs2 <- synopsis[6:15, ]

# some modification in second library
Refs2[3, "title"] <- "New Title"

# compare libraries
compare_df(Refs1, Refs2)

Detect bibtexkeys used in an r-markdown document

Description

This function screens a character vector (usually an imported r-markdown document) for the use of citations by bibtexkeys (⁠@bibtexkey⁠), retrieving the detected key with its occurrence in the vector, assuming each element as a line of the original document.

This function is based on bbt_detect_citations() from the package rbbt.

Usage

detect_keys(x, ...)

## S3 method for class 'character'
detect_keys(x, ...)

## S3 method for class 'rmd_doc'
detect_keys(x, ...)

Arguments

x

A character vector, a file imported by readLines() or an object imported by read_rmd(). If the character vector is the name of a Rmd or a Quarto document, readLines() will be internally called to read it.

...

Further arguments passed among methods. In character-method they are passed to readLines().

Value

A data frame with two columns, bibtexkey for the found keys and line with the line number of the occurrence of the key in the document.

Examples

## Screen for citations in installed document
cited_refs <- detect_keys(file.path(path.package("biblio"), "document.Rmd"))
cited_refs

Downloading bibliogrphic references from DOIs

Description

Retrieving bibliographic entries from Crossref by DOIs. This function is a wrapper for cr_cn().

Usage

doi2bib(x, ...)

Arguments

x

A character vector including DOI identifiers.

...

Further arguments (not yet used).

Value

The output is an object of class lib_df.

Examples

## Retrieve bibliographic entries for two publications
dois <- c("10.1111/1748-5967.12330",
    "10.1016/j.envsci.2019.03.017")

bibrefs <- doi2bib(dois)
bibrefs

Insert new rows in a data frame

Description

Insert new rows in a data frame

Usage

insert_rows(x, y)

Electronic library

Description

An S3 class for library entries. This class inherits properties from data frames.

Print content of lib_df objects

Description

A method for a brief overview on the content of a lib_df or a comp_df object.

Usage

## S3 method for class 'lib_df'
print(x, maxsum = 4, ...)

## S3 method for class 'comp_df'
print(x, ...)

Arguments

x

An object of class 'lib_df'.

maxsum

An integer value indicating the number of entries to be displayed in the printed output.

...

Further arguments passed among methods.

Value

A print in the console.

Author(s)

Miguel Alvarez

Examples

Refs <- read_bib(x = file.path(
        path.package("biblio"),
        "LuebertPliscoff.bib"
    ))

print(Refs, maxsum = 10)

Read BibTeX Databases

Description

Reading BibTeX databases and importing into R as a data frame. All the fields will be inserted as character values.

Usage

read_bib(x, ...)

Arguments

x

A single character value with the path to a BibTeX file. Alternativelly it can be a character vector containing the lines of a BibTeX library, for instance after using readLines().

...

Further arguments passed to readLines().

Value

An object of class lib_df.

Examples

Refs <- read_bib(x = file.path(
  path.package("biblio"),
  "LuebertPliscoff.bib"
))
Refs

Write a Reference List in rmarkdown

Description

A fast way to produce a reference list in an r-markdown document from a lib_df object.

This function may or may not produce intermediate files (bib and Rmd) and the result can be assigned to an object for further edition (see yamlme::update()).

A html file will be written by write_rmd() and render_rmd() in the working directory and displayed by browseURL().

Usage

reflist(x, ...)

## S3 method for class 'character'
reflist(
  x,
  output_file,
  delete_source = TRUE,
  title = "Automatic Reference List",
  output = "html_document",
  nocite = "'@*'",
  urlcolor = "blue",
  encoding = "UTF-8",
  ...
)

## S3 method for class 'lib_df'
reflist(x, filename, delete_source = TRUE, ...)

Arguments

x

A lib_df object to produce the reference list. In the character method, a character value indicating the path of a bibtex file (passed to read_bib()).

...

Further arguments passed to the yaml header in the intermediate Rmarkdown document.

output_file

A character value with the name for the written Rmarkdown file.

delete_source

A logical value indicating whether written bib file should be deleted after rendering html or not.

title, output, nocite, urlcolor

Arguments used for the yaml-header in r-markdown and passed to write_rmd(). They can be cancelled using the value NULL (not recommended for nocite).

encoding

A character value indicating the encoding string. It is passed to write_bib().

filename

A character value with the name for the written Rmd file, without file extension.

Value

An invisible object of class rmd_doc. A Rmd file will be written by write_rmd() as well.

Examples

## Not run: 
reflist(synopsis)

## End(Not run)

References by Lueber and Pliscoff (2018)

Description

Example of an object formatted as lib_df. This library is published with the references of the book Bioclimatic and vegetational synopsis of Chile by Luebert and Pliscoff (2017).

Usage

synopsis

Format

An object of class lib_df (inherits from data.frame) with 1701 rows and 23 columns.

Source

doi:10.5281/zenodo.60800

Examples

data(synopsis)

## Import from installed bibtex file
synopsis <- read_bib(x = file.path(
  path.package("biblio"),
  "LuebertPliscoff.bib"
))

Update data frames

Description

This function compares two versions of the same data frame and detect changes as additions, deleted entries or updates (modified entries).

A method to compare lib_df objects is also provided as well as a replace method.

Usage

update_data(object, revision, key, ...)

## S4 method for signature 'data.frame,data.frame,character'
update_data(
  object,
  revision,
  key,
  add = FALSE,
  delete = FALSE,
  update = FALSE,
  ...
)

## S4 method for signature 'lib_df,lib_df,missing'
update_data(object, revision, key, ...)

update_data(object, key, ...) <- value

## S4 replacement method for signature 'data.frame,character,data.frame'
update_data(object, key, ...) <- value

## S4 replacement method for signature 'lib_df,missing,lib_df'
update_data(object, key, ...) <- value

Arguments

object

A data frame or a lib_df object representing the original version.

revision

The updated version of 'object' to be compared.

key

A character value indicating the column used as identifier. This variable have to be in both versions otherwise this function will retrieve an error.

...

Further arguments passed among methods.

delete, add, update

Logical value indicating whether the action should be carried out. If all are 'FALSE', this function will just report differences as done by compare_df.

value

The updated version of 'object' in the replace methods.

Value

Either an invisible output with a print in the console or an updated object of class lib_df.

Examples

# Adding an ID to data set iris
iris2 <- iris
iris2$id <- 1:nrow(iris2)

# rows to add using mean values per species
iris_mod <- aggregate(cbind(
  Sepal.Length, Sepal.Width, Petal.Length,
  Petal.Width
) ~ Species, data = iris2, FUN = mean)
iris_mod$id <- (1:nrow(iris_mod)) + nrow(iris2)
iris_mod <- do.call(rbind, list(iris2, iris_mod[, colnames(iris2)]))

# delete some entries
iris_mod <- iris_mod[-c(15, 75, 105, 145), ]

# modify entries
iris_mod$Petal.Length[c(20, 30)] <- 0
iris_mod$Petal.Width[c(20, 50)] <- 0

# just a comparison
update_data(iris2, iris_mod, key = "id")

# do update
iris2 <- update_data(iris2, iris_mod,
  key = "id", delete = TRUE, add = TRUE,
  update = TRUE
)

Write BibTeX Files

Description

BibTeX databases can be created from data frames, interacting with Postgres databases.

Usage

write_bib(x, ...)

## S3 method for class 'lib_df'
write_bib(x, filename, encoding = "UTF-8", ...)

Arguments

x

A data frame with bibliographic entries.

...

Further arguments passed to file().

filename

A character value with the path and the name of the file to be written.

encoding

Character value with the encoding (passed to file()).

Value

A bibtex file.