学生代码实验包：从“能运行”到“能比较”

本包提供配套的 Python 与 R 实验。中文讲解帮助理解研究问题；英文代码注释说明操作目的和计算约定。先阅读本说明，再按实验任务单提出预测、运行、记录和解释。

数据与适用边界

所有员工记录均为合成教学数据。固定 720 行，其中训练 540 行、验证 180 行。
本包没有最终测试集、测试标签、测试结果或最终评估入口。所有调参、早停、特征比较与阈值选择都是开发过程。
验证分数不能作为独立最终性能，也不能证明构念效度、因果效应或真实组织适用性。不要用于现实员工判断。
本包是独立的七特征、单隐层模型（7→h→1）。网页的两输入、双隐层 JavaScript 演示使用不同模型与数据，不能直接对齐数值。
无需账号、API 密钥、GPU 或在线服务。代码不上传数据。

运行前准备

先解压整个 student-lab 文件夹，保留目录结构。下列命令均在该文件夹运行。数据含义见 data/data_dictionary.csv。

Python 依赖仅为 NumPy 与 pandas；requirements.txt 固定依赖版本。建议使用 Python 3.11 或 3.12。安装与运行：

python -m pip install -r requirements.txt
python student/selfcheck_python.py
python student/starter_python.py
python student/experiments_python.py

也可以用入口脚本的绝对路径运行。已有 Jupyter 环境时，在本目录或 student 子目录打开 student/starter_python.ipynb。请选择已安装 NumPy/pandas 的内核，按顺序运行各单元。Notebook 的结果会在运行后显示；Jupyter 不包含在最小依赖中。

R 仅需 base R。命令行运行：

Rscript student/selfcheck_R.R
Rscript student/starter_R.R
Rscript student/experiments_R.R

在 RStudio 中先将工作目录设为 student-lab，再使用：

source('student/selfcheck_R.R')
source('student/starter_R.R')
source('student/experiments_R.R')

三个层次

入门：一次改变一个设置。 starter_python.py / starter_R.R 运行默认网络并保存一行指标和完整曲线。只改文件顶部的 HIDDEN、LEARNING_RATE 或 L2 之一。
比较：有控制条件的实验。 experiments_python.py / experiments_R.R 自动运行常数概率基线、逻辑回归、默认神经网络，以及六个单因素变体，并扫描同一组概率的分类阈值。
进阶：检查解释与实现。 Notebook 提供标准化核查、保留轮次分析、受控特征消融和证据记录。计算检查涵盖指标边界、阈值性质、梯度或训练保留逻辑。详见任务单。

输出在哪里？

每次运行会创建独立目录，避免无声覆盖旧记录。

入门：outputs/python_single/<运行标识>/ 或 outputs/r_single/<运行标识>/
完整比较：outputs/python/<运行标识>/ 或 outputs/r/<运行标识>/
包内不预存运行输出。请自行运行，先写预期再查看结果。

完整比较写出五个 CSV：

文件	内容	用途
`comparison.csv`	9 个候选、设置、保留/停止轮次、验证指标、保留模型的训练/验证损失	比较基线与单因素变化
`learning_curves.csv`	8 个可训练候选的逐轮训练/验证交叉熵	观察收敛、分叉与停止；常数基线没有训练曲线
`thresholds.csv`	同一默认网络概率在 5 个阈值的指标与示例成本	区分概率预测与决策规则
`scaling.csv`	七个特征的训练均值与总体标准差	核查预处理来源
`val_predictions.csv`	180 条合成验证记录的标签及三个基线模型的概率	独立复算指标；这些仍是开发标签

comparison.csv 与 thresholds.csv 的 split=development_validation 明确标识分数用途。预测文件保留数据原有的 split=val。入门运行只保存前两类文件。Notebook 还会保存可填写的比较记录和特征消融结果。

固定算法约定

连续与离散特征一并标准化；均值与总体标准差仅由训练集估计。验证集应用相同参数。
神经网络：tanh 隐层、sigmoid 输出、完整批次梯度下降。逻辑回归没有隐层。
训练目标：平均二元交叉熵 + (L2/2) × 权重平方和。偏置不受 L2 惩罚。CSV 曲线显示未加惩罚的交叉熵。
默认值：隐藏单元 8、学习率 0.05、L2 0.001、最多更新 1500 轮、耐心轮次 160、最小改进 0.00001。
第 0 轮是尚未更新的参数。验证损失低于“当前保留值减去 0.00001”时保留参数；否则增加等待计数。达到耐心轮次或上限后返回保留参数。
best_epoch 是被保留参数的轮次，stop_epoch 是运行结束轮次。保留轮次不一定是原始曲线数值最小的轮次，因为存在最小改进容差。
三份初始化 CSV 固定了 4/8/16 隐藏单元的初值。Python/R 共用这些初值；不能修改初值后仍声称只改变了一个因素。一次固定初始化也不能代表所有初始化。
默认阈值 0.5 只作教学设置。概率大于或等于阈值时预测为 1。
精确率等分母为零时返回 0，这是软件约定，不是数学上有定义。AUC 遇到单类别返回 NaN/NA。
阈值实验的假阳性成本 1、假阴性成本 3 是假设值；单位记录成本为 (FP + 3×FN)/n，不代表真实金钱或组织政策。

文档和代码地图

GUIDED_EXPERIMENTS_中文.md：研究问题、操作步骤、可观察量与思考
COMMENT_GUIDE_中文.md：代码术语表与阅读提示
comparison_notes_template.csv：填写研究问题、预测、比较和限制
python/core_lab.py、r/core_functions.R：数据、模型、指标与训练逻辑
python/experiment_lab.py：Python 受控比较与 CSV 导出
student/：入门、全实验、计算检查与 Notebook 入口
data/：合成开发数据、数据字典、共享初始化

不要只交截图或最高分。请交可复现设置、CSV、比较解释和证据边界。