Chapter 2: Return Values, Macros, and Output Programs

Learning Objectives

By the end of this chapter, students will be able to:

• Create and manage log files for documenting Stata sessions
• Access and manipulate return values from statistical commands
• Format p-values according to academic publication standards
• Create and save datasets programmatically using postfile
• Generate professional documents in multiple formats (.docx, .html, .dta)
• Embed dynamic results in academic manuscripts

2.1 Introduction to Output Management

Statistical analysis is only as valuable as its documentation and presentation. Stata provides multiple pathways for capturing, formatting, and presenting results. This chapter introduces three fundamental approaches:

1. Log files - Session documentation and result capture
2. Dataset creation - Programmatic data generation and storage
3. Dynamic documents - Automated report generation with embedded results

2.2 Log Files: Session Documentation

2.2.1 Creating and Managing Log Files

Log files serve as permanent records of your Stata session, capturing both commands and their output. This is essential for reproducible research and debugging.

Basic Syntax:

log using filename.log, replace
// Your analysis commands here
log close

Key Points:

• The replace option overwrites existing log files
• Log files capture everything displayed in the Results window
• Always close log files when finished to ensure proper saving

2.2.2 Practical Example: Chi-Square Analysis

Consider this analysis of transplant diagnoses by gender:

log using chi2.log, replace 
use transplants
tab dx gender, row chi2

Interpreting the Output:

• The crosstab shows frequency and row percentages
• Pearson chi-square test: χ²(8) = 18.48, p = 0.018
• Results suggest significant association between diagnosis and gender

2.2.3 Working with Return Values

After running statistical commands, Stata stores results in memory that can be accessed programmatically.

Viewing Return Values:

return list

Common Return Values:

• r(N) - Number of observations
• r(chi2) - Chi-square statistic
• r(p) - P-value
• r(r) - Number of rows
• r(c) - Number of columns

2.2.4 Professional P-Value Formatting

Academic publications require specific p-value formatting conventions. Here's a professional approach:

return list 
qui {
    if r(p) < 0.01 {
        local p: di "p < 0.01"
    }
    else if inrange(r(p),0.01,0.05) {
        local p: di %3.2f r(p)
    }
    else {
        local p: di %2.1f r(p)
    }
    noi di "p = `p'"
}

Formatting Rules:

• p < 0.01: Report as "p < 0.01"
• 0.01 ≤ p < 0.05: Report to 2 decimal places
• p ≥ 0.05: Report to 1 decimal place

2.3 Creating Datasets Programmatically (.dta files)

2.3.1 The Postfile System

The postfile system allows you to create datasets programmatically, which is useful for:

• Storing simulation results
• Creating summary tables
• Building datasets from computed values

2.3.2 Basic Postfile Workflow

cls
clear 
postutil clear 
postfile pp str80 a float(b c) using output.dta, replace 
post pp ("1") (24.4) (123)
post pp ("2") (31.5) (164)
post pp ("3") (29.0) (118)
postclose pp

use output, clear 
list

Command Breakdown:

1. postfile - Define the structure and filename
2. post - Add observations to the dataset
3. postclose - Finalize and save the dataset
4. use - Load the created dataset for verification

Variable Types:

• str80 - String variable with maximum 80 characters
• float - Numeric variable with floating-point precision

2.4 Dynamic Document Generation

2.4.1 Introduction to putdocx

The putdocx command enables creation of Microsoft Word documents with embedded Stata results, facilitating professional report generation.

2.4.2 Basic Document Structure

putdocx clear
putdocx begin
putdocx paragraph
putdocx text ("Document Title")
putdocx paragraph
putdocx text ("Author Information")
// Add content...
putdocx save document.docx, replace

2.4.3 Professional Academic Format

The example demonstrates creating a research abstract with embedded results:

Document Sections:

• Background - Context and rationale
• Methods - Analytical approach and data description
• Results - Key findings with embedded statistics
• Conclusions - Implications and generalizations

Key Features:

• Plain text integration with statistical results
• Professional formatting for academic submission
• Reproducible document generation

2.5 Advanced Output: HTML Generation

2.5.1 Dynamic HTML Documents

HTML output enables web-based publication and sharing of results. The dyndoc command processes markdown-formatted do-files into HTML documents.

Workflow:

1. Create a do-file with markdown formatting
2. Add CSS styling files for aesthetics
3. Use dyndoc filename.do, saving(filename.html) replace

2.5.2 Markdown Integration

Special Markup Elements:

• <<dd_version: 2>> - Document version specification
• <<dd_do:nooutput>> - Execute code without showing output
• <</dd_do>> - End code block
• <<dd_display: c(N)>> - Display system values

2.5.3 Mathematical Notation

HTML documents support LaTeX mathematical notation:

• $Y = \beta_0 + \beta_1 X$ - Inline equations
• Subscripts and Greek letters render properly
• Professional mathematical presentation

2.6 Best Practices and Integration

2.6.1 Workflow Recommendations

1. Always use log files for session documentation
2. Store intermediate results using postfile when appropriate
3. Format p-values consistently using conditional logic
4. Choose output format based on final use:
   • .log for session records
   • .dta for data storage
   • .docx for traditional manuscripts
   • .html for web publication

2.6.2 Quality Assurance

• Verify results by examining created files
• Test formatting before final production
• Maintain consistent naming conventions
• Document your process for reproducibility

2.6.3 Advanced Applications

These techniques can be extended to:

• Automated report generation
• Batch processing of multiple datasets
• Integration with version control systems
• Custom table and figure generation

2.7 Summary

This chapter introduced three fundamental approaches to managing Stata output:

1. Log files provide comprehensive session documentation
2. Postfile systems enable programmatic dataset creation
3. Dynamic documents automate professional report generation

These tools form the foundation for reproducible research and professional statistical reporting. Master these techniques to enhance your analytical workflow and improve the quality of your statistical communications.

2.8 Practice Exercises

1. Create a log file documenting a basic descriptive analysis
2. Build a dataset using postfile containing summary statistics
3. Generate a Word document with embedded statistical results
4. Format p-values from multiple statistical tests using conditional logic
5. Create an HTML report with mathematical notation and embedded graphs