Bridging Code and Document: Insights into LaTeX + Python Workflows#

Why Merge LaTeX and Python?#

• Reproducible Research: Scientists and researchers strive to keep computations reproducible. If the raw results, plots, and tables in a paper are all generated by Python, embedding that directly in LaTeX ensures your final paper is always in sync with the latest data.
• Automation: If you have to generate multiple documents—like identical reports for different clients—combining Python scripts with a LaTeX template can automate this repetitive process.
• Professional Appearance: LaTeX excels at neatly typesetting equations, references, images, and tables in a uniform and high-quality format. Automating figure generation via Python deepens your productivity.

Example Use Cases#

• Academic Theses or Research Papers with integrated statistical analysis, simulations, or machine learning insights.
• Technical documentation that needs up-to-date code snippets and outputs.
• Corporate reporting that leverages data insights, with mass-generation of customized PDF reports.

Throughout the rest of this blog post, you will see several references and examples that make it easier to wield LaTeX and Python effectively.

Example of a Minimal LaTeX Document#

1
\documentclass{article}
2

3
\usepackage[utf8]{inputenc}  % Support for UTF-8 encoding
4
\usepackage{amsmath}         % Math enhancements
5
\usepackage{graphicx}        % Handling images
6

7
\begin{document}
8

9
\title{My Awesome Document}
10
\author{Jane Doe}
11
\date{\today}
12

13
\maketitle
14

15
\section{Introduction}
16
This is a minimal LaTeX document.
17

18
\section{Mathematical Example}
19
We can write an equation as:
20
\[
21
E = mc^2
22
\]
23

24
\end{document}

Compiling the above with pdflatex produces a simple PDF. Once you gain comfort with these basics, you can start looking into bridging Python outputs into this workflow.

Inclusion of Code Snippets#

You can simply copy and paste your Python code into a verbatim environment in LaTeX:

1
\begin{verbatim}
2
def fibonacci(n):
3
    a, b = 0, 1
4
    for i in range(n):
5
        print(a)
6
        a, b = b, a + b
7
\end{verbatim}

However, verbatim lacks syntax highlighting. There are advanced approaches—such as the minted or listings packages—that enable syntax highlighting and line numbering.

Generating Tables and Figures Dynamically#

Using Python, you might generate a CSV file or a set of values that feed into a LaTeX table. Manual copy-pasting is prone to error, so you can either generate the entire LaTeX code that includes the table or directly embed code that LaTeX can call upon during compilation (e.g., with PythonTeX). The best approach depends on your project’s complexity.

Installing LaTeX#

To use LaTeX effectively, you typically install a TeX distribution:

• TeX Live (cross-platform, often the go-to for Linux users)
• MiKTeX (common on Windows, also available on other platforms)
• MacTeX (for macOS)

Once installed, you’ll have a suite of commands (pdflatex, xelatex, etc.). You can also work in an integrated editor like TeXstudio, Overleaf (online), or Visual Studio Code with LaTeX Workshop extension.

Installing Python and Required Packages#

1. Python 3.x is recommended for most current applications.

2. For data analysis or advanced workflows, a typical environment might include:

   • numpy
   • matplotlib
   • pandas
   • sympy (for symbolic math)

3. Additional Python libraries or tools for bridging with LaTeX might include:

   • pip install pythontex
   • pip install pylatex
   • pip install pweave
   • pip install nbconvert

Ensuring your environment is consistent is vital. If you rely on advanced features, you might consider a virtual environment (using venv or conda) so package versions remain stable across your projects.

Why Minted?#

minted is a LaTeX package that leverages the Pygments syntax highlighter, written in Python, to colorize code. It offers an excellent range of languages (including Python) and customization.

Basic Usage#

You must install python3-pygments or an equivalent library on your system so that minted can call pygmentize. A minimal example:

1
\documentclass{article}
2
\usepackage[utf8]{inputenc}
3
\usepackage{minted}
4

5
\begin{document}
6

7
\section{Code Snippet Example}
8

9
Here is a Python function using \texttt{minted}:
10

11
\begin{minted}{python}
12
def greet(name):
13
    return f"Hello, {name}!"
14
\end{minted}
15

16
\end{document}

To compile this, you generally need to run something like:

1
pdflatex -shell-escape main.tex

The -shell-escape flag allows LaTeX to call external commands (e.g., pygmentize). If you forget the -shell-escape flag, you’ll see compilation errors indicating minted could not run the necessary external processes.

Customizing Output#

minted provides various options for line numbering, style, frames, or background colors. For instance:

1
\usepackage{minted}
2
\usemintedstyle{friendly}

You can change friendly to other styles like monokai, default, emacs, or many others. Also, you can add options in the environment itself:

1
\begin{minted}[fontsize=\small, linenos]{python}
2
def fibonacci(n):
3
    """Print the Fibonacci sequence up to n."""
4
    a, b = 0, 1
5
    while a < n:
6
        print(a, end=' ')
7
        a, b = b, a + b
8
\end{minted}

This snippet adds line numbers (linenos) and makes the font smaller (\small).

Installation and Basic Configuration#

Install PythonTeX with:

1
pip install pythontex

Then in your LaTeX file:

1
\documentclass{article}
2
\usepackage[utf8]{inputenc}
3
\usepackage{pythontex}
4

5
\begin{document}
6

7
\section{Using PythonTeX}
8
Let's compute something in Python and display the result here.
9

10
\begin{pycode}
11
# This Python code is run at compilation time
12
x = 42
13
\end{pycode}
14

15
The value of x is: \py{ x }
16

17
\end{document}

To compile:

1. Run pdflatex -shell-escape myfile.tex (generates an auxiliary script)
2. Run pythontex myfile.tex (executes Python portions and stores them)
3. Run pdflatex -shell-escape myfile.tex again (integrates updates into the final PDF)

This might vary depending on your editor—some can automate these steps for you.

PythonTeX Environments#

PythonTeX offers different environments:

• \begin{pyblock} ... \end{pyblock} for inline code that doesn’t produce textual output in the final PDF.
• \begin{pycode} ... \end{pycode} for code you want to run but not necessarily display.
• \py{...} for inline expressions.
• \begin{pyconsole} ... \end{pyconsole} to show both commands and outputs in a console-style format.

Inserting Plots#

You can generate plots with matplotlib or other libraries, save them to a file, and then embed them in the document. For example:

1
\begin{pycode}
2
import matplotlib.pyplot as plt
3

4
plt.figure()
5
plt.plot([1, 2, 3, 4], [1, 4, 2, 3], 'ro-')
6
plt.title('Simple Plot')
7
plt.savefig('myplot.png')
8
plt.close()
9
\end{pycode}
10

11
\begin{figure}[ht]
12
\centering
13
\includegraphics[width=0.5\textwidth]{myplot.png}
14
\caption{A Plot Generated by PythonTeX}
15
\end{figure}

You include the plot just like any normal LaTeX figure. Everything is automated, provided you re-run the appropriate commands.

Shell Scripting#

If you frequently re-generate reports, you can create a shell script (on Linux or macOS) or a batch file (on Windows). Example for Linux:

1
#!/bin/bash
2
pdflatex -shell-escape myreport.tex
3
pythontex myreport.tex
4
pdflatex -shell-escape myreport.tex

If you need to pass specific arguments or environment variables (e.g., to run a different Python environment), just layer that into the script. This approach helps ensure you or your colleagues only need to run a single command to produce updated PDFs.

Makefile Approach#

When building more complex projects, a Makefile can handle dependencies. The advantage is that make checks timestamps of files and only recompiles if needed:

1
all: myreport.pdf
2

3
myreport.pdf: myreport.tex
4
  pdflatex -shell-escape myreport.tex
5
  pythontex myreport.tex
6
  pdflatex -shell-escape myreport.tex
7

8
clean:
9
  rm -f *.aux *.log *.out *.pyg *.pytxcode *.pytxpyg *.pdf

Typing make in your terminal triggers the build, and make clean removes extraneous files.

Pweave#

Pweave is similar to Sweave (in R) or knitr, letting you weave Python code into document files. A Pweave file typically uses a mix of Python code blocks and markup. When processed, it executes the code and inserts results into your final document.

For instance, a file myreport.pmd might include:

1
Some text about data.
2

3
<<echo=False, results='verbatim'>>=
4
import pandas as pd
5
df = pd.DataFrame({"A": [1,2,3], "B": [4,5,6]})
6
print(df)
7
@
8

9
LaTeX instructions, math, etc.
10

11
<<echo=False, fig=True>>=
12
import matplotlib.pyplot as plt
13
plt.plot([1,2,3],[4,5,6])
14
plt.savefig('test.png')
15
@
16

17
\includegraphics{test.png}

You run pweave myreport.pmd -f tex to generate a LaTeX file that includes both code outputs and references to figures. Then compile that LaTeX file with pdflatex.

Jupyter Notebooks with nbconvert#

If your workflow is heavily reliant on Jupyter Notebooks, you can convert .ipynb files into LaTeX directly:

1
jupyter nbconvert --to latex mynotebook.ipynb

You can then compile the resulting .tex file. This approach helps if you do a lot of interactive exploration but still desire a professionally typeset final output.

pandoc One-Stop Conversions#

pandoc is a Swiss Army knife for converting between document formats. Suppose your source is Markdown with embedded code blocks. With pandoc, you can:

1
pandoc myfile.md -o myfile.pdf --pdf-engine=xelatex

Pandoc can read code fences in Markdown, highlight them with Python’s pygmentize, and produce a PDF with syntax highlighting (assuming correct configuration). If you want more sophisticated code execution, you’ll need tools like pandoc-crossref or rely on embedded scripts.

Step 1: Python Data Prep#

You might have a Python script (analysis.py) that:

1. Reads a CSV file (logs.csv).
2. Performs some aggregation or analysis.
3. Outputs results and maybe saves a figure (activity_plot.png).

Example code:

1
import pandas as pd
2
import matplotlib.pyplot as plt
3

4
def analyze_data(input_csv):
5
    df = pd.read_csv(input_csv, parse_dates=['timestamp'])
6
    daily_counts = df.groupby(df['timestamp'].dt.date).size()
7

8
    # Save basic stats
9
    summary = {
10
        "total_records": len(df),
11
        "unique_users": df['user_id'].nunique(),
12
        "days_covered": daily_counts.index[-1] - daily_counts.index[0]
13
    }
14

15
    # Plot daily activity
16
    plt.figure(figsize=(8,4))
17
    daily_counts.plot(kind='bar')
18
    plt.title("Daily Activity Counts")
19
    plt.xlabel("Date")
20
    plt.ylabel("Activity Count")
21
    plt.tight_layout()
22
    plt.savefig("activity_plot.png")
23
    plt.close()
24

25
    return summary, daily_counts
26

27
if __name__ == "__main__":
28
    summary, daily_counts = analyze_data("logs.csv")
29
    print(summary)
30
    print(daily_counts)

When this script is run, it produces a dictionary summary plus a bar plot of daily counts.

Step 2: LaTeX Report with PythonTeX#

Create a LaTeX file (report.tex):

1
\documentclass{article}
2
\usepackage[utf8]{inputenc}
3
\usepackage{graphicx}
4
\usepackage{pythontex}
5

6
\begin{document}
7

8
\title{Daily Activity Report}
9
\author{Data Analytics Team}
10
\date{\today}
11
\maketitle
12

13
\section{Introduction}
14
This report summarizes user activity from our platform logs.
15

16
\begin{pycode}
17
# Insert your analysis code or import from a module
18
import analysis
19

20
summary, daily_counts = analysis.analyze_data("logs.csv")
21
\end{pycode}
22

23
\section{Key Results}
24
\begin{itemize}
25
  \item Total Records: \py{summary["total_records"]}
26
  \item Unique Users: \py{summary["unique_users"]}
27
  \item Days Covered: \py{summary["days_covered"]}
28
\end{itemize}
29

30
\section{Activity Plot}
31
\begin{figure}[h!]
32
\centering
33
\includegraphics[width=0.7\textwidth]{activity_plot.png}
34
\caption{Daily Activity Counts}
35
\end{figure}
36

37
\section{Detailed Counts}
38
\pyc{for date_val, count_val in daily_counts.items():}
39
Date: \py{date_val}, Count: \py{count_val} \\
40
\pyc{endfor}
41

42
\end{document}

Compile commands:

1. pdflatex -shell-escape report.tex
2. pythontex report.tex
3. pdflatex -shell-escape report.tex

Voila! A single PDF is generated with the aggregated stats, a bar chart, and a table of daily counts.

Step 3: Autogenerate New Reports#

If you receive a new logs CSV every day (e.g., logs_2023-10-09.csv), you could script:

1
#!/bin/bash
2
cp logs_2023-10-09.csv logs.csv
3
pdflatex -shell-escape report.tex
4
pythontex report.tex
5
pdflatex -shell-escape report.tex
6
mv report.pdf report_2023-10-09.pdf

Now you have a daily pipeline generating custom PDFs.

Continuous Integration (CI)#

As your documentation needs grow, you might adopt a CI service (like GitHub Actions, GitLab CI, or Jenkins) to automatically build and test your LaTeX + Python content whenever changes are committed. This helps teams maintain consistent, up-to-date artifacts.

Large Multi-File Projects#

For substantial projects (e.g., a 200-page dissertation with experimental results), you can break your .tex sources into smaller files. You can also maintain separate Python scripts or notebooks. Good organization and naming schemes are essential. You might have:

1
dissertation/
2
  chap1_introduction.tex
3
  chap2_background.tex
4
  chap3_methods.tex
5
  chap4_results.tex
6
  chap5_discussion.tex
7
  main.tex
8
  scripts/
9
    analysis.py
10
    generate_plots.py

LaTeX references these chapters with \input{chapX_filename.tex} or \include{chapX_filename.tex}. Use make or a script to orchestrate the build.

Dockerization#

If you want maximum reproducibility across different operating systems, you can Dockerize your environment. For instance, you create a Dockerfile that installs TeX Live, Python, your required Python packages, and any additional tools (e.g., pythontex). Then, your entire team or a CI runner can consistently produce the same PDF without “but it works on my machine�?woes.

Handling Special Fonts and Unicode#

Some projects require custom fonts, especially for brand styling or foreign characters. Using xelatex or lualatex simplifies using system fonts and advanced OpenType features. This is handy if your project involves multiple languages or you need a perfect match to corporate brand guidelines.

Macro-Driven Automation#

LaTeX macros can drastically reduce repeated code. For example, if you’re referencing the same dataset name or parameter in multiple sections, you can store that in a LaTeX macro or use PythonTeX variables. This approach ensures consistency. In large documents, you only update the variable in one place for it to reflect throughout.