三种编辑器共用Cas9结构的distance初筛（2026-10-06）

范围
用户已确认三种编辑器使用相同Cas9。本包在既有Cas9–sgRNA–DNA结构层级复用distance。
不声称完整融合编辑器的构象相同，也不预测TadA/连接肽导致的结构变化。
TeABE和D699独立训练；本包不是编辑器类别输入的联合模型，也不是CRISPRon-BE神经网络重训。
select_distance_features.py和summarize_selection.py原样沿用ABE8e初筛包。

直接运行（无需重新整理原始数据）
cd /public/home/GENE_proc/wth/crispron-BE
unzip multi_editor_distance_selection.zip -d scripts
bash scripts/multi_editor_distance_selection/run_TeABE.sh data/ABE8e_short_sgRNA/af3_four_distances/distance_per_model.tsv data/ABE8e_short_sgRNA/af3_four_distances/structure_audit.tsv res/TeABE_distance_feature_selection
bash scripts/multi_editor_distance_selection/run_D699.sh data/ABE8e_short_sgRNA/af3_four_distances/distance_per_model.tsv data/ABE8e_short_sgRNA/af3_four_distances/structure_audit.tsv res/D699_distance_feature_selection
两个脚本可以提交到两个CPU作业。每个脚本顺序运行clean、all并汇总。
Python依赖：numpy、pandas、scipy、scikit-learn。无需GPU。
重新从原始xlsx/allele数据整理时额外需要openpyxl。
可在三个必需参数后追加自己的outcomes.tsv路径以替换包内预筛数据。

候选与评估
baseline：30nt序列one-hot、8位产物编辑组合、编辑数、长度组编码、CRISPRoff/CRISPRon评分。
四种绝对distance、四种相对L20的Δdistance，每次只加一种，均含20位曲线和8位编辑组合交互项。
长度编码沿用既有模型表中的20/18/16，代表L20/L18_19/L16_17三组；不是声称所有实际guide均精确为这些长度。
模型：HistGradientBoostingRegressor，150轮，其他参数与ABE8e相同。
外层12折LOTO，内层3折GroupKFold，target的全部长度/outcome始终同组。
训练每个条件的总权重相同；选择标准是条件/target等权MAE，单位为百分点。
预测裁剪至0–100，条件内预测总和大于100时同比缩放，不读取实验总体编辑效率。
clean剔除任一1–20位跨链C–C<2Å的整个候选结构；all保留全部结构。
两种编辑器均从同一个distance文件获取特征；Δdistance参照同一target的共用L20结构。
本次没有比较多种distance同时输入，也没有将SD作为模型特征。

标签口径与来源
原始文件：truncated sgRNA.zip中的sgRNA编号.xlsx及Alleles_frequency_table_around_sgRNA_*.txt。
编号表决定编辑器和长度组，目录和guide名称交叉核对target，目标序列来自既有canonical表。
TeABE = TeABE(49-64)(400-1-1249-1264-MU148）；D699 = D699-CBH-N-8E-D53R-2AG。
记录每条allele在完整20nt target第3–10位的A→G事件，编码为8位mask。
与旧prepare_abe8e_outcome_dataset_v3.py一致，使用原表%Reads加和，不在编辑reads中重新归一化。
不排除额外替换/indel；同一A→G组合可以包含其它变化，故这里是窗口编辑组合频率，不是纯净全长产物频率。
部分窗口未覆盖的allele沿用旧代码：未覆盖位bit=0；其频率比例逐样本记入sample_qc.tsv。
未编辑mask不作为候选；枚举所有非空A→G组合，包括观测频率为0的组合。
每份样本先计算频率，再对include=1的样本等权平均。SD是样本间SD，不能直接视为独立生物重复SD。
新表不复制ABE8e的实验频率、总体编辑效率或旧distance列。

必须记录的样本身份不确定性
目前默认使用编号表中该条件的全部已标注样本，是用于初筛的明确暂定规则。
TeABE：112份样本；D699：111份样本；各36条件、984条outcome。
多数条件3份样本，以下4个新编辑器条件需确认是否有重测/替换关系：
TeABE PT13 L16_17：6U96,6U97,6V17,6V18,6W68,6W69（6份）。
TeABE S18 L16_17：6V40,6V41,6U104,6W76（4份）。
D699 PT13 L18_19：6U61,6U62,6U63,6W64（4份）。
D699 S18 L16_17：6V42,6V43,6V44,6U105,6W77（5份）。
本包没有根据编辑效率或预测成绩挑选其中3份。当前结果只能用于预筛；正式跨编辑器结论需要先确认样本身份。
若是替换样本，在sample_manifest.tsv中将被替换样本include设为0；若是同一生物样本的技术重复，需要按实际重复关系合并，不能简单当作独立生物重复。

重新整理数据
python scripts/multi_editor_distance_selection/prepare_editor_outcomes.py --allele-zip "/path/to/truncated sgRNA.zip" --template scripts/multi_editor_distance_selection/data/ABE8e_canonical_reference.tsv --manifest scripts/multi_editor_distance_selection/data/sample_manifest.tsv --outdir data/multi_editor_outcomes
运行时将上述新outdir中的TeABE_outcomes.tsv或D699_outcomes.tsv作为run脚本第4个参数。
本包附带ABE8e重构QC：34个条件与canonical数值一致，PT13 L18_19和S18 L16_17因额外样本均值而不同。
ABE8e_reconstructed_for_qc.tsv仅用于核对，不替换已经确认的ABE8e canonical标签或既有筛选结果。

合并三编辑器结果
python scripts/multi_editor_distance_selection/compare_editors.py --results ABE8e=res/ABE8e_distance_feature_selection TeABE=res/TeABE_distance_feature_selection D699=res/D699_distance_feature_selection --outdir res/editor_distance_comparison
输出editor_comparison.tsv、editor_choices_by_fold.tsv、editor_metrics_by_length.tsv。
跨编辑器重点比较各自相对baseline的改善和选择稳定性；不能仅凭某编辑器绝对MAE较小判断它更容易预测。
选中distance表示当前回归器下的预测优势，不是编辑器作用机制或因果重要性。

验证范围
已从原始文件生成两种编辑器的完整标签，并验证序列一致性、条件覆盖、重复文件和标签重构。
TeABE与D699各做clean/all的单个外层fold试运行（仍用150轮），并测试汇总接口。
未把这些单折成绩作为最佳distance结论；服务器默认执行完整12折。
