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 |
Generate a LaTeX document from a LaTeX fragment.
author(tex, width=NA, engine=getOption("xdvir.engine"), packages=NULL)
author(tex, width=NA, engine=getOption("xdvir.engine"), packages=NULL)
tex |
LaTeX code. See Details. |
width |
Either |
engine |
The TeX engine that should be used for authoring.
May be the name of a TeX engine (character)
or a |
packages |
The LaTeX packages to be used. |
author()
can be used to generate a complete LaTeX document
from a LaTeX fragment, either as a character vector or an external file.
A "LaTeXdocument"
object.
Paul Murrell
author("this is a test")
author("this is a test")
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.
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)
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)
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 |
vjust |
Vertical justification. Typically in |
angle |
Angle (in |
lineheight |
The deafult lineheight. |
margin |
The margin around the text. |
width |
Either |
packages |
The LaTeX packages to be used.
May be the name of a LaTeX package (character) or a
|
engine |
The TeX engine that should be used to render the LaTeX.
May be the name of a TeX engine (character)
or a |
rotate_margins |
Whether margins should follow the orientation of the text. |
inherit.blank |
Should this element inherit the existence of an
|
An element_latex
object that can be used in place of
element_text
in ggplot2 theme specifications
Define a LaTeXPackage for the LaTeX fontspec package.
fontspecPackage(font=NULL, name=font)
fontspecPackage(font=NULL, name=font)
font |
The name of a font to use as the main font. See details. |
name |
The name of the resulting package. |
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"
.
A "LaTeXpackage"
object.
Paul Murrell
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")
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")
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.
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)
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)
mapping |
Set of aesthetic mappings created by
|
data |
The data to be displayed in this layer. There are three options: If A A |
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
|
... |
Other arguments passed on to
|
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 |
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 |
width |
Either |
dpi |
Resolution (dots per inch). |
packages |
The LaTeX packages to be used.
May be the name of a LaTeX package (character) or a
|
engine |
The TeX engine that should be used to render the LaTeX.
May be the name of a TeX engine (character)
or a |
na.rm |
If |
show.legend |
logical. Should this layer be included in the legends?
|
inherit.aes |
If |
A ggplot2 layer that can be added to a plot created with
ggplot2::ggplot()
.
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
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.
getMark(name) addMark(name, devx, devy, vpx=NA, vpy=NA, vpPath=NULL)
getMark(name) addMark(name, devx, devy, vpx=NA, vpy=NA, vpPath=NULL)
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. |
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.
getMark
returns a list containing the location (and viewport)
information for the mark.
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.
Paul Murrell
Render a DVI file in R graphics.
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(...)
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(...)
dvi |
A |
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 |
hjust , vjust
|
Justification of the output relative to the
|
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 |
... |
Arguments specific to methods of |
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()
.
A "DVIgrob"
object.
Paul Murrell
Author, typeset, and render LaTeX in R graphics.
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(...)
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(...)
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 |
hjust , vjust
|
Justification of the output relative to the
|
width |
Either |
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
|
engine |
The TeX engine that should be used to render the LaTeX.
May be the name of a TeX engine (character)
or a |
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 |
texFile |
Name of a file to use for LaTeX code. |
... |
Arguments passed to |
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.
A "DVIgrob"
object.
Paul Murrell
## Not run: # Requires TeX installation grid.latex("this is a test") ## End(Not run)
## Not run: # Requires TeX installation grid.latex("this is a test") ## End(Not run)
Define and register a LaTeX package for authoring, typesetting, and rendering LaTeX documents.
LaTeXpackage(name, preamble=NULL, prefix=NULL, suffix=NULL, special=NULL, init=NULL, final=NULL) registerPackage(package)
LaTeXpackage(name, preamble=NULL, prefix=NULL, suffix=NULL, special=NULL, init=NULL, final=NULL) registerPackage(package)
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()
returns a "LaTeXpackage"
object.
Paul Murrell
Define a LaTeXPackage for the LaTeX preview package.
previewPackage()
previewPackage()
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"
.
A "LaTeXpackage"
object.
This package wraps LaTeX snippets in a preview environment, which may not work for complex LaTeX snippets.
Paul Murrell
cat(author("test", packages="preview"), sep="\n")
cat(author("test", packages="preview"), sep="\n")
Read a DVI file (produced by LaTeX) into R.
readDVI(file)
readDVI(file)
file |
A character value giving the name of a DVI file. |
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.
A "DVI"
object.
There is a print method that produces a nice human-readable format.
Paul Murrell
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"))
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 and register a TeX engine for authoring, typesetting, and rendering LaTeX documents.
TeXengine(name, version, command, isEngine, fontFile, glyphIndex, options=NULL, preamble="", dviSuffix=".dvi") registerEngine(engine)
TeXengine(name, version, command, isEngine, fontFile, glyphIndex, options=NULL, preamble="", dviSuffix=".dvi") registerEngine(engine)
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 |
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 |
preamble |
A preamble that is added during authoring of a complete
LaTeX document from a LaTeX snippet. See |
dviSuffix |
The file suffix used for DVI files that are generated by this engine. |
engine |
A |
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
.
TeXengine()
returns a "TeXengine"
object.
Paul Murrell
Define a LaTeXPackage for the LaTeX tikz package.
tikzPackage(name="tikz", packages=NULL, bbox=TRUE, quote=TRUE) tikzPicture(name="tikzPicture", packages=NULL, bbox=TRUE, quote=TRUE)
tikzPackage(name="tikz", packages=NULL, bbox=TRUE, quote=TRUE) tikzPicture(name="tikzPicture", packages=NULL, bbox=TRUE, quote=TRUE)
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 |
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"
.
A "LaTeXpackage"
object.
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.
Paul Murrell
cat(author("test", packages="tikz"), sep="\n") cat(author("test", packages="tikzPicture"), sep="\n")
cat(author("test", packages="tikz"), sep="\n") cat(author("test", packages="tikzPicture"), sep="\n")
Typeset a LaTeX document, either from a character value or from an external file.
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, ...)
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, ...)
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 |
texFile |
Name of a file to use for LaTeX code. |
sig |
Add a signature to the DVI output? |
... |
Arguments passed to other |
typeset()
expects input to be either a "TeXdocument"
,
as generated by author
, or a
character value containing LaTeX code.
A "DVI"
object as produced by readDVI
.
Paul Murrell
## Not run: # Requires TeX installation tex <- author("this is a test") typeset(tex) ## End(Not run)
## Not run: # Requires TeX installation tex <- author("this is a test") typeset(tex) ## End(Not run)
Define a LaTeXPackage for the LaTeX xcolor package.
xcolorPackage()
xcolorPackage()
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"
.
A "LaTeXpackage"
object.
Paul Murrell
cat(author("test", packages="xcolor"), sep="\n")
cat(author("test", packages="xcolor"), sep="\n")
Define a LaTeXPackage for the LaTeX zref package.
zrefPackage()
zrefPackage()
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"
.
A "LaTeXpackage"
object.
Paul Murrell
cat(author("test", packages="zref"), sep="\n")
cat(author("test", packages="zref"), sep="\n")