B cell Lineage Tree List

Bases: list

Extends class list in order to store and manipulate list of LineageTrees.

Source code in tribal/lineage_tree.py

class LineageTreeList(list):
    """Extends class list in order to store and manipulate list of LineageTrees."""

    def __str__(self) -> str:
        """To string method."""
        return f"{type(self)} with {len(self)} LineageTree(s)."

    def append(self, item):
        """Append a LineageTree to the LineageTreeList."""
        super().append(self._validate_item(item))

    #only Score objects are allowd in
    def _validate_item(self, item):
        if isinstance(item, (LineageTree)):
            return item
        raise TypeError(
            f"Score expected, item got {type(item).__name__}"
        )

    def write(self, fname:str, sep=","):
        """Write the objective scores of all LineageTrees in the list to a file.

        Parameters
        ----------
        fname : str
            path to where file should be written.
        sep : str
            the seperator (default: ",").
        """
        with open(fname,'w+') as file:
            file.write(f"id{sep}shm_score{sep}csr_likelihood\n")

            for score in self:

                file.write(f"{score.tree.id}{sep}{score.objective}{sep}{score.seq_score}{sep}{score.iso_score}{sep}\n")

    def find_best_tree(self):
        """Find the LineageTree with optimal score.

        If there are multiple optimal solutions, it returns the first one it finds.  
        See `find_all_best_trees` to get all optimal solutions in the LineageTreeList or `sample_best_trees` to randomly 
        sample from among the optimal LineageTrees.

        Returns
        ----------
        float
            the optimal CSR likelihood of the best LineageTree

        LineageTree
            a LineageTree with optimal CSR likelihood
        """
        min_score = min(self, key=lambda x: x.objective).csr_obj

        # Filter objects with the minimum score
        min_score_object = [obj for obj in self if round(obj.csr_obj, 5) == round(min_score,5)][0]
        return min_score, [min_score_object]

    def find_all_best_trees(self):
        """Find the LineageTree(s) with optimal scores.

        Returns
        -------
        float
            the optimal CSR likelihood of the best LineageTree.

        LineageTreeList
            a LineageTreeList of LineageTree with optimal CSR likelihood.
        """
        min_score = min(self, key=lambda x: x.csr_obj).csr_obj


        min_score_object = [obj for obj in self if round(obj.csr_obj, 5) == round(min_score,5)]
        min_score_object = LineageTreeList(min_score_object)
        return min_score, min_score_object

    def _get_all_trees(self):

        return [x.tree for x in self]

    def _get_ids(self):
        return [x.get_id() for x in self]

    def to_pickle(self, fname):
        """Pickle the LineageTreeList.

        Parameters
        ----------
        fname : str
            the path to where the pickled object should be saved.
        """
        with open(fname, 'wb') as file:
            pickle.dump(self, file)

    def sample_best_tree(self, rng=None, seed=1016):
        """Find a LineageTree with optimal score.

        If there are multiple optimal solutions, it randomly samples among the lineage trees with optimal solutions.  
        See `find_all_best_trees` to get all optimal solutions in the LineageTreeList or `find_best_tree` to randomly 
        sample from among the optimal LineageTrees.

        Parameters
        ----------
        rng : numpy.random.Generator
            a numpy random number generator to use for sampling. (default: None)
        seed : int
            a random number seed to use to initialize a numpy.random.Generator (default: 1016)

        Returns
        ----------
        LineageTree
            a randomly sampled LineageTree with optimal CSR likelihood
        """
        if rng is None:
            rng = np.random.default_rng(seed)
        _, best_scores = self.find_all_best_trees()
        sampled_index = np.random.choice(len(best_scores))
        return best_scores[sampled_index]



    def write_all(self, outpath, isotype_encoding=None):
        """Write the data for all LineageTrees in the list to files.

        Parameters
        ----------
        outpath : str
            the path to where the files should be written.
        isotype_encoding : list
            the ordered isotype labeles
        """
        for i,lt in enumerate(self):
            lt.write(outpath,isotype_encoding=isotype_encoding, tree_label=i)

__str__()

To string method.

Source code in tribal/lineage_tree.py

def __str__(self) -> str:
    """To string method."""
    return f"{type(self)} with {len(self)} LineageTree(s)."

append(item)

Append a LineageTree to the LineageTreeList.

Source code in tribal/lineage_tree.py

def append(self, item):
    """Append a LineageTree to the LineageTreeList."""
    super().append(self._validate_item(item))

find_all_best_trees()

Find the LineageTree(s) with optimal scores.

Returns:

Type	Description
float	the optimal CSR likelihood of the best LineageTree.
LineageTreeList	a LineageTreeList of LineageTree with optimal CSR likelihood.

Source code in tribal/lineage_tree.py

def find_all_best_trees(self):
    """Find the LineageTree(s) with optimal scores.

    Returns
    -------
    float
        the optimal CSR likelihood of the best LineageTree.

    LineageTreeList
        a LineageTreeList of LineageTree with optimal CSR likelihood.
    """
    min_score = min(self, key=lambda x: x.csr_obj).csr_obj


    min_score_object = [obj for obj in self if round(obj.csr_obj, 5) == round(min_score,5)]
    min_score_object = LineageTreeList(min_score_object)
    return min_score, min_score_object

find_best_tree()

Find the LineageTree with optimal score.

If there are multiple optimal solutions, it returns the first one it finds.
See find_all_best_trees to get all optimal solutions in the LineageTreeList or sample_best_trees to randomly sample from among the optimal LineageTrees.

Returns:

Type	Description
float	the optimal CSR likelihood of the best LineageTree
LineageTree	a LineageTree with optimal CSR likelihood

Source code in tribal/lineage_tree.py

def find_best_tree(self):
    """Find the LineageTree with optimal score.

    If there are multiple optimal solutions, it returns the first one it finds.  
    See `find_all_best_trees` to get all optimal solutions in the LineageTreeList or `sample_best_trees` to randomly 
    sample from among the optimal LineageTrees.

    Returns
    ----------
    float
        the optimal CSR likelihood of the best LineageTree

    LineageTree
        a LineageTree with optimal CSR likelihood
    """
    min_score = min(self, key=lambda x: x.objective).csr_obj

    # Filter objects with the minimum score
    min_score_object = [obj for obj in self if round(obj.csr_obj, 5) == round(min_score,5)][0]
    return min_score, [min_score_object]

sample_best_tree(rng=None, seed=1016)

Find a LineageTree with optimal score.

If there are multiple optimal solutions, it randomly samples among the lineage trees with optimal solutions.
See find_all_best_trees to get all optimal solutions in the LineageTreeList or find_best_tree to randomly sample from among the optimal LineageTrees.

Parameters:

Name	Type	Description	Default
rng	Generator	a numpy random number generator to use for sampling. (default: None)	None
seed	int	a random number seed to use to initialize a numpy.random.Generator (default: 1016)	1016

Returns:

Type	Description
LineageTree	a randomly sampled LineageTree with optimal CSR likelihood

Source code in tribal/lineage_tree.py

def sample_best_tree(self, rng=None, seed=1016):
    """Find a LineageTree with optimal score.

    If there are multiple optimal solutions, it randomly samples among the lineage trees with optimal solutions.  
    See `find_all_best_trees` to get all optimal solutions in the LineageTreeList or `find_best_tree` to randomly 
    sample from among the optimal LineageTrees.

    Parameters
    ----------
    rng : numpy.random.Generator
        a numpy random number generator to use for sampling. (default: None)
    seed : int
        a random number seed to use to initialize a numpy.random.Generator (default: 1016)

    Returns
    ----------
    LineageTree
        a randomly sampled LineageTree with optimal CSR likelihood
    """
    if rng is None:
        rng = np.random.default_rng(seed)
    _, best_scores = self.find_all_best_trees()
    sampled_index = np.random.choice(len(best_scores))
    return best_scores[sampled_index]

to_pickle(fname)

Pickle the LineageTreeList.

Parameters:

Name	Type	Description	Default
fname	str	the path to where the pickled object should be saved.	required

Source code in tribal/lineage_tree.py

def to_pickle(self, fname):
    """Pickle the LineageTreeList.

    Parameters
    ----------
    fname : str
        the path to where the pickled object should be saved.
    """
    with open(fname, 'wb') as file:
        pickle.dump(self, file)

write(fname, sep=',')

Write the objective scores of all LineageTrees in the list to a file.

Parameters:

Name	Type	Description	Default
fname	str	path to where file should be written.	required
sep	str	the seperator (default: ",").	','

Source code in tribal/lineage_tree.py

def write(self, fname:str, sep=","):
    """Write the objective scores of all LineageTrees in the list to a file.

    Parameters
    ----------
    fname : str
        path to where file should be written.
    sep : str
        the seperator (default: ",").
    """
    with open(fname,'w+') as file:
        file.write(f"id{sep}shm_score{sep}csr_likelihood\n")

        for score in self:

            file.write(f"{score.tree.id}{sep}{score.objective}{sep}{score.seq_score}{sep}{score.iso_score}{sep}\n")

write_all(outpath, isotype_encoding=None)

Write the data for all LineageTrees in the list to files.

Parameters:

Name	Type	Description	Default
outpath	str	the path to where the files should be written.	required
isotype_encoding	list	the ordered isotype labeles	None

Source code in tribal/lineage_tree.py

def write_all(self, outpath, isotype_encoding=None):
    """Write the data for all LineageTrees in the list to files.

    Parameters
    ----------
    outpath : str
        the path to where the files should be written.
    isotype_encoding : list
        the ordered isotype labeles
    """
    for i,lt in enumerate(self):
        lt.write(outpath,isotype_encoding=isotype_encoding, tree_label=i)