[P] putpdf -- Create a PDF file
Syntax
Create document for export
putpdf begin [, document_options]
Add paragraph to document
putpdf paragraph [, paragraph_options]
Add text to paragraph
putpdf text (exp) [, text_options]
Add image to paragraph
putpdf image filename [, image_options]
Add table to document
putpdf table tablename = (nrows, ncols) [, table_options]
putpdf table tablename = data(varlist) [if] [in] [, varnames obsno
table_options]
putpdf table tablename = matrix(matname) [, nformat(%fmt) rownames
colnames table_options]
putpdf table tablename = mata(matname) [, nformat(%fmt)
table_options]
putpdf table tablename = etable[(#1 #2 ... #n)] [, table_options]
putpdf table tablename = returnset [, table_options]
Add content to cell
putpdf table tablename(i,j) = (exp) [, cell_options]
putpdf table tablename(i,j) = image(filename) [, cell_options]
putpdf table tablename(i,j) = table(mem_tablename) [, cell_options]
Alter table layout
putpdf table tablename(i,.), row_col_options
putpdf table tablename(.,j), row_col_options
Customize format of cells or table
putpdf table tablename(i,j) [, cell_options]
putpdf table tablename(numlist_i,.)[, cell_fmt_options]
putpdf table tablename(.,numlist_j) [, cell_fmt_options]
putpdf table tablename(numlist_i,numlist_j), cell_fmt_options
putpdf table tablename(.,.), cell_fmt_options
Add page break to document
putpdf pagebreak
Add section break to document
putpdf sectionbreak [, section_options]
Describe current document
putpdf describe
Describe table
putpdf describe tablename
Close and save document
putpdf save filename [, replace]
Close without saving
putpdf clear
tablename specifies the name of a new table. The name must be a valid
name according to Stata's naming conventions; see [U] 11.3 Naming
conventions.
document_options Description
-------------------------------------------------------------------------
pagesize(psize) set page size of document
landscape set document orientation to landscape
font(fspec) set font, font size, and font color
halign(hvalue) set horizontal alignment of document
margin(type, #[unit]) set page margins of document
bgcolor(color) set background color
-------------------------------------------------------------------------
paragraph_options Description
-------------------------------------------------------------------------
font(fspec) set font, font size, and font color
halign(hvalue) set paragraph alignment
valign(vvalue) set vertical alignment of characters on
each line
indent(indenttype, #[unit]) set paragraph indentation
spacing(position, #[unit]) set spacing between lines of text
bgcolor(color) set background color
-------------------------------------------------------------------------
text_options Description
-------------------------------------------------------------------------
nformat(%fmt) specify numeric format for text
font(fspec) set font, font size, and font color
bold format text as bold
italic format text as italic
script(sub|super) set subscript or superscript formatting of
text
strikeout strikeout text
underline underline text
bgcolor(color) set background color
linebreak[(#)] add line breaks after text
allcaps format text as all caps
-------------------------------------------------------------------------
image_options Description
-------------------------------------------------------------------------
width(#[unit]) set image width
height(#[unit]) set image height
linebreak[(#)] add line breaks after image
-------------------------------------------------------------------------
table_options Description
-------------------------------------------------------------------------
memtable keep table in memory rather than add it to
document
width(#[unit|%] | matname) set table width
halign(hvalue) set table horizontal alignment
indent(#[unit) set table indentation
spacing(position, #[unit]) set spacing before or after table
border(bspec) set pattern and color for border
title(string) add a title to the table
note(string) add notes to the table
-------------------------------------------------------------------------
cell_options Description
-------------------------------------------------------------------------
append append objects to current content of cell
rowspan(#) merge cells vertically
colspan(#) merge cells horizontally
span(#1, #2) merge cells both horizontally and
vertically
linebreak[(#)] add line breaks into the cell
cell_fmt_options options that control the look of cell
contents
-------------------------------------------------------------------------
row_col_options Description
-------------------------------------------------------------------------
nosplit prevent row from breaking across pages
addrows(# [, before|after]) add # rows in specified location
addcols(# [, before|after]) add # columns in specified location
drop drop specified row or column
cell_fmt_options options that control the look of cell
contents
-------------------------------------------------------------------------
cell_fmt_options Description
-------------------------------------------------------------------------
margin(type, #[unit]) set margins
halign(hvalue) set horizontal alignment
valign(vvalue) set vertical alignment
border(bspec) set pattern and color for border
bgcolor(color) set background color
nformat(%fmt) specify numeric format for cell text
font(fspec) set font, font size, and font color
bold format text as bold
italic format text as italic
* script(sub|super) set subscript or superscript formatting of
text
strikeout strikeout text
underline underline text
allcaps format text as all caps
-------------------------------------------------------------------------
* May only be specified when formatting a single cell.
section_options Description
-------------------------------------------------------------------------
pagesize(psize) set page size of section
landscape set section orientation to landscape
font(fspec) set font, font size, and font color
halign(hvalue) set horizontal alignment of section
margin(type, #[unit]) set page margins of section
bgcolor(color) set background color
-------------------------------------------------------------------------
fspec is
fontname [, size [, color]]
fontname may be any supported font installed on the user's
computer. Base 14 fonts, Type 1 fonts, and TrueType fonts with
an extension of .ttf and .ttc are supported. TrueType fonts that
cannot be embedded may not used. If fontname includes spaces,
then it must be enclosed in double quotes. The default font is
Helvetica.
size is a numeric value that represents font size measured in
points. The default is 11.
color sets the text color.
bspec is
bordername[, bpattern [, bcolor]]
bordername specifies the location of the border.
bpattern is a keyword specifying the look of the border.
Possible patterns are nil and single. The default is single. To
remove an existing border, specify nil as the bpattern.
bcolor specifies the border color.
unit may be in (inch), pt (point), cm (centimeter), or twip (twentieth of
a point). An inch is equivalent to 72 points, 2.54 centimeters, or
1440 twips. The default is in.
color and bcolor may be one of the colors listed in the table of colors
in the Appendix; a valid RGB value in the form ### ### ###, for
example, 171 248 103; or a valid RRGGBB hex value in the form ######,
for example, ABF867.
Output types for tables
The following output types are supported when creating a new table using
putpdf table tablename:
(nrows, ncols) creates an empty table with nrows rows and ncols
columns. A maximum of 50 columns in a table is allowed.
data(varlist) [if] [in] [, varnames obsno] adds the current Stata
dataset in memory as a table to the active document. varlist
contains a list of the variable names from the current dataset in
memory.
matrix(matname) [, nformat(%fmt) rownames colnames] adds a matrix
called matname as a table to the active document. The elements
of the matrix are formatted using %fmt. If nformat() is not
specified, then %12.0g is used.
mata(matname) [, nformat(%fmt)] adds a Mata matrix called matname as
a table to the active document. The elements of the matrix are
formatted using %fmt. If nformat() is not specified, then %12.0g
is used.
etable[(#1 #2 ... #n) adds an automatically generated table to the
active document. The table may be derived from the coefficient
table of the last estimation command, from the table of margins
after the last margins command, or from the table of results from
one or more models displayed by estimates table.
Note that if the estimation command outputs n > 1 coefficient
tables, the default is to add all tables and assign the
corresponding table names tablename1, tablename2, ...,
tablename_n. To specify which tables to add, supply the optional
numlist to etable. For example, to add the first and third
tables from the estimation output, specify etable(1 3). A few
estimation commands do not support the etable output type. See
Unsupported estimation commands in [P] putdocx for a list of
estimation commands that are not supported by putpdf.
returnset exports a group of Stata return values to a table in the
active document. It is intended primarily for use by programmers
and by those who want to do further processing of their exported
results in the active document. returnset may be one of the
following:
returnset Description
---------------------------------------------------------
escalars All ereturned scalars
rscalars All returned scalars
emacros All ereturned macros
rmacros All returned macros
ematrices All ereturned matrices
rmatrices All returned matrices
e* All ereturned scalars, macros, and matrices
r* All returned scalars, macros, and matrices
---------------------------------------------------------
The following output types are supported when adding content to an
existing table using putpdf table tablename(i, j):
(exp) writes a valid Stata expression to a cell. See [U] 13 Functions
and expressions.
image filename adds a portable network graphics (.png) or JPEG (.jpg)
file to the table cell. filename is the path to the image file.
It may be either the full path or the relative path from the
current working directory.
table(mem_tablename) adds a previously created table, identified by
mem_tablename, to the table cell.
The following combinations of tablename(numlist_i,numlist_j) (see [U]
11.1.8 numlist for valid specifications) can be used to format a cell
or range of cells in an existing table:
tablename(i,j) specifies the cell on the ith row and jth column.
tablename(i,.) and tablename(numlist_i,.) specify all cells on the
ith row or on the rows identified by numlist_i.
tablename(.,j) and tablename(.,numlist_j) specify all cells in the
jth column or in the columns identified by numlist_j.
tablename(.,.) specifies the whole table.
Description
putpdf writes paragraphs, images, and tables to a PDF file. It may also
be used to format each object added. This allows you to automate
exporting and formatting of, for example, Stata estimation results and
also generate various reports based on those results. Below, we provide
a summary of the commands to add and format the content of a PDF file.
putpdf begin creates the PDF file for export.
putpdf paragraph adds a new paragraph to the active document. The
newly created paragraph becomes the active paragraph. All
subsequent text or images will be appended to the active
paragraph.
putpdf text (exp) adds content to the paragraph created by putpdf
paragraph. exp may be a valid Stata expression (see [U] 13
Functions and expressions) or a normal string.
putpdf image filename embeds a portable network graphics (.png) or
JPEG (.jpg) file in the paragraph. filename is the path to the
image file. It may be either the full path or the relative path
from the current working directory.
putpdf table tablename creates a new table that can be identified by
its assigned name, tablename, for future modifications. Tables
may be created from several output types, including the data in
memory, matrices, and estimation results; see Output types for
tables for a complete list and a description of each type.
putpdf pagebreak adds a page break to the document, placing
subsequent content on the next page of the document.
putpdf sectionbreak adds a new section to the active document that
starts on the next page. It lets you vary the page size,
orientation, margins, and other properties of the pages within a
single document. This formatting of sections is most useful when
you want to mix portrait and landscape layouts.
putpdf describe describes the current PDF file or a table within the
current PDF file.
putpdf save closes and saves the PDF file.
putpdf clear closes the PDF file without saving the changes.
Options
Options are presented under the following headings:
Options for putpdf begin
Options for putpdf paragraph
Options for putpdf text
Options for putpdf image
Options for putpdf table
table_options
cell_options
row_col_options
cell_fmt_options
Options for putpdf sectionbreak
Option for putpdf save
Options for putpdf begin
pagesize(psize) sets the page size of the document. psize may be letter,
legal, A3, A4, A5, B4, or B5. The default is pagesize(letter).
landscape changes the document orientation from portrait to landscape.
font(fontname[, size[, color]]) sets the font, font size, and font color
for the document. Note that the font size and font color may be
specified individually without specifying fontname. Use font("",
size) to specify font size only. Use font("", "", color) to specify
font color only. For both cases, the default font will be used.
halign(hvalue) sets the horizontal alignment of the paragraphs, images,
and tables. hvalue may be left, right, or center. The default is
halign(left).
margin(type, #[unit]) sets the page margins of the document. type may be
top, left, bottom, or right, which identify the location of the
margin inside the document. The margin value # is measured in inches
unless another unit is specified. This option may be specified
multiple times in a single command to account for different margin
settings.
bgcolor(color) sets the background color for the document.
Options for putpdf paragraph
font(fontname[, size[, color]]) sets the font, font size, and font color
for the text within the paragraph. Note that the font size and font
color may be specified individually without specifying fontname. Use
font("", size) to specify font size only. Use font("", "", color) to
specify font color only. For both cases, the default font will be
used.
Specifying font() with putpdf paragraph overrides font settings
specified with putpdf begin.
halign(hvalue) sets the horizontal alignment of the text within the
paragraph. hvalue may be left, right, center, justified, or
distribute. distribute and justified justify text between the left
and right margins equally, but distribute also changes the spacing
between words and characters. The default is halign(left).
valign(vvalue) sets the vertical alignment of the characters on each line
when the paragraph contains characters of varying size. vvalue may
be baseline, bottom, center, or top. The default is
valign(baseline).
indent(indenttype, #[unit]) specifies that the paragraph be indented by #
units. indenttype may be left, right, or para. left and right
indent # units from the left or the right, respectively. para uses
standard paragraph indentation and indents the first line by # inches
unless another unit is specified. This option may be specified
multiple times in a single command to accommodate different
indentation settings.
spacing(position, #[unit]) sets the spacing between lines of text.
position may be before, after, or line. before specifies the space
before the first line of the current paragraph, after specifies the
space after the last line of the current paragraph, and line
specifies the space between lines within the current paragraph. This
option may be specified multiple times in a single command to
accommodate different spacing settings.
bgcolor(color) sets the background color for the paragraph.
Specifying bgcolor() with putpdf paragraph overrides background color
specifications from putpdf begin.
Options for putpdf text
nformat(%fmt) specifies the numeric format of the text when the content
of the new text appended to the paragraph is a numeric value. This
setting has no effect when the content is a string.
font(fontname[, size[, color]]) sets the font, font size, and font color
for the new text within the active paragraph. Note that the font
size and font color may be specified individually without specifying
fontname. Use font("", size) to specify font size only. Use
font("", "", color) to specify font color only. For both cases, the
default font will be used.
Specifying font() with putpdf text overrides all other font settings,
including those specified with putpdf begin and putpdf paragraph.
bold specifies that the new text in the active paragraph be formatted as
bold.
italic specifies that the new text in the active paragraph be formatted
as italic.
script(sub|super) changes the script style of the new text. script(sub)
makes the text a subscript. script(super) makes the text a
superscript.
strikeout specifies that the new text in the active paragraph have a
strikeout mark.
underline specifies that the new text in the active paragraph be
underlined.
bgcolor(color) sets the background color for the active paragraph.
Specifying bgcolor() with putpdf text overrides background color
specifications from putpdf begin and putpdf paragraph.
linebreak[(#)] specifies that one or # line breaks be added after the new
text.
allcaps specifies that all letters of the new text in the active
paragraph be capitalized.
Options for putpdf image
width(#[unit]) sets the width of the image. If the width is larger than
the body width of the document, then the body width is used. If
width() is not specified, then the default size is used; the default
is determined by the image information and the body width of the
document.
height(#[unit]) sets the height of the image. If height() is not
specified, then the height of the image is determined by the width
and the aspect ratio of the image.
linebreak[(#)] specifies that one or # line breaks be added after the new
image.
Options for putpdf table
table_options
memtable specifies that the table be created and held in memory instead
of being added to the active document. By default, the table is
added to the document immediately after it is created. This option
is useful if the table is intended to be added to a cell of another
table or to be used multiple times later.
width(#[unit|%]) and width(matname) set the table width. Any two of the
types of width specifications can be combined.
width(#[unit|%]) sets the width based on a specified value. # may be
an absolute width or a percent of the default table width, which is
determined by the page width of the document. For example,
width(50%) sets the table width to 50% of the default table width.
The default is width(100%).
width(matname) sets the table width based on the dimensions specified
in the Stata matrix matname, which has contents in the form of (#1,
#2, ..., #n) to denote the percent of the default table width for
each column. n is the number of columns of the table, and the sum of
#1 to #n must be equal to 100.
halign(hvalue) sets the horizontal alignment of the table within the
page. hvalue may be left, right, or center. The default is
halign(left).
indent(#[unit]) specifies the table indentation from the left margin of
the current document.
spacing(position, #[unit]) sets the spacing before or after the table.
position may be before or after. before specifies the space before
the top of the current table, and after specifies the space after the
bottom of the current table. This option may be specified multiple
times in a single command to account for different space settings.
border(bordername [, bpattern [, bcolor]]) adds a single border in the
location specified by bordername, which may be start, end, top,
bottom, insideH (inside horizontal borders), insideV (inside vertical
borders), or all. Optionally, you may change the pattern and color
for the border by specifying bpattern and bcolor.
This option may be specified multiple times in a single command to
accommodate different border settings. If multiple border() options
are specified, they are applied in the order specified from left to
right.
varnames specifies that the variable names be included as the first row
in the table when the table is created using the dataset in memory.
By default, only the data values are added to the table.
obsno specifies that the observation numbers be included as the first
column in the table when the table is created using the dataset in
memory. By default, only the data values are added to the table.
nformat(%fmt) specifies the numeric format to be applied to the source
values when creating the table from a Stata or Mata matrix. The
default is nformat(%12.0g).
rownames specifies that the row names of the Stata matrix be included as
the first column in the table. By default, only the matrix values
are added to the table.
colnames specifies that the column names of the Stata matrix be included
as the first row in the table. By default, only the matrix values
are added to the table.
title(string) inserts a row without borders above the current table. The
added row spans all the columns of the table and contains string as
text. The added row shifts all other table contents down by one row.
You should account for this when referencing table cells in
subsequent commands.
note(string) inserts a row without borders to the bottom of the table.
The added row spans all the columns of the table. This option may be
specified multiple times in a single command to add notes on new
lines within the same cell. Note text is inserted in the order it
was specified from left to right.
cell_options
append specifies that the new content for the cell be appended to the
current content of the cell. If append is not specified, then the
current content of the cell is replaced by the new content. Unlike
with the [P] putdocx command, this option with putpdf is used only
for appending a new string to the cell when the original cell content
is also a string.
rowspan(#) sets the specified cell to span vertically # cells downward.
If the span exceeds the total number of rows in the table, the span
stops at the last row.
colspan(#) sets the specified cell to span horizontally # cells to the
right. If the span exceeds the total number of columns in the table,
the span stops at the last column.
span(#1, #2) sets the specified cell to span #1 cells downward and span
#2 cells to the right.
linebreak[(#)] specifies that one or # line breaks be added after the
text within the cell.
row_col_options
nosplit specifies that row i not split across pages. When a table row is
displayed, a page break may fall within the contents of a cell on the
row, causing the contents of that cell to be displayed across two
pages. nosplit prevents this behavior. If the entire row cannot fit
on the current page, the row will be moved to the start of the next
page.
addrows(#[, before|after]) adds # rows to the current table before or
after row i. If before is specified, the rows are added before the
specified row. By default, rows are added after the specified row.
addcols(#[, before|after]) adds # columns to the current table to the
right or the left of column j. If before is specified, the columns
are added to the left of the specified column. By default, the
columns are added after, or to the right of, the specified column.
drop deletes row i or column j from the table.
cell_fmt_options
margin(type, #[unit]) sets the margins inside the cells in row i or
column j. type may be top, left, bottom, or right, which identify
the top margin, left margin, bottom margin, or right margin of the
cell, respectively. This option may be specified multiple times in a
single command to account for different margin settings.
halign(hvalue) sets the horizontal alignment of the cells in row i or
column j. hvalue may be left, right, or center. The default is
halign(left).
valign(vvalue) sets the vertical alignment of the cells in row i or
column j. vvalue may be top, bottom, or center. The default is
valign(top).
border(bordername [, bpattern [, bcolor]]) adds a single border to all
cells in a given row or column in the location specified by
bordername, which may be start, end, top, bottom, or all. Optionally,
you may change the pattern and color for the border by specifying
bpattern and bcolor.
This option may be specified multiple times in a single command to
accommodate different border settings. If multiple border() options
are specified, they are applied in the order specified from left to
right.
bgcolor(color) sets the background color for the specified cell or for
all cells in the specified row, column, or range.
nformat(%fmt) applies the Stata numeric format %fmt to the text within
the specified cell or within all cells in the specified row, column,
or range. This setting only applies when the content of the cell is
a numeric value.
font(fontname[, size[, color]]) sets the font, font size, and font color
for the text within the row or column. Note that the font size and
font color may be specified individually without specifying fontname.
Use font("", size) to specify font size only. Use font("", "",
color) to specify font color only. For both cases, the default font
will be used.
bold specifies that the cell text in the row or column be formatted as
bold.
italic specifies that the cell text in the row or column be formatted as
italic.
script(sub|super) changes the script style of the text. script(sub)
makes the text a subscript. script(super) makes the text a
superscript. script() may only be specified when formatting a single
cell.
strikeout specifies that the cell text in the row or column have a
strikeout mark.
underline specifies that the cell text in the row or column be
underlined.
allcaps uses capital letters for all letters of the current text within
the specified cell or within all cells in the specified row, column,
or range.
Options for putpdf sectionbreak
pagesize(psize) sets the page size of the section. psize may be letter,
legal, A3, A4, A5, B4, or B5. The default is pagesize(letter).
landscape changes the section orientation from portrait to landscape.
font(fontname[, size[, color]]) sets the font, font size, and font color
for the section. Note that the font size and font color may be
specified individually without specifying fontname. Use font("",
size) to specify font size only. Use font("", "", color) to specify
font color only. For both cases, the default font will be used.
halign(hvalue) sets the horizontal alignment of the paragraphs, images,
and tables within the section. hvalue may be left, right, or center.
The default is halign(left).
margin(type, #[unit]) sets the page margins of the section. type may be
top, left, bottom, or right, which identify the location of the
margin inside the section. The margin value # is measured in inches
unless another unit is specified. This option may be specified
multiple times in a single command to account for different margin
settings.
bgcolor(color) sets the background color for the section.
Option for putpdf save
replace specifies to overwrite filename, if it exists, by the contents of
the document in memory.
Examples
Setup
. sysuse auto
Create the .pdf document in memory
. putpdf begin
Use summarize to obtain summary statistics on mpg
. summarize mpg
Add a new paragraph to the active document and append text to it
. putpdf paragraph
. putpdf text ("In this dataset, there are `r(N)' models")
. putpdf text (" of automobiles. The maximum MPG among them is ")
. putpdf text (r(max)), bold
. putpdf text (".")
putpdf text can be used to break long sentences into pieces, and each
piece in the paragraph can be customized to have a different style.
Above, r(max) is formatted as bold.
Create a scatterplot and export the graph as a .png file
. scatter mpg price
. graph export auto.png
Add the .png file to the to the document in a new paragraph that is
centered horizontally
. putpdf paragraph, halign(center)
. putpdf image auto.png, width(4)
Fit a linear regression model of mpg as a function of weight and foreign
. regress mpg weight foreign
Export the estimation results to the document as a table with the name
tbl1
. putpdf table tbl1 = etable, width(100%)
Keep only the point estimates and confidence intervals
. putpdf table tbl1(.,5), drop
. putpdf table tbl1(.,4), drop
. putpdf table tbl1(.,3), drop
Modify the column headings to omit the dependent variable name
. putpdf table tbl1(1,2) = ("")
Export the first 15 observations of the make, price, and mpg variables
from the dataset in memory
. putpdf table tbl1 = data("make price mpg") in 1/15, varnames
Save the document to disk
. putpdf save example.pdf
Stored results
putpdf describe tablename stores the following in r():
Scalars
r(nrows) number of rows in the table
r(ncols) number of columns in the table
Appendix
Colors
color
----------------------------------------------------
aliceblue ghostwhite navajowhite
antiquewhite gold navy
aqua goldenrod oldlace
aquamarine gray olive
azure green olivedrab
beige greenyellow orange
bisque honeydew orangered
black hotpink orchid
blanchedalmond indianred palegoldenrod
blue indigo palegreen
blueviolet ivory paleturquoise
brown khaki palevioletred
burlywood lavender papayawhip
cadetblue lavenderblush peachpuff
chartreuse lawngreen peru
chocolate lemonchiffon pink
coral lightblue plum
cornflowerblue lightcoral powderblue
cornsilk lightcyan purple
crimson lightgoldenrodyellow red
cyan lightgray rosybrown
darkblue lightgreen royalblue
darkcyan lightpink saddlebrown
darkgoldenrod lightsalmon salmon
darkgray lightseagreen sandybrown
darkgreen lightskyblue seagreen
darkkhaki lightslategray seashell
darkmagenta lightsteelblue sienna
darkolivegreen lightyellow silver
darkorange lime skyblue
darkorchid limegreen slateblue
darkred linen slategray
darksalmon magenta snow
darkseagreen maroon springgreen
darkslateblue mediumaquamarine steelblue
darkslategray mediumblue tan
darkturquoise mediumorchid teal
darkviolet mediumpurple thistle
deeppink mediumseagreen tomato
deepskyblue mediumslateblue turquoise
dimgray mediumspringgreen violet
dodgerblue mediumturquoise wheat
firebrick mediumvioletred white
floralwhite midnightblue whitesmoke
forestgreen mintcream yellow
fuchsia mistyrose yellowgreen
gainsboro moccasin
----------------------------------------------------
