help for ltop (Roger Newson)

Divide a dataset into pages without splitting internal by-groups

ltop newvarname [if] [in] [weight] ,
[
maxlperp(#)
by(varlist) iby(varlist)
]

fweights, pweights, aweights, and iweights are allowed for ltop;
see weight.

Description

ltop ("lines to pages") creates a page-number variable,
dividing the dataset (or its by-groups)
into pages, with a maximum number of lines
per page,
optionally with internal by-groups which will not be split between pages.
ltop is designed for use when outputting datasets to multi-page tables,
using the SSC packages
chardef, listtab, and docxtab.
The user may weight pages, in case different font sizes are to be used,
or in case the first line of each internal by-group is preceded by a gap line.

Options

maxlperp(#) specifies a maximum number of lines per page,
or a maximum sum of line weights per page,
if weights are specified..
It defaults to 50 lines, but should probably usually be set by the user.

by(varlist) specifies a list of external by-variables,
defining external by-groups within which the generated page numbers are evaluated.
If by() is not set, then ltop uses 1 by-group,
which is the whole current dataset,
or the subset of the current dataset specified by the if and/or in qualifiers.

iby(varlist) specifies a list of internal by-variables,
defining internal by-groups for the generated page numbers.
These internal by-groups will not be split between pages.
If at least 1 internal by-group has a number of lines
(or sum of line weights) greater than the maxperp() option,
then ltop will fail, and tell the user that this is the case.

Remarks

The ltop package is designed for use with the SSC packages
chardef, listtab, and docxtab,
to create multi-page tables in multiple formats,
including Markdown,
plain TeX, LaTeX or HTML (using listtab),
or in a .docx document created using putdocx
(using docxtab).
For more about the use of chardef and listtab to make tables,
see Newson, 2012.

Examples

The following example uses the auto dataset,
distributed with Stata,
to create a multi-page table of weight and mileage in the car models,
with a limit of 16 table rows per page,
ordered alphabetically by car model,
and with all the models from each firm in the same table page.

Set-up auto data and sort by firm and make:

. sysuse auto, clear

. gene firm=word(make,1)

. lab var firm "Firm"

. sort firm make

. describe, full

. tab firm, miss

Create page number variable mypage:

. ltop mypage, iby(firm) maxlperp(16)

. list firm make weight mpg mypage, sepby(mypage)

Create Markdown document mymddoc1.md with multi-page table
using a capture noisily group
and the SSC packages chardef and listtab:

. tempname mdb1

. file open `mdb1' using `"mymddoc1.md"', write replace

. capture noisily {

. file write `mdb1' "# Table of weight and mileage of cars in the auto data by firm" _n

. chardef make weight mpg, char(varname) pref(*) suff(*) val("Car model" "Weight (US pounds)" "Mileage (mpg)")

. chardef make weight mpg, char(halign) val(":---" "---:" "---:")

. levelsof mypage, lo(mypages)

. foreach MP of num `mypages' {

. preserve

. keep if mypage==`MP'

. file write `mdb1' "## Car weight and mileage by firm, Page `MP'" _n

. listtab make weight mpg, handle(`mdb1') rstyle(markdown) headc(varname halign) type

. restore

. }

. }

. file close `mdb1'

Convert Markdown document mymddoc.md to HTML document mymddoc.htm:

. markdown mymddoc1.md, saving(mymddoc1.htm) replace

For more about capture noisily groups,
see Newson, 2017.
For more about the SSC packages listtab and chardef,
and their role in making tables with header labels,
see Newson, 2012.

Alternatively, we could have used the SSC packages chardef and docxtab,
with the putdocx utility,
to make a .docx file containing multi-page tables with real pages,
each with a page number and a page count,
suitable for printing to hardcopy.
The program to do this would be a bit more complicated.

Author

Roger Newson, King's College London, UK.
Email: roger.newson@kcl.ac.uk

References

Newson, R. B. 2012.
From resultssets to resultstables in Stata.
The Stata Journal 12 (2): 191-213.
Download from The Stata Journal website.

Newson, R. B. 2017.
Stata Tip 127: Use capture noisily groups.
The Stata Journal 17 (2): 511-514.
Download from The Stata Journal website.

Also see

Manual: [U] weight, [P] capture

Help: [U] weight, [P] capture

On-line: help for chardef, listtab, docxtab if installed