PyStatsV1 — Applied Statistics (R ↔ Python)

PyStatsV1 provides plain, transparent Python scripts that mirror classical R textbook analyses, making it easy for students, tutors, and practitioners to:

• run statistical analyses from the command line,
• generate synthetic data for teaching,
• produce figures and JSON summaries,
• and compare outputs across R/Python.

⭐ Fastest start (PyPI + Workbook)

Install from PyPI (recommended: include the Workbook bundle so you can run pytest checks):

python -m pip install -U pip
python -m pip install "pystatsv1[workbook]"

Sanity-check your environment:

pystatsv1 doctor

Create a local Workbook starter and run Chapter 10:

pystatsv1 workbook init
cd pystatsv1_workbook

python scripts/psych_ch10_problem_set.py
pytest -q

Psychological Statistics by Design companion — PyStatsV1 v0.26.0

PyStatsV1 v0.26.0 distributes Psychological Statistics by Design — Executable Companion v0.1. It unifies ten synthetic Student Well-Being and Learning studies behind one registry, ten visible Python entry scripts, independent R implementations, verification receipts, figure specifications, reviewer packets, and synthetic-safe adaptation templates. PyStatsV1 remains the versioned bridge and launcher; it does not choose a method, validate an instrument, authorize data, or establish causality.

The verified public reader route is:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "pystatsv1[psych-design]==0.26.0"
pystatsv1 psych-design info
pystatsv1 psych-design init
cd psychological_statistics_by_design_companion_v0_1
pystatsv1 psych-design verify --dest .
python -m pip install -r requirements-psych-design-companion.txt
pystatsv1 psych-design doctor --dest .
make first-result  # complete SWL-S02 Python/R V2 chain; requires Rscript
pystatsv1 psych-design verify --dest .

The governed reader proofs cover native Ubuntu and Windows 11 WSL2 with Ubuntu. The companion remains synthetic-only. Portal deployment, book binding, and real-data use remain separately governed and unauthorized by this release. The public foundations companion continues to use the separately pinned Book 1 route below.

Psych Stats with Python — Book 1 companion

PyStatsV1 v0.25.2 packages Companion v0.2.1, the corrected synthetic-only executable companion to Psych Stats with Python. Chapter 8 now uses globally unique participant IDs (ch08_001 through ch08_048) while preserving the analytical columns, row order, reported statistics, APA sentence, Python/R parity, and figure content.

The historical PyStatsV1 v0.25.0 with Companion v0.2 proof route remains preserved as immutable lineage evidence. New installations should use the corrected route below. The launcher writes an inspectable local folder; it does not hide the analysis, overwrite an existing destination, or turn a real-data workflow into a one-command claim.

python -m pip install "pystatsv1[book1]==0.25.2"
pystatsv1 book1 init
cd psych_stats_with_python_companion_v0_2_1
python -m pip install -r requirements-book1-companion.txt
make figures
make all  # requires Rscript for Python/R parity
pystatsv1 book1 verify --dest .

The launcher bundle contains versioned synthetic CSVs, transparent Python scripts, optional base-R verification scripts, six source-faithful grayscale figure specifications, a source-file manifest, and a maintenance receipt. Chapter 10 correlation and Chapter 11 regression use separate source datasets and figures. It is a foundations teaching companion, not a real-data intake service or a substitute for statistical judgment.

Open the bundled local PDF docs (works offline):

pystatsv1 docs
# optional convenience script:
pystatsv1-docs

Tip: the online docs are always available via the ReadTheDocs badge at the top of this README.

🧠 Psychology support helpers (v0.23.0)

PyStatsV1 v0.23.0 adds a small public pystatsv1.psych helper layer for proof-first psychology and APA-style companion labs. These helpers are intentionally modest: they do not replace SciPy, statsmodels, Pingouin, or R for inferential statistics. They provide a reusable bridge for identity receipts, descriptive summaries, stable JSON receipts, and numeric parity comparisons.

from pystatsv1.psych import (
    package_identity,
    describe_by_group,
    write_json_receipt,
    compare_numeric_results,
)

This supports the companion-lab positioning:

Python for the workflow. R for verification. PyStatsV1 for the bridge.

See docs/source/psych_support_helpers.rst and docs/source/release_notes.rst for details.

Full repository (scripts, Makefile targets, tests, docs)

If you want the full chapter-by-chapter repo (simulators, analyzers, Makefile targets, tests, and the docs source), clone from GitHub and install in editable mode:

git clone https://github.com/pystatsv1/PyStatsV1.git
cd PyStatsV1
pip install -e .
pip install -r requirements-dev.txt

Project Structure

The project follows a chapter-based structure — each chapter includes a simulator, an analyzer, Makefile targets, and CI smoke tests.

Who is this for?

PyStatsV1 is designed for:

• Students who want to run textbook-style analyses in real Python code.
• Instructors / TAs who need reproducible demos and synthetic data for lectures, labs, or assignments.
• Practitioners who prefer plain scripts and command-line tools over large frameworks.
• R users who want a clear, line-by-line bridge from R examples into Python.

---

🚀 Using a Virtual Environment

Option A — Student mode (PyPI + Workbook)

macOS / Linux

python -m venv pystatsv1-env
source pystatsv1-env/bin/activate
python -m pip install -U pip
python -m pip install "pystatsv1[workbook]"
pystatsv1 doctor
pystatsv1 workbook init

Windows (Git Bash)

python -m venv pystatsv1-env
source pystatsv1-env/Scripts/activate
python -m pip install -U pip
python -m pip install "pystatsv1[workbook]"
pystatsv1 doctor
pystatsv1 workbook init

Option B — Repo dev install (contributors)

python -m venv .venv
# Git Bash first; PowerShell as fallback
source .venv/Scripts/activate 2>/dev/null || .venv\\Scripts\\Activate.ps1
python -m pip install -U pip
pip install -e .
pip install -r requirements-dev.txt

---

📊 Chapter Scripts

Chapter 1 — Introduction

python -m scripts.ch01_introduction

Chapter 13 — Within-subjects & Mixed Models

make ch13-ci   # tiny CI smoke
make ch13      # full demo

Chapter 14 — Tutoring A/B Test (two-sample t-test)

make ch14-ci
make ch14

Chapter 15 — Reliability (Cronbach’s α, ICC, Bland–Altman)

make ch15-ci
make ch15

For an overview of what each chapter contains:

• CHAPTERS.md — coverage, commands, and outputs
• ROADMAP.md — planned chapters (e.g., Ch16 Epidemiology RR)

---

📚 Project Docs & Policies

PyStatsV1 is structured with a core set of documentation:

• CONTRIBUTING.md — environment setup, development workflow, Makefile usage, PR process.
• CODE_OF_CONDUCT.md — community expectations & enforcement.
• CHAPTERS.md — high-level description of all implemented chapters.
• ROADMAP.md — the future of the project: upcoming chapters & milestones.
• SECURITY.md — how to privately report vulnerabilities.
• SUPPORT.md — how to get help or ask questions.
• Case Study Template: docs/case_study_template.md — structure for building new chapter teaching documentation.

If you want to contribute, start with CONTRIBUTING.md and check issues labeled good first issue or help wanted.

---

🤝 Contribute in 5 minutes

Want to help but not sure where to start?

1. Browse issues labeled good first issue or help wanted.

2. Pick one small thing (typo, doc improvement, tiny refactor, or a missing test).

3. Fork & clone the repo.

4. Create and activate a virtual environment, then:

   pip install -r requirements.txt
   make lint
   make test

5. Make your change, and ensure make lint and make test both pass.

6. Open a Pull Request and briefly describe:

   • what you changed,
   • how you tested it,
   • which chapter(s) it touches, if any.

Maintainer promise: we’ll give constructive feedback and help first-time contributors land their PRs.

---

🗺️ Roadmap snapshot

High-level upcoming work (see ROADMAP.md for details):

• ✅ v0.17.0 — Onboarding and issue templates
• ⏳ Next steps:
  • Additional regression chapters (logistic, Poisson, etc.)
  • Power and sample size simulations
  • Epidemiology-focused examples (risk ratios, odds ratios)
  • More teaching case studies using docs/case_study_template.md

If you’d like to champion a specific chapter or topic, open an issue and we can design it together.

---

📘 Psychological Statistics by Design source candidate

The private, synthetic-only SWL-S02 through SWL-S05 implementation batch lives under psych_design_companion/swl_s02_s05_v0_1/. It supplies the governed study assets needed before Chapters 6–9 of Psychological Statistics by Design are drafted. It is not part of the public Book 1 companion and does not change the PyPI release version.

make psych-design-swl-s02-s05-verify
make psych-design-swl-s02-s05-r-verify

The first target checks exact regeneration, study IDs, design contracts, result receipts, figure specifications, APA source maps, matched limitations, and source boundaries. The second runs independent base-R analyses and compares them with the Python results. R parity is a governed local gate and is not executed by GitHub-hosted Actions.

For one authoritative command covering all three SWL batches and the current Book 1 companion, prepare the pinned local environment and run:

make PYTHON="$PWD/.venv-psych-design-r/bin/python" local-r-verify

See docs/LOCAL_R_VERIFICATION_POLICY.md and docs/PSYCH_DESIGN_SWL_S02_S05_FIRST_BATCH.md for scope and exclusions.

Second study-specific source batch

The private, synthetic-only SWL-S01, SWL-S06, and SWL-S07 source candidate lives under psych_design_companion/swl_s01_s06_s07_v0_1/. It supplies the association, prediction, complete-case repeated-measures, missing-visit, and baseline-adjusted evidence required before Chapters 10 through 13 may be drafted. It is not a public companion release and does not change the PyPI version.

make psych-design-swl-s01-s06-s07-verify
make psych-design-swl-s01-s06-s07-r-verify

The R target runs locally in the governed Python 3.10 environment; GitHub CI does not install or execute R. See docs/LOCAL_R_VERIFICATION_POLICY.md and docs/PSYCH_DESIGN_SWL_S01_S06_S07_SECOND_BATCH.md for scope and exclusions.

The private, synthetic-only SWL-S08 through SWL-S10 final source candidate lives under psych_design_companion/swl_s08_s10_v0_1/. It supplies the longitudinal mixed-model, outcome/distribution extension, and power/replication/cumulative-evidence assets required before Chapters 14 through 19 may be constructed. It is not a public companion release and does not change the PyPI version.

make psych-design-swl-s08-s10-verify
make psych-design-swl-s08-s10-r-verify

The R target runs locally and requires the nlme R package. GitHub CI remains Python-only. See docs/LOCAL_R_VERIFICATION_POLICY.md and docs/PSYCH_DESIGN_SWL_S08_S10_FINAL_BATCH.md for scope and exclusions.

---

🧪 Development Workflow

From the project root:

make lint    # ruff check
make test    # pytest

To run chapter smoke tests:

make ch13-ci
make ch14-ci
make ch15-ci

All synthetic data is written to:

• data/synthetic/
• outputs/<chapter>/

…and ignored by Git.

---

🔀 Pull Requests

Every pull request should:

• pass make lint and make test,
• avoid committing generated outputs,
• follow the structure described in CONTRIBUTING.md.

GitHub provides:

• 🐛 Bug report template
• 💡 Feature request template
• 📘 Good first issue template
• 🔀 Pull request template

---

🔒 Security

If you believe you’ve found a security issue, do not open a public GitHub issue.
Follow the private disclosure process described in SECURITY.md.

---

💬 Community & support

• Questions?
  Open a GitHub issue with the question label.

• Using PyStatsV1 in a course?
  We’d love to hear about it — open an issue titled Course report: <institution> or mention it in your PR description.

• Feature ideas / chapter requests?
  Open an issue with the enhancement or chapter-idea label.

As the project grows, we plan to enable GitHub Discussions and possibly a lightweight chat space for instructors and contributors.

---

python -m pip install --upgrade pip
python -m pip install "pystatsv1[workbook]"

pystatsv1 workbook init --dest pystatsv1_workbook
pystatsv1 workbook run ch10 --workdir pystatsv1_workbook
pystatsv1 workbook check ch10 --workdir pystatsv1_workbook

Notes:

• No make required. The workbook commands work on Linux, macOS, and Windows.
• workbook check runs pytest (installed via the [workbook] extra).
• If you prefer, you can also run the chapter scripts directly under pystatsv1_workbook/scripts/.

📜 License

MIT © 2025 Nicholas Elliott Karlson