Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@

In development

- Each `[match.sources.<name>]` section accepts a `recombination_rate`
(a constant rate per bp, or a HapMap genetic map file), `mismatch` and
`likelihood_threshold`, setting the parameters of the matching HMM.
Unlike tsinfer 0.5.1 there is no `mismatch_ratio`: the mismatch
probability is set directly.

- Contig metadata is read from `variant_contig`, rather than assuming the first
contig in the header, and the top-level `contig` config option selects one
contig from multi-contig VCZ stores.
Expand Down
34 changes: 34 additions & 0 deletions docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,40 @@ sequence needs an entry here.
|-------|------|---------|-------------|
| `node_flags` | int | 1 | tskit node flags (`1` = `NODE_IS_SAMPLE`, `0` for ancestors) |
| `create_individuals` | bool | `true` | Group sample nodes into tskit individuals |
| `recombination_rate` | float or string | — | Recombination rate per bp per generation, or the path to a HapMap genetic map (see below). Cannot be combined with `recombination`. |
| `recombination` | float | `0.01` | Probability of recombination between each pair of adjacent inference sites |
| `mismatch` | float | `1e-20` | Probability of a mismatch (an extra mutation) at each inference site |
| `likelihood_threshold` | float | smallest positive double | Lower bound on the normalised HMM likelihoods. Larger values (e.g. `1e-13`) let more likelihoods be merged, making matching faster at some cost in accuracy |

These are the parameters of the Li & Stephens copying HMM used to match each
haplotype from the source. The defaults (a high recombination probability and a
negligible mismatch probability) mean that haplotypes are copied exactly, using
recombination rather than extra mutations to explain differences.

When `recombination_rate` is given, the genetic distance *d* (in Morgans)
between adjacent inference sites is converted to a recombination probability
using Haldane's map function, (1 - exp(-2*d)) / 2. A genetic map file is in
HapMap format: a single header line followed by whitespace-separated columns
giving the chromosome, position (bp), rate (cM/Mb) and cumulative map
position (cM). Only the position and map columns are used. The map is
linearly interpolated between entries, starts at 0 cM at position 0, and
has zero recombination rate beyond the last entry.

The mismatch probability is not derived from the recombination rate, so
setting `recombination_rate` on its own still allows no mismatches; set
`mismatch` as well to allow them. For example:

```toml
[match.sources.ancestors]
node_flags = 0
create_individuals = false
recombination_rate = "maps/chr20.txt"
mismatch = 1e-10

[match.sources.cohort]
recombination_rate = "maps/chr20.txt"
mismatch = 1e-4
```


## `[post_process]`
Expand Down
116 changes: 116 additions & 0 deletions tests/test_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -1346,3 +1346,119 @@ def test_config_format_optional_fields(self):
text = cfg.format()
assert "regions" in text
assert "targets" in text


class TestMatchHmmParameters:
def _load(self, tmp_path, ancestors_extra, cohort_extra=""):
toml = _STANDARD_TOML.replace(
"create_individuals = false\n",
"create_individuals = false\n" + ancestors_extra,
).replace(
"[match.sources.cohort]\n",
"[match.sources.cohort]\n" + cohort_extra,
)
return config.Config.from_toml(_write_toml(tmp_path, toml))

def test_defaults(self, tmp_path):
cfg = self._load(tmp_path, "")
src = cfg.match.sources["cohort"]
assert src.recombination is None
assert src.recombination_rate is None
assert src.mismatch is None
assert src.likelihood_threshold is None

def test_parse_values(self, tmp_path):
cfg = self._load(
tmp_path,
"recombination_rate = 1e-8\nmismatch = 1e-10\n",
'recombination_rate = "maps/chr20.txt"\nmismatch = 1e-4\n'
"likelihood_threshold = 1e-12\n",
)
anc = cfg.match.sources["ancestors"]
assert anc.recombination_rate == 1e-8
assert anc.mismatch == 1e-10
assert anc.likelihood_threshold is None
cohort = cfg.match.sources["cohort"]
assert cohort.recombination_rate == "maps/chr20.txt"
assert cohort.mismatch == 1e-4
assert cohort.likelihood_threshold == 1e-12

def test_integer_rate_becomes_float(self, tmp_path):
cfg = self._load(tmp_path, "recombination_rate = 0\n")
rate = cfg.match.sources["ancestors"].recombination_rate
assert isinstance(rate, float)
assert rate == 0

def test_parse_recombination(self, tmp_path):
cfg = self._load(tmp_path, "recombination = 0.1\n")
assert cfg.match.sources["ancestors"].recombination == 0.1

def test_recombination_and_rate_exclusive(self, tmp_path):
with pytest.raises(ValueError, match="both 'recombination' and"):
self._load(tmp_path, "recombination = 0.1\nrecombination_rate = 1e-8\n")

def test_direct_construction_exclusive(self):
with pytest.raises(ValueError, match="both 'recombination' and"):
config.MatchSourceConfig(recombination=0.1, recombination_rate=1e-8)

def test_format(self):
sources = {
"ancestors": config.MatchSourceConfig(
node_flags=0, recombination_rate="map.txt", mismatch=1e-6
),
"cohort": config.MatchSourceConfig(
recombination=0.01, likelihood_threshold=1e-9
),
}
text = _minimal_config(match=_minimal_match_cfg(sources=sources)).format()
assert "recombination_rate = map.txt" in text
assert "mismatch = 1e-06" in text
assert "recombination = 0.01" in text
assert "likelihood_threshold = 1e-09" in text

def test_format_omits_unset(self):
text = _minimal_config().format()
assert "recombination" not in text
assert "mismatch" not in text

def _validate_with_rate(self, tmp_path, rate):
vcz_path = _write_sample_vcz(tmp_path)
sources = {
"ancestors": config.MatchSourceConfig(node_flags=0),
"cohort": config.MatchSourceConfig(recombination_rate=rate),
}
cfg = config.Config(
sources={
"cohort": config.Source(path=vcz_path, name="cohort"),
"ancestors": config.Source(
path=tmp_path / "ancestors.vcz",
name="ancestors",
sample_time="sample_time",
),
},
ancestors=[
config.AncestorsConfig(
name="ancestors",
path=tmp_path / "ancestors.vcz",
sources=["cohort"],
)
],
match=_minimal_match_cfg(sources=sources),
ancestral_state=config.AncestralState(
path=vcz_path, field="variant_ancestral_allele"
),
)
return cfg.validate()

def test_validate_missing_map(self, tmp_path):
errors = self._validate_with_rate(tmp_path, str(tmp_path / "nope.txt"))
assert len(errors) == 1
assert "recombination_rate path does not exist" in errors[0]

def test_validate_existing_map(self, tmp_path):
map_path = tmp_path / "map.txt"
map_path.write_text("header\n")
assert self._validate_with_rate(tmp_path, map_path) == []

def test_validate_float_rate(self, tmp_path):
assert self._validate_with_rate(tmp_path, 1e-8) == []
4 changes: 3 additions & 1 deletion tests/test_matcher_fixtures.py
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,9 @@ def _match(ts, positions, query, allele_mapper):
ts,
positions,
allele_mapper=allele_mapper,
source_parameters={"test": config.MatchSourceConfig()},
hmm_parameters={
"test": matching.hmm_parameters(config.MatchSourceConfig(), positions)
},
)
results = list(matcher.match([job], _ArrayReader([query])))
_, r = results[0]
Expand Down
Loading
Loading