Skip to content

mecfs_bio.build_system.task.fast_ct_ldsc.alignment_guards

Fail-fast guards against upstream harmonization bugs in a trait aligned for fast CT-LDSC.

The trait is joined to the HapMap3 regression SNPs by rsID, so a trait whose rsIDs were assigned wrongly upstream (for example from positions in the wrong genome build) would silently yield z-scores for the wrong variants. Three diagnostics expose that, all over the context SNP set:

  • coverage = n_matched / n_context: the fraction of context SNPs the trait supplies with alleles that match the index (directly or swapped).
  • allele_mismatch_fraction = (n_found - n_matched) / n_found: among context rsIDs the trait carries, the fraction whose alleles do not match the index. Correct rsIDs mismatch well under 1%; rsIDs pointing at the wrong variant mismatch at a large rate.
  • position_concordance = n_position_concordant / n_position_compared: among matched SNPs with a trait position, the fraction whose (CHR, POS) equals the index's hg19 position. Only meaningful when the trait declares build 19, so the guard is applied only then.

Classes:

  • AlignmentDiagnostics –

    Counts from aligning one trait to the context SNP set, plus the trait's declared build.

  • AlignmentGuards –

    Thresholds for the alignment diagnostics; each lies in [0, 1].

Functions:

AlignmentDiagnostics

Counts from aligning one trait to the context SNP set, plus the trait's declared build.

Methods:

Attributes:

allele_mismatch_fraction property 

allele_mismatch_fraction: float

coverage property 

coverage: float

declared_build instance-attribute 

declared_build: GenomeBuild | None

n_context instance-attribute 

n_context: int

n_found instance-attribute 

n_found: int

n_matched instance-attribute 

n_matched: int

n_position_compared instance-attribute 

n_position_compared: int | None

n_position_concordant instance-attribute 

n_position_concordant: int | None

position_concordance property 

position_concordance: float | None

from_json_dict classmethod 

from_json_dict(
    d: dict[str, int | str | None],
) -> AlignmentDiagnostics
Source code in mecfs_bio/build_system/task/fast_ct_ldsc/alignment_guards.py 
 95
 96
 97
 98
 99
100
101
102
103
104
@classmethod
def from_json_dict(cls, d: dict[str, int | str | None]) -> AlignmentDiagnostics:
    return cls(
        n_context=_as_int(d["n_context"]),
        n_found=_as_int(d["n_found"]),
        n_matched=_as_int(d["n_matched"]),
        n_position_compared=_as_optional_int(d["n_position_compared"]),
        n_position_concordant=_as_optional_int(d["n_position_concordant"]),
        declared_build=_as_optional_build(d["declared_build"]),
    )

to_json_dict 

to_json_dict() -> dict[str, int | str | None]
Source code in mecfs_bio/build_system/task/fast_ct_ldsc/alignment_guards.py 
85
86
87
88
89
90
91
92
93
def to_json_dict(self) -> dict[str, int | str | None]:
    return {
        "n_context": self.n_context,
        "n_found": self.n_found,
        "n_matched": self.n_matched,
        "n_position_compared": self.n_position_compared,
        "n_position_concordant": self.n_position_concordant,
        "declared_build": self.declared_build,
    }

AlignmentGuards

Thresholds for the alignment diagnostics; each lies in [0, 1].

The defaults leave wide margin around the values observed on the 13 traits of the initial genetic correlation study (experiments/claude/fast_ct_ldsc_vs_gwaslab): coverage 0.954 to 0.999, allele_mismatch_fraction at most 0.0007, and position_concordance at least 0.99999.

Attributes:

max_allele_mismatch_fraction class-attribute instance-attribute 

max_allele_mismatch_fraction: float = 0.01

min_coverage class-attribute instance-attribute 

min_coverage: float = 0.8

min_position_concordance class-attribute instance-attribute 

min_position_concordance: float = 0.99

alignment_diagnostics 

alignment_diagnostics(
    aligned: TraitAligned,
    declared_build: GenomeBuild | None,
) -> AlignmentDiagnostics
Source code in mecfs_bio/build_system/task/fast_ct_ldsc/alignment_guards.py 
125
126
127
128
129
130
131
132
133
134
135
def alignment_diagnostics(
    aligned: TraitAligned, declared_build: GenomeBuild | None
) -> AlignmentDiagnostics:
    return AlignmentDiagnostics(
        n_context=int(aligned.z.shape[0]),
        n_found=aligned.n_found,
        n_matched=aligned.n_matched,
        n_position_compared=aligned.n_position_compared,
        n_position_concordant=aligned.n_position_concordant,
        declared_build=declared_build,
    )

check_alignment_guards 

check_alignment_guards(
    diagnostics: AlignmentDiagnostics,
    guards: AlignmentGuards,
    alias: str,
) -> None

Assert, in order, the coverage, allele-mismatch and (build 19 only) position guards.

Source code in mecfs_bio/build_system/task/fast_ct_ldsc/alignment_guards.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
def check_alignment_guards(
    diagnostics: AlignmentDiagnostics, guards: AlignmentGuards, alias: str
) -> None:
    """Assert, in order, the coverage, allele-mismatch and (build 19 only) position guards."""
    assert diagnostics.coverage >= guards.min_coverage, (
        f"{alias}: coverage {diagnostics.coverage:.4f} of the HapMap3 regression SNPs is below "
        f"min_coverage={guards.min_coverage}; check the trait's rsID assignment"
    )
    assert (
        diagnostics.allele_mismatch_fraction <= guards.max_allele_mismatch_fraction
    ), (
        f"{alias}: allele_mismatch_fraction {diagnostics.allele_mismatch_fraction:.4f} exceeds "
        f"max_allele_mismatch_fraction={guards.max_allele_mismatch_fraction}; the trait's rsIDs "
        "likely point at the wrong variants (e.g. assigned from the wrong genome build)"
    )
    concordance = diagnostics.position_concordance
    if diagnostics.declared_build == "19" and concordance is not None:
        assert concordance >= guards.min_position_concordance, (
            f"{alias}: position_concordance {concordance:.4f} with the hg19 index is below "
            f"min_position_concordance={guards.min_position_concordance}, although the trait "
            "declares build 19; the declared build is likely wrong"
        )