Stata 15 help for putpdf table

[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 ----------------------------------------------------


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index