Package 'InsectLabelR'

Generate a Complete 'LaTeX' Document and Compile it into a PDF

Description

This function generates a 'LaTeX' document by sequentially adding a header, printing labels for each raw of a data table, appending a footer, and then compiling the 'LaTeX' code into a PDF document. The 'LaTeX' code is adapted from work by Samuel Brown (see https://github.com/sdjbrown/publicFiles/blob/master/labels.tex and http://the-praise-of-insects.blogspot.com/2010/03/latex-insect-labels.html). Ensure you have a compatible installation of 'pdflatex' (see https://www.latex-project.org/get/).

Usage

create_pdf(
  file_out,
  ind_list,
  print_info,
  lab_width = 15,
  lab_height = 9,
  font_size = 4,
  n_col = 8,
  col_N_name = NA,
  hl_col = "orange",
  compile = TRUE
)

Arguments

file_out	A character string specifying the name of returned 'LaTeX' and PDF files.
ind_list	A data frame containing individual data. Each row represents data for one individual to be printed in the document.
print_info	A data frame specifying the parameters for printing, including field names, formatting options, what data to print and, on how many labels.
lab_width	An integer specifying the width (in mm) for the labels (default is 15 mm).
lab_height	An integer specifying the height (in mm) for the labels (default is 9).
font_size	A real (one digit) specifying the size of the font for the label (default is 4)
n_col	An integer specifying the number of label columns in the 'LaTeX' document (default is 8 columns).
col_N_name	A character string specifying the column name to be used for labels duplication (default is NA).
hl_col	A character string specifying the highlight color for specific elements (default is "orange").
compile	Boolean (TRUE/FALSE). Does the 'LaTeX' document should be compiled into a PDF document ? (default to TRUE)

Details

This function first calls print_header to write the beginning of the 'LaTeX' document. Then, it iterates over each row of ind_list, calling print_line to generate labels according to the provided print_info. After all labels are printed, it appends the 'LaTeX' document footer using print_bottom. Finally, it compiles the 'LaTeX' document into a PDF using pdflatex.

Value

The function creates a 'LaTeX' file, compiles it into a PDF, and saves the outputs to the specified location. It does not return any value in R.

Examples

outfile <- file.path(tempdir(), "labels.tex")

# This example only generates the LaTeX file (no pdflatex required)
create_pdf(
  file_out = outfile,
  ind_list = mosquito_collection,
  print_info = print_parameters,
  compile = FALSE
)

## Not run: 
# Full PDF generation requires pdflatex installed
create_pdf(
  file_out = outfile,
  ind_list = mosquito_collection,
  print_info = print_parameters
)

## End(Not run)

---

Launch the InsectLabelR 'shiny' application

Description

This function launches an interactive 'shiny' application allowing users to use InsectLabelR with either example datasets included in the package or user-provided data. It provides a graphical interface for generating labels without requiring programming expertise.

The application is available online at https://nicolas-moiroux.shinyapps.io/InsectLabelR/.

Usage

InsectLabelR_App()

Value

A 'shiny' application object.

Examples

if(interactive()){
InsectLabelR_App()
}

---

Example mosquito collection dataset for label generation

Description

A toy dataset representing mosquito specimens collected in southern France and intended for pinning and label printing with create_pdf().

Format

A data frame with 24 rows and 12 variables:

rec_date

Collection date (character). Example: "06/2024".

rec_place

Locality name, optionally including administrative unit.

rec_cntry

Country of collection.

Y

Latitude in degrees-minutes-seconds (DMS) format (character).

X

Longitude in degrees-minutes-seconds (DMS) format (character).

rec_name

Collector name.

id_name

Identifier (person who identified the specimen).

sex

Biological sex of the specimen (e.g., "Male", "Female").

genus

Genus name (e.g., Culiseta, Culex).

subgenus

Subgenus name (may be empty).

species

Species epithet.

N

Number of specimens sharing identical metadata.

id

Unique specimen identifier (integer).

Details

The dataset follows the standard input structure expected by InsectLabelR, with one row per specimen (or per group of identical specimens when N > 1). It includes collection metadata, taxonomic identification, sex, geographic coordinates (in DMS format), and a unique specimen identifier.

This dataset can be used to test label layout, formatting, and PDF generation without requiring external files.

The dataset contains specimens of Culiseta (Cal.) longiareolata and Culex pipiens.

Source

Simulated dataset for demonstration purposes.

---

Append the Closing Section to a 'LaTeX' Document

Description

This function writes the closing commands to a 'LaTeX' document. Specifically, it appends the end of a ⁠multicols*⁠ environment and the document environment.

Usage

print_bottom(file_out)

Arguments

file_out

A character string specifying the path to the output file where the 'LaTeX' closing commands will be appended.

Details

The function appends 'LaTeX' commands for ending a multiple-column layout (using the ⁠multicols*⁠ environment) and the document. It ensures the proper closure of a 'LaTeX' document that was generated by the preceding steps.

Value

This function appends 'LaTeX' code to the file specified in file_out. It does not return any output in R.

---

Create 'LaTeX' Header for Mosquito Labels Document

Description

This function generates a 'LaTeX' document header for mosquito labels and writes it to the specified output file. The header includes various 'LaTeX' packages, document settings, metadata, and the front cover of the document. The 'LaTeX' code is adapted from work by Samuel Brown (see https://github.com/sdjbrown/publicFiles/blob/master/labels.tex and http://the-praise-of-insects.blogspot.com/2010/03/latex-insect-labels.html).

Usage

print_header(
  file_out,
  lab_width = 15,
  lab_height = 9,
  font_size = 4,
  n_col = 8
)

Arguments

file_out	A character string specifying the name of the output file to write the 'LaTeX' header to.
lab_width	An integer specifying the width (in mm) for the labels (default is 15 mm).
lab_height	An integer specifying the height (in mm) for the labels (default is 9).
font_size	A real (one digit) specifying the size of the font for the label (default is 4)
n_col	An integer specifying the number of columns in the 'LaTeX' document (default is 8 columns).

Details

This function is primarily used for creating labels in 'LaTeX' for mosquito specimen identification. It sets the document's layout and font sizes, allowing customization of label size and number of columns on the page.

---

Print 'LaTeX' Labels for Each Line of a Data Table

Description

This function prints 'LaTeX' labels for each line of a data table based on specified information and user-defined printing parameters. It formats each label according to the provided field names, data, and formatting options. The function generates 'LaTeX' code for printing the labels into an external file. The 'LaTeX' code is based on the work by Samuel Brown (see https://github.com/sdjbrown/publicFiles/blob/master/labels.tex and http://the-praise-of-insects.blogspot.com/2010/03/latex-insect-labels.html)

Usage

print_line(
  file_out,
  ind_list,
  print_info,
  line_n,
  col_N_name = NA,
  hl_col = "orange"
)

Arguments

file_out	A character string specifying the path to the output file where 'LaTeX' code will be appended.
ind_list	A data frame containing the data for individuals. Each row corresponds to a specific individual.
print_info	A data frame specifying the printing parameters, including which fields to print, formatting options, and field names.
line_n	An integer indicating the row number in ind_list for which the labels should be created.
col_N_name	A character string specifying the name of the column in ind_list that indicates the number of individuals per row. Default is NA indicating 1 row per individual (and no replication of the labels)
hl_col	A character string specifying the color to be used for text highlighting

Details

The function retrieves data from a specified row in ind_list and matches it with the corresponding print parameters in print_info. It formats each label using the 'LaTeX' code according to the user-defined options in print_info, such as whether to italicize or bracket certain fields, and whether to include field names before the information. The function generates 'LaTeX' code for individual labels and appends it to the specified output file.

Value

The function appends 'LaTeX' code to the file specified in file_out. It does not return anything in R.

---

Example print parameter table for label formatting

Description

A toy parameter table defining how specimen data fields are arranged, formatted, and distributed across labels when using create_pdf().

Format

A data frame with 13 rows and 10 variables:

field_name

Name of the field in the ‘mosquito_collection’ data table.

print

Logical (0/1). Whether the field is printed on labels.

label_no

Numeric. Label number on which the field is printed (e.g., 1 = identification label, 2 = locality/date label, 3 = collector/identifier label).

order_lab

Numeric. Order of appearance within the label.

prefix

Character string added before the field value (e.g., "leg.", "det.", "no.").

print_opt_it

Logical (0/1). Whether the field should be printed in italics (typically for taxonomic names).

print_opt_par

Logical (0/1). Whether the field should be printed in parentheses (commonly used for subgenus).

line_break

Logical (0/1). Whether a line break follows the field.

print_opt_hl

Logical (0/1). Whether the field should be highlighted.

print_sex_symbol

Logical (0/1). Whether to print a sex symbol instead of the full sex text.

Details

This dataset illustrates the structure expected by InsectLabelR to control label composition (field selection, ordering, formatting options, line breaks, highlighting, and symbol printing).

Each row corresponds to a field present in the specimen data table and specifies whether and how it should be printed.

This example configuration produces three labels per specimen:

1. Taxonomic label (genus, subgenus, species, sex).

2. Collection label (date and locality).

3. Collector/identifier label (collector, determiner, specimen number).

Taxonomic names are printed in italics, the subgenus is enclosed in parentheses, and sex can optionally be rendered as a biological symbol.

Source

Simulated parameter table for demonstration purposes.

---

Convert Sex Data to 'LaTeX' Format

Description

This function converts a string representing sex data into the appropriate 'LaTeX' code for displaying male or female symbols in small font.

Usage

sex_to_latex(sex_data)

Arguments

sex_data

A character string representing the sex of an individual. It can start with "f" or "F" for female, "m" or "M" for male, or it can be NA.

Details

The function checks the first letter of the input string. If it starts with "f" or "F", it returns the 'LaTeX' code for the female symbol. If it starts with "m" or "M", it returns the 'LaTeX' code for the male symbol. If the input is NA or unrecognized, the function returns NA.

Value

A character string containing the corresponding 'LaTeX' code: "\smallfemale" for female, "\smallmale" for male, or NA if the input is not recognized or is NA.

---