Psych support helpers

PyStatsV1 includes a small pystatsv1.psych helper layer for proof-first psychology examples and companion labs.

The helpers are intentionally modest. They do not replace SciPy, statsmodels, Pingouin, or R for inferential statistics. They provide reusable bridge utilities for package identity receipts, simple group summaries, stable JSON receipts, and numeric parity comparisons.

This supports the PyStatsV1 book-series positioning:

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

Install

For readers using the public package after the v0.23.0 release:

python -m pip install "pystatsv1==0.23.0"

For contributors working from the repository:

python -m pip install -e .

Public helpers

package_identity(): Public helper. Full call signature: package_identity(package_name="pystatsv1", module_name="pystatsv1") Records the imported package name, module name, version, module file, module directory, distribution location, source-kind label, Python executable, and public top-level exports. Companion labs use this to prove which PyStatsV1 package was imported.
describe_by_group(): Public helper. Full call signature: describe_by_group(data, group_col, value_cols, *, decimals=6) Creates JSON-stable descriptive summaries by group for one or more numeric variables. data may be a pandas DataFrame or an iterable of row dictionaries. The returned records include n, mean, sd, min, and max for each group/variable pair.
write_json_receipt(): Public helper. Full call signature: write_json_receipt(path, payload) Writes sorted, indented JSON receipts with a final newline and creates parent directories as needed. The return value is the written Path.
compare_numeric_results(): Public helper. Full call signature: compare_numeric_results(left, right, *, tolerance=1e-6) Compares numeric outputs from two analysis engines and returns a JSON-serializable comparison receipt. Missing values, non-numeric values, pass/fail status, absolute differences, and the stated tolerance are recorded explicitly.

Minimal example

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

rows = [
    {"condition": "control", "score": 1.0},
    {"condition": "control", "score": 3.0},
    {"condition": "planning", "score": 5.0},
    {"condition": "planning", "score": 7.0},
]

identity = package_identity()
descriptives = describe_by_group(rows, "condition", "score", decimals=3)
parity = compare_numeric_results(
    {"mean_difference": 4.0},
    {"mean_difference": 4.0000001},
    tolerance=1e-5,
)

write_json_receipt(
    "outputs/pystatsv1_psych_receipt.json",
    {
        "identity": identity,
        "descriptives": descriptives,
        "parity": parity,
    },
)

Honest computation-source story

The helper layer is a bridge, not a replacement for statistical libraries. In the APA Article Lab pattern, PyStatsV1 records package identity, descriptive summaries, JSON receipts, and numeric comparison receipts. SciPy, statsmodels, Pingouin, and R remain the appropriate sources for many inferential procedures and independent verification checks.