Skip to contents

Format the citations for a tree result

Source: R/pr_cite_tree.R
pr_cite_tree.Rd

Given a pr_tree_result produced by pr_get_tree() or pr_date_tree(), emit a formatted citation block listing the backend used, the underlying paper(s), and per-tree source citations when the result is a multi-tree posterior. Useful when writing the methods section of a paper or when adding a tree provenance footnote to a figure.

Usage

pr_cite_tree(result, format = c("text", "markdown", "bibtex"))

Arguments

result

A pr_tree_result from pr_get_tree() or pr_date_tree().

format

A length-1 character vector. One of:

"text" (default)

Plain-text citation block, suitable for printing or copy-pasting.

"markdown"

GitHub-flavoured markdown with bullets and headings; suitable for issue threads, PR descriptions, and README sections.

"bibtex"

One BibTeX entry per source. Use this to paste into a manuscript bibliography. Note: the entries are hand-rolled from package metadata, not pulled from a canonical bibliographic source — always sanity-check before submission.

Value

A length-1 character vector containing the formatted citation block. The result is also printed (invisibly returned) so calling pr_cite_tree(res) on its own at the console shows the block.

See also

pr_get_tree() / pr_date_tree() for producing the pr_tree_result that this function formats.

Examples

# Build a minimal `pr_tree_result` by hand so the three citation
# formats are visible without a network call. In real use this
# object is returned by `pr_get_tree()` or `pr_date_tree()`.
fake_res <- structure(
  list(
    source       = "fishtree",
    tree         = ape::read.tree(text = "(Salmo_salar,Esox_lucius);"),
    backend_meta = list(tree_provenance = list())
  ),
  class = "pr_tree_result"
)

cat(pr_cite_tree(fake_res, format = "text"))      # human-readable
#> Tree retrieved via prepR4pcm::pr_get_tree(source = "fishtree").
#> 
#> Backend package:
#>   Chang, J., Rabosky, D. L., Smith, S. A., & Alfaro, M. E. (2019). An R package and online resource for macroevolutionary studies using the ray-finned fish tree of life. Methods in Ecology and Evolution, 10(7), 1118-1124. doi:10.1111/2041-210X.13182
#> 
#> Underlying reference:
#>   Rabosky, D. L., Chang, J., Title, P. O., Cowman, P. F., Sallan, L., Friedman, M., Kashner, K., Garilao, C., Near, T. J., Coll, M., & Alfaro, M. E. (2018). An inverse latitudinal gradient in speciation rate for marine fishes. Nature, 559(7714), 392-395. doi:10.1038/s41586-018-0273-1
#> Tree retrieved via prepR4pcm::pr_get_tree(source = "fishtree").
#> 
#> Backend package:
#>   Chang, J., Rabosky, D. L., Smith, S. A., & Alfaro, M. E. (2019). An R package and online resource for macroevolutionary studies using the ray-finned fish tree of life. Methods in Ecology and Evolution, 10(7), 1118-1124. doi:10.1111/2041-210X.13182
#> 
#> Underlying reference:
#>   Rabosky, D. L., Chang, J., Title, P. O., Cowman, P. F., Sallan, L., Friedman, M., Kashner, K., Garilao, C., Near, T. J., Coll, M., & Alfaro, M. E. (2018). An inverse latitudinal gradient in speciation rate for marine fishes. Nature, 559(7714), 392-395. doi:10.1038/s41586-018-0273-1
cat(pr_cite_tree(fake_res, format = "markdown"))  # for a README
#> ### Tree retrieved via `prepR4pcm::pr_get_tree(source = "fishtree")`
#> 
#> **Backend package:**
#> 
#> - Chang, J., Rabosky, D. L., Smith, S. A., & Alfaro, M. E. (2019). An R package and online resource for macroevolutionary studies using the ray-finned fish tree of life. Methods in Ecology and Evolution, 10(7), 1118-1124. doi:10.1111/2041-210X.13182
#> 
#> **Underlying reference:**
#> 
#> - Rabosky, D. L., Chang, J., Title, P. O., Cowman, P. F., Sallan, L., Friedman, M., Kashner, K., Garilao, C., Near, T. J., Coll, M., & Alfaro, M. E. (2018). An inverse latitudinal gradient in speciation rate for marine fishes. Nature, 559(7714), 392-395. doi:10.1038/s41586-018-0273-1
#> ### Tree retrieved via `prepR4pcm::pr_get_tree(source = "fishtree")`
#> 
#> **Backend package:**
#> 
#> - Chang, J., Rabosky, D. L., Smith, S. A., & Alfaro, M. E. (2019). An R package and online resource for macroevolutionary studies using the ray-finned fish tree of life. Methods in Ecology and Evolution, 10(7), 1118-1124. doi:10.1111/2041-210X.13182
#> 
#> **Underlying reference:**
#> 
#> - Rabosky, D. L., Chang, J., Title, P. O., Cowman, P. F., Sallan, L., Friedman, M., Kashner, K., Garilao, C., Near, T. J., Coll, M., & Alfaro, M. E. (2018). An inverse latitudinal gradient in speciation rate for marine fishes. Nature, 559(7714), 392-395. doi:10.1038/s41586-018-0273-1
cat(pr_cite_tree(fake_res, format = "bibtex"))    # for a .bib file
#> % Auto-generated by prepR4pcm::pr_cite_tree(format = "bibtex").
#> % Sanity-check before submitting to a journal.
#> @misc{rabosky2018fishtree_pkg,
#>   note = {Chang, J., Rabosky, D. L., Smith, S. A., & Alfaro, M. E. (2019). An R package and online resource for macroevolutionary studies using the ray-finned fish tree of life. Methods in Ecology and Evolution, 10(7), 1118-1124. doi:10.1111/2041-210X.13182}
#> }
#> 
#> @misc{rabosky2018fishtree_paper,
#>   note = {Rabosky, D. L., Chang, J., Title, P. O., Cowman, P. F., Sallan, L., Friedman, M., Kashner, K., Garilao, C., Near, T. J., Coll, M., & Alfaro, M. E. (2018). An inverse latitudinal gradient in speciation rate for marine fishes. Nature, 559(7714), 392-395. doi:10.1038/s41586-018-0273-1}
#> }
#> % Auto-generated by prepR4pcm::pr_cite_tree(format = "bibtex").
#> % Sanity-check before submitting to a journal.
#> @misc{rabosky2018fishtree_pkg,
#>   note = {Chang, J., Rabosky, D. L., Smith, S. A., & Alfaro, M. E. (2019). An R package and online resource for macroevolutionary studies using the ray-finned fish tree of life. Methods in Ecology and Evolution, 10(7), 1118-1124. doi:10.1111/2041-210X.13182}
#> }
#> 
#> @misc{rabosky2018fishtree_paper,
#>   note = {Rabosky, D. L., Chang, J., Title, P. O., Cowman, P. F., Sallan, L., Friedman, M., Kashner, K., Garilao, C., Near, T. J., Coll, M., & Alfaro, M. E. (2018). An inverse latitudinal gradient in speciation rate for marine fishes. Nature, 559(7714), 392-395. doi:10.1038/s41586-018-0273-1}
#> }

# \donttest{
  # Realistic use after actually retrieving a tree from a backend:
  if (requireNamespace("fishtree", quietly = TRUE)) {
    res <- pr_get_tree(c("Salmo salar", "Esox lucius"),
                       source = "fishtree")
    cat(pr_cite_tree(res, format = "markdown"))
  }
#> ### Tree retrieved via `prepR4pcm::pr_get_tree(source = "fishtree")`
#> 
#> **Backend package:**
#> 
#> - Chang, J., Rabosky, D. L., Smith, S. A., & Alfaro, M. E. (2019). An R package and online resource for macroevolutionary studies using the ray-finned fish tree of life. Methods in Ecology and Evolution, 10(7), 1118-1124. doi:10.1111/2041-210X.13182
#> 
#> **Underlying reference:**
#> 
#> - Rabosky, D. L., Chang, J., Title, P. O., Cowman, P. F., Sallan, L., Friedman, M., Kashner, K., Garilao, C., Near, T. J., Coll, M., & Alfaro, M. E. (2018). An inverse latitudinal gradient in speciation rate for marine fishes. Nature, 559(7714), 392-395. doi:10.1038/s41586-018-0273-1
#> ### Tree retrieved via `prepR4pcm::pr_get_tree(source = "fishtree")`
#> 
#> **Backend package:**
#> 
#> - Chang, J., Rabosky, D. L., Smith, S. A., & Alfaro, M. E. (2019). An R package and online resource for macroevolutionary studies using the ray-finned fish tree of life. Methods in Ecology and Evolution, 10(7), 1118-1124. doi:10.1111/2041-210X.13182
#> 
#> **Underlying reference:**
#> 
#> - Rabosky, D. L., Chang, J., Title, P. O., Cowman, P. F., Sallan, L., Friedman, M., Kashner, K., Garilao, C., Near, T. J., Coll, M., & Alfaro, M. E. (2018). An inverse latitudinal gradient in speciation rate for marine fishes. Nature, 559(7714), 392-395. doi:10.1038/s41586-018-0273-1
# }