claude.md

Learn Probability - Style and Structure Guide

This document describes the writing style, structure patterns, and code organization for the Learn Probability course.

Chapter Structure

Opening Pattern

1. Welcoming introduction - Start with context linking to previous chapters
2. Why this matters - Explain the importance and real-world relevance
3. Learning objectives (optional) - Bullet list of what readers will learn
4. Progressive structure - Build from simple to complex

Section Organization

1. Numbered sections - Use clear hierarchical numbering (e.g., "## 1. Topic Name")
2. Subsections - Use "### 1.1 Subtopic" format
3. Visual separators - Use +++ to separate major sections

Chapter Closing

1. Summary section - Recap key takeaways in bullet format
2. Exercises - 4-6 exercises with answers in dropdown admonitions
3. Forward link - Brief mention of what's next

Exercise Format

Structure:

## Exercises

1.  **Exercise Title:** Description of the problem.
    a.  First sub-question
    b.  Second sub-question

    \`\`\`{admonition} Answer
    :class: dropdown

    a) Solution to first sub-question

    b) Solution to second sub-question
    \`\`\`

2.  **Next Exercise:** ...

Guidelines:

• Use numbered list (1., 2., 3., etc.)
• Exercise title in bold followed by colon: **Title:**
• Sub-questions use letters (a., b., c., etc.)
• Always indent answer blocks under the exercise
• Answers always use {admonition} Answer with :class: dropdown
• For exercises with hints instead of full solutions, use {admonition} Hint with :class: tip

Content Development Pattern

For Each Major Concept

Follow this sequence:

1. Intuitive introduction

   • Start with a concrete, relatable example
   • Use plain language before formal terminology

2. Visual representation

   • Create diagrams, area models, or tree diagrams
   • Use hidden code blocks for visualization code
   • Include figure captions with clear descriptions

3. Formal definition

   • Present mathematical definition in a clear box or section
   • Use LaTeX for all mathematical notation
   • Include all necessary conditions

4. Worked examples

   • Provide step-by-step solutions
   • Show multiple examples of increasing complexity
   • Use admonition boxes for longer examples

5. Python implementation

   • Show code in appropriate format (see Code Organization below)

Code Organization

Setup Code (imports and configuration)

Purpose: Import libraries and configure plot settings

Format:

\`\`\`{code-cell} ipython3
:tags: [remove-input, remove-output]

import numpy as np
import matplotlib.pyplot as plt
from scipy.special import comb, perm

# Set plot style
plt.style.use('seaborn-v0_8-whitegrid')
\`\`\`

When to use:

• At the start of a chapter
• When introducing new libraries
• Always hide with :tags: [remove-input, remove-output]

Plot Style Settings:

# Standard plot style for all chapters
plt.style.use('seaborn-v0_8-whitegrid')

# Standard figure sizes
figsize=(8, 4)    # Single plots
figsize=(10, 5)   # Plots with legends on the side
figsize=(12, 5)   # Side-by-side comparisons (1x2 subplots)

Consistent Color Palette:

# Primary colors (use consistently across chapters)
'skyblue'      # PMF bars, primary data
'lightgreen'   # Empirical/simulated data
'lightcoral'   # Transformed distributions, secondary data
'darkgreen'    # CDF lines
'red'          # Mean/expected value lines
'orange'       # ±1 standard deviation
'purple'       # ±2 standard deviations
'blue'         # Theoretical curves

# Alpha values
alpha=0.7      # Bars and fills
alpha=0.6      # Grids

# Edge colors
edgecolor='black'   # For bars and patches

Visualization Code (NOT part of learning)

Purpose: Creates figures, plots, diagrams that support concepts

Format:

:::{code-cell} ipython3
:tags: [remove-input, remove-output]

# Code to create visualization
# This code is HIDDEN from readers
# Saves to SVG or displays plot
:::

When to use:

• Creating Venn diagrams
• Generating area models
• Building tree diagrams
• Making illustrative plots that aren't teaching code skills

Learning Code (part of the pedagogy)

Purpose: Demonstrates calculations, implementations readers should understand

Format - Use dropdown:

:::{dropdown} Python Implementation
\`\`\`{code-cell} ipython3
# Code that readers should see and understand
# Shows how to calculate or implement concept
\`\`\`
:::

When to use:

• Demonstrating how to use scipy.stats functions
• Showing probability calculations
• Implementing formulas
• Calculating examples from the text

Exploration Code (hands-on practice)

Purpose: Simulation, experimentation, comparison to theory

Format - Visible, split into logical cells:

\`\`\`{code-cell} ipython3
# Setup and parameters
num_simulations = 10000
\`\`\`

\`\`\`{code-cell} ipython3
# Run simulation
results = simulate(...)
\`\`\`

\`\`\`{code-cell} ipython3
# Analyze results
print(f"Mean: {np.mean(results)}")
\`\`\`

When to use:

• Simulations that verify theoretical results
• Hands-on sections
• Interactive explorations

Code Cell Splitting Guidelines

Split cells when:

1. Moving from setup to execution to analysis
2. Each output should be separate (one print per cell generally)
3. Separating conceptually different operations
4. The cell output is large or takes time to compute

Keep cells together when:

1. Tightly coupled operations (import statements)
2. Defining a helper function
3. Setup that has no meaningful output

Example - Good splitting:

\`\`\`{code-cell} ipython3
# Define parameters
n = 52
k = 5
\`\`\`

\`\`\`{code-cell} ipython3
# Calculate combinations
total_hands = comb(n, k, exact=True)
print(f"Total hands: {total_hands:,}")
\`\`\`

\`\`\`{code-cell} ipython3
# Visualize
plt.figure(figsize=(8, 4))
plt.bar(...)
plt.show()
\`\`\`

Example - Bad splitting:

\`\`\`{code-cell} ipython3
import numpy as np
\`\`\`

\`\`\`{code-cell} ipython3
import matplotlib.pyplot as plt
\`\`\`

\`\`\`{code-cell} ipython3
from scipy.special import comb
\`\`\`

Better as:

\`\`\`{code-cell} ipython3
import numpy as np
import matplotlib.pyplot as plt
from scipy.special import comb
\`\`\`

Code Cell Combining Guidelines

Combine cells when:

1. All imports should be in one cell at the start
2. Defining multiple related helper functions
3. Setting up parameters that belong together
4. Multiple calculations that produce one logical output

Admonition Usage

Types and When to Use

Examples

• Short examples: Inline with **Example:** marker (no admonition box)

  **Example:** A restaurant offers 3 starters, 4 mains, and 2 desserts. How many meal combinations are possible?

• Long examples: Use :::{admonition} Example with :class: tip dropdown

  :::{admonition} Example: The Grocery Store
  :class: tip dropdown
  
  Long detailed example that might interrupt flow...
  :::

• When to use which: Use inline for examples that are 1-2 paragraphs. Use dropdown admonition for examples longer than 2 paragraphs or with multiple steps.

Definitions

• Always inline with **Definition:** marker
• NEVER use admonition boxes for definitions
• Keep definitions close to where concepts are introduced

  **Definition:** The **Probability Mass Function (PMF)** of a discrete random variable $X$ is...

• May use **Formal Definition:** for more rigorous statements
• May use **Derivation:** or **Interpretation:** as needed

Notes - :::{admonition} Note with :class: note

• Terminology clarifications
• Important points that aren't warnings
• Connections to other concepts
• "Why this name?" explanations

Tips - :::{admonition} Tip with :class: tip

• Study strategies
• Memory aids
• Key insights
• "How to remember this" guidance

Warnings - :::{admonition} Warning with :class: warning

• Common mistakes
• Confusing distinctions
• Critical points not to miss
• Pitfalls to avoid

Dropdowns - :class: dropdown

• Long examples that interrupt flow
• Supplementary content
• Derivations that some readers may skip
• Optional depth

Mathematical Notation

Formatting Standards

Inline math: Use single $...$ for inline: $P(A \cap B)$

Display math: Use $$...$$ for centered equations:

$$P(A|B) = \frac{P(A \cap B)}{P(B)}$$

Multi-line derivations: Use align blocks:

$$
\begin{align*}
P(A \cap B) &= P(A|B) \times P(B) \\
&= 0.5 \times 0.3 \\
&= 0.15
\end{align*}
$$

Sets: Use \{ and \}: $\{1, 2, 3\}$

Conditional probability: Always use | (not colon): $P(A|B)$

Expected value: Use square brackets: $E[X]$

Conditional sums/sets: When using colon notation (e.g., $\sum_{x: g(x)=y}$ or ${x: x > 0}$), explain it the first time:

\`\`\`{admonition} Reading the notation
:class: note

The notation $\sum_{x: g(x)=y}$ is read as "sum over all values of $x$ such that $g(x) = y$". The colon (:) means "such that" or "where".
\`\`\`

Visual Elements

Figures

SVG preferred for:

• Venn diagrams
• Tree diagrams
• Custom visualizations
• Area models

Format:

\`\`\`{figure} filename.svg
---
width: 80%
figclass: full-width (optional)
---
Clear caption describing what the figure shows.
\`\`\`

Plots

Use matplotlib with:

• Consistent style: plt.style.use('seaborn-v0_8-whitegrid')
• Clear labels: xlabel, ylabel, title
• Appropriate figure size: figsize=(8, 4) or similar
• Grid for readability: plt.grid(...)
• Always save before show: plt.savefig('filename.svg', format='svg', bbox_inches='tight')
• Use consistent colors from the palette (see Code Organization section)

Standard plot template:

\`\`\`{code-cell} ipython3
:tags: [remove-input, remove-output]

plt.figure(figsize=(8, 4))
# Plot content here
plt.xlabel("X Label")
plt.ylabel("Y Label")
plt.title("Descriptive Title")
plt.grid(axis='y', linestyle='--', alpha=0.7)
plt.savefig('ch06_descriptive_name.svg', format='svg', bbox_inches='tight')
plt.show()
\`\`\`

Writing Style

Voice and Tone

• Welcoming and encouraging - "Let's explore..."
• Clear and direct - Avoid unnecessary complexity
• Build confidence - "Notice that..." "We can see..."
• Connect concepts - Link to previous learning frequently

Example Language Patterns

Good:

• "Let's think through this step-by-step"
• "Notice how this connects to..."
• "The key insight is..."
• "This makes intuitive sense because..."

Avoid:

• "Obviously..." (might not be obvious!)
• "Simply..." (might not be simple!)
• "Trivially..." (condescending)
• "As everyone knows..." (assumption)

Mathematical Exposition

Pattern for introducing formulas:

1. Motivate why we need it
2. Show the formula
3. Explain each component
4. Work through an example
5. Show Python implementation

Example:

The number of permutations is given by:

$$ P(n, k) = \frac{n!}{(n-k)!} $$

where:
* $n$ is the total number of objects
* $k$ is the number of objects selected
* $n!$ (read "n factorial") is the product...

Let's calculate $P(8, 3)$...

Mobile Formatting Considerations

Math Display

Blank lines before math blocks: Essential for mobile rendering

The probability is calculated as follows:

$$
P(A) = \frac{1}{6}
$$

This shows that...

Avoid long equations: Break into multiple lines using align

Lists and Spacing

Blank lines in numbered lists: Add before math or code blocks

1. First step

   $$
   P(A) = 0.5
   $$

2. Second step

Chapter-Specific Patterns

Counting Chapter (Ch 3)

• Heavy use of step-by-step multiplication principle
• "Building Intuition" then "General Formula" pattern
• Quick reference table at end
• Decision trees for choosing methods

Conditional Probability (Ch 4)

• Strong emphasis on visual representation (Venn diagrams)
• Tree diagrams for sequential events
• "Tips for differentiating" sections

Bayes & Independence (Ch 5)

• Area models for Bayes' theorem
• Careful distinction between related concepts
• Multiple visual representations of same concept
• "Why this section matters" boxes

Random Variables (Ch 6)

• Progression: Definition → PMF → CDF → Expected Value → Variance
• Strong connection to simulation
• "Hands-on" sections for empirical verification

Quality Checklist

Before finalizing a chapter:

• Introduction links to previous content
• Each major concept follows: intuition → visual → formal → example → code
• Visualization code is hidden with tags
• Learning code is in dropdowns
• Code cells are appropriately split/combined
• All math has blank lines before/after for mobile
• Figures have descriptive captions
• Exercises have dropdown solutions
• Summary section captures key points
• Forward link to next chapter
• Consistent notation throughout
• No orphaned concepts (everything is explained or linked)