Visualization

Composition plots

hide_deconv.visualization.plot_pca(C_est, out_path, labeling=[], group_name='Cohorts', title_suffix='', biplot=False, datasets_to_map=[], labels_data_map=[])

Performs a principal component analysis on the given composition and plots the result as a scatterplot. the labeling list can be used to add a coloring to the points.

Parameters:

Name	Type	Description	Default
C_est	DataFrame	Composition dataframe (celltypes x bulks)	required
out_path	str	Filename + Path, where the plot will be stored.	required
labeling	list = []	List with labels for each bulk.	[]
group_name	str = "Cohorts"	Name of the legend.	'Cohorts'
title_suffix	str = ''	Suffix displayed after the image title.	''
biplot	bool = False	If True saves a PCA biplot.	False

Source code in src/hide_deconv/visualization/compositions.py

def plot_pca(
    C_est: pd.DataFrame,
    out_path: str,
    labeling: list = [],
    group_name: str = "Cohorts",
    title_suffix: str = "",
    biplot: bool = False,
    datasets_to_map: list[pd.DataFrame] = [],
    labels_data_map: list[str] = [],
) -> None:
    """
    Performs a principal component analysis on the given composition and plots the result as a scatterplot.
    the labeling list can be used to add a coloring to the points.

    Parameters
    ----------
    C_est : pd.DataFrame
        Composition dataframe (celltypes x bulks)
    out_path : str
        Filename + Path, where the plot will be stored.
    labeling : list = []
        List with labels for each bulk.
    group_name : str = "Cohorts"
        Name of the legend.
    title_suffix : str = ''
        Suffix displayed after the image title.
    biplot : bool = False
        If True saves a PCA biplot.
    """

    df = C_est.T
    label_values = list(labeling)

    if label_values:
        labels_series = pd.Series(label_values, index=df.index)
        mask = labels_series.notna()

        df = df.loc[mask]
        label_values = labels_series.loc[mask].tolist()

    scaler = StandardScaler()
    df_scaled = scaler.fit_transform(df)

    pca = PCA(n_components=2)
    X_pca = pca.fit_transform(df_scaled)

    pca_df = pd.DataFrame(X_pca, index=df.index, columns=["PC1", "PC2"])
    if len(datasets_to_map) != len(labels_data_map):
        raise ValueError("Mapped datasets and labels must have the same length.")

    mapped_pca = []
    mapped_labels = []
    for dataset, label in zip(datasets_to_map, labels_data_map):
        mapped_df = dataset.T.reindex(columns=df.columns)
        mapped_pca.append(
            pd.DataFrame(
                pca.transform(scaler.transform(mapped_df)),
                index=mapped_df.index,
                columns=["PC1", "PC2"],
            )
        )
        mapped_labels.extend([label] * len(mapped_df))

    if mapped_pca:
        mapped_pca_df = pd.concat(mapped_pca)
        pca_df = pd.concat([pca_df, mapped_pca_df])

    fig, ax = plt.subplots(figsize=(7, 5))
    sns.set_theme(style="whitegrid", context="paper")

    if label_values or mapped_labels:
        if mapped_labels:
            label_values = [*label_values, *mapped_labels]
            if len(label_values) < len(pca_df):
                label_values = [None] * (len(pca_df) - len(label_values)) + label_values
        pca_df.loc[:, "labels"] = label_values

        labels = pca_df["labels"].dropna().unique()
        palette = dict(zip(labels, sns.color_palette("hls", len(labels))))

        sns.scatterplot(
            x="PC1", y="PC2", data=pca_df, hue="labels", ax=ax, palette=palette
        )
        ax.legend(title=group_name, bbox_to_anchor=(1.02, 1), loc="upper left")
    else:
        sns.scatterplot(x="PC1", y="PC2", data=pca_df, ax=ax)

    ax.set_title(f"PCA{title_suffix}")
    ax.set_xlabel(f"PC1 ({pca.explained_variance_ratio_[0] * 100:.1f}%)")
    ax.set_ylabel(f"PC2 ({pca.explained_variance_ratio_[1] * 100:.1f}%)")
    ax.axhline(0, color="0.85", linewidth=1, zorder=0)
    ax.axvline(0, color="0.85", linewidth=1, zorder=0)
    ax.spines["top"].set_visible(False)
    ax.spines["right"].set_visible(False)
    ax.set_aspect("equal", adjustable="datalim")

    fig.savefig(out_path, dpi=300, bbox_inches="tight")
    pca_df.to_csv(out_path.removesuffix(".png") + ".csv")

    if biplot:
        plot_pca_biplot(
            pca=pca,
            X_pca=X_pca,
            df=df,
            pca_df=pca_df,
            out_path=out_path,
            group_name=group_name,
            title_suffix=title_suffix,
        )

    plt.close(fig)

hide_deconv.visualization.plot_umap(C_est, out_path, labeling=[], group_name='Cohorts', title_suffix='', datasets_to_map=[], labels_data_map=[])

Performs a principal component analysis combined with an universal manifold projection on the given composition and plots the result. The labeling list can be used to add a coloring to the points.

Parameters:

Name	Type	Description	Default
C_est	DataFrame	Composition dataframe (celltypes x bulks)	required
out_path	str	Filename + Path, where the plot will be stored.	required
labeling	list = []	List with labels for each bulk.	[]
group_name	str = "Cohorts"	Name of the legend.	'Cohorts'
title_suffix	str = ''	Suffix displayed after the image title.	''

Source code in src/hide_deconv/visualization/compositions.py

def plot_umap(
    C_est: pd.DataFrame,
    out_path: str,
    labeling: list = [],
    group_name="Cohorts",
    title_suffix: str = "",
    datasets_to_map: list[pd.DataFrame] = [],
    labels_data_map: list[str] = [],
) -> None:
    """
    Performs a principal component analysis combined with an universal manifold projection on the given composition and plots the result.
    The labeling list can be used to add a coloring to the points.

    Parameters
    ----------
    C_est : pd.DataFrame
        Composition dataframe (celltypes x bulks)
    out_path : str
        Filename + Path, where the plot will be stored.
    labeling : list = []
        List with labels for each bulk.
    group_name : str = "Cohorts"
        Name of the legend.
    title_suffix : str = ''
        Suffix displayed after the image title.
    """

    df = C_est.T
    label_values = list(labeling)

    if label_values:
        labels_series = pd.Series(label_values, index=df.index)
        mask = labels_series.notna()

        df = df.loc[mask]
        label_values = labels_series.loc[mask].tolist()

    scaler = StandardScaler()
    df_scaled = scaler.fit_transform(df)

    pca = PCA()
    X_pca = pca.fit_transform(df_scaled)

    reducer = umap.UMAP(random_state=2304)
    embedding = reducer.fit_transform(X_pca)

    umap_df = pd.DataFrame(
        {
            "UMAP1": embedding[:, 0],
            "UMAP2": embedding[:, 1],
        },
        index=df.index,
    )
    if len(datasets_to_map) != len(labels_data_map):
        raise ValueError("Mapped datasets and labels must have the same length.")

    mapped_umap = []
    mapped_labels = []
    for dataset, label in zip(datasets_to_map, labels_data_map):
        mapped_df = dataset.T.reindex(columns=df.columns)
        mapped_umap.append(
            pd.DataFrame(
                reducer.transform(pca.transform(scaler.transform(mapped_df))),
                index=mapped_df.index,
                columns=["UMAP1", "UMAP2"],
            )
        )
        mapped_labels.extend([label] * len(mapped_df))

    if mapped_umap:
        umap_df = pd.concat([umap_df, *mapped_umap])

    fig, ax = plt.subplots(figsize=(7, 5))
    sns.set_theme(style="whitegrid", context="paper")

    if label_values or mapped_labels:
        if mapped_labels:
            label_values = [*label_values, *mapped_labels]
            if len(label_values) < len(umap_df):
                label_values = [None] * (
                    len(umap_df) - len(label_values)
                ) + label_values
        umap_df.loc[:, "labels"] = label_values

        labels = umap_df["labels"].dropna().unique()
        palette = dict(zip(labels, sns.color_palette("hls", len(labels))))

        sns.scatterplot(
            x="UMAP1", y="UMAP2", data=umap_df, hue="labels", ax=ax, palette=palette
        )
        ax.legend(title=group_name, bbox_to_anchor=(1.02, 1), loc="upper left")
    else:
        sns.scatterplot(x="UMAP1", y="UMAP2", data=umap_df, ax=ax)

    ax.set_title(f"UMAP{title_suffix}")

    fig.savefig(out_path, dpi=300, bbox_inches="tight")
    umap_df.to_csv(out_path.removesuffix(".png") + ".csv")

    plt.close(fig)

hide_deconv.visualization.plot_kmeans_pca(C_est, out_path, n_clusters, labeling=[], group_name='Cohorts', title_suffix='', biplot=False)

Perform PCA, perform k-means and saves a scatter plot.

Parameters:

Name	Type	Description	Default
C_est	DataFrame	Composition dataframe (celltypes x bulks)	required
out_path	str	Filename + Path, where the plot will be stored.	required
n_clusters	int	Number of clusters to create.	required
labeling	list = []	List with labels for each bulk.	[]
group_name	str = "Cohorts"	Name of the legend.	'Cohorts'
title_suffix	str = ''	Suffix displayed after the image title.	''

Returns:

Type	Description
DataFrame	Cluster assignments

Source code in src/hide_deconv/visualization/compositions.py

def plot_kmeans_pca(
    C_est: pd.DataFrame,
    out_path: str,
    n_clusters: int,
    labeling: list = [],
    group_name: str = "Cohorts",
    title_suffix: str = "",
    biplot: bool = False,
) -> pd.DataFrame:
    """
    Perform PCA, perform k-means and saves a scatter plot.

    Parameters
    ----------
    C_est : pd.DataFrame
        Composition dataframe (celltypes x bulks)
    out_path : str
        Filename + Path, where the plot will be stored.
    n_clusters : int
        Number of clusters to create.
    labeling : list = []
        List with labels for each bulk.
    group_name : str = "Cohorts"
        Name of the legend.
    title_suffix : str = ''
        Suffix displayed after the image title.

    Returns
    -------
    pd.DataFrame
        Cluster assignments
    """

    df = C_est.T

    if len(labeling) > 0:
        labeling = pd.Series(labeling, index=df.index)
        mask = labeling.notna()

        df = df.loc[mask]
        labeling = labeling.loc[mask].tolist()

    if len(df.index) < n_clusters:
        raise ValueError("Number of clusters must not exceed number of samples.")

    df_scaled = StandardScaler().fit_transform(df)

    pca = PCA(n_components=2)
    X_pca = pca.fit_transform(df_scaled)

    kmeans = KMeans(n_clusters=n_clusters, random_state=2304, n_init=10)
    cluster_labels = kmeans.fit_predict(X_pca)

    pca_df = pd.DataFrame(X_pca, index=df.index, columns=["PC1", "PC2"])
    pca_df.loc[:, "cluster"] = cluster_labels

    fig, ax = plt.subplots(figsize=(7, 5))
    sns.set_theme(style="whitegrid", context="paper")

    plot_kmean_bgrd(ax, kmeans, X_pca[:, 0], X_pca[:, 1])

    if len(labeling) > 0:
        pca_df.loc[:, "labels"] = labeling

        labels = pca_df["labels"].dropna().unique()
        palette = dict(zip(labels, sns.color_palette("hls", len(labels))))

        sns.scatterplot(
            x="PC1",
            y="PC2",
            data=pca_df,
            hue="labels",
            ax=ax,
            palette=palette,
            s=55,
            edgecolor="white",
            linewidth=0.4,
        )
        ax.legend(title=group_name, bbox_to_anchor=(1.02, 1), loc="upper left")
    else:
        pca_df.loc[:, "cluster_label"] = pca_df["cluster"].astype(str)
        cluster_palette = dict(
            zip(
                [str(i) for i in range(n_clusters)],
                sns.color_palette("hls", n_clusters),
            )
        )

        sns.scatterplot(
            x="PC1",
            y="PC2",
            data=pca_df,
            hue="cluster_label",
            ax=ax,
            palette=cluster_palette,
            s=55,
            edgecolor="white",
            linewidth=0.4,
        )
        ax.legend(title="Cluster", bbox_to_anchor=(1.02, 1), loc="upper left")

    ax.set_title(f"K-means PCA{title_suffix}")
    ax.set_xlabel(f"PC1 ({pca.explained_variance_ratio_[0] * 100:.1f}%)")
    ax.set_ylabel(f"PC2 ({pca.explained_variance_ratio_[1] * 100:.1f}%)")
    ax.axhline(0, color="0.85", linewidth=1, zorder=0)
    ax.axvline(0, color="0.85", linewidth=1, zorder=0)
    ax.spines["top"].set_visible(False)
    ax.spines["right"].set_visible(False)
    ax.set_aspect("equal", adjustable="datalim")

    fig.savefig(out_path, dpi=300, bbox_inches="tight")
    pca_df.to_csv(Path(out_path).with_suffix(".csv"))

    if biplot:
        plot_kmeans_pca_biplot(
            pca=pca,
            X_pca=X_pca,
            df=df,
            pca_df=pca_df,
            out_path=out_path,
            kmeans=kmeans,
            group_name=group_name,
            title_suffix=title_suffix,
        )

    plt.close(fig)

    return pd.DataFrame({"id": list(df.index), "assigned_cluster": cluster_labels})

hide_deconv.visualization.plot_celltype_bar_scatter(C_est, out_path, labeling=[], displayed_celltypes=[], celltypes_to_normalize_to=[], group_name='Cohorts', title_suffix='', show_meta=False)

Plots the cell-type abundance as a scatter plot.

If labeling is provided, samples are colored by cohort. Renormalizes samples when list of cell-types to renormalize is provided.

Parameters:

Name	Type	Description	Default
C_est	DataFrame	Composition dataframe (celltypes x samples).	required
out_path	str	Filename + path, where the plot will be stored.	required
labeling	list = []	List with one cohort label for each sample.	[]
displayed_celltypes	list = []	Cell types to display. If empty, all cell types are displayed.	[]
celltypes_to_normalize_to	list = []	Cell types to exclude before sample wise renormalization.	[]
group_name	str = "Cohorts"	Name of the legend.	'Cohorts'
title_suffix	str = ""	Suffix displayed after the figure title.	''
show_meta	bool = False	Shows meta information.	False

Source code in src/hide_deconv/visualization/compositions.py

def plot_celltype_bar_scatter(
    C_est: pd.DataFrame,
    out_path: str,
    labeling: list = [],
    displayed_celltypes: list = [],
    celltypes_to_normalize_to: list = [],
    group_name: str = "Cohorts",
    title_suffix: str = "",
    show_meta: bool = False,
) -> None:
    """
    Plots the cell-type abundance as a scatter plot.

    If labeling is provided, samples are colored by cohort.
    Renormalizes samples when list of cell-types to renormalize is provided.

    Parameters
    ----------
    C_est : pd.DataFrame
        Composition dataframe (celltypes x samples).
    out_path : str
        Filename + path, where the plot will be stored.
    labeling : list = []
        List with one cohort label for each sample.
    displayed_celltypes : list = []
        Cell types to display. If empty, all cell types are displayed.
    celltypes_to_normalize_to : list = []
        Cell types to exclude before sample wise renormalization.
    group_name : str = "Cohorts"
        Name of the legend.
    title_suffix : str = ""
        Suffix displayed after the figure title.
    show_meta : bool = False
        Shows meta information.
    """
    point_size = 10

    # Renormalize samples
    if len(celltypes_to_normalize_to) > 0:
        C_plot = C_est.drop(index=celltypes_to_normalize_to).copy()
        sample_sums = C_plot.sum(axis=0)
        C_plot = C_plot.div(sample_sums, axis=1)
    else:
        C_plot = C_est.copy()

    if len(displayed_celltypes) > 0:
        celltypes = displayed_celltypes
    else:
        celltypes = list(C_plot.index)

    if len(celltypes) == 0:
        raise ValueError("No cell types available for plotting.")

    sns.set_theme(style="whitegrid", context="paper")

    if len(labeling) > 0:
        labels = pd.Series(labeling, index=C_plot.columns)
        unique_labels = labels.dropna().unique()
        palette = dict(zip(unique_labels, sns.color_palette("hls", len(unique_labels))))
    else:
        labels = None
        unique_labels = []
        palette = None

    if len(unique_labels) > 0:
        n_cohorts = len(unique_labels)
        cohort_spacing = 0.28
        block_height = max(1.0, cohort_spacing * n_cohorts)

        celltype_centers = np.arange(len(celltypes)) * block_height
        cohort_offsets = (np.arange(n_cohorts) - (n_cohorts - 1) / 2) * cohort_spacing
    else:
        celltype_centers = np.arange(len(celltypes))
        cohort_offsets = np.array([0.0])

    fig, ax = plt.subplots(figsize=(8, max(4, 0.55 * len(celltypes) + 1)))

    for celltype_idx, celltype in enumerate(celltypes):
        values = C_plot.loc[celltype]

        if len(unique_labels) > 0:
            for cohort_idx, label in enumerate(unique_labels):
                sample_mask = labels == label
                x_values = values.loc[sample_mask].values * 100

                y = celltype_centers[celltype_idx] + cohort_offsets[cohort_idx]

                y_values = np.full(len(x_values), y, dtype=float)

                if len(x_values) > 1:
                    y_values += np.linspace(-0.07, 0.07, len(x_values))

                ax.scatter(
                    x_values,
                    y_values,
                    color=palette[label],
                    s=point_size,
                    alpha=0.75,
                    zorder=3,
                    label=label if celltype_idx == 0 else None,
                )

                mean_value = values.loc[sample_mask].mean() * 100

                ax.vlines(
                    mean_value,
                    y - 0.15,
                    y + 0.15,
                    linewidth=2,
                    zorder=4,
                )

        else:
            x_values = values.values * 100
            y = celltype_centers[celltype_idx]

            y_values = np.full(len(x_values), y, dtype=float)

            if len(x_values) > 1:
                y_values += np.linspace(-0.07, 0.07, len(x_values))

            ax.scatter(
                x_values,
                y_values,
                s=point_size,
                alpha=0.75,
                zorder=3,
            )

        if len(celltypes) > 1:
            separator_positions = (celltype_centers[:-1] + celltype_centers[1:]) / 2

            for y_sep in separator_positions:
                ax.axhline(
                    y=y_sep,
                    color="0.8",
                    linewidth=0.8,
                    linestyle="-",
                    zorder=1,
                )

    ax.set_yticks(celltype_centers)
    ax.set_yticklabels(celltypes)
    ax.set_xlabel("total abundance (%)")
    ax.set_ylabel("")
    ax.set_title(f"Cell type abundance{title_suffix}")

    if len(unique_labels) > 0:
        ax.legend(
            title=group_name,
            bbox_to_anchor=(1.02, 1),
            loc="upper left",
        )

    ax.spines["top"].set_visible(False)
    ax.spines["right"].set_visible(False)

    y_margin = abs(cohort_offsets).max() + 0.25 if len(unique_labels) > 0 else 0.5

    ax.set_ylim(
        celltype_centers[0] - y_margin,
        celltype_centers[-1] + y_margin,
    )

    if show_meta and len(celltypes_to_normalize_to) > 0:
        fig.subplots_adjust(bottom=0.18)
        fig.text(
            0.5,
            0.04,
            "Excluded before normalization: " + ", ".join(celltypes_to_normalize_to),
            ha="center",
            va="bottom",
            fontsize=8,
        )
    else:
        fig.tight_layout()

    fig.savefig(
        out_path,
        dpi=300,
        bbox_inches="tight",
    )

    plt.close(fig)

hide_deconv.visualization.plot_eval(C_true, C_hat, out_path)

Plots a scatter-box-plot of two compositions and saves it at the given directory.

Additionally calculates various metrics between the two compositions and returns them

Parameters:

Name	Type	Description	Default
C_true	DataFrame	Ground truth composition (celltype x mixture)	required
C_hat	DataFrame	Estimated composition (celltype x mixture)	required
out_path	str	Path, where the scatter-box-plot will be saved.	required

Returns:

Type	Description
DataFrame	Dataframe containing various metrics for comparing the two compositions.

Source code in src/hide_deconv/visualization/compositions.py

def plot_eval(C_true: pd.DataFrame, C_hat: pd.DataFrame, out_path: str) -> pd.DataFrame:
    """
    Plots a scatter-box-plot of two compositions and saves it at the given directory.

    Additionally calculates various metrics between the two compositions and returns them

    Parameters
    ----------
    C_true : pd.DataFrame
        Ground truth composition (celltype x mixture)
    C_hat : pd.DataFrame
        Estimated composition (celltype x mixture)
    out_path : str
        Path, where the scatter-box-plot will be saved.

    Returns
    -------
    pd.DataFrame
        Dataframe containing various metrics for comparing the two compositions.
    """
    C_true = C_true.loc[C_hat.index, C_hat.columns]

    results = []

    celltypes = list(C_true.index)
    n = len(celltypes)

    ncols = 3
    nrows = int(np.ceil(n / ncols))

    fig, axes = plt.subplots(nrows, ncols, figsize=(5 * ncols, 4 * nrows), sharey=False)
    axes = np.array(axes).reshape(-1)

    for idx, ct in enumerate(celltypes):
        ax = axes[idx]

        c_true = C_true.loc[ct].values
        c_hat = C_hat.loc[ct].values

        c_true = C_true.loc[ct].values
        c_hat = C_hat.loc[ct].values

        min_val = np.min(c_true)
        max_val = np.max(c_true)

        bins = np.linspace(min_val, max_val, 11)

        bin_ids = np.digitize(c_true, bins) - 1
        bin_ids = np.clip(bin_ids, 0, len(bins) - 2)

        df_plot = pd.DataFrame({"true": c_true, "hat": c_hat, "bin": bin_ids})

        sns.stripplot(
            data=df_plot,
            x="bin",
            y="hat",
            ax=ax,
            color="black",
            size=2,
            alpha=0.4,
            jitter=0.2,
        )
        sns.boxplot(
            data=df_plot,
            x="bin",
            y="hat",
            ax=ax,
            color="white",
            linecolor="lightblue",
            fliersize=2,
        )

        ax.set_title(ct)
        ax.set_xlabel("True")
        ax.set_ylabel("Estimated")

        ax.set_xticks(range(len(bins) - 1))
        ax.set_xticklabels(
            [f"{bins[j]:.3f}" for j in range(len(bins) - 1)], rotation=45
        )

        # Metrics
        pcc = pearsonr(c_true, c_hat)[0]
        scc = spearmanr(c_true, c_hat)[0]
        kt = kendalltau(c_true, c_hat)[0]
        rmse = np.sqrt(np.mean((c_true - c_hat) ** 2))
        nmae = np.mean(np.abs(c_true - c_hat)) / (np.mean(c_true) + 1e-8)
        cos_sim = np.dot(c_true, c_hat) / (norm(c_true) * norm(c_hat) + 1e-8)

        annot = f"PCC: {pcc:.2f}\nSCC: {scc:.2f}\nNMAE: {nmae:.2f}"

        ax.text(
            0.98, 0.98, annot, transform=ax.transAxes, ha="right", va="top", fontsize=7
        )

        results.append(
            {
                "celltype": ct,
                "PCC": pcc,
                "SCC": scc,
                "KT": kt,
                "RMSE": rmse,
                "NMAE": nmae,
                "COS_SIM": cos_sim,
            }
        )

    for j in range(len(celltypes), len(axes)):
        fig.delaxes(axes[j])

    plt.tight_layout()

    if out_path is not None:
        fig.savefig(out_path, dpi=300)

    plt.close(fig)

    return pd.DataFrame(results).set_index("celltype")

hide_deconv.visualization.plot_hier_heat(mwu_sub, mwu_higher, layer_names, A_matrix, cohort_1_name, cohort_2_name, out_path)

Plots Man Whitney U results as hierarchical heatmap connected by the relationship between the celltypes.

Parameters:

Name	Type	Description	Default
mwu_sub	DataFrame	mwu results of finest layer	required
mwu_higher	list[DataFrame]	mwu results of higher layers	required
layer_names	list[str]	Layer names, as they should appear in the plot	required
A_matrix	list[DataFrame]	Projection matrices, note, that the first entry should be the identity	required
cohort_1_name	str	Name of the first cohort as it should appear in the plot	required
cohort_2_name	str	Name of the second cohort as it should appear in the plot	required
out_path	Path	Path, where the plot will be saved	required

Source code in src/hide_deconv/visualization/heatmaps.py

def plot_hier_heat(
    mwu_sub: pd.DataFrame,
    mwu_higher: list[pd.DataFrame],
    layer_names: list[str],
    A_matrix: list[pd.DataFrame],
    cohort_1_name: str,
    cohort_2_name: str,
    out_path: Path,
) -> None:
    """
    Plots Man Whitney U results as hierarchical heatmap connected by the relationship between the celltypes.

    Parameters
    ----------
    mwu_sub : pd.DataFrame
        mwu results of finest layer
    mwu_higher : list[pd.DataFrame]
        mwu results of higher layers
    layer_names : list[str]
        Layer names, as they should appear in the plot
    A_matrix : list[pd.DataFrame]
        Projection matrices, note, that the first entry should be the identity
    cohort_1_name : str
        Name of the first cohort as it should appear in the plot
    cohort_2_name : str
        Name of the second cohort as it should appear in the plot
    out_path : Path
        Path, where the plot will be saved
    """

    sns.set_theme(style="whitegrid", context="paper")

    level_dfs = list(reversed(mwu_higher)) + [mwu_sub]
    level_names = list(reversed(layer_names[1:])) + [layer_names[0]]

    proj_dict = {name: mat for name, mat in zip(layer_names, A_matrix)}

    subtypes = order_subtypes(mwu_sub, A_matrix)
    mwu_sub = mwu_sub.reindex(subtypes)

    n_sub = len(subtypes)

    row_spacing = 1.15
    sub_y = {ct: (n_sub - 1 - i) * row_spacing for i, ct in enumerate(subtypes)}

    # determine positions of cell types
    y_positions = {}
    y_positions[layer_names[0]] = sub_y

    for level_name, proj in zip(layer_names[1:], A_matrix[1:]):
        level_pos = {}

        for parent in proj.index:
            members = proj.loc[parent]
            members = members[members == 1].index

            ys = [sub_y[m] for m in members]

            level_pos[parent] = np.mean(ys)

        y_positions[level_name] = level_pos

    ordered_level_dfs = []

    for level_name, df in zip(level_names, level_dfs):
        ordered_index = sorted(
            df.index, key=lambda ct: (y_positions[level_name][ct], df.index.get_loc(ct))
        )

        ordered_level_dfs.append(df.loc[ordered_index])

    # Collect mean expressions and normalize them
    all_means = []

    for df in ordered_level_dfs:
        all_means.extend(df.iloc[:, 0].values)
        all_means.extend(df.iloc[:, 2].values)

    all_means = np.asarray(all_means)

    log_vals = np.log10(all_means + 1e-8)

    vmin = np.quantile(log_vals, 0.02)
    vmax = np.quantile(log_vals, 0.98)

    norm = Normalize(vmin=vmin, vmax=vmax)

    cmap = sns.color_palette("viridis", as_cmap=True)

    n_levels = len(level_dfs)

    heatmap_width = 2.0
    layer_spacing = 2.5

    x_positions = {
        level_name: i * layer_spacing for i, level_name in enumerate(level_names)
    }

    fig_width = n_levels * 2.5 + 4
    fig_height = max(6, n_sub * 0.6)
    top_label_y = (n_sub - 1) * row_spacing + row_spacing * 2.35
    bottom_label_y = -row_spacing * 1.25

    fig, ax = plt.subplots(figsize=(fig_width, fig_height))

    # Create connections between the various layers
    for i in range(n_levels - 1):
        parent_name = level_names[i]
        child_name = level_names[i + 1]

        parent_df = level_dfs[i]
        child_df = level_dfs[i + 1]

        parent_proj = proj_dict[parent_name]
        child_proj = proj_dict[child_name]

        x_parent = x_positions[parent_name] + heatmap_width
        x_child = x_positions[child_name]

        for parent in parent_df.index:
            parent_subs = set(
                parent_proj.loc[parent][parent_proj.loc[parent] == 1].index
            )

            y_parent = y_positions[parent_name][parent]

            for child in child_df.index:
                child_subs = set(
                    child_proj.loc[child][child_proj.loc[child] == 1].index
                )

                if len(parent_subs & child_subs) == 0:
                    continue

                y_child = y_positions[child_name][child]

                ax.plot(
                    [x_parent, x_child],
                    [y_parent, y_child],
                    color="lightgrey",
                    lw=1,
                    zorder=1,
                )

    # Draw heatmaps
    cell_height = min(0.9, row_spacing * 0.75)
    cell_width = 1.0

    for level_name, df in zip(level_names, ordered_level_dfs):
        x0 = x_positions[level_name]

        for celltype, row in df.iterrows():
            y = y_positions[level_name][celltype]

            mean_1 = row.iloc[0]
            mean_2 = row.iloc[2]

            val_1 = np.log10(mean_1 + 1e-8)
            val_2 = np.log10(mean_2 + 1e-8)

            color_1 = cmap(norm(val_1))
            color_2 = cmap(norm(val_2))

            rect1 = Rectangle(
                (x0, y - cell_height / 2),
                cell_width,
                cell_height,
                facecolor=color_1,
                edgecolor="white",
                linewidth=0.5,
                zorder=2,
            )

            rect2 = Rectangle(
                (x0 + cell_width, y - cell_height / 2),
                cell_width,
                cell_height,
                facecolor=color_2,
                edgecolor="white",
                linewidth=0.5,
                zorder=2,
            )

            ax.add_patch(rect1)
            ax.add_patch(rect2)

            marker = ""

            if row["p_adj"] < 0.05:
                marker = "**"

            elif row["p"] < 0.05:
                marker = "*"

            if marker:
                ax.text(
                    x0 + 0.5,
                    y,
                    marker,
                    ha="center",
                    va="center",
                    fontsize=8,
                    fontweight="bold",
                    c="r",
                    zorder=3,
                )

                ax.text(
                    x0 + 1.5,
                    y,
                    marker,
                    ha="center",
                    va="center",
                    fontsize=8,
                    fontweight="bold",
                    c="r",
                    zorder=3,
                )

    for level_name in level_names:
        x0 = x_positions[level_name]

        ax.text(
            x0 + 1.0,
            top_label_y,
            level_name,
            ha="center",
            va="bottom",
            fontsize=12,
            fontweight="bold",
        )

    for level_name in level_names:
        x0 = x_positions[level_name]

        ax.text(
            x0 + 0.5, bottom_label_y, cohort_1_name, ha="center", va="top", rotation=45
        )

        ax.text(
            x0 + 1.5, bottom_label_y, cohort_2_name, ha="center", va="top", rotation=45
        )

    left_level = level_names[0]

    for ct in ordered_level_dfs[0].index:
        y = y_positions[left_level][ct]
        ax.text(
            x_positions[left_level] - 0.2, y, ct, ha="right", va="center", fontsize=9
        )

    right_level = layer_names[0]

    for ct in ordered_level_dfs[-1].index:
        y = y_positions[right_level][ct]
        ax.text(
            x_positions[right_level] + 2.2, y, ct, ha="left", va="center", fontsize=9
        )

    sm = ScalarMappable(norm=norm, cmap=cmap)

    cbar = fig.colorbar(sm, ax=ax, fraction=0.03, pad=0.02)

    cbar.set_label("log10(mean proportion)")

    ax.set_xlim(-1.5, max(x_positions.values()) + 4)

    ax.set_ylim(bottom_label_y - row_spacing * 1.3, top_label_y + row_spacing * 1.1)

    ax.set_xticks([])
    ax.set_yticks([])

    for spine in ax.spines.values():
        spine.set_visible(False)

    ax.grid(False)

    fig.text(
        0.5, 0.02, "* nominal p < 0.05 ** adjusted p < 0.05", ha="center", fontsize=10
    )

    plt.tight_layout(rect=(0, 0.05, 1, 1))

    out_path = Path(out_path)

    plt.savefig(
        out_path,
        dpi=300,
        bbox_inches="tight",
    )

    plt.close()

hide_deconv.visualization.plot_genemap(X, gene_series, title, out_path)

Plot subset of genes of reference profile as heatmap and cluster them.

Parameters:

Name	Type	Description	Default
X	DataFrame	Reference profile	required
gene_series	list	List of genes to plot	required
title	str	Title of plot	required
out_path	str	Path, where plot will be saved	required

Source code in src/hide_deconv/visualization/heatmaps.py

def plot_genemap(X: pd.DataFrame, gene_series, title: str, out_path: Path) -> None:
    """
    Plot subset of genes of reference profile as heatmap and cluster them.

    Parameters
    ----------
    X : pd.DataFrame
        Reference profile
    gene_series : list
        List of genes to plot
    title : str
        Title of plot
    out_path : str
        Path, where plot will be saved
    """

    # Normalize genes, such that sum over each gene = 1
    X_standardized = (X.T / X.T.sum(axis=0)).T.loc[gene_series]
    n_celltypes = X_standardized.shape[1]
    n_genes = X_standardized.shape[0]

    row_linkage = linkage(X_standardized.T, method="single")
    col_linkage = linkage(X_standardized, method="single")

    clustermap = sns.clustermap(
        X_standardized.T,
        row_cluster=True,
        col_cluster=True,
        figsize=(max(25, n_genes * 0.45), max(6, n_celltypes * 0.35)),
        row_linkage=row_linkage,
        col_linkage=col_linkage,
        # cmap="coolwarm",
        # linewidths=0.8,
        cbar_kws={"label": "Expression Level"},
        xticklabels=True,
        yticklabels=True,
        # cbar_pos=(0.05, 0.8, 0.03, 0.15),
    )
    clustermap.ax_heatmap.tick_params(axis="x", labelrotation=90, labelsize=16)
    clustermap.ax_heatmap.tick_params(axis="y", labelsize=16)
    plt.title(f"{title}")

    clustermap.savefig(out_path)

hide_deconv.visualization.plot_volcano(results, out_path)

Visualizes pydeseq2 results as volcano plot

Parameters:

Name	Type	Description	Default
results	DataFrame	Results of pydeseq2 that must at least contain columns 'padj' and 'log2FoldChange'	required
out_path	Path	Path, where the figures is saved	required

Source code in src/hide_deconv/visualization/deg.py

def plot_volcano(results: pd.DataFrame, out_path: Path) -> None:
    """
    Visualizes pydeseq2 results as volcano plot

    Parameters
    ----------
    results : pd.DataFrame
        Results of pydeseq2 that must at least contain columns 'padj' and 'log2FoldChange'
    out_path : Path
        Path, where the figures is saved
    """

    out_path = Path(out_path)
    out_path.parent.mkdir(parents=True, exist_ok=True)

    padj = results["padj"].fillna(1.0).clip(lower=1e-300)
    log_padj = -np.log10(padj)
    significant = padj < 0.05

    plt.figure(figsize=(7, 6))
    plt.scatter(
        results["log2FoldChange"],
        log_padj,
        c=np.where(significant, "#b22222", "#4c78a8"),
        s=14,
        alpha=0.8,
        linewidths=0,
    )
    plt.axvline(0.0, color="#666666", linewidth=1)
    plt.axhline(-np.log10(0.05), color="#666666", linewidth=1, linestyle="--")
    plt.xlabel("log2 fold change")
    plt.ylabel("-log10 adjusted p-value")
    plt.tight_layout()
    plt.savefig(out_path, dpi=300)
    plt.close()

PLS-DA plots

hide_deconv.visualization.plot_plsda_score(scores, out_path, cohort_col)

Save a PLS-DA score plot.

Source code in src/hide_deconv/visualization/plsda.py

def plot_plsda_score(
    scores: pd.DataFrame,
    out_path: Path,
    cohort_col: str,
) -> None:
    """
    Save a PLS-DA score plot.
    """

    fig, ax = plt.subplots(figsize=(7, 5))
    sns.set_theme(style="whitegrid", context="paper")

    labels = scores[cohort_col].dropna().unique()
    palette = dict(zip(labels, sns.color_palette("hls", len(labels))))

    sns.scatterplot(
        data=scores,
        x="PLS1",
        y="PLS2",
        hue=cohort_col,
        ax=ax,
        palette=palette,
        s=65,
    )

    ax.axhline(0, color="0.85", linewidth=1, zorder=0)
    ax.axvline(0, color="0.85", linewidth=1, zorder=0)
    ax.set_title("PLS-DA Score Plot")
    ax.set_xlabel("PLS1")
    ax.set_ylabel("PLS2")
    ax.spines["top"].set_visible(False)
    ax.spines["right"].set_visible(False)
    ax.legend(title=cohort_col, bbox_to_anchor=(1.02, 1), loc="upper left")
    ax.set_aspect("equal", adjustable="datalim")

    fig.savefig(out_path, dpi=300, bbox_inches="tight")
    plt.close(fig)

hide_deconv.visualization.plot_plsda_loading(loading, out_path, title='PLS-DA Loading Plot', top_n=20)

Save a PLS-DA loading plot.

Source code in src/hide_deconv/visualization/plsda.py

def plot_plsda_loading(
    loading, out_path: Path, title: str = "PLS-DA Loading Plot", top_n: int = 20
) -> None:
    """
    Save a PLS-DA loading plot.
    """

    fig, ax = plt.subplots(figsize=(10, 6))
    sns.set_theme(style="whitegrid", context="paper")

    df_load = pd.DataFrame(loading).copy()
    df_load = df_load.iloc[:, :2]
    df_load.columns = ["PLS1", "PLS2"]

    rank = df_load.abs().max(axis=1).sort_values(ascending=False)
    top_idx = rank.head(min(top_n, len(rank))).index

    df_plot = df_load.loc[top_idx].copy()
    df_plot["Feature"] = df_plot.index
    comp_cols = ["PLS1", "PLS2"]
    df_melt = df_plot.reset_index(drop=True).melt(
        id_vars=["Feature"],
        value_vars=comp_cols,
        var_name="Component",
        value_name="Loading",
    )

    sns.barplot(
        data=df_melt,
        x="Loading",
        y="Feature",
        hue="Component",
        ax=ax,
        palette=["tab:orange", "tab:green"],
    )

    ax.set_title(title)
    ax.set_xlabel("Loading")
    ax.set_ylabel("Feature")
    ax.legend(title="Component", bbox_to_anchor=(1.02, 1), loc="upper left")

    fig.savefig(out_path, dpi=300, bbox_inches="tight")
    plt.close(fig)

hide_deconv.visualization.plot_plsda_vip(vip, out_path, title='PLS-DA VIP Plot')

Save a PLS-DA VIP plot.

Source code in src/hide_deconv/visualization/plsda.py

def plot_plsda_vip(
    vip: pd.Series, out_path: Path, title: str = "PLS-DA VIP Plot"
) -> None:
    """
    Save a PLS-DA VIP plot.
    """

    fig, ax = plt.subplots(figsize=(8, 4.5))
    sns.set_theme(style="whitegrid", context="paper")

    vip = vip.sort_values(key=lambda s: np.abs(s), ascending=False)
    top_vip = vip.head(min(20, len(vip)))

    sns.barplot(x=top_vip.values, y=top_vip.index, ax=ax, color="steelblue")
    ax.axvline(1.0, color="tab:red", linestyle="--", linewidth=1)
    ax.set_title(title)
    ax.set_xlabel("VIP")
    ax.set_ylabel("Feature")

    fig.savefig(out_path, dpi=300, bbox_inches="tight")
    plt.close(fig)

hide_deconv.visualization.plot_plsda_biplot(scores, loadings, out_path, cohort_col, top_n=15)

Save a PLS-DA biplot.

Source code in src/hide_deconv/visualization/plsda.py

def plot_plsda_biplot(
    scores: pd.DataFrame,
    loadings: pd.DataFrame,
    out_path: Path,
    cohort_col: str,
    top_n: int = 15,
) -> None:
    """
    Save a PLS-DA biplot.
    """

    fig, ax = plt.subplots(figsize=(8, 6))
    sns.set_theme(style="whitegrid", context="paper")

    labels = scores[cohort_col].dropna().unique()
    palette = dict(zip(labels, sns.color_palette("hls", len(labels))))

    sns.scatterplot(
        data=scores,
        x="PLS1",
        y="PLS2",
        hue=cohort_col,
        ax=ax,
        palette=palette,
        s=65,
    )

    ax.axhline(0, color="0.85", linewidth=1, zorder=0)
    ax.axvline(0, color="0.85", linewidth=1, zorder=0)

    # select top n features
    loadings = loadings.copy()
    loadings["norm"] = (loadings["PLS1"] ** 2 + loadings["PLS2"] ** 2) ** 0.5
    top = loadings.sort_values("norm", ascending=False).head(min(top_n, len(loadings)))

    x_lim = ax.get_xlim()
    y_lim = ax.get_ylim()
    score_span = max(abs(x_lim[1] - x_lim[0]), abs(y_lim[1] - y_lim[0]))

    if top["norm"].max() == 0:
        scale = 1.0
    else:
        scale = 0.8 * score_span / top["norm"].max()

    for idx, row in top.iterrows():
        x = row["PLS1"] * scale
        y = row["PLS2"] * scale
        ax.arrow(
            0,
            0,
            x,
            y,
            head_width=0.02 * score_span,
            head_length=0.03 * score_span,
            linewidth=1.0,
            color="tab:red",
            length_includes_head=True,
            alpha=0.8,
        )
        ax.text(x * 1.05, y * 1.05, str(idx), fontsize=8, color="black")

    ax.set_title("PLS-DA Biplot")
    ax.set_xlabel("PLS1")
    ax.set_ylabel("PLS2")
    ax.spines["top"].set_visible(False)
    ax.spines["right"].set_visible(False)
    ax.legend(title=cohort_col, bbox_to_anchor=(1.02, 1), loc="upper left")

    fig.savefig(out_path, dpi=300, bbox_inches="tight")
    plt.close(fig)