rms_permute

rms_permute(confusion_matrix, labels)

Perform reverse merge/split (RMS) permutation analysis on a confusion matrix.

This function analyzes and permutes a confusion matrix to identify merge and split relationships between predicted and ground truth labels. A merge relationship occurs when multiple ground truth labels map to the same predicted label, while a split relationship occurs when a single ground truth label maps to multiple predicted labels.

Parameters:

Name	Type	Description	Default
confusion_matrix	ndarray	The confusion matrix to analyze, shape (n_classes, n_classes)	required
labels	ndarray	The labels corresponding to the confusion matrix rows/columns, shape (n_classes,)	required

Returns:

Name	Type	Description
permuted_matrix	ndarray	The confusion matrix after permuting rows and columns to group related labels
permuted_labels	ndarray	The reordered labels corresponding to the permuted matrix
rms_label_map	dict	Dictionary mapping predicted labels to tuples of (ground truth label, relationship type)
rms_map_matrix	ndarray	Matrix representation of merge/split relationships between labels
rms_map_type	ndarray	Array of relationship types ('rmerge' or 'rsplit') for each relationship

See Also

mheatmap.amc_postprocess : Related module for confusion matrix post-processing mheatmap.spectral_permute : Alternative permutation method using spectral ordering

Notes

The function identifies two types of label relationships: - Merge (rmerge): Multiple ground truth labels map to same predicted label - Split (rsplit): Single ground truth label maps to multiple predicted labels

Examples:

>>> import numpy as np
>>> conf_mat = np.array([[2, 1, 0], [0, 3, 1], [1, 0, 2]])
>>> labels = np.array([1, 2, 3])
>>> perm_mat, perm_labs, rmap, rmat, rtypes = rms_permute(conf_mat, labels)

Source code in mheatmap/_rms_permute.py

def rms_permute(confusion_matrix: np.ndarray, labels: np.ndarray) -> tuple:
    """`rms_permute(confusion_matrix, labels)`

    Perform reverse merge/split (RMS) permutation analysis on a confusion matrix.

    This function analyzes and permutes a confusion matrix to identify merge and split
    relationships between predicted and ground truth labels. A merge relationship occurs
    when multiple ground truth labels map to the same predicted label, while a split
    relationship occurs when a single ground truth label maps to multiple predicted labels.

    Parameters
    ----------
    confusion_matrix : numpy.ndarray
        The confusion matrix to analyze, shape (n_classes, n_classes)
    labels : numpy.ndarray
        The labels corresponding to the confusion matrix rows/columns, shape (n_classes,)

    Returns
    -------
    permuted_matrix : numpy.ndarray
        The confusion matrix after permuting rows and columns to group related labels
    permuted_labels : numpy.ndarray
        The reordered labels corresponding to the permuted matrix
    rms_label_map : dict
        Dictionary mapping predicted labels to tuples of (ground truth label, relationship type)
    rms_map_matrix : numpy.ndarray
        Matrix representation of merge/split relationships between labels
    rms_map_type : numpy.ndarray
        Array of relationship types ('rmerge' or 'rsplit') for each relationship

    See Also
    --------
    mheatmap.amc_postprocess : Related module for confusion matrix post-processing
    mheatmap.spectral_permute : Alternative permutation method using spectral ordering

    Notes
    -----
    The function identifies two types of label relationships:
    - Merge (rmerge): Multiple ground truth labels map to same predicted label
    - Split (rsplit): Single ground truth label maps to multiple predicted labels

    Examples
    --------
    >>> import numpy as np
    >>> conf_mat = np.array([[2, 1, 0], [0, 3, 1], [1, 0, 2]])
    >>> labels = np.array([1, 2, 3])
    >>> perm_mat, perm_labs, rmap, rmat, rtypes = rms_permute(conf_mat, labels)
    """
    rms = _RMSPermute(confusion_matrix, labels)
    permuted_matrix = rms.get_permuted_matrix()
    permuted_labels = rms.get_permuted_labels()
    rms_label_map = rms.rms_label_map
    rms_map_matrix, rms_map_type = rms.get_rms_map_matrix()

    return permuted_matrix, permuted_labels, rms_label_map, rms_map_matrix, rms_map_type