Stata program to create a nicely formatted photobook from a list of image files
To always ensure you have the most up-to-date version, you can install the photobook
command directly from GitHub by using either of the two methods mentioned below in the Stata console window.
* method 1 - use Stata's net install command
net install photobook, ///
from("https://raw.githubusercontent.com/PovertyAction/photobook/master") ///
replace
* method 2 - use haghish's github command
github install PovertyAction/photobook
If you encounter a clear bug, please file a minimal reproducible example on github. For questions and other discussion, please email us at researchsupport@poverty-action.org.
The photobook
command is designed to work directly on data as exported by SurveyCTO. To run it you simply load your dataset into Stata and run photobook
on the media variable where photos were collected (e.g. if you programmed an image variable named respondent_photo
in your survey you would run photobook on this variable in the exported data). See below for example syntax.
* simple example with default settings
photobook respondent_photo using "myphotobook.pdf", replace
* add formatting
photobook respondent_photo using "myphotobook.pdf", ncol(5) bold allcaps landscape replace
The certification script of photobook
is cscript/test.do
. If you are new to certification scripts, you may find this Stata Journal article helpful.
Titlephotobook -- Create a nicely formatted photobook from a list of image files
photobook varname using filename [if] [in] [, options]
options Description ------------------------------------------------------------------------- Document pagesize(psize) set page size of document landscape set document orientation to landscape font(fspec) set font, font size, and font color margin(type, #[unit]) set page margins of document bgcolor(color) set background color replace specifies to overwrite filename, if it exists
Table * ncol(#) number of columns on a page border(bspec) set pattern and color for border title(string) add a title to the table note(string) add notes to the table
Caption * caption(varlist) list of variables to use to create caption separator(string) character to use as a separator when combining caption variables halign(hvalue) set horizontal alignment valign(vvalue) set vertical alignment 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
Image width(#) set image width height(#) set image height linebreak[(#)] add line breaks after image
------------------------------------------------------------------------- * Most commonly used options. by is allowed; see [D] by.
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.
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.
photobook creates a nicely formatted photobook from a list of image files stored in varname and saves them as a PDF.
With the revolution in mobile device technology and the growth of digital data collection software, it is increasingly easy for research projects to collect digital images. At IPA we often collect photos of respondents in order to facilitate tracking and to confirming their identity during subsuquent survey waves or during the administration of different interventions. However, we've found that processing large batches of image files into something usable by the field team is an arduous and time-consuming task.
photobook attempts to fill this need by making it easy to quickly create nicely-formatted PDFs of images arrayed in a tidy table with captions while also providing a suite of options to fully for power users to customize the look and feel. At IPA, we often use photobook to create tracking books with photos of participants as well as some of their basic demographic information. Enumerators use these during follow ups to help them find and verify respondents. However, the use of photobook is not necessarily restricted to this particular application. In theory it could be used in any application that involves merging a list of image files into a single PDF, e.g. creating inventories books from photo databases of store products.
+----------+ ----+ Document +---------------------------------------------------------
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.
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.
replace specifies to overwrite filename, if it exists, by the contents of the document in memory.
+-------+ ----+ Table +------------------------------------------------------------
ncol(#) sets the number of columns of images per page in the output photobook. By default this is set to 4 columns. Note that photobook attempts to resize all images appropriately but it is not always perfect. In these circumstances you may have to play with the width() and height() settings, the page size and margins, an the font sizes to get it right.
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.
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.
+---------+ ----+ Caption +----------------------------------------------------------
caption(varlist) specifies a list of variables whose contents are used to create a caption for each image. If no variables are specified no caption will be displayed.
separator(string) sets the character to be used to separate values of varlist when creating a caption using the caption(varlist) option. By default values will be separated by ",".
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).
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 photobook text overrides background color specifications from photobook begin and photobook 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.
+-------+ ----+ Image +------------------------------------------------------------
width(#) sets the width of the image in pixels. 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(#) sets the height of the image in pixels. 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.
Create a simple photobook (without captions) . use lfw_reduced . photobook file using "01/test01.pdf", replace
Same as the previous, but adds a caption using caption option . photobook file using "03/test03.pdf", cap(id name) replace
Christopher Boyer, Innovations for Poverty Action
For questions or suggestions, submit a GitHub issue or e-mail researchsupport@poverty-action.org.
Also see
Help: [D] putpdf