tikzDevice-package: Support for native LaTeX output of R graphics
In tikzDevice: R Graphics Output in LaTeX Format
Description
Details
Options That Affect Package Behavior
Font Size Calculations
Unicode
Author(s)
References
See Also
Description
The tikzDevice package implements the tikz ouput device which
generates R graphics in a LaTeX friendly format. LaTeX handles the
typesetting of all text in graphics generated by tikz. This allows for
seamless integration between these graphics and documents that are also being
typeset by LaTeX. Using LaTeX to generate graph text also means that
LaTeX mathematics can be typeset directly into labels and
annotations
Details
Package: tikzDevice
Type: Package
Version: 0.6.3
Date: 2011-11-13
License: GPL 2 or greater
LazyLoad: yes
Options That Affect Package Behavior
The tikzDevice package is currently influenced by a number of global
options that may be set in R scripts, from the R console or in a
.Rprofile file. All of the options can be set by using
options(<option> = <value>). These options allow for the use of
custom documentclass declarations, LaTeX packages, and typesetting
engines (e.g. XeLaTeX or LuaLaTeX). The defaults , if are any for a given
option, are shown below the description. The global options are:
tikzDefaultEngine-
Specifies which typesetting engine functions in the tikzDevice package
will prefer. Current possible values are pdftex, xetex or
luatex. Respectively, these values trigger the use of the
pdflatex, xelatex and lualatex compilers.
tikzLatex-
Specifies the location of the LaTeX compiler to be used by
tikzDevice. Setting this option may help the package locate a
missing compiler. The default is searched for when the package is loaded,
otherwise it can be set manually. This option may be set as follows:
options( tikzLatex = '/path/to/latex/compiler' ).
tikzXelatex-
Functions similar to tikzLatex, except this option specifies the
location of the XeLaTeX compiler.
tikzLualatex-
Functions similar to tikzLatex, except this option specifies the
location of the LuaLaTeX compiler.
tikzMetricsDictionary-
When using the graphics device provided by tikzDevice, you may
notice that R appears to “lag" or “hang" when commands such as
plot() are executed. This is because the device must query the
LaTeX compiler for string widths and font metrics. For a normal plot,
this may happen dozens or hundreds of times- hence R becomes
unresponsive for a while. The good news is that the tikz code is
designed to cache the results of these computations so they need only be
performed once for each string or character. By default, these values are
stored in a temporary cache file which is deleted when R is shut down.
A location for a permanent cache file may be specified by setting the
value of tikzMetricsDictionary in .Rprofile with
options(tikzMetricsDictionary = '/path/to/dictionary/location').
tikzDocumentDeclaration-
A string. The LaTeX documentclass declaration used in output files when
standAlone == TRUE. tikzDocumentDeclaration also influences
the calculation of font metrics. The default value is:
options(tikzDocumentDeclaration = "\\documentclass[10pt]{article}")
tikzLatexPackages-
A character vector. These are the packages which are included when using
the pdftex engine and tikz is used with the the
standAlone option as well as when font metrics are calculated.
tikzXelatexPackages-
This option works like tikzLatexPackages, except is is used when
the xetex engine is in use.
tikzLualatexPackages-
This option works like tikzXelatexPackages, except is is used when
the luatex engine is in use.
tikzFooter-
A character vector. The footer to be used only when
standAlone==TRUE.
tikzMetricPackages-
A character vector. These are the packages which are additionally loaded
when doing font metric calculations. As you see below, the font encoding
is set to Type 1. This is very important so that character codes of LaTeX
and R match up. The default value is:
options(tikzMetricPackages = c(
"\\usepackage[utf8]{inputenc}",
"\\usepackage[T1]{fontenc}",
"\\usetikzlibrary{calc}"
))
tikzUnicodeMetricPackages-
This vector is used when font metric calculations are performed using the
xetex or luatex engines. It should have the same contents
as tikzMetricPackages with the addition of the fontspec and
xunicode packages.
tikzSanitizeCharacters-
A character vector of special latex characters to replace. These values
should correspond to the replacement values from the
tikzReplacementCharacters option. See
sanitizeTexString for more details.
tikzReplacementCharacters-
A character vector of replacements for special latex characters. These
values should correspond to the values from the
tikzSanitizeCharacters option.
tikzRasterResolution-
When tikz is requested to add a raster to a graphic, the
raster is written to a PNG file which is then included into the LaTeX
code. This option controls the resolution (dpi) at which the PNG files
are created.
tikzPdftexWarnUTF-
A TRUE/FALSE value that controls whether warnings are printed if
Unicode characters are sent to a device using the pdftex engine.
Default values for all options may be viewed or restored using the
setTikzDefaults function.
Font Size Calculations
The overarching goal of the tikzDevice is to provide seamless
integration between text in R graphics and the text of LaTeX documents
that contain those graphics. In order to achieve this integration the device
must translate font sizes specified in R to corresponding font sizes in
LaTeX.
A major consideration is that font sizes in LaTeX are controlled by a “base
font size” that is specified at the beginning of the document; typically
10pt. Furthermore, LaTeX typically provides only a finite number of sizes
for each font. Fortunately, the TikZ graphics system allows text to be
resized using a scaling factor. The tikzDevice calculates this
scaling factor using three inputs:
The “base font size” specified when the graphics device is created.
The “character expansion factor” parameter, specified using the
cex argument to functions such as par.
The “font size” parameter, specified using the ps argument
to functions such as par or the fontsize argument to
functions such as gpar.
The tricky bit is the specification of the “base font size”. By default
the tikzDevice will attempt to determine this parameter by scaning the
value of options( "tikzDocumentDeclaration" ) using the regular
expression \d+[pt]. For the default header of:
1
2
\documentclass[10pt]{article}
This regular expression will return 10 as the base pointsize to be used by the
device. If the regular expression fails to produce a match, the value of the
pointsize argument to the tikz function will be used.
Unicode
Using tikzDevice functions on strings containing Unicode (multibyte)
characters requires special consideration. The primary reason for this is
that pdftex, the typesetting engine most commonly used to compile
LaTeX documents, has no native support for Unicode. Recently, two new engines
have become widely available that do support Unicode natively. These engines
are:
The xetex engine which has been a part of standard TeX
distributions since TeX Live 2007 and MiKTeX 2.7.
The luatex engine which is a direct sucessor to pdftex.
LuaTeX is still considered ‘beta’ software (as of spring 2012) but is very
stable and has been included in standard TeX distributions since TeX Live
2008 and MiKTeX 2.9.
As of Version 0.6.0, the tikzDevice package includes support for the
xetex engine provided a recent version of TeX Live or MiKTeX is
available. Support for the luatex engine was added in Version 0.7.0.
The tikzDevice defaults to using the pdftex engine, but this may be
changed by setting an option: option(tikzDefaultEngine = 'xetex').
When working with text that contains Unicode characters, we strongly
reccomend switching to the xetex or luatex engines. The package
will produce warning messages when multibyte characters are sent to the
pdftex engine. Users who find these warnings annoying may disable them
by setting options(tikzPdftexWarnUTF = FALSE) as it is possible to
send Unicode information to the pdftex engine with the following
caveats:
The task of determining the proper mix of LaTeX packages required to
supply glyphs for Unicode characters is left entirely up to the user.
options(tikzLatexPackages) may need to be customized in order to get
proper behavior.
The getLatexCharMetrics function will always return 0
for ascent, descent and width when passed a character code outside the
range 32–127 when using the pdftex engine.
When using the xetex or luatex engines, Unicode support is
enabled by loading the LaTeX packages fontspec and xunicode.
Using this setup, support for Unicode characters should be limited only by
the fonts used in the document. The font selection may be adjusted using
options(tikzXelatexPackages).
Author(s)
Cameron Bracken: cameron.bracken@gmail.com
Charlie Sharpsteen: source@sharpsteen.net
Submit bug reports to: tikzdevice-bugs@lists.r-forge.r-project.org
References
The TikZ and PGF Packages: Manual for version 2.00
http://sourceforge.net/projects/pgf
Till Tanatu, February 20, 2008
See Also
tikzDevice documentation built on May 2, 2019, 4:50 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Details Options That Affect Package Behavior Font Size Calculations Unicode Author(s) References See Also
Description
The tikzDevice package implements the tikz ouput device which
generates R graphics in a LaTeX friendly format. LaTeX handles the
typesetting of all text in graphics generated by tikz. This allows for
seamless integration between these graphics and documents that are also being
typeset by LaTeX. Using LaTeX to generate graph text also means that
LaTeX mathematics can be typeset directly into labels and
annotations
Details
| Package: | tikzDevice |
| Type: | Package |
| Version: | 0.6.3 |
| Date: | 2011-11-13 |
| License: | GPL 2 or greater |
| LazyLoad: | yes |
Options That Affect Package Behavior
The tikzDevice package is currently influenced by a number of global
options that may be set in R scripts, from the R console or in a
.Rprofile file. All of the options can be set by using
options(<option> = <value>). These options allow for the use of
custom documentclass declarations, LaTeX packages, and typesetting
engines (e.g. XeLaTeX or LuaLaTeX). The defaults , if are any for a given
option, are shown below the description. The global options are:
tikzDefaultEngine-
Specifies which typesetting engine functions in the tikzDevice package will prefer. Current possible values are
pdftex,xetexorluatex. Respectively, these values trigger the use of thepdflatex,xelatexandlualatexcompilers. tikzLatex-
Specifies the location of the LaTeX compiler to be used by tikzDevice. Setting this option may help the package locate a missing compiler. The default is searched for when the package is loaded, otherwise it can be set manually. This option may be set as follows:
options( tikzLatex = '/path/to/latex/compiler' ). tikzXelatex-
Functions similar to
tikzLatex, except this option specifies the location of the XeLaTeX compiler. tikzLualatex-
Functions similar to
tikzLatex, except this option specifies the location of the LuaLaTeX compiler. tikzMetricsDictionary-
When using the graphics device provided by tikzDevice, you may notice that R appears to “lag" or “hang" when commands such as
plot()are executed. This is because the device must query the LaTeX compiler for string widths and font metrics. For a normal plot, this may happen dozens or hundreds of times- hence R becomes unresponsive for a while. The good news is that thetikzcode is designed to cache the results of these computations so they need only be performed once for each string or character. By default, these values are stored in a temporary cache file which is deleted when R is shut down. A location for a permanent cache file may be specified by setting the value oftikzMetricsDictionaryin.Rprofilewithoptions(tikzMetricsDictionary = '/path/to/dictionary/location'). tikzDocumentDeclaration-
A string. The LaTeX documentclass declaration used in output files when
standAlone == TRUE.tikzDocumentDeclarationalso influences the calculation of font metrics. The default value is:options(tikzDocumentDeclaration = "\\documentclass[10pt]{article}") tikzLatexPackages-
A character vector. These are the packages which are included when using the
pdftexengine andtikzis used with the thestandAloneoption as well as when font metrics are calculated. tikzXelatexPackages-
This option works like
tikzLatexPackages, except is is used when thexetexengine is in use. tikzLualatexPackages-
This option works like
tikzXelatexPackages, except is is used when theluatexengine is in use. tikzFooter-
A character vector. The footer to be used only when
standAlone==TRUE. tikzMetricPackages-
A character vector. These are the packages which are additionally loaded when doing font metric calculations. As you see below, the font encoding is set to Type 1. This is very important so that character codes of LaTeX and R match up. The default value is:
options(tikzMetricPackages = c( "\\usepackage[utf8]{inputenc}", "\\usepackage[T1]{fontenc}", "\\usetikzlibrary{calc}" )) tikzUnicodeMetricPackages-
This vector is used when font metric calculations are performed using the
xetexorluatexengines. It should have the same contents astikzMetricPackageswith the addition of thefontspecandxunicodepackages. tikzSanitizeCharacters-
A character vector of special latex characters to replace. These values should correspond to the replacement values from the
tikzReplacementCharactersoption. SeesanitizeTexStringfor more details. tikzReplacementCharacters-
A character vector of replacements for special latex characters. These values should correspond to the values from the
tikzSanitizeCharactersoption. tikzRasterResolution-
When
tikzis requested to add a raster to a graphic, the raster is written to a PNG file which is then included into the LaTeX code. This option controls the resolution (dpi) at which the PNG files are created. tikzPdftexWarnUTF-
A
TRUE/FALSEvalue that controls whether warnings are printed if Unicode characters are sent to a device using thepdftexengine.
Default values for all options may be viewed or restored using the
setTikzDefaults function.
Font Size Calculations
The overarching goal of the tikzDevice is to provide seamless
integration between text in R graphics and the text of LaTeX documents
that contain those graphics. In order to achieve this integration the device
must translate font sizes specified in R to corresponding font sizes in
LaTeX.
A major consideration is that font sizes in LaTeX are controlled by a “base
font size” that is specified at the beginning of the document; typically
10pt. Furthermore, LaTeX typically provides only a finite number of sizes
for each font. Fortunately, the TikZ graphics system allows text to be
resized using a scaling factor. The tikzDevice calculates this
scaling factor using three inputs:
The “base font size” specified when the graphics device is created.
The “character expansion factor” parameter, specified using the
cexargument to functions such aspar.The “font size” parameter, specified using the
psargument to functions such asparor thefontsizeargument to functions such asgpar.
The tricky bit is the specification of the “base font size”. By default
the tikzDevice will attempt to determine this parameter by scaning the
value of options( "tikzDocumentDeclaration" ) using the regular
expression \d+[pt]. For the default header of:
1 2 | \documentclass[10pt]{article}
|
This regular expression will return 10 as the base pointsize to be used by the
device. If the regular expression fails to produce a match, the value of the
pointsize argument to the tikz function will be used.
Unicode
Using tikzDevice functions on strings containing Unicode (multibyte)
characters requires special consideration. The primary reason for this is
that pdftex, the typesetting engine most commonly used to compile
LaTeX documents, has no native support for Unicode. Recently, two new engines
have become widely available that do support Unicode natively. These engines
are:
The
xetexengine which has been a part of standard TeX distributions since TeX Live 2007 and MiKTeX 2.7.The
luatexengine which is a direct sucessor topdftex. LuaTeX is still considered ‘beta’ software (as of spring 2012) but is very stable and has been included in standard TeX distributions since TeX Live 2008 and MiKTeX 2.9.
As of Version 0.6.0, the tikzDevice package includes support for the
xetex engine provided a recent version of TeX Live or MiKTeX is
available. Support for the luatex engine was added in Version 0.7.0.
The tikzDevice defaults to using the pdftex engine, but this may be
changed by setting an option: option(tikzDefaultEngine = 'xetex').
When working with text that contains Unicode characters, we strongly
reccomend switching to the xetex or luatex engines. The package
will produce warning messages when multibyte characters are sent to the
pdftex engine. Users who find these warnings annoying may disable them
by setting options(tikzPdftexWarnUTF = FALSE) as it is possible to
send Unicode information to the pdftex engine with the following
caveats:
The task of determining the proper mix of LaTeX packages required to supply glyphs for Unicode characters is left entirely up to the user.
options(tikzLatexPackages)may need to be customized in order to get proper behavior.The
getLatexCharMetricsfunction will always return 0 for ascent, descent and width when passed a character code outside the range 32–127 when using thepdftexengine.
When using the xetex or luatex engines, Unicode support is
enabled by loading the LaTeX packages fontspec and xunicode.
Using this setup, support for Unicode characters should be limited only by
the fonts used in the document. The font selection may be adjusted using
options(tikzXelatexPackages).
Author(s)
Cameron Bracken: cameron.bracken@gmail.com
Charlie Sharpsteen: source@sharpsteen.net
Submit bug reports to: tikzdevice-bugs@lists.r-forge.r-project.org
References
The TikZ and PGF Packages: Manual for version 2.00
http://sourceforge.net/projects/pgf
Till Tanatu, February 20, 2008
See Also
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.