<!-- README.md is generated from README.Rmd. Please edit that file -->

labeleR

<!-- badges: start -->

<!-- [](https://hits.dwyl.com/EcologyR/labeleR) --> <!-- [](https://hits.dwyl.com/EcologyR/labeleR) -->

<!-- badges: end --> <img src="man/figures/labeleR.png" width="140px" align="right"/>

Have you ever thought, if there was an automatic way…? labeleR is an R package to optimize the creation of your own collection labels, scientific documentation for events, and much more! 🏷️

If you need to create your labels (for your lab, plant vouchers, insect collections), attendance, participation certificates or accreditation badges (to a course, a congress)… labeleR is the answer! Decide which function to use, copy the code into your console, modify it and run! Keep an eye 👀 on this easy tutorial on how to use it 👇

Installing labeleR

To install the latest stable version of labeleR from CRAN, just use install.packages() function.

install.packages("labeleR")

However, if you want to install the latest version of labeleR from GitHub, you might need to install the devtools package. Once you have it, you just have to specify the repository and install:

# install.packages("devtools")
devtools::install_github("EcologyR/labeleR")

Ps. If you want to clone the repository, you can find the code here.

TinyTeX

labeleR depends on LaTeX, so you must have it also installed. We recommend using TinyTeX.

First, you would need to install the tinytex R package:

# install.packages("tinytex")
tinytex::install_tinytex()

⏱️ The first time you install tinytex or use labeleR it may take a while until all packages are correctly installed. Don’t worry, it will be much quicker next time!

TinyTeX troubleshooting

In case you have problems installing TinyTeX’s packages, try running this in your console:

    tinytex::tlmgr_install(pkgs = c( "zref", "needspace", "pagecolor",
                                     "bookmark", "changepage", "fp",
                                     "mdframed", "ms", "pgf", 
                                     "pspicture", "qrcode"))

1. Getting started

library("labeleR")

1.1 Loading the data

The very first thing you need to start using labeleR is a dataset where the information is included. This dataset can be imported to the R environment from a file (‘.csv’), excel sheet (‘.xlsx’), a Google Sheet, using read.table(), readxl::read_excel(), gsheet::gsheet2tbl() and alike functions.

Here an example of a dataset imported from a Google Sheet URL:

library(gsheet)

#URL: https://docs.google.com/spreadsheets/d/1inkk3_oNvvt8ajdK4wOkSgPoUyE8JzENrZgSTFJEFBw/edit#gid=0
people_list_long <- gsheet2tbl("1inkk3_oNvvt8ajdK4wOkSgPoUyE8JzENrZgSTFJEFBw")

A key point is that the Google Sheet document must grant at least view access to anyone with the link; otherwise R will not be able to open it.

1.2 Some advice for the labeleR functions

When using labeleR’s functions, there are some widely used arguments and nomenclature you should be aware of.

The first required argument in all functions is data, which is the data frame that has been previously loaded. The second one is path, which is the folder where the output PDFs will be stored. In case the specified folder does not exist, it will be automatically created. If you want to name the output PDF file in a certain way, you must specify it using the filename argument. Additionally, you can store the created intermediate files (e.g. RMarkdown, picture files) using keep.files = TRUE.

Ultimately, labeleR uses its own templates to create the documents. However, these can be modified for specific purposes. To do so, open a RMarkdown file in RStudio from the labeleR template you want to edit, and after saving it locally, specify its directory path in the template argument.

RStudio > File > New File > RMarkdown… > From Template > {LabeleRTemplate.Rmd}

Pictures (such as logos or signatures) are included in some templates. For these, argument names are lpic (standing for left picture, in the top), rpic (right picture, also in the top), signature.pic (signature picture) in the certificates, and logo in the collection label. In all these cases the path to the picture file must be provided.

As for the arguments nomenclature, there are two kinds. On the one hand, the “fixed” arguments, which are those that remain the same in all the documents (e.g. the name of a conference in an accreditation, or the name of a herbarium institution). These arguments are named using a unique word (e.g. event or speaker), and can be filled in using free text. On the other hand, “variable” arguments are those which vary among documents, and therefore differ among rows (e.g. attendees names to a conference, or species in herbarium labels). To specify the column of data in which this information is stored, two-word parameters are used (i.e. name.column or species.column). The only argument that does not follow this philosophy is qr (present in create_herbarium_label, create_collection_label and create_tiny_label). This parameter can be set as a column name, used as a “variable” argument, or as a free text,as a “fixed” one.

2. labeleR functions

Now let’s start using labeleR!

Here we will display a blank example to help you see the internal template structure, accompanied by some examples inspired in the Harry Potter universe! 🔮

2.1 Collection labels

2.1.1 Herbarium labels

Herbarium labels are one of the documents with more variable parameters, as there is a lot of information that can be included. Here, we have chosen what we consider to be the most useful parameters, but we have included three free fields for the user to include the information they prefer. Of course, a field’s name does not force the user to use it for that category (location can be set in the elevation column, on top; and vice versa), but be aware that the family.column content will always be capitalized, and the taxon.column one in italics, so those ones we recommend to use them as stated.

As said before, the QR can stand for a free text (and therefore remain identical in all labels), or be a column name, and the codes will be rendered with the individual information of each row. Four different labels will fit in each of the A4 pdf pages.

Warning! Including too long texts may cause the alteration of the structure of the labels, so we recommend to be concise (specially with area description!)

| | |--------------------------------------|

Herbarium labels example:

In this example, we show the labels some students have created for their herbarium assignment of the Herbology class.

create_herbarium_label(
  data = herbarium.table,
  path = "labeleR_output",
  filename = "herbarium_labels",
  qr = "QR_code",
  title ="Magical flora of the British Isles" ,
  subtitle = "Project: Eliminating plant blindness in Hogwarts students",
  family.column = "Family",
  taxon.column = "Taxon",
  author.column = "Author",
  det.column = "det",
  date.det.column = "Det_date",
  location.column = "Location",
  area.description.column = "Area_description",
  latitude.column = "Latitude",
  longitude.column = "Longitude",
  elevation.column = "Elevation",
  field1.column = "life_form",
  field2.column = "Observations",
  field3.column = "Height",
  collector.column = "Collector",
  collection.column = "Collection_number",
  assistants.column = "Assistants",
  date.column = "Date"
)

| | |---------------------------------------|

2.1.2. Collection labels

Collection labels are one of the most aesthetic labels. They have five variable parameters (which are not recommended to be too long, as explained in the herbarium labels), along with the possibility of including a QR code (fixed or variable), an image (logo or picture). Field 1 will be always capitalized (as in family.column in the herbarium label), and Field 2 italicized. Any field can be left blank.

As a novelty, the user may manually fix the backgroud and text colors to their preference, using HTML color codes (same code as HEX, but without the ‘#’). By default, background colors are two hues of green. Eight different labels will fit in each of the A4 pdf pages.

| | |----------------------------------------------|

Collection labels example:

In this example we can see six labels created for the school’s displayed collection of stuffed animals.

create_collection_label(
  data = collection.table,
  path = "labeleR_output",
  filename = "labels",
  qr = "QR_code",
  field1.column = "field1",
  field2.column = "field2",
  field3.column = "field3",
  field4.column = "field6",
  field5.column = "field7",
  system.file("rmarkdown/pictures/Hogwarts_BnW.png", package = "labeleR"),
  bgcolor =