Plotting dendrograms

Convenience wrapper

idendrogram.Dendrogram.plot(...)

Plot the dendrogram using one of the supported backends. This is a convenience function, you can also use to_*() functions from appropriate target backends at idendrogram.targets.[backend].to_[backend]().

Parameters:

Name	Type	Description	Default
backend	str	Backend to use, one of 'altair', 'streamlit', 'plotly', 'matplotlib'.	'altair'
orientation	str	Position of dendrogram's root node. One of "top", "bottom", "left", "right".	'top'
show_nodes	bool	Whether to draw nodes.	True
height	float	Height of the dendrogram.	400
width	float	Width of the dendrogram.	400
scale	str	Scale used for the value axis. One of "linear", "symlog", "log".	'linear'

Raises:

Type	Description
ValueError	Parameters supplied did not comform to allowed values.

Returns:

Name	Type	Description
Any	Any	Varies by backend: Altair: altair.Layered chart object Plotly: plotly.graph_objs.Figure figure object Matplotlib: matplotlib.pyplot.ax axes object Streamlit: idendrogram.ClusterNode object that was clicked on (None if no clicks took place)

Source code in idendrogram/containers.py

def plot(
    self,
    backend: str = "altair",
    orientation: str = "top",
    show_nodes: bool = True,
    height: float = 400,
    width: float = 400,
    scale: str = "linear",
) -> Any:
    """
    Plot the dendrogram using one of the supported backends. This is a convenience function,
        you can also use `to_*()` functions from appropriate target backends at `idendrogram.targets.[backend].to_[backend]()`.

    Args:
        backend (str, optional): Backend to use, one of 'altair', 'streamlit', 'plotly', 'matplotlib'. 
        orientation (str, optional): Position of dendrogram's root node. One of "top", "bottom", "left", "right". 
        show_nodes (bool, optional): Whether to draw nodes. 
        height (float, optional): Height of the dendrogram. 
        width (float, optional): Width of the dendrogram. 
        scale (str, optional): Scale used for the value axis. One of "linear", "symlog", "log". 

    Raises:
        ValueError: Parameters supplied did not comform to allowed values.  

    Returns:
        Any: 

            Varies by backend: 

            - Altair: `altair.Layered` chart object
            - Plotly: `plotly.graph_objs.Figure` figure object
            - Matplotlib: `matplotlib.pyplot.ax` axes object
            - Streamlit: [idendrogram.ClusterNode][] object that was clicked on (None if no clicks took place)
    """
    if backend == 'altair':
        from .targets.altair import to_altair
        return to_altair(self, orientation=orientation, show_nodes=show_nodes, height=height, width=width, scale=scale)
    elif backend == 'matplotlib':
        from .targets.matplotlib import to_matplotlib
        return to_matplotlib(self, orientation=orientation, show_nodes=show_nodes, height=height, width=width, scale=scale)
    elif backend == 'plotly':
        from .targets.plotly import to_plotly
        return to_plotly(self, orientation=orientation, show_nodes=show_nodes, height=height, width=width, scale=scale)
    elif backend == 'streamlit':
        from .targets.streamlit import to_streamlit
        return to_streamlit(self, orientation=orientation, show_nodes=show_nodes, height=height, width=width, scale=scale)
    else:
        raise ValueError(f"Unsupported backend '{backend}', should be one of 'plotly', 'matplotlib', 'altair', 'streamlit'")

Backend-specific functions

idendrogram.targets.altair.to_altair(...)

Converts a dendrogram object into Altair chart.

Parameters:

Name	Type	Description	Default
dendrogram	Dendrogram	idendrogram dendrogram object	required
orientation	str	Position of dendrogram's root node. One of "top", "bottom", "left", "right". Defaults to "top".	'top'
show_nodes	bool	Whether to draw nodes. Defaults to True.	True
height	float	Height of the dendrogram. Defaults to 400.	400
width	float	Width of the dendrogram. Defaults to 400.	400
scale	str	Scale used for the value axis. One of "linear", "symlog", "log". Defaults to 'linear'.	'linear'

Returns:

Type	Description
alt.LayerChart	Altair chart object

Source code in idendrogram/targets/altair.py

def to_altair(
    dendrogram: Dendrogram,
    orientation: str = "top",
    show_nodes: bool = True,
    height: float = 400,
    width: float = 400,
    scale: str = "linear",
) -> alt.LayerChart:
    """Converts a dendrogram object into Altair chart.

    Args:
        dendrogram (Dendrogram): idendrogram dendrogram object
        orientation (str, optional): Position of dendrogram's root node. One of "top", "bottom", "left", "right". Defaults to "top".
        show_nodes (bool, optional): Whether to draw nodes. Defaults to True.
        height (float, optional): Height of the dendrogram. Defaults to 400.
        width (float, optional): Width of the dendrogram. Defaults to 400.
        scale (str, optional): Scale used for the value axis. One of "linear", "symlog", "log". Defaults to 'linear'.

    Returns:
        Altair chart object
    """
    _check_orientation(dendrogram, orientation)
    _check_scale(dendrogram, scale)
    _check_nodes(dendrogram, show_nodes)

    return AltairConverter().convert(
        dendrogram=dendrogram,
        orientation=orientation,
        show_nodes=show_nodes,
        height=height,
        width=width,
        scale=scale,
    )

idendrogram.targets.altair.to_plotly(...)

Converts a dendrogram object into Plotly chart

Parameters:

Name	Type	Description	Default
dendrogram	Dendrogram	idendrogram dendrogram object	required
orientation	str	Position of dendrogram's root node. One of "top", "bottom", "left", "right". Defaults to "top".	'top'
show_nodes	bool	Whether to draw nodes. Defaults to True.	True
height	float	Height of the dendrogram. Defaults to 400.	400
width	float	Width of the dendrogram. Defaults to 400.	400
scale	str	Scale used for the value axis. One of "linear", "log". "symlog" is not supported by Plotly. Defaults to 'linear'.	'linear'

Returns:

Type	Description
Any	plotly.graph_objs.Figure: Plotly figure object

Source code in idendrogram/targets/plotly.py

def to_plotly(
        dendrogram: Dendrogram,
        orientation: str = "top",
        show_nodes: bool = True,
        height: float = 400,
        width: float = 400,
        scale: str = "linear",
    ) -> Any:
        """Converts a dendrogram object into Plotly chart

        Args:
            dendrogram (Dendrogram): idendrogram dendrogram object
            orientation (str, optional): Position of dendrogram's root node. One of "top", "bottom", "left", "right". Defaults to "top".
            show_nodes (bool, optional): Whether to draw nodes. Defaults to True.
            height (float, optional): Height of the dendrogram. Defaults to 400.
            width (float, optional): Width of the dendrogram. Defaults to 400.
            scale (str, optional): Scale used for the value axis. One of "linear", "log". "symlog" is not supported by Plotly. Defaults to 'linear'.

        Returns:
            plotly.graph_objs.Figure: Plotly figure object
        """
        _check_orientation(dendrogram, orientation)
        _check_scale(dendrogram, scale, supported=["linear", "log"])
        _check_nodes(dendrogram, show_nodes)

        return PlotlyConverter().convert(
            dendrogram=dendrogram,
            orientation=orientation,
            show_nodes=show_nodes,
            height=height,
            width=width,
            scale=scale,
        )

idendrogram.targets.altair.to_matplotlib(...)

Converts a dendrogram object into matplotlib chart

Parameters:

Name	Type	Description	Default
dendrogram	Dendrogram	idendrogram dendrogram object	required
orientation	str	Position of dendrogram's root node. One of "top", "bottom", "left", "right". Defaults to "top".	'top'
show_nodes	bool	Whether to draw nodes. Defaults to True.	True
height	float	Height of the dendrogram. Defaults to 400.	400
width	float	Width of the dendrogram. Defaults to 400.	400
scale	str	Scale used for the value axis. One of "linear", "symlog", "log". Defaults to 'linear'.	'linear'

Returns:

Type	Description
Axes	matplotlib.pyplot.ax: matplotlib axes object

Source code in idendrogram/targets/matplotlib.py

def to_matplotlib(
        dendrogram: Dendrogram,
        orientation: str = "top",
        show_nodes: bool = True,
        height: float = 400,
        width: float = 400,
        scale: str = "linear",
    ) -> Axes:
        """Converts a dendrogram object into matplotlib chart

        Args:
            dendrogram (Dendrogram): idendrogram dendrogram object
            orientation (str, optional): Position of dendrogram's root node. One of "top", "bottom", "left", "right". Defaults to "top".
            show_nodes (bool, optional): Whether to draw nodes. Defaults to True.
            height (float, optional): Height of the dendrogram. Defaults to 400.
            width (float, optional): Width of the dendrogram. Defaults to 400.
            scale (str, optional): Scale used for the value axis. One of "linear", "symlog", "log". Defaults to 'linear'.

        Returns:
            matplotlib.pyplot.ax: matplotlib axes object
        """
        _check_orientation(dendrogram, orientation)
        _check_scale(dendrogram, scale)
        _check_nodes(dendrogram, show_nodes)

        return matplotlibConverter().convert(
            dendrogram=dendrogram,
            orientation=orientation,
            show_nodes=show_nodes,
            height=height,
            width=width,
            scale=scale,
        )

idendrogram.targets.altair.to_streamlit(...)

Renders dendrogram object as a custom bi-directional Streamlit component

Parameters:

Name	Type	Description	Default
dendrogram	Dendrogram	idendrogram dendrogram object	required
orientation	str	Position of dendrogram's root node. One of "top", "bottom", "left", "right". Defaults to "top".	'top'
show_nodes	bool	Whether to draw nodes. Defaults to True.	True
height	float	Height of the dendrogram. Defaults to 400.	400
width	float	Width of the dendrogram. Defaults to 400.	400
scale	str	Scale used for the value axis. One of "linear", "symlog", "log". Defaults to 'linear'.	'linear'

Returns:

Type	Description
Optional[ClusterNode]	Optional[ClusterNode]: A ClusterNode object that was clicked on (None if no clicks took place)

Source code in idendrogram/targets/streamlit.py

def to_streamlit(
    dendrogram: Dendrogram,
    orientation: str = "top",
    show_nodes: bool = True,
    height: float = 400,
    width: float = 400,
    scale: str = "linear",
) -> Optional[ClusterNode]:
    """Renders dendrogram object as a custom bi-directional Streamlit component

    Args:
        dendrogram (Dendrogram): idendrogram dendrogram object
        orientation (str, optional): Position of dendrogram's root node. One of "top", "bottom", "left", "right". Defaults to "top".
        show_nodes (bool, optional): Whether to draw nodes. Defaults to True.
        height (float, optional): Height of the dendrogram. Defaults to 400.
        width (float, optional): Width of the dendrogram. Defaults to 400.
        scale (str, optional): Scale used for the value axis. One of "linear", "symlog", "log". Defaults to 'linear'.

    Returns:
        Optional[ClusterNode]: A ClusterNode object that was clicked on (None if no clicks took place)
    """

    _check_orientation(dendrogram, orientation)
    _check_scale(dendrogram, scale)
    _check_nodes(dendrogram, show_nodes)

    return idendrogram_streamlit.StreamlitConverter(release=True).convert(
        dendrogram=dendrogram,
        orientation=orientation,
        show_nodes=show_nodes,
        height=height,
        width=width,
        key="idendrogram",
        scale=scale,
    )