crypto-economics

View on GitHub

---

Information

Property	Value
Language	TeX
Stars	0
Forks	0
Watchers	0
Open Issues	0
License	No License
Created	2026-01-11
Last Updated	2026-02-19
Last Push	2026-03-13
Contributors	1
Default Branch	master
Visibility	private

Datasets

This repository includes 16 dataset(s):

Dataset	Format	Size

| complexity_assessment.json | .json | 0.65 KB |

| graph_hints.json | .json | 0.12 KB |

| implementation_plan.json | .json | 4.13 KB |

| project_index.json | .json | 0.16 KB |

| requirements.json | .json | 0.23 KB |

| task_logs.json | .json | 145.89 KB |

| task_metadata.json | .json | 0.08 KB |

| complexity_assessment.json | .json | 4.58 KB |

| context.json | .json | 1.81 KB |

| implementation_plan.json | .json | 17.89 KB |

| project_index.json | .json | 1.06 KB |

| requirements.json | .json | 0.17 KB |

| review_state.json | .json | 0.18 KB |

| task_logs.json | .json | 453.24 KB |

| task_metadata.json | .json | 0.08 KB |

| .claude_settings.json | .json | 0.57 KB |

Reproducibility

This repository includes reproducibility tools:

• Python requirements.txt

• Makefile for automation

Status

• Issues: Enabled
• Wiki: Enabled
• Pages: Enabled

README

Crypto Economics Lecture Series

A modular LaTeX Beamer presentation system for crypto-economics lectures with Python chart generation and automated GitHub Pages deployment.

Table of Contents

• Overview
• Features
• Project Structure
• Prerequisites
• Quick Start
• Build Commands
• Adding New Modules
• Creating Charts
• LaTeX Template System
• GitHub Pages Deployment
• Development Workflow
• Troubleshooting
• License

Overview

This project provides a complete infrastructure for creating professional crypto-economics lecture presentations:

• 8 Modular Lectures: Self-contained modules covering crypto-economics topics
• Consistent Visual Style: Custom LaTeX Beamer theme matching a professional color palette
• Python Chart Generation: Programmatic chart creation with consistent styling
• Automated Builds: Full pipeline from source to deployed GitHub Pages

Features

• Modular LaTeX Template System: Reusable theme, commands, and layout templates
• Python Chart Framework: matplotlib-based charts with matching color scheme
• Multiple Build Options: Make, Python scripts, or full orchestration
• Watch Mode: Auto-rebuild on file changes during development
• GitHub Actions CI/CD: Automated builds and deployment
• Responsive Landing Page: Course overview with module downloads

Project Structure

crypto-economics/
├── templates/                    # LaTeX template system
│   ├── beamerthemecryptoeconomics.sty  # Main theme (colors, layout)
│   ├── commands.sty              # Custom commands and environments
│   ├── module-template.tex       # Master document template
│   └── layouts/                  # Reusable slide layouts
│       ├── title-slide.tex       # Title and section openers
│       ├── two-column.tex        # Side-by-side layouts
│       ├── full-chart.tex        # Full-width visualizations
│       ├── comparison.tex        # Pros/cons, A vs B
│       ├── definition.tex        # Formal definitions
│       └── summary.tex           # Takeaways and conclusions
│
├── scripts/                      # Python tools
│   ├── __init__.py               # Package exports
│   ├── chart_style.py            # Matplotlib styling (matches LaTeX)
│   ├── chart_utils.py            # Chart helpers and export
│   ├── build_charts.py           # Chart generation CLI
│   ├── build_latex.py            # LaTeX compilation CLI
│   ├── build_all.py              # Master build orchestrator
│   └── examples/                 # Example chart scripts
│       ├── line_chart.py         # Time series visualizations
│       ├── bar_chart.py          # Comparison charts
│       ├── pie_chart.py          # Composition charts
│       └── scatter_chart.py      # Correlation charts
│
├── modules/                      # Lecture content (8 modules)
│   ├── module-01/                # Introduction to Crypto-Economics
│   │   ├── slides.tex            # Presentation source
│   │   ├── charts/               # Module-specific charts
│   │   └── notes.md              # Lecture notes
│   ├── module-02/                # [Topic TBD]
│   │   └── ...
│   └── module-08/                # [Topic TBD]
│
├── assets/                       # Shared resources
│   ├── images/                   # Common images
│   └── charts/                   # Generated example charts
│       └── examples/             # Output from example scripts
│
├── docs/                         # GitHub Pages site
│   ├── index.html                # Landing page
│   ├── assets/style.css          # Site styling
│   ├── pdfs/                     # Compiled module PDFs
│   └── charts/                   # Chart images for web
│
├── build/                        # Build output (git-ignored)
│
├── .github/workflows/            # CI/CD configuration
│   └── build.yml                 # Automated build pipeline
│
├── Makefile                      # GNU Make build interface
├── init.sh                       # Environment setup script
├── pyproject.toml                # Python project configuration
├── requirements.txt              # Python dependencies
├── requirements-dev.txt          # Development dependencies
└── .gitignore                    # Git ignore patterns

Prerequisites

Required

• Python 3.10+ with pip
• LaTeX Distribution with pdflatex:
• Windows: MiKTeX or TeX Live
• macOS: MacTeX
• Linux: sudo apt install texlive-full (Ubuntu/Debian)

Recommended

• GNU Make for streamlined builds (included in most Unix systems, available via Git Bash on Windows)
• Git for version control

Quick Start

1. Clone the Repository

git clone https://github.com/YOUR_USERNAME/crypto-economics.git
cd crypto-economics

2. Set Up Development Environment

Using the setup script (recommended):

# Standard setup
./init.sh

# With development tools (pytest, black, ruff)
./init.sh --dev

# Check dependencies only
./init.sh --check

Or manually:

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Build Everything

# Using Make
make

# Or using Python
python -m scripts.build_all

4. View Results

• PDFs: build/module-XX.pdf
• Charts: assets/charts/examples/
• Website: Open docs/index.html in a browser

Build Commands

Using Make (Recommended)

make                  # Build everything (charts + LaTeX)
make latex            # Compile all LaTeX presentations
make charts           # Generate all charts
make module-01        # Build specific module (01-08)
make clean            # Remove auxiliary files
make distclean        # Remove all generated files
make check            # Verify dependencies
make help             # Show all available targets

Using Python Scripts

# Master build (charts -> LaTeX -> copy to docs)
python -m scripts.build_all

# Watch mode (auto-rebuild on changes)
python -m scripts.build_all --watch

# Build specific modules
python -m scripts.build_all -m 01 02 03

# Charts only
python -m scripts.build_charts

# LaTeX only
python -m scripts.build_latex

# Dry run (preview without changes)
python -m scripts.build_all --dry-run

Build Script Options

build_all.py - Master Orchestrator

python -m scripts.build_all [options]

Options:
  --charts        Build charts only
  --latex         Build LaTeX only
  --copy          Copy to docs only
  --watch, -w     Watch for changes and auto-rebuild
  --clean         Clean auxiliary files before build
  --dry-run       Show what would be done
  -m, --modules   Specify modules to build (e.g., -m 01 02)
  -v, --verbose   Verbose output

build_latex.py - LaTeX Compilation

python -m scripts.build_latex [options]

Options:
  --list          List available modules
  --check         Verify pdflatex installation
  -m, --module    Build specific module
  --single-pass   Run pdflatex once (faster, may have broken refs)
  --clean         Remove auxiliary files after build
  --dry-run       Preview without building

build_charts.py - Chart Generation

python -m scripts.build_charts [options]

Options:
  --list          List available chart scripts
  --examples      Generate example charts only
  -m, --module    Generate charts for specific module
  --dry-run       Preview without generating
  -v, --verbose   Verbose output

Adding New Modules

Step 1: Create Module Directory

Each module follows a consistent structure:

modules/module-XX/
├── slides.tex       # Main presentation file
├── charts/          # Module-specific charts
│   └── charts.py    # Chart generation script (optional)
└── notes.md         # Lecture notes and speaker guidance

Step 2: Copy the Template

# Copy the master template
cp templates/module-template.tex modules/module-XX/slides.tex

Step 3: Customize Your Module

Edit modules/module-XX/slides.tex:

% 1. Set module metadata at the top
\newcommand{\modulenumber}{XX}
\newcommand{\moduletitle}{Your Module Title}
\newcommand{\modulesubtitle}{Detailed Subtitle}
\newcommand{\moduleauthor}{Your Name}

% 2. Replace example content with your slides
% Use the available layouts and commands (see LaTeX Template System below)

Step 4: Build Your Module

# Build single module
make module-XX

# Or using Python
python -m scripts.build_latex -m XX

Creating Charts

Chart Framework Overview

The Python chart framework provides:

• Consistent styling matching the LaTeX theme
• Easy export to PDF/PNG formats
• Reusable utilities for common chart elements

Quick Example

from scripts import chart_style, chart_utils

# Apply the theme
chart_style.apply_style()

# Create a figure
fig, ax = chart_utils.create_figure(size="default", title="My Chart")

# Plot your data
ax.plot(x_data, y_data, color=chart_style.COLORS['mlblue'])

# Save with automatic formatting
chart_utils.save_chart(fig, "my_chart", output_dir="assets/charts")

Available Colors

Colors match the LaTeX theme exactly:

from scripts.chart_style import COLORS

COLORS = {
    'mlblue': '#0066CC',      # Primary blue
    'mlpurple': '#3333B2',    # Secondary purple
    'mlorange': '#FF7F0E',    # Accent orange
    'mlgreen': '#2CA02C',     # Positive/success
    'mlred': '#D62728',       # Negative/warning
    'mlgray': '#7F7F7F',      # Neutral gray
    'mllavender1': '#E8E0F0', # Light lavender
    'mllavender2': '#D1C4E9', # Medium lavender
    'mllavender3': '#B39DDB', # Darker lavender
    'mllavender4': '#9575CD', # Deep lavender
}

Figure Size Presets

from scripts.chart_style import FIGURE_SIZES

FIGURE_SIZES = {
    'default': (10, 6),   # Standard slide chart
    'small': (6, 4),      # Quarter slide
    'medium': (8, 5),     # Half slide width
    'large': (14, 8),     # Full slide
    'wide': (12, 4),      # Wide banner
    'square': (6, 6),     # Square format
}

Creating Module-Specific Charts

1. Create a chart script in your module:

# modules/module-01/charts/charts.py
from scripts import chart_style, chart_utils
from pathlib import Path

def generate_charts():
    """Generate all charts for Module 01."""
    output_dir = Path(__file__).parent
    chart_style.apply_style()

    # Chart 1: Example line chart
    fig, ax = chart_utils.create_figure(title="Bitcoin Price Trend")
    ax.plot(dates, prices, color=chart_style.COLORS['mlblue'])
    chart_utils.save_chart(fig, "btc_price", output_dir=output_dir)

    # Chart 2: ...

if __name__ == "__main__":
    generate_charts()

1. Build charts:

python -m scripts.build_charts -m 01

Utility Functions

from scripts.chart_utils import (
    # Figure creation
    create_figure,           # Standard figure with optional title
    create_figure_grid,      # Multi-panel layouts

    # Export
    save_chart,              # Save to PDF/PNG
    save_chart_for_module,   # Save to module's charts/ directory

    # Annotations
    add_annotations,         # Label data points
    add_vertical_line,       # Mark events
    add_horizontal_line,     # Mark thresholds
    add_shaded_region,       # Highlight periods

    # Formatting
    format_currency,         # $1,234 or $1.2M
    format_percentage,       # 12.3%
    format_btc,              # ₿0.5
    format_eth,              # Ξ1.2
    set_currency_axis,       # Apply currency formatting to axis
    set_percentage_axis,     # Apply percentage formatting to axis
)

Example Chart Types

See scripts/examples/ for complete examples:

Script	Chart Types
line_chart.py	Price trends, moving averages, multi-asset comparison
bar_chart.py	Market cap rankings, grouped/stacked bars, comparisons
pie_chart.py	Market share, donut charts, hierarchical composition
scatter_chart.py	Risk-return analysis, correlations, bubble charts

Generate all examples:

python -m scripts.build_charts --examples

LaTeX Template System

Theme and Commands

The template system provides consistent styling:

\documentclass[8pt,aspectratio=169]{beamer}

% Load the theme and commands
\usepackage{beamerthemecryptoeconomics}
\usepackage{commands}

Available Commands

Text Formatting

\bottomnote{Key takeaway text}        % Bottom annotation
\compactlist                          % Reduce list spacing
\code{inline code}                    % Monospace inline code

% Color highlights
\hlblue{blue text}
\hlpurple{purple text}
\hlorange{orange text}
\hlgreen{green text}
\hlred{red text}

Lists and Comparisons

\pro{Advantage point}                 % Green checkmark
\con{Disadvantage point}              % Red X
\positive{+15\%}                      % Green positive value
\negative{-8\%}                       % Red negative value

Chart Placeholders

\chartplaceholder{Chart Title}        % Default 5cm height
\chartplaceholder[7cm]{Chart Title}   % Custom height
\smallchart{Description}              % Small placeholder
\mediumchart{Description}             % Medium placeholder
\largechart{Description}              % Large placeholder

Special Environments

% Definition box
\begin{definitionbox}{Term}
    Definition text here.
\end{definitionbox}

% Equation box
\begin{equationbox}{Equation Name}
    E = mc^2
\end{equationbox}

% Code block
\begin{codebox}{Python}
    def hello():
        print("Hello!")
\end{codebox}

Layout Templates

Import layouts in your module:

\input{../../templates/layouts/title-slide}
\input{../../templates/layouts/two-column}
\input{../../templates/layouts/full-chart}
\input{../../templates/layouts/comparison}
\input{../../templates/layouts/definition}
\input{../../templates/layouts/summary}

See templates/layouts/ for available environments and examples.

Building LaTeX Manually

From a module directory:

cd modules/module-01
TEXINPUTS=../../templates:../../templates/layouts: pdflatex slides.tex
pdflatex slides.tex  # Second pass for cross-references

GitHub Pages Deployment

Automatic Deployment

The GitHub Actions workflow (.github/workflows/build.yml) automatically:

1. Installs Python and LaTeX dependencies
2. Generates all charts
3. Compiles all LaTeX modules
4. Copies PDFs to docs/pdfs/
5. Deploys to GitHub Pages

Triggered on push to main or master branches.

Manual Deployment

# Build and prepare docs
python -m scripts.build_all

# Files are ready in docs/
# - docs/index.html (landing page)
# - docs/pdfs/*.pdf (compiled modules)
# - docs/charts/ (chart images)

Local Preview

# Using Python's built-in server
cd docs
python -m http.server 8000

# Open http://localhost:8000

Development Workflow

Recommended Workflow

1. Start watch mode for automatic rebuilds:

   python -m scripts.build_all --watch
   

2. Edit your module (modules/module-XX/slides.tex)

3. View changes - PDF updates automatically in build/

Code Quality Tools

# Install dev dependencies
pip install -r requirements-dev.txt

# Format Python code
black scripts/

# Lint Python code
ruff check scripts/

# Type checking
mypy scripts/

# Run tests
pytest

Pre-commit Checks

# Check dependencies are available
make check

# Dry run to preview build
python -m scripts.build_all --dry-run

Troubleshooting

LaTeX Issues

Problem: pdflatex not found

# Check installation
which pdflatex        # Unix
where pdflatex        # Windows

# If missing, install:
# Windows: Install MiKTeX
# macOS: brew install --cask mactex
# Linux: sudo apt install texlive-full

Problem: Missing LaTeX packages

# MiKTeX: Opens package manager automatically
# TeX Live:
tlmgr install <package-name>

Problem: Template not found

# Ensure TEXINPUTS is set correctly
export TEXINPUTS=./templates:./templates/layouts:

# Or use the build scripts which handle this automatically

Python Issues

Problem: Module not found

# Activate virtual environment first
source .venv/bin/activate   # Unix
.venv\Scripts\activate      # Windows

# Or run as module
python -m scripts.build_all

Problem: matplotlib display issues

# Set backend before importing pyplot
import matplotlib
matplotlib.use('Agg')  # For headless environments

Build Issues

Problem: Charts not appearing in PDF

# Ensure charts exist and path is correct
ls modules/module-XX/charts/

# Check LaTeX graphics path in slides.tex
\graphicspath{{charts/}{../../assets/}}

Problem: Watch mode not detecting changes

# Restart watch mode
# Ensure you're editing files in watched directories
python -m scripts.build_all --watch -v  # Verbose mode

License

Copyright (c) Joerg Osterrieder. All rights reserved.