Skip to content

IMPROVEMENTS_SUMMARY.md

Latest commit

 

History

History
199 lines (135 loc) · 5.78 KB

IMPROVEMENTS_SUMMARY.md

File metadata and controls

199 lines (135 loc) · 5.78 KB

Chapter 6 Improvements Summary

This document summarizes the improvements made to chapter_06.md based on the style guide extracted from chapters 3-5.

Major Changes

1. Code Organization

Visualization Code - Now Hidden

All visualization code that is not part of learning (creating plots to illustrate concepts) is now hidden using :tags: [remove-input, remove-output]:

Examples:

  • PMF plot (line ~97)
  • CDF plot (line ~169)
  • Mean visualization (line ~229)
  • Variance visualization (line ~320)
  • Y=X² plot (line ~410)
  • Empirical vs theoretical comparison plots (line ~487)

Why: These plots support the narrative but don't teach coding skills. Hiding the code keeps the focus on concepts.

Learning Code - Now in Dropdowns

Code that demonstrates calculations readers should understand is now in :::{dropdown} Python Implementation blocks:

Examples:

  • PMF definition and dictionary creation
  • CDF calculation and function definition
  • Expected value calculation
  • Variance calculation (all three methods)
  • Functions of random variables (LOTUS)

Why: Allows readers to see implementation details without interrupting the conceptual flow.

Imports - Combined

All imports are now in a single cell at the beginning instead of spread across multiple cells.

Before:

import numpy as np
import matplotlib.pyplot as plt

After:

import numpy as np
import matplotlib.pyplot as plt
from scipy.stats import rv_discrete

2. Code Cell Splitting

Better Split - Simulation Section

The simulation section now has better separation between:

  1. Setup (num_simulations, generate data)
  2. Calculation (mean, variance)
  3. Display results (comparisons)

Before: Large cells combining setup, calculation, and output

After: Each conceptual step in its own cell

Better Combined - Related Calculations

Variance calculations that show equivalent methods are now together in one dropdown instead of scattered across multiple cells.

3. Figure Captions

All figures now have descriptive captions explaining what they show:

Examples:

  • "PMF of a fair die roll showing uniform probability of 1/6 for each outcome."
  • "CDF of a fair die roll showing the cumulative probability as a step function."
  • "Comparison of empirical (simulated) and theoretical distributions, demonstrating convergence."

Why: Helps mobile readers and those using screen readers understand visualizations.

4. Math Formatting

Added blank lines before and after all display math blocks to ensure proper rendering on mobile devices.

Before:

Let's calculate the variance:
$$Var(X) = E[X^2] - (E[X])^2$$
Now we can see...

After:

Let's calculate the variance:

$$
Var(X) = E[X^2] - (E[X])^2
$$

Now we can see...

5. Exercise Format

Exercises now use consistent dropdown format for answers:

```{admonition} Answer
:class: dropdown

[Answer content here]
\```

File Structure

New Files Created

  1. claude.md - Comprehensive style guide extracted from chapters 3-5
  2. chapter_06_improved.md - Improved version of chapter 6
  3. IMPROVEMENTS_SUMMARY.md - This file

Generated Figures

The improved chapter will generate these SVG files:

  • ch06_pmf_die.svg
  • ch06_cdf_die.svg
  • ch06_pmf_with_mean.svg
  • ch06_pmf_with_std.svg
  • ch06_pmf_y_squared.svg
  • ch06_empirical_vs_theoretical.svg

Key Principles Applied

From the Style Guide

  1. Build intuition first, then formalize - Each concept follows: intuition → visual → definition → example → code

  2. Hide non-learning code - Visualization code is hidden; learning code is in dropdowns

  3. Split cells logically - Each cell represents one conceptual unit or one output

  4. Use admonitions strategically - Dropdowns for examples, notes for terminology, tips for insights

  5. Mobile-friendly formatting - Blank lines around math, appropriate figure widths

  6. Clear progression - Introduction → concepts → hands-on → summary → exercises

Benefits

For Readers

  • Cleaner reading experience - Less code clutter in the main narrative
  • Optional depth - Can expand dropdowns to see implementation details
  • Better mobile experience - Proper math rendering and figure captions
  • Consistent structure - Same patterns across chapters

For Maintainers

  • Clear guidelines - claude.md provides explicit patterns to follow
  • Easier updates - Consistent structure makes changes predictable
  • Quality control - Checklist in style guide ensures completeness

Before/After Comparison

Code Visibility

Before: ~30 visible code cells throughout the chapter After: ~15 visible code cells (learning/hands-on), ~6 hidden cells (visualization)

Dropdown Usage

Before: Minimal use of dropdowns After: 6 dropdown blocks for implementation details

Figure Quality

Before: Figures without captions or context After: All figures have descriptive captions and proper sizing

Next Steps

To apply the improved version:

  1. Review chapter_06_improved.md
  2. Test by converting to Jupyter notebook: jupytext --to ipynb chapter_06_improved.md
  3. Run all cells and verify outputs
  4. If satisfied, replace original: mv chapter_06_improved.md chapter_06.md
  5. Apply similar patterns to other chapters using claude.md as reference

Recommendations

For Future Chapters

  1. Start with claude.md - Review the style guide before writing
  2. Use the checklist - The quality checklist ensures nothing is missed
  3. Be consistent - Follow the same patterns for the same types of content
  4. Test on mobile - Verify math rendering and figure display

For Existing Chapters

Consider reviewing chapters 1-2 and 7+ to apply these patterns consistently across the entire book.