first pass

update documentation and float k values

Author: hossam26644

docs/api.md

@@ -21,8 +21,7 @@ for discussion and examples of individual features.
   sim_ancestry
   SampleSet
   StandardCoalescent
-  SmcApproxCoalescent
-  SmcPrimeApproxCoalescent
+  SmcKApproxCoalescent
   DiscreteTimeWrightFisher
   FixedPedigree
   BetaCoalescent

msprime/ancestry.py

@@ -67,8 +67,8 @@ def _model_factory(model: None | str | AncestryModel) -> AncestryModel:
     """
     model_map = {
         "hudson": StandardCoalescent(),
-        "smc": SmcApproxCoalescent(),
-        "smc_prime": SmcPrimeApproxCoalescent(),
+        "smc": SmcKApproxCoalescent(hull_offset=0.0),
+        "smc_prime": SmcKApproxCoalescent(hull_offset=1.0),
         "dtwf": DiscreteTimeWrightFisher(),
         "fixed_pedigree": FixedPedigree(),
     }
@@ -1799,8 +1799,6 @@ class SmcApproxCoalescent(AncestryModel):
         and so it may not be any more efficient to simulate than the
         standard Hudson model.
         We recommend using the ``SmcKApproxCoalescent(hull_offset=0)`` instead
-
-    The string ``"smc"`` can be used to refer to this model.
     """
 
     name = "smc"
@@ -1824,7 +1822,6 @@ class SmcPrimeApproxCoalescent(AncestryModel):
         standard Hudson model. We recommend using the
         ``SmcKApproxCoalescent(hull_offset=1)`` instead.
 
-    The string ``"smc_prime"`` can be used to refer to this model.
     """
 
     name = "smc_prime"
@@ -1851,17 +1848,22 @@ class SmcKApproxCoalescent(ParametricAncestryModel):
     segments can share a common ancestor, which is equivalent to the standard Hudson
     coalescent.
 
+    The string ``"smc"`` can be used to refer to this model with a `` hull_offset=0``.
+
+    The string ``"smc_prime"`` can be used to refer to this model with a
+    `` hull_offset=1``.
+
     :param float hull_offset: Determines the maximum distance between genomic tracts
         of ancestral material that can be joined by a common ancestor event.
-        Defaults to 0 (equivalent to the SMC model).
+
     """
 
     name = "smc_k"
 
     hull_offset: float
 
     # We have to define an __init__ to enforce keyword-only behaviour
-    def __init__(self, *, duration=None, hull_offset=0.0):
+    def __init__(self, *, hull_offset, duration=None):
         self.duration = duration
         self.hull_offset = hull_offset
 

tests/test_ancestry.py

@@ -1453,7 +1453,7 @@ def test_model(self):
         # Extensive testing of the model parsing is done elsewhere.
         sim = ancestry._parse_sim_ancestry(10, model="smc")
         assert len(sim.models) == 1
-        assert isinstance(sim.models[0], msprime.SmcApproxCoalescent)
+        assert isinstance(sim.models[0], msprime.SmcKApproxCoalescent)
         assert sim.models[0].duration is None
 
         sim = ancestry._parse_sim_ancestry(
@@ -3052,7 +3052,7 @@ class TestSMCK:
     def test_discrete(self, seed):
         tss = msprime.sim_ancestry(
             samples=10,
-            model=msprime.SmcKApproxCoalescent(),
+            model=msprime.SmcKApproxCoalescent(hull_offset=1),
             recombination_rate=0.005,
             sequence_length=1000,
             random_seed=seed,
@@ -3064,7 +3064,7 @@ def test_discrete(self, seed):
     def test_continuous(self):
         tss = msprime.sim_ancestry(
             samples=10,
-            model=msprime.SmcKApproxCoalescent(),
+            model=msprime.SmcKApproxCoalescent(hull_offset=1),
             recombination_rate=0.005,
             sequence_length=1000,
             num_replicates=10,
@@ -3086,7 +3086,7 @@ def test_ancient_samples(self):
         ts = msprime.sim_ancestry(
             initial_state=tables,
             population_size=10_000,
-            model=msprime.SmcKApproxCoalescent(),
+            model=msprime.SmcKApproxCoalescent(hull_offset=1),
             recombination_rate=1e-6,
         )
         for tree in ts.trees():
@@ -3098,7 +3098,7 @@ def test_model_switch(self):
             population_size=10_000,
             model=[
                 msprime.StandardCoalescent(duration=10),
-                msprime.SmcKApproxCoalescent(duration=10),
+                msprime.SmcKApproxCoalescent(hull_offset=1, duration=10),
                 msprime.StandardCoalescent(),
             ],
             random_seed=10,
@@ -3114,7 +3114,7 @@ def test_model_switch_high_rec(self):
             population_size=10_000,
             model=[
                 msprime.StandardCoalescent(duration=100),
-                msprime.SmcKApproxCoalescent(),
+                msprime.SmcKApproxCoalescent(hull_offset=1),
             ],
             random_seed=10,
             recombination_rate=1e-4,
@@ -3149,7 +3149,7 @@ def test_two_pops(self):
         ts = msprime.sim_ancestry(
             samples={0: 2, 1: 2},
             demography=demography,
-            model=msprime.SmcKApproxCoalescent(),
+            model=msprime.SmcKApproxCoalescent(hull_offset=1),
             random_seed=74024,
             recombination_rate=1e-5,
             sequence_length=100,
@@ -3166,7 +3166,7 @@ def test_gc(self):
         ):
             msprime.sim_ancestry(
                 samples=10,
-                model=msprime.SmcKApproxCoalescent(),
+                model=msprime.SmcKApproxCoalescent(hull_offset=1),
                 sequence_length=100,
                 gene_conversion_rate=1.0,
                 gene_conversion_tract_length=5,

tests/test_demography.py

@@ -2521,7 +2521,7 @@ class TestMigrationRecordsSmcPrime(MigrationRecordsMixin):
 
 
 class TestMigrationRecordsSmcK(MigrationRecordsMixin):
-    model = msprime.SmcKApproxCoalescent()
+    model = msprime.SmcKApproxCoalescent(hull_offset=1)
 
 
 class TestMigrationRecordsDtwf(MigrationRecordsMixin):
@@ -2576,7 +2576,11 @@ def test_full_arg_migration(self):
         self.verify_two_pops_full_arg(ts)
 
     def test_full_arg_migration_smc(self):
-        for model in ["smc", "smc_prime", msprime.SmcKApproxCoalescent()]:
+        for model in [
+            msprime.SmcApproxCoalescent(),
+            msprime.SmcPrimeApproxCoalescent(),
+            msprime.SmcKApproxCoalescent(hull_offset=1),
+        ]:
             population_configurations = [
                 msprime.PopulationConfiguration(10),
                 msprime.PopulationConfiguration(10),

tests/test_models.py

@@ -60,7 +60,7 @@ def test_smc_models(self):
         assert repr(model) == repr_s
         assert str(model) == repr_s
 
-        model = msprime.SmcKApproxCoalescent()
+        model = msprime.SmcKApproxCoalescent(hull_offset=0.0)
         repr_s = "SmcKApproxCoalescent(duration=None, hull_offset=0.0)"
         assert repr(model) == repr_s
         assert str(model) == repr_s
@@ -115,8 +115,8 @@ def test_bad_model_names(self):
     def test_named_model_variants(self):
         simulation_models = [
             ("hudson", msprime.StandardCoalescent),
-            ("smc", msprime.SmcApproxCoalescent),
-            ("smc_prime", msprime.SmcPrimeApproxCoalescent),
+            ("smc", msprime.SmcKApproxCoalescent),
+            ("smc_prime", msprime.SmcKApproxCoalescent),
             ("dtwf", msprime.DiscreteTimeWrightFisher),
             ("fixed_pedigree", msprime.FixedPedigree),
         ]
@@ -128,6 +128,11 @@ def test_named_model_variants(self):
             model = ancestry._model_factory(model=name)
             assert isinstance(model, model_class)
 
+            if name == "smc":
+                assert model.hull_offset == 0.0
+            elif name == "smc_prime":
+                assert model.hull_offset == 1.0
+
     def test_named_parametric_models_fail(self):
         parametric_models = ["beta", "dirac"]
         for name in parametric_models:
@@ -144,7 +149,7 @@ def test_model_instances(self):
             msprime.StandardCoalescent(),
             msprime.SmcApproxCoalescent(),
             msprime.SmcPrimeApproxCoalescent(),
-            msprime.SmcKApproxCoalescent(),
+            msprime.SmcKApproxCoalescent(hull_offset=1),
             msprime.DiscreteTimeWrightFisher(),
             msprime.FixedPedigree(),
             msprime.SweepGenicSelection(
@@ -332,9 +337,6 @@ def test_sweep_genic_selection(self):
             msprime.SweepGenicSelection(1)
 
     def test_smck_coalescent(self):
-        model = msprime.SmcKApproxCoalescent()
-        assert model.duration is None
-        assert model.hull_offset == 0.0
 
         model = msprime.SmcKApproxCoalescent(hull_offset=1.1)
         assert model.duration is None
@@ -371,7 +373,10 @@ def test_hudson(self):
         assert sim2.num_rejected_common_ancestor_events == 0
 
     def test_smc_variants(self):
-        for model in ["smc", "smc_prime"]:
+        for model in [
+            msprime.SmcApproxCoalescent(),
+            msprime.SmcPrimeApproxCoalescent(),
+        ]:
             threshold = 20
             sim = ancestry._parse_simulate(
                 sample_size=10, recombination_rate=5, model=model, random_seed=432