repare 0.0.2__py3-none-any.whl → 0.1.0__py3-none-any.whl

repare/pedigree_reconstructor.py

@@ -47,12 +47,13 @@ class PedigreeReconstructor:
         self._write_alternate_pedigrees = write_alternate_pedigrees
         self._random_seed = random_seed
         random.seed(self._random_seed)
+        self._validate_arguments()
 
         # Maximum number of times to run the algorithm if no valid pedigree is found
         self._MAX_RUNS = 10
         self._candidate_pedigrees: list[Pedigree] = [self._get_initial_pedigree()]
         self._pair_to_constraints: defaultdict[tuple[str, str], list[tuple[str, ...]]] = self._get_pair_to_constraints()
-        self._final_pedigree: Pedigree | None = None
+        self._final_pedigrees: list[Pedigree] = []
 
     def _validate_node_data(self, nodes_path: str) -> None:
         """
@@ -71,6 +72,12 @@ class PedigreeReconstructor:
         if self._node_data["id"].str.isnumeric().any():
             raise ValueError("Sample IDs cannot be completely numeric.")
 
+        if self._node_data["id"].duplicated().any():
+            raise ValueError("Sample IDs must be unique.")
+
+        if self._node_data["id"].str.strip().eq("").any():
+            raise ValueError("Sample IDs cannot be empty.")
+
         if not self._node_data["sex"].isin(["M", "F"]).all():
             raise ValueError('Node sex must be "M" or "F".')
 
@@ -275,6 +282,15 @@ class PedigreeReconstructor:
             [self._first_degree_relations, self._second_degree_relations, self._third_degree_relations]
         ).reset_index(drop=True)
 
+    def _validate_arguments(self) -> None:
+        """
+        Validate constructor arguments.
+        """
+        if not isinstance(self._max_candidate_pedigrees, int) or self._max_candidate_pedigrees <= 0:
+            raise ValueError("max_candidate_pedigrees must be a positive integer.")
+        if not (0 <= self._epsilon <= 1):
+            raise ValueError("epsilon must be between 0 and 1.")
+
     def _shuffle_relations(self) -> None:
         """
         Shuffle relation DataFrames (when we want to restart the algorithm).
@@ -333,11 +349,14 @@ class PedigreeReconstructor:
                 self._add_relation(
                     node1, node2, degree=degree, constraints=constraints, force_constraints=force_constraints
                 )
-                self._clean_relation_dicts()
+                self._clean_pedigree_data()
+                self._validate_pedigree_structures()
 
                 processed_relations = self._all_relations.iloc[: idx + 1]
                 pair_to_relations_so_far = self._get_pair_to_relations_so_far(processed_relations)
                 if degree == "1" and len(processed_relations) < len(self._first_and_second_degree_relations):
+                    # Don't check for extraneous half-sibling relations because
+                    # the 2 non-shared parents might be "merged" later
                     self._prune_pedigrees(pair_to_relations_so_far, check_half_siblings=False)
                 else:
                     self._prune_pedigrees(pair_to_relations_so_far, check_half_siblings=True)
@@ -358,6 +377,7 @@ class PedigreeReconstructor:
             logger.error(f"No valid pedigree found after {self._MAX_RUNS} runs. Exiting.")
             raise RuntimeError(f"No valid pedigree found after {self._MAX_RUNS} runs.")
 
+        self._clean_pedigree_data()
         # Plot and write outputs of sample pedigree
         sample_idx = random.randint(0, len(self._final_pedigrees) - 1)
         self._sample_pedigree = self._final_pedigrees[sample_idx]
@@ -373,7 +393,7 @@ class PedigreeReconstructor:
         )
         if self._plot:
             try:
-                self._sample_pedigree.plot(os.path.join(self._outputs_dir, "reconstructed_pedigree.png"))
+                self._sample_pedigree.plot(os.path.join(self._outputs_dir, "reconstructed_pedigree.pdf"))
                 pygraphviz_found = True
             except ImportError:
                 logger.warning(
@@ -386,7 +406,7 @@ class PedigreeReconstructor:
         if self._write_alternate_pedigrees:
             os.makedirs(os.path.join(self._outputs_dir, "alternate_pedigrees"), exist_ok=True)
             for idx, (pedigree, strike_count, strike_log) in enumerate(
-                zip(self._final_pedigrees, self._final_strike_counts, self._final_strike_logs)
+                zip(self._final_pedigrees, self._final_strike_counts, self._final_strike_logs, strict=True)
             ):
                 self._write_corrected_input_relations(
                     strike_count,
@@ -402,6 +422,119 @@ class PedigreeReconstructor:
                     pedigree.plot(os.path.join(self._outputs_dir, "alternate_pedigrees", f"pedigree_{idx}.png"))
         return self._sample_pedigree
 
+    @staticmethod
+    def _check_haplogroups(haplogroup1: str, haplogroup2: str) -> bool:
+        """
+        Checks if two haplogroups are compatible. Same semantics as pedigree.validate_haplogroups().
+        "*" is wild card character.
+        """
+        if not haplogroup1 or not haplogroup2:  # empty OK
+            return True
+        haplogroup1_stripped, haplogroup2_stripped = haplogroup1.rstrip("*"), haplogroup2.rstrip("*")
+        return haplogroup1_stripped.startswith(haplogroup2_stripped) or haplogroup2_stripped.startswith(
+            haplogroup1_stripped
+        )
+
+    @staticmethod
+    def _check_parent_child_haplogroups(pedigree: Pedigree, parent: str, child: str) -> bool:
+        """
+        Checks if the haplogroups of a parent and child are compatible.
+        """
+        if pedigree.get_data(parent)["sex"] == "M" and pedigree.get_data(child)["sex"] == "M":
+            return PedigreeReconstructor._check_haplogroups(
+                pedigree.get_data(parent)["y_haplogroup"], pedigree.get_data(child)["y_haplogroup"]
+            )
+        if pedigree.get_data(parent)["sex"] == "F":
+            return PedigreeReconstructor._check_haplogroups(
+                pedigree.get_data(parent)["mt_haplogroup"], pedigree.get_data(child)["mt_haplogroup"]
+            )
+        return True
+
+    @staticmethod
+    def _check_sibling_haplogroups(pedigree: Pedigree, sibling1: str, sibling2: str) -> bool:
+        """
+        Checks if the haplogroups of two full siblings are compatible.
+        """
+        if pedigree.get_data(sibling1)["sex"] == "M" and pedigree.get_data(sibling2)["sex"] == "M":
+            # MT haplogroups still need to agree as well
+            if not PedigreeReconstructor._check_haplogroups(
+                pedigree.get_data(sibling1)["y_haplogroup"], pedigree.get_data(sibling2)["y_haplogroup"]
+            ):
+                return False
+        # All full siblings should share MT haplogroups
+        return PedigreeReconstructor._check_haplogroups(
+            pedigree.get_data(sibling1)["mt_haplogroup"], pedigree.get_data(sibling2)["mt_haplogroup"]
+        )
+
+    @staticmethod
+    def _check_aunt_uncle_nephew_niece_haplogroups(
+        pedigree: Pedigree, aunt_uncle: str, nephew_niece: str, shared_relative_sex: str | None
+    ) -> bool:
+        """
+        Checks if the haplogroups of an aunt/uncle and nephew/niece are compatible.
+        """
+        if not shared_relative_sex:
+            return True
+
+        if (
+            shared_relative_sex == "M"
+            and pedigree.get_data(aunt_uncle)["sex"] == "M"
+            and pedigree.get_data(nephew_niece)["sex"] == "M"
+        ):
+            return PedigreeReconstructor._check_haplogroups(
+                pedigree.get_data(aunt_uncle)["y_haplogroup"], pedigree.get_data(nephew_niece)["y_haplogroup"]
+            )
+        if shared_relative_sex == "F":
+            return PedigreeReconstructor._check_haplogroups(
+                pedigree.get_data(aunt_uncle)["mt_haplogroup"], pedigree.get_data(nephew_niece)["mt_haplogroup"]
+            )
+        return True
+
+    @staticmethod
+    def _check_grandparent_grandchild_haplogroups(
+        pedigree: Pedigree, grandparent: str, grandchild: str, shared_relative_sex: str | None
+    ) -> bool:
+        """
+        Checks if the haplogroups of a grandparent and grandchild are compatible.
+        """
+        if not shared_relative_sex:
+            return True
+
+        if (
+            shared_relative_sex == "M"
+            and pedigree.get_data(grandparent)["sex"] == "M"
+            and pedigree.get_data(grandchild)["sex"] == "M"
+        ):
+            return PedigreeReconstructor._check_haplogroups(
+                pedigree.get_data(grandparent)["y_haplogroup"], pedigree.get_data(grandchild)["y_haplogroup"]
+            )
+        if shared_relative_sex == "F" and pedigree.get_data(grandparent)["sex"] == "F":
+            return PedigreeReconstructor._check_haplogroups(
+                pedigree.get_data(grandparent)["mt_haplogroup"], pedigree.get_data(grandchild)["mt_haplogroup"]
+            )
+        return True
+
+    @staticmethod
+    def _check_half_sibling_haplogroups(
+        pedigree: Pedigree, half_sibling1: str, half_sibling2: str, shared_relative_sex: str | None
+    ) -> bool:
+        """
+        Checks if the haplogroups of two half-siblings are compatible.
+        """
+        if (
+            shared_relative_sex == "M"
+            and pedigree.get_data(half_sibling1)["sex"] == "M"
+            and pedigree.get_data(half_sibling2)["sex"] == "M"
+        ):
+            return PedigreeReconstructor._check_haplogroups(
+                pedigree.get_data(half_sibling1)["y_haplogroup"], pedigree.get_data(half_sibling2)["y_haplogroup"]
+            )
+        if shared_relative_sex == "F":
+            return PedigreeReconstructor._check_haplogroups(
+                pedigree.get_data(half_sibling1)["mt_haplogroup"], pedigree.get_data(half_sibling2)["mt_haplogroup"]
+            )
+        return True
+
     def _add_relation(self, node1: str, node2: str, degree: str, constraints: str, force_constraints: bool) -> None:
         """
         Connects two nodes in every pedigree.
@@ -451,7 +584,7 @@ class PedigreeReconstructor:
         self._candidate_pedigrees = new_pedigrees
 
     @staticmethod
-    def _connect_first_degree_relation(pedigree: Pedigree, node1: str, node2: str, constraints: str) -> None:
+    def _connect_first_degree_relation(pedigree: Pedigree, node1: str, node2: str, constraints: str) -> list[Pedigree]:
         """
         Update pedigree with a first-degree relation.
         """
@@ -470,7 +603,7 @@ class PedigreeReconstructor:
         return new_pedigrees
 
     @staticmethod
-    def _connect_second_degree_relation(pedigree: Pedigree, node1: str, node2: str, constraints: str) -> None:
+    def _connect_second_degree_relation(pedigree: Pedigree, node1: str, node2: str, constraints: str) -> list[Pedigree]:
         """
         Update pedigree with a second-degree relation.
         """
@@ -536,16 +669,20 @@ class PedigreeReconstructor:
         """
         assert node1 in pedigree.node_to_data and node2 in pedigree.node_to_data
 
+        # Pre-check invalid relations to avoid unnecessary deep-copying
+        if not PedigreeReconstructor._check_parent_child_haplogroups(pedigree, node1, node2):
+            return []
+
         ret: list[Pedigree] = []
         new_pedigree = copy.deepcopy(pedigree)
         new_pedigree.fill_node_parents(node2)
         original_parent: str
-        if new_pedigree.node_to_data[node1]["sex"] == "M":
-            original_parent = new_pedigree.node_to_father[node2]
+        if new_pedigree.get_data(node1)["sex"] == "M":
+            original_parent = new_pedigree.get_father(node2)
         else:
-            original_parent = new_pedigree.node_to_mother[node2]
+            original_parent = new_pedigree.get_mother(node2)
 
-        if not new_pedigree.check_cycles_if_merged(node1, original_parent):
+        if new_pedigree.check_valid_merge(node1, original_parent):
             new_pedigree.merge_nodes(node1, original_parent)
             ret.append(new_pedigree)
         return ret
@@ -558,18 +695,22 @@ class PedigreeReconstructor:
         """
         assert node1 in pedigree.node_to_data and node2 in pedigree.node_to_data
 
+        # Pre-check invalid relations to avoid unnecessary deep-copying
+        if not PedigreeReconstructor._check_sibling_haplogroups(pedigree, node1, node2):
+            return []
+
         ret: list[Pedigree] = []
         new_pedigree = copy.deepcopy(pedigree)
         new_pedigree.fill_node_parents(node1)
         new_pedigree.fill_node_parents(node2)
 
-        father1 = new_pedigree.node_to_father[node1]
-        father2 = new_pedigree.node_to_father[node2]
-        if not new_pedigree.check_cycles_if_merged(father1, father2):
+        father1 = new_pedigree.get_father(node1)
+        father2 = new_pedigree.get_father(node2)
+        if new_pedigree.check_valid_merge(father1, father2):
             new_pedigree.merge_nodes(father1, father2)
-            mother1 = new_pedigree.node_to_mother[node1]
-            mother2 = new_pedigree.node_to_mother[node2]
-            if not new_pedigree.check_cycles_if_merged(mother1, mother2):
+            mother1 = new_pedigree.get_mother(node1)
+            mother2 = new_pedigree.get_mother(node2)
+            if new_pedigree.check_valid_merge(mother1, mother2):
                 new_pedigree.merge_nodes(mother1, mother2)
                 new_pedigree.add_sibling_relation(node1, node2)
                 ret.append(new_pedigree)
@@ -586,17 +727,23 @@ class PedigreeReconstructor:
         assert node1 in pedigree.node_to_data and node2 in pedigree.node_to_data
         assert shared_relative_sex in ["M", "F", None]
 
+        # Pre-check invalid relations to avoid unnecessary deep-copying
+        if not PedigreeReconstructor._check_aunt_uncle_nephew_niece_haplogroups(
+            pedigree, node1, node2, shared_relative_sex
+        ):
+            return []
+
         ret: list[Pedigree] = []
         new_pedigree = copy.deepcopy(pedigree)
         new_pedigree.fill_node_parents(node2)
 
         node2_parents: list[str]
         if shared_relative_sex == "M":
-            node2_parents = [new_pedigree.node_to_father[node2]]
+            node2_parents = [new_pedigree.get_father(node2)]
         elif shared_relative_sex == "F":
-            node2_parents = [new_pedigree.node_to_mother[node2]]
+            node2_parents = [new_pedigree.get_mother(node2)]
         else:
-            node2_parents = [new_pedigree.node_to_father[node2], new_pedigree.node_to_mother[node2]]
+            node2_parents = [new_pedigree.get_father(node2), new_pedigree.get_mother(node2)]
 
         for node2_parent in node2_parents:
             if node1 != node2_parent:
@@ -614,17 +761,23 @@ class PedigreeReconstructor:
         assert node1 in pedigree.node_to_data and node2 in pedigree.node_to_data
         assert shared_relative_sex in ["M", "F", None]
 
+        # Pre-check invalid relations to avoid unnecessary deep-copying
+        if not PedigreeReconstructor._check_grandparent_grandchild_haplogroups(
+            pedigree, node1, node2, shared_relative_sex
+        ):
+            return []
+
         ret: list[Pedigree] = []
         new_pedigree = copy.deepcopy(pedigree)
         new_pedigree.fill_node_parents(node2)
 
         node2_parents: list[str]
         if shared_relative_sex == "M":
-            node2_parents = [new_pedigree.node_to_father[node2]]
+            node2_parents = [new_pedigree.get_father(node2)]
         elif shared_relative_sex == "F":
-            node2_parents = [new_pedigree.node_to_mother[node2]]
+            node2_parents = [new_pedigree.get_mother(node2)]
         else:
-            node2_parents = [new_pedigree.node_to_father[node2], new_pedigree.node_to_mother[node2]]
+            node2_parents = [new_pedigree.get_father(node2), new_pedigree.get_mother(node2)]
 
         for node2_parent in node2_parents:
             if node1 != node2_parent:
@@ -641,6 +794,10 @@ class PedigreeReconstructor:
         """
         assert node1 in pedigree.node_to_data and node2 in pedigree.node_to_data
 
+        # Pre-check invalid relations to avoid unnecessary deep-copying
+        if not PedigreeReconstructor._check_half_sibling_haplogroups(pedigree, node1, node2, shared_relative_sex):
+            return []
+
         ret: list[Pedigree] = []
         new_pedigree = copy.deepcopy(pedigree)
         new_pedigree.fill_node_parents(node1)
@@ -649,14 +806,14 @@ class PedigreeReconstructor:
         node1_parents: list[str]
         node2_parents: list[str]
         if shared_relative_sex == "M":
-            node1_parents = [new_pedigree.node_to_father[node1]]
-            node2_parents = [new_pedigree.node_to_father[node2]]
+            node1_parents = [new_pedigree.get_father(node1)]
+            node2_parents = [new_pedigree.get_father(node2)]
         elif shared_relative_sex == "F":
-            node1_parents = [new_pedigree.node_to_mother[node1]]
-            node2_parents = [new_pedigree.node_to_mother[node2]]
+            node1_parents = [new_pedigree.get_mother(node1)]
+            node2_parents = [new_pedigree.get_mother(node2)]
         else:
-            node1_parents = [new_pedigree.node_to_father[node1], new_pedigree.node_to_mother[node1]]
-            node2_parents = [new_pedigree.node_to_father[node2], new_pedigree.node_to_mother[node2]]
+            node1_parents = [new_pedigree.get_father(node1), new_pedigree.get_mother(node1)]
+            node2_parents = [new_pedigree.get_father(node2), new_pedigree.get_mother(node2)]
 
         # Node 1 and Node 2 are half-siblings via one of Node 1's parents
         for node1_parent in node1_parents:
@@ -668,12 +825,22 @@ class PedigreeReconstructor:
                 ret.extend(PedigreeReconstructor._connect_parent_relation(new_pedigree, node2_parent, node1))
         return ret
 
-    def _clean_relation_dicts(self) -> None:
+    def _clean_pedigree_data(self) -> None:
         """
         Remove unnecessary entries in Pedigree dicts.
         """
         for pedigree in self._candidate_pedigrees:
-            pedigree.clean_up_relations()
+            pedigree.clean_data()
+
+        for pedigree in self._final_pedigrees:
+            pedigree.clean_data()
+
+    def _validate_pedigree_structures(self) -> None:
+        """
+        Validate that all candidate pedigrees are consistent.
+        """
+        for pedigree in self._candidate_pedigrees:
+            assert pedigree.validate_structure()
 
     def _get_pair_to_constraints(self) -> defaultdict[tuple[str, str], list[tuple[str, ...]]]:
         """
@@ -730,12 +897,12 @@ class PedigreeReconstructor:
 
         strikes = []
         third_degree_strikes = []
-        counts = defaultdict(int)
+        counts: defaultdict[int, int] = defaultdict(int)
         for pedigree in new_potential_pedigrees:
             num_strikes, _ = pedigree.count_inconsistencies(
                 self._pair_to_constraints, pair_to_relations_so_far, check_half_siblings
             )
-            num_third_degree_strikes = pedigree.count_third_degree_inconcistencies(self._pair_to_constraints)
+            num_third_degree_strikes = pedigree.count_third_degree_inconsistencies(self._pair_to_constraints)
             strikes.append(num_strikes)
             third_degree_strikes.append(num_third_degree_strikes)
             counts[num_strikes] += 1
@@ -754,7 +921,9 @@ class PedigreeReconstructor:
 
             sorted_pedigrees = [
                 pedigree
-                for pedigree, _, _ in sorted(zip(pedigrees, strikes, third_degree_strikes), key=lambda x: (x[1], x[2]))
+                for pedigree, _, _ in sorted(
+                    zip(pedigrees, strikes, third_degree_strikes, strict=True), key=lambda x: (x[1], x[2])
+                )
             ]
             exploitation_max_candidate_pedigrees = int((1 - epsilon) * max_candidate_pedigrees)
             exploration_max_candidate_pedigrees = max_candidate_pedigrees - exploitation_max_candidate_pedigrees
@@ -778,19 +947,21 @@ class PedigreeReconstructor:
             # Final iteration
             best_pedigrees = [
                 pedigree
-                for pedigree, num_strikes in zip(new_potential_pedigrees, strikes)
+                for pedigree, num_strikes in zip(new_potential_pedigrees, strikes, strict=True)
                 if num_strikes == min(strikes)
             ]
             # Use 3rd-degree strikes as tiebreaker
             third_degree_strikes = [
-                pedigree.count_third_degree_inconcistencies(self._pair_to_constraints) for pedigree in best_pedigrees
+                pedigree.count_third_degree_inconsistencies(self._pair_to_constraints) for pedigree in best_pedigrees
             ]
 
-            self._final_pedigrees = [
-                pedigree
-                for pedigree, num_strikes in zip(best_pedigrees, third_degree_strikes)
-                if num_strikes == min(third_degree_strikes)
-            ]
+            self._final_pedigrees.extend(
+                [
+                    pedigree
+                    for pedigree, num_strikes in zip(best_pedigrees, third_degree_strikes, strict=True)
+                    if num_strikes == min(third_degree_strikes)
+                ]
+            )
             self._final_strike_counts = []
             self._final_strike_logs = []
             for pedigree in self._final_pedigrees:
@@ -799,10 +970,9 @@ class PedigreeReconstructor:
                 )
                 self._final_strike_counts.append(strike_count)
                 self._final_strike_logs.append(strike_log)
-                pedigree.clean_up_relations()
 
     def _write_corrected_input_relations(
-        self, strike_count: int, strike_log: list[tuple[str, str, str]], path: str
+        self, strike_count: int, strike_log: list[tuple[str, str, str, str]], path: str
     ) -> None:
         """
         Write corrected input relations to file. Includes information about added/removed/changed input relations.
@@ -827,7 +997,7 @@ class PedigreeReconstructor:
 
         with open(path, "w") as file:
             file.write("id1,id2,degree,constraints\n")  # Header line
-            file.write(f"# Final strike count: {strike_count}\n")
+            file.write(f"# Final inconsistency count: {strike_count}\n")
 
             def write_relations_line(node1, node2, degree, constraints, commented=False):
                 if constraints == self._DEFAULT_CONSTRAINTS[degree]:

repare-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: repare
+Version: 0.1.0
+Summary: Reconstruct (ancient) pedigrees from pairwise kinship relations.
+Author-email: Edward Huang <edwardhuangc@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: networkx
+Requires-Dist: pandas
+Requires-Dist: tqdm
+Provides-Extra: benchmark
+Requires-Dist: scikit-learn; extra == "benchmark"
+Requires-Dist: seaborn; extra == "benchmark"
+Provides-Extra: plot
+Requires-Dist: pygraphviz; extra == "plot"
+Dynamic: license-file
+
+:evergreen_tree: **repare** is a Python package for (ancient) pedigree reconstruction.
+
+## Installation
+
+### Recommended
+```
+conda create -n "repare" -c conda-forge python=3.13 pygraphviz matplotlib networkx pandas tqdm
+conda activate repare
+pip install repare
+```
+repare uses PyGraphviz to plot reconstructed pedigrees. Since PyGraphviz relies on Graphviz which cannot be installed using `pip`, we recommend installing repare and its dependencies in a fresh conda environment, as shown above.
+
+If you don't need to plot reconstructed pedigrees, you can install repare directly with `pip install repare`. If you need to plot reconstructed pedigrees and have your own Graphviz installation, you can install repare and Pygraphviz with `pip install repare[plot]`.
+
+To install conda, see [this page](https://www.anaconda.com/docs/getting-started/miniconda/install). To install PyGraphviz and Graphviz (yourself), see [this page](https://pygraphviz.github.io/documentation/stable/install.html).
+
+
+## Usage
+
+We recommend running repare through its command-line interface.
+```
+repare -n NODES -r RELATIONS [-o OUTPUT] [-m MAX_CANDIDATE_PEDIGREES] [-e EPSILON] [-s SEED] [-d] [-w] [-v]
+```
+
+> [!NOTE]
+> Minimal command:
+> ```
+> repare -n nodes.csv -r relations.csv
+> ```
+> For example data inputs, see [examples/nodes.csv](examples/nodes.csv) and [examples/relations.csv](examples/relations.csv).
+
+### Inputs
+**Nodes** (-n) (*required*): Path to a CSV file that contains information about the individuals to be analyzed by repare. 
+
+<dl>
+  <dd>
+<details open>
+  <summary><ins>Nodes CSV file columns</ins></summary>
+
+  - **id** *(required)*: ID of individual. Cannot be fully numeric, as numeric IDs are reserved for placeholder nodes.
+  - **sex** *(required)*: Genetic sex of individual. Value must be "M" or "F".
+  - **y_haplogroup** *(required)*: Y chromosome haplogroup of individual. Can include "*" as a wildcard expansion character at the end if haplogroup is not fully inferred.
+  - **mt_haplogroup** *(required)*: Mitochondrial haplogroup of individual. Can include "*" as a wildcard expansion character at the end if haplogroup is not fully inferred.
+  - **can_have_children** *(optional)*: Whether the individual *can* have offspring (e.g., as indicated by age of death). If provided, value must be "True" or "False". Defaults to "True".
+  - **can_be_inbred** *(optional)*: Whether the individual *can* have parents related at the 3rd-degree or closer (e.g., as indicated by ROH). If provided, value must be "True" or "False". Defaults to "True".
+  - **years_before_present** *(optional)*: (Approximate) date of birth of individual, in years before present. If provided, will be used to prune temporally invalid pedigrees. *This column should only be used when backed by strong dating evidence.*
+</details>
+  </dd>
+</dl>
+
+**Relations** (-r) (*required*): Path to a CSV file that contains information about inferred pairwise kinship relations. Methods to infer these kinship relations include [KIN](https://doi.org/10.1186/s13059-023-02847-7) and [READv2](https://doi.org/10.1186/s13059-024-03350-3). All individuals included in this file must be specified in the nodes CSV.
+
+<dl>
+  <dd>
+<details open>
+  <summary><ins>Relations CSV file columns</ins></summary>
+
+  - **id1** *(required)*: ID of individual 1.
+  - **id2** *(required)*: ID of individual 2.
+  - **degree** *(required)*: Degree of (inferred) kinship relation between individual 1 and individual 2. Value must be "1", "2", or "3". Higher-degree relatives are considered unrelated.
+  - **constraints** *(optional)*: Semicolon-delimited list of possible configurations of kinship relation. For example, a parental 1st-degree relation can be constrained with "parent-child;child-parent". Many kinship inference methods will classify 1st-degree relation types, which can be used as relation constraints. Valid constraints: "parent-child", "child-parent", "siblings", "maternal aunt/uncle-nephew/niece", "maternal nephew/niece-aunt/uncle", "paternal aunt/uncle-nephew/niece", "paternal nephew/niece-aunt/uncle", "maternal grandparent-grandchild", "maternal grandchild-grandparent", "paternal grandparent-grandchild", "paternal grandchild-grandparent" "maternal half-siblings", "paternal half-siblings".
+  - **force_constraints** *(optional)*: Whether the corresponding constraint should be forced. If provided, value must be "True" or "False". If "True", the constraint must be followed. If "False", breaking the constraint counts as one inconsistency. Defaults to "False".
+</details>
+  </dd>
+</dl>
+
+**Output** (-o) (*optional*): Path to directory for saving repare outputs. Defaults to the current working directory.
+
+**Max Candidate Pedigrees** (-m) (*optional*): Maximum number of candidate pedigrees to keep after each algorithm iteration. Defaults to 1000.
+
+**Epsilon** (-e) (*optional*): Parameter for adapted epsilon-greedy sampling at the end of each algorithm iteration. Defaults to 0.2.
+
+**Seed** (-s) (*optional*): Random seed for reproducibility. Defaults to 42.
+
+**Do Not Plot** (-d) (*flag*): If set, do not plot reconstructed pedigree(s).
+
+**Write Alternate Pedigrees** (-w) (*flag*): If set, write outputs for alternate reconstructed pedigrees to disk.
+
+**Verbose** (-v) (*flag*): If set, enable verbose output (INFO-level logging).
+
+<p align="center">
+  <img src="examples/algorithm_diagram.svg" alt="Reconstruction Process Diagram" width="600" />
+  <br>
+  <em>Diagram of repare's pedigree reconstruction process</em>
+</p>
+
+## Reproducibility
+We recommend using [pixi](https://pixi.sh/) to reproduce the results in this repo.
+```
+git clone https://github.com/ehuangc/repare.git
+cd repare
+pixi shell
+```
+
+Once in the pixi shell, you can run the script(s) corresponding to the results you'd like to reproduce. For example:
+```
+python benchmarks/published/run_parameter_experiment.py
+exit
+```
+To install pixi, see [this page](https://pixi.sh/latest/installation/).

repare-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+repare/__init__.py,sha256=esYDcCYXwJUJVVpWQFFpocPwCZzL5xo_Hxihbknfunc,138
+repare/main.py,sha256=Jmdzzc2_XxBzQ5vU5l0Q0Sh_M714-EWpYCBPOqnng_k,2628
+repare/pedigree.py,sha256=0YXNz2qeML63pgOyX6izaf0zcYIm61N5GU29816P1kg,70547
+repare/pedigree_reconstructor.py,sha256=zbkc9uyd5uqKM9HCZVg6rvvEEo28i65PN-RybrQxILE,49359
+repare-0.1.0.dist-info/licenses/LICENSE,sha256=uqhB_C7lgd3rOQU5SLtWeu_tVc_L0zGGdN488GCrtmY,1063
+repare-0.1.0.dist-info/METADATA,sha256=-tPVXVOv-jdHobgF5kXa4MaibmwgYjQdPgf1MpIxHz4,6523
+repare-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+repare-0.1.0.dist-info/entry_points.txt,sha256=tWRppCTqmNN8n4hJ_ShCgO8dJFU4PKTQsexMZS-PFHw,44
+repare-0.1.0.dist-info/top_level.txt,sha256=MBgnP6OarsEmlqLXjKcPqKFIMIdpwADg5vt6eMPVA0M,7
+repare-0.1.0.dist-info/RECORD,,

{repare-0.0.2.dist-info → repare-0.1.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.1.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

repare-0.0.2.dist-info/METADATA

@@ -1,35 +0,0 @@
-Metadata-Version: 2.4
-Name: repare
-Version: 0.0.2
-Summary: Reconstruct ancient pedigrees.
-Author-email: Edward Huang <edwardhuang02@gmail.com>
-License-Expression: MIT
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: matplotlib
-Requires-Dist: networkx
-Requires-Dist: pandas
-Requires-Dist: tqdm
-Provides-Extra: benchmark
-Requires-Dist: scikit-learn; extra == "benchmark"
-Requires-Dist: seaborn; extra == "benchmark"
-Provides-Extra: plot
-Requires-Dist: pygraphviz; extra == "plot"
-Dynamic: license-file
-
-**repare** is a Python package for (ancient) pedigree reconstruction.
-
-## Installation
-
-### Recommended
-```
-conda create -n "repare" -c conda-forge python=3.13 pygraphviz
-conda activate repare
-pip install repare
-```
-repare uses PyGraphviz to plot reconstructed pedigrees. Since PyGraphviz relies on Graphviz which cannot be installed using `pip`, we recommend installing repare and its dependencies in a fresh conda environment.
-
-If you don't need to plot reconstructed pedigrees, you can install repare directly with `pip install repare`. If you need to plot reconstructed pedigrees and have your own Graphviz installation, you can install repare and Pygraphviz with `pip install repare[plot]`.
-
-To install conda, see [this page](https://www.anaconda.com/docs/getting-started/miniconda/install). To install PyGraphviz and Graphviz (yourself), see [this page](https://pygraphviz.github.io/documentation/stable/install.html).

repare-0.0.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-repare/__init__.py,sha256=esYDcCYXwJUJVVpWQFFpocPwCZzL5xo_Hxihbknfunc,138
-repare/main.py,sha256=N33DO2NggJIuJ1-LrZZNiyd--niou7DJqiq30MFT-OY,2387
-repare/pedigree.py,sha256=zPWmyzE1SheAnRxz_0ZWFMvm0fCcV1ng0fHED3aqtdU,60347
-repare/pedigree_reconstructor.py,sha256=6SGdHyyI8uLsA1xmRg4L9Jb-h79R1JLQFRHUiY8R3DQ,42047
-repare-0.0.2.dist-info/licenses/LICENSE,sha256=uqhB_C7lgd3rOQU5SLtWeu_tVc_L0zGGdN488GCrtmY,1063
-repare-0.0.2.dist-info/METADATA,sha256=fDGofIvoNkr1tweFsI1NkzqxNZsBRBvYFVHVkX40yM8,1478
-repare-0.0.2.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-repare-0.0.2.dist-info/entry_points.txt,sha256=tWRppCTqmNN8n4hJ_ShCgO8dJFU4PKTQsexMZS-PFHw,44
-repare-0.0.2.dist-info/top_level.txt,sha256=MBgnP6OarsEmlqLXjKcPqKFIMIdpwADg5vt6eMPVA0M,7
-repare-0.0.2.dist-info/RECORD,,