B cell Lineage Tree

A class to model B cell lineage trees.

Attributes:

Name	Type	Description
clonotype	str	The name of the clonotype.
tree	BaseTree	The rooted tree topology.
csr_obj	float	The current CSR likelihood of the Lineage tree (default: 0).
isotype	dict	The isotype labels of the Lineage tree nodes.
shm_obj	float	The current SHM Parsimony score of the Lineage tree (default: 0).
sequences	dict	The BCR sequences of the Lineage tree nodes.

Notes

A B cell lineage tree is a rooted tree with nodes labeled by BCR sequences (concatenated heavy and light chain) and isotypes. The somatic hypermutation (SHM) parsimony score is the total number of base substitutions within the sequences, and the class switch (CSR) likelihood is the likelihood of the isotype labels given an isotype transition probability matrix.

Source code in tribal/lineage_tree.py

@dataclass
@total_ordering
class LineageTree:
    """
    A class to model B cell lineage trees.

    Attributes
    ----------
    clonotype : str
        The name of the clonotype.
    tree : BaseTree
        The rooted tree topology.
    csr_obj : float 
        The current CSR likelihood of the Lineage tree (default: 0).
    isotype : dict
        The isotype labels of the Lineage tree nodes.
    shm_obj : float 
        The current SHM Parsimony score of the Lineage tree (default: 0).
    sequences : dict
        The BCR sequences of the Lineage tree nodes.

    Notes
    -----
    A B cell lineage tree is a rooted tree with nodes labeled by BCR sequences (concatenated heavy and light chain) and
    isotypes. The somatic hypermutation (SHM) parsimony score is the total number of base substitutions within the sequences, and 
    the class switch (CSR) likelihood is the likelihood of the isotype labels given an isotype transition probability matrix.
    """

    clonotype: str
    tree: BaseTree= None
    csr_obj: float = 0
    isotypes: dict = field(default_factory=dict)
    shm_obj: float = 0
    sequences: dict = field(default_factory=dict)

    def __post_init__(self):
        """Initialize the objective tuple and root."""
        self.objective = (self.shm_obj,self.csr_obj)
        self.root = self.tree.root

    def _validate_item(self, item):
        """Check comparison items is an instance of LineageTree."""
        if isinstance(item, (LineageTree)):
            return item
        raise TypeError(
            f"Score expected, item got {type(item).__name__}"
        )
    def __eq__(self, __value: object) -> bool:
        """Check if two lineage tree items have the same objective score."""
        item = self._validate_item(__value)
        return self.objective ==item.objective

    def __lt__(self, __value: object) -> bool:
        """Check if a LineageTree is less than another."""
        item = self._validate_item(__value)
        return self.objective <item.objective

    def __str__(self):
        """To string method."""
        mystr = f"B cell lineage tree for {len(self.tree.get_leafs())} cells"
        mystr += f"\nRoot id: {self.root}"
        mystr += f"# of nodes: {len(self.tree.T.nodes)}"
        mystr +=  f"\nObjective\n----------\nSHM: {self.shm_obj}\nCSR: {self.csr_obj}"
        return mystr

    def to_pickle(self, fname):
        """Pickle the B cell lineage tree.

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

    def _seq_len(self):
        for _, val in self.sequences.items():
            return len(val)

    def compute_csr_likelihood(self, transmat):
        """Compute CSR likelihood of a lineage tree for a given isotype transition probability matrix.

        Parameters
        ----------
        transmat : numpy.array
            The isotype transition probability used to compute the CSR likelihood.

        Returns
        -------
            The class switch recombination (CSR) likelihood.
        """
        transmat = -np.log(transmat)

        iso = self.isotypes
        score = 0
        try:
            nodes = self.tree.preorder_traversal()
            for n in nodes:
                t = iso[n]
                for c in self.tree.children(n):
                    s = iso[c]
                    score += transmat[t, s]
        except:
            raise ValueError("Invalid isotypes or tree. \
                             First run isotype parsimony or refinement functions.")

        self.csr_obj = score
        return self.csr_obj


    def get_id(self):
        """Get the internal id of the tree topology. Useful for mapping refined trees back the to the unrefined tree in the parsimony forest.

        Returns
        -------
        : int
            the internal id of the tree topology
        """
        return self.tree.id

    def ancestral_sequence_reconstruction(self, alignment,
                           alphabet=("A", "C", "G", "T","N", "-"), 
                           cost_function=None):
        """Infer the ancestral BCR sequences of the internal nodes given an alignment.

        Parameters
        ----------
        alignment : dict
            a dictionary with leaf labels and root id as keys and the BCR sequence as value.

        alphabet : tuple
            the valid alphabet for BCR sequences, default:  ("A", "C", "G", "T","N", "-")

        cost_function : dict|None
            the cost function for substitution of a single nucleotide base. If None, the 
            standard 0/1 cost function is used for matches and mismatches. If dictionary
            all pairs of the elements in the alpabet should be be includes in the keys.

        Examples
        --------
        Here is an example of how to reconstruct ancestral sequences::

        ```python  
            from tribal import clonotypes, LineageTree
            id = "Clonotype_1036"
            clonotype = clonotypes[id]
            forest = clonotype.get_forest()
            lt = LineageTree(id=id, tree = forest[0])
            shm_score, sequences = lt.ancestral_sequence_reconstruction(clonotype.alignment)
            print(lt)
        ```

        Returns
        -------
        : float
            a float with the somatic hypermutation (SHM) parsimony score for the lineage tree

        : dict
            a dictionary containing the BCR sequence labels of the lineage tree

        """     
        alignment = {k: list(alignment[k]) for k in alignment}
        sp = SmallParsimony(self.tree, 
                            alphabet= alphabet,
                            cost = cost_function)
        self.shm_obj, sequences = sp.sankoff(alignment)
        self.sequences = {key : "".join(value) for key, value in sequences.items()}

        return self.shm_obj, self.sequences



    def isotype_parsimony(self, isotype_labels:dict, transmat:np.array):
        """Infer the isotype of the B cell lineage tree using weighted parsimony.

        Parameters
        ----------
        isotype_labels : dict
            a dictionary with leaf labels and root id as keys and isotypes as values.  
        transmat : numpy.array
            the isotype transition probability used to compute the CSR likelihood.  

        Examples
        --------
        Here is an example of how to infer isotypes::

        ```python
            from tribal import clonotypes, probabilities, LineageTree

            id = "Clonotype_1036"
            clonotype = clonotypes[id]
            forest = clonotype.get_forest()
            lt = LineageTree(id=id, tree = forest[0] )
            csr_likelihood, isotypes = lt.isotype_parsimony(isotype_labels= clonotype.isotypes,
                                                                        transmat=probabilities )
            print(lt)
        ```

        Returns
        -------
        csr_obj : float
            a float with the class switch recombination likelihood score for the lineage tree.  
        isotypes : dict
            a dictionary containing the isotypes of the lineage tree.  
        """
        transmat = -np.log(transmat)
        states = list(range(transmat.shape[0]))
        sp = SmallParsimony(self.tree, alphabet=states,cost=transmat)
        self.csr_obj, self.isotypes = sp.sankoff(isotype_labels)


    def refinement(self, isotype_labels: Dict[str, str], transmat: np.ndarray) -> Tuple[float, Dict[str, str]]:
        """Solves the most parsimonious tree refinement problem (MPTR).

        Parameters
        ----------
        isotype_labels : dict
            A dictionary with leaf labels and root id as keys and isotypes as values.
        transmat : numpy.array
            The isotype transition probability used to compute the CSR likelihood.

        Examples
        --------
        Here is an example of how to refine a lineage tree:

        ```python
        from tribal import clonotypes, probabilities, LineageTree

        id = "Clonotype_1036"
        clonotype = clonotypes[id]
        forest = clonotype.get_forest()
        lt = LineageTree(id=id, tree=forest[0])
        csr_likelihood, isotypes = lt.refinement(isotype_labels=clonotype.isotypes, transmat=probabilities)
        print(lt)
        ```

        Returns
        -------
        float
            A float with the class switch recombination likelihood score for the lineage tree.  

        dict
            A dictionary containing the isotypes of the lineage tree.  
        """
        cost = -np.log(transmat)
        cg = ConstructGraph(cost, isotype_labels, root_identifier=self.root)
        fg = cg.build(self.tree)

        st = MPTR(fg.G,
                  self.tree.T,
                  fg.find_terminals(),
                  fg.iso_weights,
                  fg.tree_to_graph,
                  root=self.root)

        self.csr_obj, tree = st.run()

        tree, self.isotypes = cg.decodeTree(tree)
        self.tree = BaseTree(tree, self.root, self.tree.id, self.tree.name)

        return self.csr_obj, self.isotypes

    def draw(self,
            fname,
            isotype_encoding=None,
            show_legend=False,
            show_labels=True,
            hide_underscore=True,
            color_encoding = None,
            dot = False):
        """Visualization of the current B cell lineage tree saves as a png or pdf.

        Parameters
        ----------
        fname : str
            The filename where the visualization should be saved.  
        isotype_encoding : list
            The list of the isotype labels to use.  
        show_legend : bool
            Optionally display the legend of the isotype colors (default=True).  
        show_labels : bool
            label the nodes by the sequence label
        hide_underscore : bool
            internal nodes that undergo refinement will have an underscore and copy number appended
            to the label. Setting this to true hides the underscore during visualization and retains 
            only the original label.
        color_encoding : dict, optional
            optional dictionary that maps isotype encoding to a color, if None, the default
            color palette is used.
        dot : bool
            if the file should be saved as a dot file, otherwise it will be saved
            as a png or pdf, depending on the file exentsion of fname
        """
        parents = self.get_parents()
        dt = DrawTree(parents, 
                    self.isotypes,
                    show_legend=show_legend,
                    root=self.root,
                    isotype_encoding=isotype_encoding,
                    show_labels=show_labels,
                    hide_underscore=hide_underscore,
                    color_encoding=color_encoding)
        if not dot:
            dt.save(fname)
        else:
            dt.save_dot(fname)


    def postorder_traversal(self) -> list:
        """Perform a postorder traversal of the lineage tree."""
        return self.tree.postorder_traversal()


    def preorder_traversal(self) -> list:
        """Perform a preorder traversal of the lineage tree."""
        return self.tree.preorder_traversal()

    def parent(self,n):
        """Identify the parent of a specified node.

        Parameters
        ----------
        n: str | int
            id of query node.

        Returns
        -------
           the parent of query node n.
        """
        return self.tree.parent(n)

    def children(self, n):
        """
        Identify the set of children of a specified node.

        Parameters
        ----------
        n : str
            ID of the query node.  

        Returns
        -------
            A list of children of node `n`.
        """
        return self.tree.children(n)

    def is_leaf(self,n):
        """Check if node is a leaf."""
        return self.tree.is_leaf(n)


    def get_leafs(self):
        """
        Identify the leafset of the lineage tree.

        Returns
        -------
            the leafset of the lineage tree.

        """
        return self.tree.get_leafs()

    def get_parents(self):
        """Identify the part of each node in the lineage tree.

        Returns
        -------
            a mapping of each node in the lineage tree to its parent node.

        """
        return self.tree.get_parents()


    def save_tree(self,fname):
        """Write the parent dictionary of the lineage tree to a file.

        Parameters
        ----------
        fname : str
            filename where the file should be saved 
        """
        parents = self.get_parents()
        save_dict( parents, fname)

    def save_edges(self, fname):
        """Write the edge list of a lineage tree to a file.

        Parameters
        ----------
        fname : str
            filename to where edge list should be saved 
        """
        self.tree.save_edges(fname)


    def get_edge_dataframe(self):
        """Obtain the edge list of the lineage tree as a pandas.DataFrame."""
        return self.tree.get_edge_df()

    def write(self, outpath:str, isotype_encoding=None, tree_label=None):
        """Write the lineage tree data to files.

        Parameters
        ----------
        outpath : str
            the path to file the files should be written.  
        isotype_encoding : list, optional
            the ordered isotype labels  
        """
        if tree_label is None:
            tree_label = ""
        else:
            tree_label = f"{tree_label}"
        clono_name = self.clonotype
        if isotype_encoding is not None:
            isotypes = {}
            for key, iso in self.isotypes.items():
                if iso >=0 and iso < len(isotype_encoding):
                    isotypes[key] = isotype_encoding[iso]
                else:
                    isotypes[key] = iso
            isotype_encoding = isotype_encoding

        else:
            isotypes = self.isotypes
            isotype_encoding = None


        if not os.path.exists(outpath):
            os.makedirs(outpath)

        write_fasta(f"{outpath}/{clono_name}_sequences{tree_label}.fasta", self.sequences)
        save_dict(f"{outpath}/{clono_name}_isotypes{tree_label}.csv",isotypes)
        self.save_edges(f"{outpath}/{clono_name}_edge_list{tree_label}.txt")
        self.draw(f"{outpath}/{clono_name}_tree{tree_label}.png",
                    isotype_encoding=isotype_encoding,
                    hide_underscore=False,
                    show_legend=True)

__eq__(__value)

Check if two lineage tree items have the same objective score.

Source code in tribal/lineage_tree.py

def __eq__(self, __value: object) -> bool:
    """Check if two lineage tree items have the same objective score."""
    item = self._validate_item(__value)
    return self.objective ==item.objective

__lt__(__value)

Check if a LineageTree is less than another.

Source code in tribal/lineage_tree.py

def __lt__(self, __value: object) -> bool:
    """Check if a LineageTree is less than another."""
    item = self._validate_item(__value)
    return self.objective <item.objective

__post_init__()

Initialize the objective tuple and root.

Source code in tribal/lineage_tree.py

def __post_init__(self):
    """Initialize the objective tuple and root."""
    self.objective = (self.shm_obj,self.csr_obj)
    self.root = self.tree.root

__str__()

To string method.

Source code in tribal/lineage_tree.py

def __str__(self):
    """To string method."""
    mystr = f"B cell lineage tree for {len(self.tree.get_leafs())} cells"
    mystr += f"\nRoot id: {self.root}"
    mystr += f"# of nodes: {len(self.tree.T.nodes)}"
    mystr +=  f"\nObjective\n----------\nSHM: {self.shm_obj}\nCSR: {self.csr_obj}"
    return mystr

ancestral_sequence_reconstruction(alignment, alphabet=('A', 'C', 'G', 'T', 'N', '-'), cost_function=None)

Infer the ancestral BCR sequences of the internal nodes given an alignment.

Parameters:

Name	Type	Description	Default
alignment	dict	a dictionary with leaf labels and root id as keys and the BCR sequence as value.	required
alphabet	tuple	the valid alphabet for BCR sequences, default: ("A", "C", "G", "T","N", "-")	('A', 'C', 'G', 'T', 'N', '-')
cost_function	dict | None	the cost function for substitution of a single nucleotide base. If None, the standard 0/1 cost function is used for matches and mismatches. If dictionary all pairs of the elements in the alpabet should be be includes in the keys.	None

Examples:

Here is an example of how to reconstruct ancestral sequences::

    from tribal import clonotypes, LineageTree
    id = "Clonotype_1036"
    clonotype = clonotypes[id]
    forest = clonotype.get_forest()
    lt = LineageTree(id=id, tree = forest[0])
    shm_score, sequences = lt.ancestral_sequence_reconstruction(clonotype.alignment)
    print(lt)

Returns:

Type	Description
float	a float with the somatic hypermutation (SHM) parsimony score for the lineage tree
dict	a dictionary containing the BCR sequence labels of the lineage tree

Source code in tribal/lineage_tree.py

def ancestral_sequence_reconstruction(self, alignment,
                       alphabet=("A", "C", "G", "T","N", "-"), 
                       cost_function=None):
    """Infer the ancestral BCR sequences of the internal nodes given an alignment.

    Parameters
    ----------
    alignment : dict
        a dictionary with leaf labels and root id as keys and the BCR sequence as value.

    alphabet : tuple
        the valid alphabet for BCR sequences, default:  ("A", "C", "G", "T","N", "-")

    cost_function : dict|None
        the cost function for substitution of a single nucleotide base. If None, the 
        standard 0/1 cost function is used for matches and mismatches. If dictionary
        all pairs of the elements in the alpabet should be be includes in the keys.

    Examples
    --------
    Here is an example of how to reconstruct ancestral sequences::

    ```python  
        from tribal import clonotypes, LineageTree
        id = "Clonotype_1036"
        clonotype = clonotypes[id]
        forest = clonotype.get_forest()
        lt = LineageTree(id=id, tree = forest[0])
        shm_score, sequences = lt.ancestral_sequence_reconstruction(clonotype.alignment)
        print(lt)
    ```

    Returns
    -------
    : float
        a float with the somatic hypermutation (SHM) parsimony score for the lineage tree

    : dict
        a dictionary containing the BCR sequence labels of the lineage tree

    """     
    alignment = {k: list(alignment[k]) for k in alignment}
    sp = SmallParsimony(self.tree, 
                        alphabet= alphabet,
                        cost = cost_function)
    self.shm_obj, sequences = sp.sankoff(alignment)
    self.sequences = {key : "".join(value) for key, value in sequences.items()}

    return self.shm_obj, self.sequences

children(n)

Identify the set of children of a specified node.

Parameters:

Name	Type	Description	Default
n	str	ID of the query node.	required

Returns:

Type	Description
A list of children of node `n`.

Source code in tribal/lineage_tree.py

def children(self, n):
    """
    Identify the set of children of a specified node.

    Parameters
    ----------
    n : str
        ID of the query node.  

    Returns
    -------
        A list of children of node `n`.
    """
    return self.tree.children(n)

compute_csr_likelihood(transmat)

Compute CSR likelihood of a lineage tree for a given isotype transition probability matrix.

Parameters:

Name	Type	Description	Default
transmat	array	The isotype transition probability used to compute the CSR likelihood.	required

Returns:

Type	Description
The class switch recombination (CSR) likelihood.

Source code in tribal/lineage_tree.py

def compute_csr_likelihood(self, transmat):
    """Compute CSR likelihood of a lineage tree for a given isotype transition probability matrix.

    Parameters
    ----------
    transmat : numpy.array
        The isotype transition probability used to compute the CSR likelihood.

    Returns
    -------
        The class switch recombination (CSR) likelihood.
    """
    transmat = -np.log(transmat)

    iso = self.isotypes
    score = 0
    try:
        nodes = self.tree.preorder_traversal()
        for n in nodes:
            t = iso[n]
            for c in self.tree.children(n):
                s = iso[c]
                score += transmat[t, s]
    except:
        raise ValueError("Invalid isotypes or tree. \
                         First run isotype parsimony or refinement functions.")

    self.csr_obj = score
    return self.csr_obj

draw(fname, isotype_encoding=None, show_legend=False, show_labels=True, hide_underscore=True, color_encoding=None, dot=False)

Visualization of the current B cell lineage tree saves as a png or pdf.

Parameters:

Name	Type	Description	Default
fname	str	The filename where the visualization should be saved.	required
isotype_encoding	list	The list of the isotype labels to use.	None
show_legend	bool	Optionally display the legend of the isotype colors (default=True).	False
show_labels	bool	label the nodes by the sequence label	True
hide_underscore	bool	internal nodes that undergo refinement will have an underscore and copy number appended to the label. Setting this to true hides the underscore during visualization and retains only the original label.	True
color_encoding	dict	optional dictionary that maps isotype encoding to a color, if None, the default color palette is used.	None
dot	bool	if the file should be saved as a dot file, otherwise it will be saved as a png or pdf, depending on the file exentsion of fname	False

Source code in tribal/lineage_tree.py

def draw(self,
        fname,
        isotype_encoding=None,
        show_legend=False,
        show_labels=True,
        hide_underscore=True,
        color_encoding = None,
        dot = False):
    """Visualization of the current B cell lineage tree saves as a png or pdf.

    Parameters
    ----------
    fname : str
        The filename where the visualization should be saved.  
    isotype_encoding : list
        The list of the isotype labels to use.  
    show_legend : bool
        Optionally display the legend of the isotype colors (default=True).  
    show_labels : bool
        label the nodes by the sequence label
    hide_underscore : bool
        internal nodes that undergo refinement will have an underscore and copy number appended
        to the label. Setting this to true hides the underscore during visualization and retains 
        only the original label.
    color_encoding : dict, optional
        optional dictionary that maps isotype encoding to a color, if None, the default
        color palette is used.
    dot : bool
        if the file should be saved as a dot file, otherwise it will be saved
        as a png or pdf, depending on the file exentsion of fname
    """
    parents = self.get_parents()
    dt = DrawTree(parents, 
                self.isotypes,
                show_legend=show_legend,
                root=self.root,
                isotype_encoding=isotype_encoding,
                show_labels=show_labels,
                hide_underscore=hide_underscore,
                color_encoding=color_encoding)
    if not dot:
        dt.save(fname)
    else:
        dt.save_dot(fname)

get_edge_dataframe()

Obtain the edge list of the lineage tree as a pandas.DataFrame.

Source code in tribal/lineage_tree.py

def get_edge_dataframe(self):
    """Obtain the edge list of the lineage tree as a pandas.DataFrame."""
    return self.tree.get_edge_df()

get_id()

Get the internal id of the tree topology. Useful for mapping refined trees back the to the unrefined tree in the parsimony forest.

Returns:

Type	Description
int	the internal id of the tree topology

Source code in tribal/lineage_tree.py

def get_id(self):
    """Get the internal id of the tree topology. Useful for mapping refined trees back the to the unrefined tree in the parsimony forest.

    Returns
    -------
    : int
        the internal id of the tree topology
    """
    return self.tree.id

get_leafs()

Identify the leafset of the lineage tree.

Returns:

Type	Description
the leafset of the lineage tree.

Source code in tribal/lineage_tree.py

def get_leafs(self):
    """
    Identify the leafset of the lineage tree.

    Returns
    -------
        the leafset of the lineage tree.

    """
    return self.tree.get_leafs()

get_parents()

Identify the part of each node in the lineage tree.

Returns:

Type	Description
a mapping of each node in the lineage tree to its parent node.

Source code in tribal/lineage_tree.py

def get_parents(self):
    """Identify the part of each node in the lineage tree.

    Returns
    -------
        a mapping of each node in the lineage tree to its parent node.

    """
    return self.tree.get_parents()

is_leaf(n)

Check if node is a leaf.

Source code in tribal/lineage_tree.py

def is_leaf(self,n):
    """Check if node is a leaf."""
    return self.tree.is_leaf(n)

isotype_parsimony(isotype_labels, transmat)

Infer the isotype of the B cell lineage tree using weighted parsimony.

Parameters:

Name	Type	Description	Default
isotype_labels	dict	a dictionary with leaf labels and root id as keys and isotypes as values.	required
transmat	array	the isotype transition probability used to compute the CSR likelihood.	required

Examples:

Here is an example of how to infer isotypes::

    from tribal import clonotypes, probabilities, LineageTree

    id = "Clonotype_1036"
    clonotype = clonotypes[id]
    forest = clonotype.get_forest()
    lt = LineageTree(id=id, tree = forest[0] )
    csr_likelihood, isotypes = lt.isotype_parsimony(isotype_labels= clonotype.isotypes,
                                                                transmat=probabilities )
    print(lt)

Returns:

Name	Type	Description
csr_obj	float	a float with the class switch recombination likelihood score for the lineage tree.
isotypes	dict	a dictionary containing the isotypes of the lineage tree.

Source code in tribal/lineage_tree.py

def isotype_parsimony(self, isotype_labels:dict, transmat:np.array):
    """Infer the isotype of the B cell lineage tree using weighted parsimony.

    Parameters
    ----------
    isotype_labels : dict
        a dictionary with leaf labels and root id as keys and isotypes as values.  
    transmat : numpy.array
        the isotype transition probability used to compute the CSR likelihood.  

    Examples
    --------
    Here is an example of how to infer isotypes::

    ```python
        from tribal import clonotypes, probabilities, LineageTree

        id = "Clonotype_1036"
        clonotype = clonotypes[id]
        forest = clonotype.get_forest()
        lt = LineageTree(id=id, tree = forest[0] )
        csr_likelihood, isotypes = lt.isotype_parsimony(isotype_labels= clonotype.isotypes,
                                                                    transmat=probabilities )
        print(lt)
    ```

    Returns
    -------
    csr_obj : float
        a float with the class switch recombination likelihood score for the lineage tree.  
    isotypes : dict
        a dictionary containing the isotypes of the lineage tree.  
    """
    transmat = -np.log(transmat)
    states = list(range(transmat.shape[0]))
    sp = SmallParsimony(self.tree, alphabet=states,cost=transmat)
    self.csr_obj, self.isotypes = sp.sankoff(isotype_labels)

parent(n)

Identify the parent of a specified node.

Parameters:

Name	Type	Description	Default
n		id of query node.	required

Returns:

Type	Description
the parent of query node n.

Source code in tribal/lineage_tree.py

def parent(self,n):
    """Identify the parent of a specified node.

    Parameters
    ----------
    n: str | int
        id of query node.

    Returns
    -------
       the parent of query node n.
    """
    return self.tree.parent(n)

postorder_traversal()

Perform a postorder traversal of the lineage tree.

Source code in tribal/lineage_tree.py

def postorder_traversal(self) -> list:
    """Perform a postorder traversal of the lineage tree."""
    return self.tree.postorder_traversal()

preorder_traversal()

Perform a preorder traversal of the lineage tree.

Source code in tribal/lineage_tree.py

def preorder_traversal(self) -> list:
    """Perform a preorder traversal of the lineage tree."""
    return self.tree.preorder_traversal()

refinement(isotype_labels, transmat)

Solves the most parsimonious tree refinement problem (MPTR).

Parameters:

Name	Type	Description	Default
isotype_labels	dict	A dictionary with leaf labels and root id as keys and isotypes as values.	required
transmat	array	The isotype transition probability used to compute the CSR likelihood.	required

Examples:

Here is an example of how to refine a lineage tree:

from tribal import clonotypes, probabilities, LineageTree

id = "Clonotype_1036"
clonotype = clonotypes[id]
forest = clonotype.get_forest()
lt = LineageTree(id=id, tree=forest[0])
csr_likelihood, isotypes = lt.refinement(isotype_labels=clonotype.isotypes, transmat=probabilities)
print(lt)

Returns:

Type	Description
float	A float with the class switch recombination likelihood score for the lineage tree.
dict	A dictionary containing the isotypes of the lineage tree.

Source code in tribal/lineage_tree.py

def refinement(self, isotype_labels: Dict[str, str], transmat: np.ndarray) -> Tuple[float, Dict[str, str]]:
    """Solves the most parsimonious tree refinement problem (MPTR).

    Parameters
    ----------
    isotype_labels : dict
        A dictionary with leaf labels and root id as keys and isotypes as values.
    transmat : numpy.array
        The isotype transition probability used to compute the CSR likelihood.

    Examples
    --------
    Here is an example of how to refine a lineage tree:

    ```python
    from tribal import clonotypes, probabilities, LineageTree

    id = "Clonotype_1036"
    clonotype = clonotypes[id]
    forest = clonotype.get_forest()
    lt = LineageTree(id=id, tree=forest[0])
    csr_likelihood, isotypes = lt.refinement(isotype_labels=clonotype.isotypes, transmat=probabilities)
    print(lt)
    ```

    Returns
    -------
    float
        A float with the class switch recombination likelihood score for the lineage tree.  

    dict
        A dictionary containing the isotypes of the lineage tree.  
    """
    cost = -np.log(transmat)
    cg = ConstructGraph(cost, isotype_labels, root_identifier=self.root)
    fg = cg.build(self.tree)

    st = MPTR(fg.G,
              self.tree.T,
              fg.find_terminals(),
              fg.iso_weights,
              fg.tree_to_graph,
              root=self.root)

    self.csr_obj, tree = st.run()

    tree, self.isotypes = cg.decodeTree(tree)
    self.tree = BaseTree(tree, self.root, self.tree.id, self.tree.name)

    return self.csr_obj, self.isotypes

save_edges(fname)

Write the edge list of a lineage tree to a file.

Parameters:

Name	Type	Description	Default
fname	str	filename to where edge list should be saved	required

Source code in tribal/lineage_tree.py

def save_edges(self, fname):
    """Write the edge list of a lineage tree to a file.

    Parameters
    ----------
    fname : str
        filename to where edge list should be saved 
    """
    self.tree.save_edges(fname)

save_tree(fname)

Write the parent dictionary of the lineage tree to a file.

Parameters:

Name	Type	Description	Default
fname	str	filename where the file should be saved	required

Source code in tribal/lineage_tree.py

def save_tree(self,fname):
    """Write the parent dictionary of the lineage tree to a file.

    Parameters
    ----------
    fname : str
        filename where the file should be saved 
    """
    parents = self.get_parents()
    save_dict( parents, fname)

to_pickle(fname)

Pickle the B cell lineage tree.

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 B cell lineage tree.

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

write(outpath, isotype_encoding=None, tree_label=None)

Write the lineage tree data to files.

Parameters:

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

Source code in tribal/lineage_tree.py

def write(self, outpath:str, isotype_encoding=None, tree_label=None):
    """Write the lineage tree data to files.

    Parameters
    ----------
    outpath : str
        the path to file the files should be written.  
    isotype_encoding : list, optional
        the ordered isotype labels  
    """
    if tree_label is None:
        tree_label = ""
    else:
        tree_label = f"{tree_label}"
    clono_name = self.clonotype
    if isotype_encoding is not None:
        isotypes = {}
        for key, iso in self.isotypes.items():
            if iso >=0 and iso < len(isotype_encoding):
                isotypes[key] = isotype_encoding[iso]
            else:
                isotypes[key] = iso
        isotype_encoding = isotype_encoding

    else:
        isotypes = self.isotypes
        isotype_encoding = None


    if not os.path.exists(outpath):
        os.makedirs(outpath)

    write_fasta(f"{outpath}/{clono_name}_sequences{tree_label}.fasta", self.sequences)
    save_dict(f"{outpath}/{clono_name}_isotypes{tree_label}.csv",isotypes)
    self.save_edges(f"{outpath}/{clono_name}_edge_list{tree_label}.txt")
    self.draw(f"{outpath}/{clono_name}_tree{tree_label}.png",
                isotype_encoding=isotype_encoding,
                hide_underscore=False,
                show_legend=True)