Package 'xdvir'

Title: Render 'LaTeX' in Plots
Description: High-level functions to render 'LaTeX' fragments in plots, including as labels and data symbols in 'ggplot2' plots, plus low-level functions to author 'LaTeX' fragments (to produce 'LaTeX' documents), typeset 'LaTeX' documents (to produce 'DVI' files), read 'DVI' files (to produce "DVI" objects), and render "DVI" objects.
Authors: Paul Murrell [aut, cre]
Maintainer: Paul Murrell <[email protected]>
License: GPL-3
Version: 0.1-2
Built: 2025-02-24 19:22:19 UTC
Source: CRAN

Help Index


Generate a LaTeX Document

Description

Generate a LaTeX document from a LaTeX fragment.

Usage

author(tex,
       width=NA,
       engine=getOption("xdvir.engine"),
       packages=NULL)

Arguments

tex

LaTeX code. See Details.

width

Either NA or a numeric value. The latter is assumed to be a number of inches.

engine

The TeX engine that should be used for authoring. May be the name of a TeX engine (character) or a "TeXengine" object.

packages

The LaTeX packages to be used.

Details

author() can be used to generate a complete LaTeX document from a LaTeX fragment, either as a character vector or an external file.

Value

A "LaTeXdocument" object.

Author(s)

Paul Murrell

See Also

LaTeXpackage.

Examples

author("this is a test")

ggplot2 Theme Element Supporting Latex Syntax

Description

This theme element is an alternative to ggplot2::element_text() for producing labels from LaTeX fragments.

Both hjust and vjust can be character values: one of "left", "bbleft", "centre", "center", "right", "bbright" for horizontal justification; and one of "bottom", "baseline", "centre", "center", or "top" for vertical justification.

Usage

element_latex(family=NULL,
              fontface=NULL,
              colour=NULL,
              size=NULL,
              hjust=NULL, vjust=NULL,
              angle=NULL,
              lineheight=NULL,
              color=NULL,
              margin=NULL,
              width=NULL,
              packages=NULL,
              engine=getOption("xdvir.engine"),
              rotate_margins=FALSE,
              inherit.blank=FALSE)

Arguments

family

The default font family.

fontface

The default font face.

colour, color

The default text colour.

size

The deafult font size.

hjust

Horizontal justification. Typically in [0,1][0, 1], but see Details.)

vjust

Vertical justification. Typically in [0,1][0, 1], but see Details.)

angle

Angle (in [0,360][0, 360])

lineheight

The deafult lineheight.

margin

The margin around the text.

width

Either NA or a numeric value or a unit specifying the width for typesetting. NA means the natural width of the label.

packages

The LaTeX packages to be used. May be the name of a LaTeX package (character) or a "LaTeXpackage" object.

engine

The TeX engine that should be used to render the LaTeX. May be the name of a TeX engine (character) or a "TeXengine" object.

rotate_margins

Whether margins should follow the orientation of the text.

inherit.blank

Should this element inherit the existence of an element_blank among its parents? If TRUE the existence of a blank element among its parents will cause this element to be blank as well. If FALSE any blank parent element will be ignored when calculating final element state.

Value

An element_latex object that can be used in place of element_text in ggplot2 theme specifications


LaTeX Package fontspec.

Description

Define a LaTeXPackage for the LaTeX fontspec package.

Usage

fontspecPackage(font=NULL, name=font)

Arguments

font

The name of a font to use as the main font. See details.

name

The name of the resulting package.

Details

This function creates a "LaTeXpackage" object that provides support for the LaTeX fontspec package.

The font argument provides some convenience for setting the main font to be used. The font can be the common name of a system font or a complete path to the font file.

For more complex situations, fontspec commands can be added to the LaTeX code that is sent to functions like author and grid.latex (see the Examples).

A predefined package, with no main font defined, is pre-registered under the name "fontspec".

Value

A "LaTeXpackage" object.

Author(s)

Paul Murrell

Examples

cat(author("test", packages="fontspec"), sep="\n")
cat(author("test", packages=fontspecPackage(font="Courier")), sep="\n")
tex <- "\\setmainfont{fontname.ttf}[Path=/path/to/font/]\ntest"
cat(author(tex, packages="fontspec"), sep="\n")

Latex Data Symbols in ggplot2 Plots

Description

This geom draws text labels similar to ggplot2::geom_text(), but with the text interpreted as a LaTeX fragment. Most styling parameters can be used as aesthetics and can be applied separately to each text label drawn.

Usage

geom_latex(mapping=NULL, data=NULL, stat="identity",
           position="identity", ...,
           nudge_x=0, nudge_y=0,
           width=NA,
           dpi=NA, packages=NULL,
           engine=getOption("xdvir.engine"),
           na.rm=FALSE,
           show.legend=NA, inherit.aes=TRUE)

Arguments

mapping

Set of aesthetic mappings created by aes() or aes_(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.

data

The data to be displayed in this layer. There are three options:

If NULL, the default, the data is inherited from the plot data as specified in the call to ggplot().

A data.frame, or other object, will override the plot data. All objects will be fortified to produce a data frame. See fortify() for which variables will be created.

A function will be called with a single argument, the plot data. The return value must be a data.frame, and will be used as the layer data. A function can be created from a formula (e.g. ~ head(.x, 10)).

stat

The statistical transformation to use on the data for this layer, as a string.

position

Position adjustment, either as a string, or the result of a call to a position adjustment function. Cannot be jointy specified with nudge_x or nudge_y.

...

Other arguments passed on to layer(). These are often aesthetics, used to set an aesthetic to a fixed value, like colour = "red" or size = 3. They may also be parameters to the paired geom/stat.

nudge_x

Horizontal and vertical adjustment to nudge labels by. Useful for offsetting text from points, particularly on discrete scales. Cannot be jointly specified with position.

nudge_y

Horizontal and vertical adjustment to nudge labels by. Useful for offsetting text from points, particularly on discrete scales. Cannot be jointly specified with position.

width

Either NA or a numeric value or a unit specifying the width for typesetting. NA means the natural width of the label.

dpi

Resolution (dots per inch).

packages

The LaTeX packages to be used. May be the name of a LaTeX package (character) or a "LaTeXpackage" object.

engine

The TeX engine that should be used to render the LaTeX. May be the name of a TeX engine (character) or a "TeXengine" object.

na.rm

If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.

show.legend

logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display.

inherit.aes

If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. borders().

Value

A ggplot2 layer that can be added to a plot created with ggplot2::ggplot().

Aesthetics

geom_latex() understands the following aesthetics (required aesthetics are in bold; select aesthetics are annotated):

  • x

  • y

  • label

  • alpha

  • angle

  • colour Default color of label text and label outline.

  • family

  • group

  • hjust

  • lineheight

  • size Default font size of label text.

  • vjust


Access LaTeX Marks

Description

getMark() allows access a location within LaTeX output relative to the rendering in R.

addMark() allows third-party packages to add marks to the rendering in R.

Usage

getMark(name)
addMark(name, devx, devy, vpx=NA, vpy=NA, vpPath=NULL)

Arguments

name

The name of a mark.

devx, devy

The location of the mark on the device (in inches).

vpx, vpy

The location of the mark relative to the viewport in which the mark was rendered.

vpPath

The viewport path to the viewport in which the mark was rendered.

Details

Some LaTeX packages, e.g., see zrefPackage, allow positions within text to be saved with a label. This function allows those saved locations to be accessed, e.g., to add further drawing relative to those locations.

Value

getMark returns a list containing the location (and viewport) information for the mark.

Warning

The saved locations are only relative to the current device size. Resizing the device, or copying between devices will result in incorrect locations.

A call to addMark() using an existing mark name will overwrite the previous mark information.

Author(s)

Paul Murrell


Render DVI File in R

Description

Render a DVI file in R graphics.

Usage

dviGrob(dvi, ...) 
## S3 method for class 'character'
dviGrob(dvi, ...)
## S3 method for class 'DVI'
dviGrob(dvi, ...,
        packages=NULL,
        engine=getOption("xdvir.engine"))
## S3 method for class 'list'
dviGrob(dvi, x = 0.5, y = 0.5,
        margin=0, rot=0,
        default.units = "npc",
        hjust="centre", vjust="centre",
        dpi=NA,
        page=1,
        packages=NULL,
        engine=getOption("xdvir.engine"),
        fontLib=getOption("xdvir.fontLib"),
        ...,
        name=NULL,
        gp=gpar(),
        vp=NULL)
grid.dvi(...)
render(...)

Arguments

dvi

A "DVI" object, as produced by readDVI, or a "DVIfile" object, as produced by typeset, or the name of a DVI file, or a list containing some combination of all three.

x, y

Numeric values or units specifying where to draw the output.

margin

Numeric values or units specifying margins (in the order bottom, left, top, right). Recycled if necessary.

rot

Rotation angle (in degrees).

default.units

Units to use if x or y are numeric.

hjust, vjust

Justification of the output relative to the x/y location.

dpi

Resolution (dots per inch) for rendering.

page

Which page should be drawn.

engine

The TeX engine that should be used to render the DVI file (see Details).

fontLib

The font libraary the should be used to query fonts and glyphs.

packages

The LaTeX packages to be used in rendering the DVI.

name

Character value giving name for the grob.

gp

Graphical parameter settings.

vp

A viewport or NULL.

...

Arguments specific to methods of dviGrob.

Details

If the engine is NULL (the default), one is chosen based on the engine attribute of the dvi input (if an engine of that name has been registered).

If the engine is specified, but does not match the engine attribute of the dvi then, if the dvi engine was guessed the engine will be used, otherwise the conflict will result in an error.

render() is an alias for grid.dvi().

Value

A "DVIgrob" object.

Author(s)

Paul Murrell

See Also

readDVI, LaTeXpackage.


Render LaTeX in R

Description

Author, typeset, and render LaTeX in R graphics.

Usage

latexGrob(tex,
          x=0.5, y=0.5,
          margin=0, rot=0,
          default.units="npc",
          hjust="centre", vjust="centre",
          width=NA,
          dpi=NA,
          page=1,
          packages=NULL,
          engine=getOption("xdvir.engine"),
          fontLib=getOption("xdvir.fontLib"),
          texFile=NULL,
          name=NULL,
          gp=gpar(),
          vp=NULL) 
grid.latex(...)

xelatexGrob(tex, ...)
grid.xelatex(...)

lualatexGrob(tex, ...)
grid.lualatex(...)

Arguments

tex

LaTeX code as a character vector.

x, y

Numeric values or units specifying where to draw the output.

margin

Numeric values or units specifying margins (in the order bottom, left, top, right). Recycled if necessary.

rot

Rotation angle (in degrees).

default.units

Units to use if x or y are numeric.

hjust, vjust

Justification of the output relative to the x/y location.

width

Either NA or a numeric value or a unit specifying the width for typesetting. NA means the natural width of tex.

dpi

Resolution (dots per inch) for rendering.

page

Which page should be drawn.

packages

The LaTeX packages to be used. May be the name of a LaTeX package (character) or a "LaTeXpackage" object.

engine

The TeX engine that should be used to render the LaTeX. May be the name of a TeX engine (character) or a "TeXengine" object.

fontLib

The font libraary the should be used to query fonts and glyphs.

name

Character value giving name for the grob.

gp

Graphical parameter settings.

vp

A viewport or NULL.

texFile

Name of a file to use for LaTeX code.

...

Arguments passed to dviGrob.

Details

grid.latex() takes a LaTeX fragment, generates a LaTeX document, typesets it, reads the resulting DVI file and renders the result.

grid.xelatex() is just a convenient front end for grid.latex(), with appropriate default engine.

grid.latex() attempts to be smart about delaying typesetting until drawing time if necessary in order to get the correct context for width and gp settings. This means that, unless gp is set to NULL and width is set to either NA or an absolute unit (e.g., a number of inches), the calculation of, for example, the width of a grob will be less efficient because the typesetting has to be performed all over again.

Value

A "DVIgrob" object.

Author(s)

Paul Murrell

See Also

LaTeXpackage.

Examples

## Not run: 
# Requires TeX installation
grid.latex("this is a test")

## End(Not run)

Define a LaTeX Package.

Description

Define and register a LaTeX package for authoring, typesetting, and rendering LaTeX documents.

Usage

LaTeXpackage(name,
             preamble=NULL,
             prefix=NULL,
             suffix=NULL,
             special=NULL,
             init=NULL,
             final=NULL)
registerPackage(package)

Arguments

name

Character name for the package.

preamble, prefix, suffix

Character preamble, prefix, and suffix for authoring LaTeX documents.

special

Function for handling DVI specials during rendering.

init, final

Functions to initialise package before rendering and finalise after rendering.

package

A "LaTeXpackage" object.

Value

LaTeXpackage() returns a "LaTeXpackage" object.

Author(s)

Paul Murrell


LaTeX Package preview.

Description

Define a LaTeXPackage for the LaTeX preview package.

Usage

previewPackage()

Details

This function creates a "LaTeXpackage" object that provides support for the LaTeX preview package.

This adds a "preview-baseline" anchor to use for aligning the rendered LaTeX in R.

A predefined package is pre-registered under the name "preview".

Value

A "LaTeXpackage" object.

Warning

This package wraps LaTeX snippets in a preview environment, which may not work for complex LaTeX snippets.

Author(s)

Paul Murrell

Examples

cat(author("test", packages="preview"), sep="\n")

Read DVI File

Description

Read a DVI file (produced by LaTeX) into R.

Usage

readDVI(file)

Arguments

file

A character value giving the name of a DVI file.

Details

A "DVI" object is a list of memory blocks (as produced by functions from the hexView package), with one block per DVI operation.

This is the detailed, byte-level contents of the DVI file.

Value

A "DVI" object.

There is a print method that produces a nice human-readable format.

Author(s)

Paul Murrell

Examples

readDVI(system.file("DVI", "test-pdftex.dvi", package="xdvir"))
readDVI(system.file("DVI", "test-luatex.dvi", package="xdvir"))
readDVI(system.file("DVI", "test-xetex.xdv", package="xdvir"))
readDVI(system.file("DVI", "test-uptex.dvi", package="xdvir"))

Define a TeX Engine.

Description

Define and register a TeX engine for authoring, typesetting, and rendering LaTeX documents.

Usage

TeXengine(name,
          version,
          command,
          isEngine,
          fontFile,
          glyphIndex,
          options=NULL,
          preamble="",
          dviSuffix=".dvi")
registerEngine(engine)

Arguments

name

Character name for the engine.

version

A function with no arguments that returns the engine version as a character value.

command

The command used to typeset a latex document with this engine.

isEngine

A function with one argument, a "DVI" object, that returns a logical indicating whether this engine was used to generate that DVI output.

fontFile

A function with one argument, a font description from a font definition opertaion in DVI output, that returns a path to the appropriate font file.

glyphIndex

A function with one argument, a raw vector of bytes from a set char operation in DVI output, that returns an integer index of the appropriate glyph.

options

Any required options to command to ensure that the engine generates DVI output.

preamble

A preamble that is added during authoring of a complete LaTeX document from a LaTeX snippet. See author and grid.latex.

dviSuffix

The file suffix used for DVI files that are generated by this engine.

engine

A "TeXengine" object, as generated by TeXengine().

Details

TeXengine() can be used to create a typesetting engine for use with, e.g., grid.latex. Registering the engine via registerEngine() means that the engine can be specified by name.

Value

TeXengine() returns a "TeXengine" object.

Author(s)

Paul Murrell


LaTeX Package tikz.

Description

Define a LaTeXPackage for the LaTeX tikz package.

Usage

tikzPackage(name="tikz", packages=NULL, bbox=TRUE, quote=TRUE)
tikzPicture(name="tikzPicture", packages=NULL, bbox=TRUE, quote=TRUE)

Arguments

name

The name of the resulting package.

packages

A character list of TikZ package names.

bbox

Either a logical indicating whether to use (or ignore) the TikZ bounding box at the end of a TikZ picture, or a numeric vector of 4 values (left, bottom, right, top) describing the bounding box to use for the TikZ picture.

quote

Whether to place single quotes around the path to the pgfsysdriver file. This might help if the path to the R installation contains spaces. Conversely, at least some LuaTeX versions require this to be FALSE.

Details

This function creates a "LaTeXpackage" object that provides support for the LaTeX xcolor package.

This allows TikZ pictures to be included in LaTeX snippets. when calling grid.latex.

The "tikzPicture" package is provided for convenience if the LaTeX snippet only consists of TikZ code.

Two predefined packages are pre-registered under the names "tikz" and "tikzPicture".

Value

A "LaTeXpackage" object.

Note

If "tikzmark" is one of the packages, then a new command, \xdvirtikzmark{label}, is defined to allow saved positions also to be recorded in the rendered LaTeX in R. This produces nullGrob objects at the relevant locations plus anchors (for justification) at the relevant locations.

Author(s)

Paul Murrell

Examples

cat(author("test", packages="tikz"), sep="\n")
cat(author("test", packages="tikzPicture"), sep="\n")

Typeset a LaTeX Document

Description

Typeset a LaTeX document, either from a character value or from an external file.

Usage

typeset(tex,
        engine=getOption("xdvir.engine"),
        ...)
## S3 method for class 'LaTeXdocument'
typeset(tex,
        engine=NULL,
        texFile=NULL,
        ...)
## S3 method for class 'character'
typeset(tex,
        engine=NULL,
        texFile=NULL,
        sig=FALSE, 
        ...)

Arguments

tex

LaTeX code. See Details.

engine

The TeX engine that should be used to typeset the LaTeX. May be the name of a TeX engine (character) or a "TeXengine" object.

texFile

Name of a file to use for LaTeX code.

sig

Add a signature to the DVI output?

...

Arguments passed to other typeset methods.

Details

typeset() expects input to be either a "TeXdocument", as generated by author, or a character value containing LaTeX code.

Value

A "DVI" object as produced by readDVI.

Author(s)

Paul Murrell

See Also

LaTeXpackage.

Examples

## Not run: 
# Requires TeX installation
tex <- author("this is a test")
typeset(tex)

## End(Not run)

LaTeX Package xcolor.

Description

Define a LaTeXPackage for the LaTeX xcolor package.

Usage

xcolorPackage()

Details

This function creates a "LaTeXpackage" object that provides support for the LaTeX xcolor package.

This allows commands like \color{blue} to be included in LaTeX snippets when calling grid.latex.

A predefined package is pre-registered under the name "xcolor".

Value

A "LaTeXpackage" object.

Author(s)

Paul Murrell

Examples

cat(author("test", packages="xcolor"), sep="\n")

LaTeX Package zref.

Description

Define a LaTeXPackage for the LaTeX zref package.

Usage

zrefPackage()

Details

This function creates a "LaTeXpackage" object that provides support for the LaTeX zref package.

This allows commands like \zsavepos{label} to be included in LaTeX snippets when calling grid.latex.

A new command, \xdvirzmark{label}, is defined to allow saved positions also to be recorded in the rendered LaTeX in R. This produces nullGrob objects at the relevant locations plus anchors (for justification) at the relevant locations.

A predefined package is pre-registered under the name "zref".

Value

A "LaTeXpackage" object.

Author(s)

Paul Murrell

Examples

cat(author("test", packages="zref"), sep="\n")