Core API

pen_compare.core.certify

Hierarchical TrueWriter tier classifier (v3.2).

Applies the 5 TrueWriterScore gates per config/gates_v3.yaml (SHA-256 locked). G1 is the necessary gate: failing it auto-classifies as NOT_WRITER regardless of all other gates. G2–G5 are qualifying gates; tier depends on how many pass and whether cell_based is in the evidence set.

class pen_compare.core.certify.TrueWriterResult(editor_id: 'str', tier: 'str', necessary_gates_passed: 'int', qualifying_gates_passed: 'int', has_cell_based_evidence: 'bool', gate_results: 'tuple[GateResult, ...]', auto_demoted: 'bool', auto_demote_reason: 'str | None')[source]

Bases: object

Parameters:

  • editor_id (str)

  • tier (str)

  • necessary_gates_passed (int)

  • qualifying_gates_passed (int)

  • has_cell_based_evidence (bool)

  • gate_results (tuple[GateResult, ...])

  • auto_demoted (bool)

  • auto_demote_reason (str | None)

editor_id: str
tier: str
necessary_gates_passed: int
qualifying_gates_passed: int
has_cell_based_evidence: bool
gate_results: tuple[GateResult, ...]
auto_demoted: bool
auto_demote_reason: str | None
pen_compare.core.certify.certify(editor_id, s_dsb, s_prog, s_cargo, length_aa, evidence_sources, intrinsic_cargo_mechanism, split_aav_eligible=False, g1_threshold=None, g2_threshold=None, g3_threshold=None, g4_size_max=900)[source]

Apply 5-gate hierarchical certification.

Tier ladder (v3.2):

TRUE_WRITER — G1 pass + all 4 qualifying pass + cell_based in evidence PROBABLE_WRITER — G1 pass + (4 qualifying, no cell_based) OR (3 qualifying + cell_based) EMERGING_WRITER — G1 pass + 1–2 qualifying pass NOT_WRITER — G1 FAILS (auto-demote, final) OR 0 qualifying pass

Parameters:

  • editor_id (str)

  • s_dsb (float)

  • s_prog (float)

  • s_cargo (float)

  • length_aa (int | None)

  • evidence_sources (list[str])

  • intrinsic_cargo_mechanism (bool)

  • split_aav_eligible (bool)

  • g1_threshold (float | None)

  • g2_threshold (float | None)

  • g3_threshold (float | None)

  • g4_size_max (int)

Return type:

TrueWriterResult

pen_compare.core.gates

5 TrueWriterScore gate functions: 1 necessary + 4 qualifying.

All thresholds come from config/gates_v3.yaml (SHA-256 locked at pre-registration).

class pen_compare.core.gates.GateRole(value)[source]

Bases: Enum

An enumeration.

NECESSARY = 'necessary'
QUALIFYING = 'qualifying'
class pen_compare.core.gates.GateResult(gate_id: 'str', name: 'str', role: 'GateRole', passes: 'bool', observed_value: 'float | None', threshold: 'float | None', rationale: 'str')[source]

Bases: object

Parameters:
gate_id: str
name: str
role: GateRole
passes: bool
observed_value: float | None
threshold: float | None
rationale: str
pen_compare.core.gates.gate_1_dsb(s_dsb, threshold=None)[source]

NECESSARY gate — DSB Avoidance. Failing auto-classifies as NOT_WRITER.

Parameters:
Return type:

GateResult

pen_compare.core.gates.gate_2_programmability(s_prog, threshold=None)[source]

QUALIFYING gate — Programmability.

Parameters:
Return type:

GateResult

pen_compare.core.gates.gate_3_native_cargo(s_cargo, intrinsic_cargo_mechanism, threshold=None)[source]

QUALIFYING gate — Native Cargo Capability.

Requires BOTH S_Cargo >= threshold AND intrinsic_cargo_mechanism=True. HDR-template-based cargo (SpCas9) does not satisfy intrinsic_cargo_mechanism.

Parameters:

  • s_cargo (float)

  • intrinsic_cargo_mechanism (bool)

  • threshold (float | None)

Return type:

GateResult

pen_compare.core.gates.gate_4_deliverability(length_aa, split_aav_eligible=False, size_max=900)[source]

QUALIFYING gate — Deliverability (AAV-compatible size).

Passes if length_aa <= size_max OR split_aav_eligible. When length_aa is None (not yet annotated), passes if split_aav_eligible=True.

Parameters:

  • length_aa (int | None)

  • split_aav_eligible (bool)

  • size_max (int)

Return type:

GateResult

pen_compare.core.gates.gate_5_evidence(evidence_sources)[source]

QUALIFYING gate — Evidence (≥ 2 eligible sources).

Parameters:

evidence_sources (list[str])

Return type:

GateResult

pen_compare.core.sensitivity

Sensitivity analysis — 18,000 threshold combinations per entity.

Replaces fabricated-sigma bootstrap. Each entity is certified under every combination of the pre-registered sensitivity grid and a robustness fraction is reported: fraction of combinations that agree with the modal tier.

pen_compare.core.sensitivity.sensitivity_for_entity(row, grid={'g1_threshold': [0.85, 0.86, 0.87, 0.88, 0.89, 0.9, 0.91, 0.92, 0.93, 0.94, 0.95, 0.96, 0.97, 0.98, 0.99, 1.0], 'g2_threshold': [0.85, 0.86, 0.87, 0.88, 0.89, 0.9, 0.91, 0.92, 0.93, 0.94, 0.95, 0.96, 0.97, 0.98, 0.99, 1.0], 'g3_threshold': [0.8, 0.81, 0.82, 0.83, 0.84, 0.85, 0.86, 0.87, 0.88, 0.89, 0.9, 0.91, 0.92, 0.93, 0.94, 0.95], 'g4_size_max': [600, 750, 900, 1050, 1200]})[source]

Run 18,000 certifications for one entity; return robustness metrics.

Parameters:
Return type:

dict

pen_compare.core.sensitivity.build_sensitivity_rows(universe, scorecard)[source]

Merge universe + scorecard into flat dicts ready for sensitivity_for_entity.

Parameters:

  • universe (DataFrame)

  • scorecard (DataFrame)

Return type:

list[dict]

pen_compare.core.sensitivity.run_sensitivity_parallel(universe, scorecard, n_jobs=24, grid={'g1_threshold': [0.85, 0.86, 0.87, 0.88, 0.89, 0.9, 0.91, 0.92, 0.93, 0.94, 0.95, 0.96, 0.97, 0.98, 0.99, 1.0], 'g2_threshold': [0.85, 0.86, 0.87, 0.88, 0.89, 0.9, 0.91, 0.92, 0.93, 0.94, 0.95, 0.96, 0.97, 0.98, 0.99, 1.0], 'g3_threshold': [0.8, 0.81, 0.82, 0.83, 0.84, 0.85, 0.86, 0.87, 0.88, 0.89, 0.9, 0.91, 0.92, 0.93, 0.94, 0.95], 'g4_size_max': [600, 750, 900, 1050, 1200]})[source]

Run sensitivity analysis in parallel; return results DataFrame.

Parameters:

  • universe (DataFrame)

  • scorecard (DataFrame)

  • n_jobs (int)

  • grid (dict)

Return type:

DataFrame