pyxla 0.0.1__py3-none-any.whl

pyxla/__init__.py

@@ -0,0 +1,1380 @@
+
+"""The core functions of the library are defined here."""
+
+import matplotlib.axes
+import numpy as np
+import pandas as pd
+import seaborn as sns
+import matplotlib.pyplot as plt
+import statistics
+import scipy
+from scipy.stats import spearmanr
+from scipy.spatial.distance import pdist
+from typing import Tuple
+import matplotlib
+import math
+from typing import Callable, Union, List, Iterable
+from tqdm.auto import tqdm
+import logging
+import itertools
+from sklearn.linear_model import Ridge, LassoLars
+from sklearn.model_selection import train_test_split
+from sklearn.inspection import permutation_importance
+
+from . import util
+
+logging.basicConfig(level=logging.INFO)
+
+# allow importing `load_data` immediately from `pyxla`
+from .util import load_data
+
+# definition of the sample structure
+# (the data files should include the global optima if known)
+sample = {'name': None,
+            'size': 0,
+            # variable space
+            'X':    None,   # dataframe
+            #'Xd':   0,      # int
+            'Xcsv': None,   # str
+            # objective space
+            'F':    None,
+            #'Fd':   0,
+            'Fcsv': None,
+            'numF': 0,
+            'max':  False,  # we minimize by default
+            # violation space
+            'V':    None,
+            #'Vd':   0,
+            'Vcsv': None,
+            'numV': 0,
+            # neighborhood
+            'N':    None,
+            'Ncsv': None,
+            # distance
+            'D':    None,
+            'Dcsv': None,
+            'representation': 'continuous', # by default
+            'd_metric_func': None, # distance metric function of the form dist(X1, X2) -> d
+            'neighbourhood_func':  None, # of the form f(X1, X2) -> bool
+            'p':    2       # Euclidean distance by default
+}
+
+def descriptive_stats(data, name):
+    result = dict()
+    result[str(name + '_min')]  = min(data)
+    result[str(name + '_max')]  = max(data)
+    result[str(name + '_mean')] = statistics.mean(data)
+    result[str(name + '_med')]  = statistics.median(data)
+    result[str(name + '_q1')]   = statistics.quantiles(data, n = 4)[0]
+    result[str(name + '_q3')]   = statistics.quantiles(data, n = 4)[2]
+    result[str(name + '_sd')]   = statistics.stdev(data)
+    result[str(name + '_skew')] = scipy.stats.skew(data).item()
+    result[str(name + '_kurt')] = scipy.stats.kurtosis(data).item()
+    return result
+
+
+def distr_f(sample: dict, bins: int = 'auto') -> Tuple[dict, matplotlib.figure.Figure]:
+    """
+    **Distribution of objectives (fitness values)**
+
+    The ``distr_f`` feature visualises the spread of objective values and computes
+    some descriptive statistics of the objective values. Alongside a histogram of 
+    objective values and a histogram of their dense ranking, various descriptive statistics
+    are computed, including: minimum, maximum, mean, median, quartiles (Q1, Q3), 
+    standard deviation, skewness, and kurtosis. Dense ranking is a ranking method 
+    provided by the `Link pandas https://pandas.pydata.org` package, which entails 
+    assigning to a group of equally valued solutions the least rank in the group 
+    and ensuring that rank increases by 1 from group to group.
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing the various input files i.e `F`, `V`.
+
+    Returns
+    -------
+    dict
+        Descriptive statistics of objective values.
+    matplotlib.figure.Figure
+        Histograms of objective values and or ranks of objective values.
+
+    Examples
+    --------
+    >>> from pyxla import util, distr_f
+    >>> import matplotlib
+    >>> sample = util.load_sample('cec2010_c01_2d_F1_V2', test=True)
+    >>> feat, plot = distr_f(sample)
+    >>> type(feat)
+    <class 'dict'>
+    >>> isinstance(plot, matplotlib.figure.Figure)
+    True
+
+    """ 
+    F = sample['F']
+    numF = sample['numF']
+    R = pd.DataFrame()
+
+    for col in F:
+        R[f"{col}_rank"] = F[col].rank(ascending = not sample['max'], method = 'min').astype(int)
+    
+    feat = dict()
+    for i in range(0, len(F.columns)):
+        feat.update(descriptive_stats(F.iloc[:,i], F.columns[i]))
+        feat.update(descriptive_stats(R.iloc[:,i], R.columns[i]))
+
+    # plots
+    ncols = numF + (numF > 1)
+    nrows = 2
+    fig, axs = plt.subplots(ncols=ncols, nrows=nrows, figsize=(3 * ncols, 3 * nrows))
+    palette = sns.color_palette()[-numF:] # pick last n colors in palette
+
+    ax = lambda i, j: axs[i, j] if numF > 1 else axs[i] 
+    for i, col in enumerate(F):
+        sns.histplot(F[col], ax=ax(0, i), color=palette[i], bins=bins)
+        sns.histplot(R[f"{col}_rank"], ax=ax(1, i), color=palette[i])
+    
+    # blend plots
+    if numF > 1:
+        sns.histplot(F, ax=ax(0, numF), palette=palette)
+        sns.histplot(R, ax=ax(1, numF), palette=palette)
+
+    fig.suptitle('Distribution of objective values/ranks')
+    plt.tight_layout()
+
+    return feat, fig
+
+def distr_v(sample: dict) -> Tuple[dict, matplotlib.figure.Figure]:
+    """
+    **Distribution of violation values**
+
+    The ``distr_v`` feature visualises the spread of violation values and 
+    computes some descriptive statistics of the violation values. 
+    Alongside a histogram of violation values and a histogram of their 
+    dense ranking, descriptive statistics are computed, including: 
+    minimum, maximum, mean, median, quartiles (Q1, Q3), standard deviation,
+    skewness, and kurtosis. Additionally, the feasibility rate is computed
+    per violation, and the overall feasibility, taking all constraints into 
+    account, is computed. Feasibility rate refers to the proportion of solutions 
+    that are feasible with respect to a constraint.
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing the various input files i.e `F`, `V`.
+
+    Returns
+    -------
+    dict
+        Descriptive statistics of violation values.
+    matplotlib.figure.Figure
+        Histograms of violation values and ranks of violation values.
+    """  
+    V = sample['V']
+    if V is None: raise ValueError('V is absent in the sample. Please provide input V first.') 
+    
+    V_ = V.drop('feasible', axis=1)
+    numV = sample['numV']
+
+
+    R = pd.DataFrame()
+
+    for col in V_:
+        R[f"{col}_rank"] = V[col].rank(ascending = True, method = 'min').astype(int)
+
+    # features
+    feat = dict()
+    # exclude column 'feasible'
+    for i, col in enumerate(V_):
+        feat.update(descriptive_stats(V.iloc[:,i], col))
+        # feasibility rate per constraint
+        feat[f'{col}_feas_rate'] = (V.iloc[:,i] == 0).mean().item()
+    feat[f'overall_feas_rate'] = V['feasible'].mean().item()
+
+    # plots
+    ncols = numV + (numV > 1)
+    nrows = 2
+    fig, axs = plt.subplots(ncols=ncols, nrows=nrows, figsize=(3 * ncols, 3 * nrows))
+    palette = sns.color_palette()[-numV:] # pick last n colors in palette
+
+    ax = lambda i, j: axs[i, j] if numV > 1 else axs[i] 
+
+    for i, col in enumerate(V_):
+        sns.histplot(V[col], ax=ax(0, i), color=palette[i])
+        sns.histplot(R[f"{col}_rank"], ax=ax(1, i), color=palette[i])
+    
+    # blend plots
+    if numV > 1:
+        sns.histplot(V_, ax=ax(0, numV), palette=palette)
+        sns.histplot(R, ax=ax(1, numV), palette=palette)
+
+    fig.suptitle('Distribution of violation values/ranks')
+    plt.tight_layout()
+    
+    return feat, fig
+
+def distr_Par(sample: dict) -> Tuple[dict, sns.axisgrid.FacetGrid]:
+    """_summary_
+
+    Parameters
+    ----------
+    sample : dict
+        _description_
+
+    Returns
+    -------
+    sns.axisgrid.FacetGrid
+        _description_
+    """
+    Par = sample['R'].filter(like='pareto')
+    numPar = len(Par.columns)
+    if not numPar: raise Exception('Pareto rank is not possible for this sample.')
+
+    feat = dict()
+
+    for i in range(0, numPar):
+        feat.update(descriptive_stats(Par.iloc[:,i], Par.columns[i]))
+
+    # plots
+    ncols = numPar
+    fig, axs = plt.subplots(ncols=ncols, figsize=(3 * ncols, 3))
+    palette = sns.color_palette()[-numPar:] # pick last n colors in palette
+
+    ax = lambda i : axs[i] if numPar > 1 else axs
+
+    for i, col in enumerate(Par):
+        sns.histplot(Par[col], ax=ax(i), color=palette[i])
+
+    fig.suptitle('Distribution of Pareto ranks')
+    plt.tight_layout()    
+    
+    return feat, fig
+
+def distr_Deb(sample: dict) -> Tuple[dict, sns.axisgrid.FacetGrid]:
+    """_summary_
+
+    Parameters
+    ----------
+    sample : dict
+        _description_
+
+    Returns
+    -------
+    sns.axisgrid.FacetGrid
+        _description_
+    """
+    if 'Deb' not in sample['R']: raise Exception("Deb's feasibility rule ranking is not possible for this sample.")
+    deb_ranks = sample['R']['Deb']
+    plot = sns.displot(deb_ranks)
+    plot.set(title=f"Deb\'s feasibility rule ranking distribution {sample['name']}")
+    feat = dict()
+    feat.update(descriptive_stats(deb_ranks, 'Deb'))
+
+    return feat, plot
+
+def annotate_with_corr_coefs(x, y, label=None, color=None, **kwargs) -> None:
+    ax = plt.gca()
+    cor, _ = spearmanr(x, y)
+    cor = 'undefined' if math.isnan(cor) else f'{cor:.2f}'
+    # if sample has V file
+    if label != None:
+        feasibility = 'feasible' if label else 'infeasible'
+        kwargs['feat'].update({f"{x.name}_{y.name} ({feasibility})": cor})
+        pos = (0.5, 0.5) if label else (0.5, 0.25)
+        ax.annotate(f'corr = {cor} ({feasibility})', xy = pos, xycoords='axes fraction', ha = 'center', color = color)
+    # else if no V file
+    else:
+        kwargs['feat'].update({f"{x.name}_{y.name}": cor})
+        pos = (0.5, 0.5)
+        ax.annotate(f'corr = {cor}', xy = pos, xycoords='axes fraction', ha = 'center', color = color)
+    ax.set_axis_off()
+
+def corr(sample: dict) -> Tuple[dict, sns.PairGrid]:
+    """Correlation of values
+
+    @todo summary
+    
+    Parameters
+    ----------
+    sample : dict
+        A sample containing the various input files i.e `F`, `V`.
+
+    Returns
+    -------
+    sns.PairGrid
+        Grid of scatter plots of all objectives and violations against 
+        each other, with feasibility indicated per solution.
+    feat: dict
+        Spearman's correlation coefficients for all pairs of sets of 
+        values split by feasibility
+    """
+    if util.present(sample, 'V'):
+        FV = pd.merge(sample['F'], sample['V'], left_index=True, right_index=True)
+        g = sns.PairGrid(FV, hue = 'feasible', hue_order=[True, False])
+    else: 
+        FV = sample['F']
+        if sample['numF'] == 1: logging.warning('The sample has a single objective with no constraint, therefore this feature is meaningless.')
+        g = sns.PairGrid(FV)
+    # diagonal
+    g.map_diag(sns.histplot)
+    # lower triangle
+    g.map_lower(sns.scatterplot, alpha = 0.5)
+    g.map_lower(sns.regplot, scatter = False)
+    # upper triangle
+    feat = {}
+    g.map_upper(annotate_with_corr_coefs, feat=feat)
+    # legend
+    g.add_legend()
+    violation_txt = ' and violations' if util.present(sample, 'V') else ''
+    g.figure.suptitle(f"Correlation of objectives{violation_txt}")
+    return feat, g
+
+def corr_ranks(sample: dict) -> Tuple[dict, sns.PairGrid]:
+    """Correlation of ranks
+
+    @todo summary
+    
+    Parameters
+    ----------
+    sample : dict
+        A sample containing the various input files i.e `F`, `V`
+
+    Returns
+    -------
+    sns.PairGrid
+        Grid of scatter plots of all objective, violation, Pareto and Deb's
+        ranks against each other, with feasibility indicated per solution
+    feat: dict
+        Spearman's correlation coefficients for all pairs of sets of ranks 
+        split by feasibility
+    """
+    if util.present(sample, 'V'):
+        g = sns.PairGrid(sample['R'], hue='feasible', hue_order=[True, False])
+    else:
+        g = sns.PairGrid(sample['R'])
+        if sample['numF'] == 1: logging.warning('The sample has a single objective with no constraint, therefore this feature is meaningless.')
+
+    g.map_diag(sns.histplot)
+    # diagonal
+    g.map_diag(sns.histplot)
+    # lower triangle
+    g.map_lower(sns.scatterplot, alpha=0.5)
+    g.map_lower(sns.regplot, scatter=False)
+    # upper triangle
+    feat = {}
+    g.map_upper(annotate_with_corr_coefs, feat=feat)
+    # legend
+    g.add_legend()
+    g.figure.suptitle('Correlation of ranks')
+    g.figure.tight_layout()
+    return feat, g
+
+def pw_dist(sample: dict, id_a: int, id_b: int, metric=None) -> float:
+    """Calculates the distance between 2 solutions given their indices.
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing the various input files i.e `F`, `V`.
+    id_a : int
+        Index of solution `a`
+    id_b : int
+        Index of solution `b`
+    
+    Returns
+    -------
+    float
+        Distance between solution `a` and `b` as a float
+    """
+    if id_a == id_b: 
+        return 0  
+    else:
+        d = None
+        D = sample['D']
+        # check if D file is provided
+        if isinstance(D, pd.DataFrame):
+            if id_a < id_b: d = D.loc[(id_a, id_b), 'd']
+            else: d =  D.loc[(id_b, id_a), 'd']
+        # if D not provided calculate d's
+        else:
+            # if no metric specific use default metrics
+            if not metric:
+                metric = 'euclidean' if sample['representation'] == 'continuous' else 'hamming'
+
+            if 'X' not in sample: raise ValueError('Please provide either an X input file.')
+            X = sample['X']
+            a = X.iloc[id_a].to_numpy()
+            b = X.iloc[id_b].to_numpy()
+            # d = np.linalg.norm(a - b, ord = sample['p'])
+            d = pdist([a, b], metric=metric)
+        return d
+
+def fdc(sample: dict, compute_D_file: bool = True) -> Tuple[dict, matplotlib.axes.Axes]:
+    """Computes objective-distance correlation
+
+    @todo summary
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing the various input files i.e `F`, `V`.
+    compute_D_file : bool, optional
+        By default `True`; when there is no D file in the sample, if 
+        `compute_D_file` is set to `True`, the whole D file is 
+        calculated. Calculating the whole D file will eliminate redundant
+        distance calculations in the future, but it can be time consuming.
+        To speed up calculation of `fdc`, set `compute_D_file` to
+        `False` so that only the required distances are calculated.
+
+    Returns
+    -------
+    corr : dict
+        Dictionary containing Spearman's correlation coefficients 
+        objective-distance correlation per objective.
+    fig : matplotlib.axes.Axes
+        `matplotlib` axes containing scatter plots of objective 
+        values against distance to the nearest best solution in 
+        sample per objective, for all solutions or for feasible 
+        solutions only.
+
+    Raises
+    ------
+    Exception
+        Raises an exception if both D and X inputs are absent. One of D 
+        or X is needed to compute distances between solution.
+    """
+    util.handle_missing_D_file(sample, compute_D_file)
+
+    sample['FDC'] = pd.DataFrame()
+    FDC = sample['FDC']
+    F = sample['F']
+    R = sample['R']
+    corr = {}
+
+    fig, axs = plt.subplots(ncols=len(F.columns), figsize=(5 * len(F.columns), 5))
+    for i, col in enumerate(F.columns):
+        FDC[col] = F[col]
+        FDC['distance'] = 0.0
+        # pick F with rank 1, 
+        bestF = R.query(f'{col} == 1')
+        # for rank 1 solution set distance to 0
+        FDC.loc[bestF.index, 'distance'] = 0.0
+        # compute distance only for non-rank-1 solutions
+        for t_idx in FDC[~FDC.index.isin(bestF.index)].index:
+            d_nearest_best_f = pw_dist(sample, t_idx, bestF.index[0])
+            # check for the nearest among all bestFs
+            for b_idx in bestF[1:].index:
+                d = pw_dist(sample, t_idx, b_idx)
+                if d < d_nearest_best_f: d_nearest_best_f = d
+            FDC.loc[t_idx, 'distance'] = d_nearest_best_f
+
+        r, _ = scipy.stats.spearmanr(FDC[col], FDC['distance'])
+        corr.update({f"fdc_{col}": r})
+
+        ax = axs[i] if len(F.columns) > 1 else axs
+        sns.scatterplot(data = FDC, x = 'distance', y = col, ax = ax)
+        sns.regplot(data = FDC, x = 'distance', y = col, ax = ax, scatter=False)
+        ax.set_title(f'FDC (corr = {r:.2f})')
+    
+    fig.tight_layout()
+       
+    return corr, fig
+    
+def vdc(sample: dict, compute_D_file: bool = True) -> Tuple[dict, matplotlib.axes.Axes]:
+    """Calculates violation-distance correlation. 
+    
+    This function calculates the violation distance 
+    correlation: the correlation between violation values and distance
+    to the nearest feasible solution.
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing the at least input files V and D.
+    compute_D_file : bool, optional
+        By default `True`; when there is no D file in the sample, if 
+        `compute_D_file` is set to `True`, the whole D file is 
+        calculated. Calculating the whole D file will eliminate redundant
+        distance calculations in the future, but it can be time consuming.
+        To speed up calculation of `fdc`, set `compute_D_file` to
+        `False` so that only the required distances are calculated.
+
+    Returns
+    -------
+    corr : dict
+        Dictionary containing correlation between constraints and
+        distance to the nearest feasible solution.
+    fig : matplotlib.axes.Axes
+        `matplotlib` axes containing a scatter plot of violation
+        values against distance to the nearest feasible solution.
+
+    Examples
+    --------
+    >>> from pyxla import util, vdc
+    >>> import matplotlib
+    >>> sample = util.load_sample('cec2010_c01_2d_F1_V2', test=True)
+    >>> corr, plot = vdc(sample)
+    >>> type(corr)
+    <class 'dict'>
+    >>> isinstance(plot, matplotlib.figure.Figure)
+    True
+    """
+    if not util.present(sample, 'V'): raise Exception('V is required. Please provide V.')
+
+    util. handle_missing_D_file(sample, compute_D_file)
+        
+    V = sample['V']
+    
+    if V[V['feasible'] == True].empty: raise Exception('VDC is undefined as there is no feasible solution.')
+
+    corr = {}
+    fig, axs = plt.subplots(ncols=len(V.columns[:-1]), figsize=(5 * len(V.columns[:-1]), 5))
+    
+    for i, col in tqdm(enumerate(V.columns[:-1]), total=sample['numV']): # exclude col 'feasible'
+        sample[f'VDC_{col}'] = pd.DataFrame()
+        VDC = sample[f'VDC_{col}']
+        # separate feasible and infeasible solutions.
+        feas_v, infeas_v = V.query(f'{col} == 0'), V.query(f'{col} != 0')
+
+        VDC[col] = infeas_v[col]
+        # for each infeasible solution:
+        for infeas_idx in infeas_v.index:
+            d_nearest_feas = pw_dist(sample, infeas_idx, feas_v.index[0])
+            # compute dist to all feas. solutions
+            for feas_idx in feas_v.iloc[1:].index:  
+                d = pw_dist(sample, infeas_idx, feas_idx)
+                if d < d_nearest_feas:
+                    # look for the nearest feas. solution
+                    d_nearest_feas = d
+            VDC.loc[infeas_idx, 'distance'] = d_nearest_feas
+        # no existing infeasible solutions
+        if infeas_v.empty: VDC['distance'] = 0
+
+        r, _ = scipy.stats.spearmanr(VDC[col], VDC['distance'])
+        corr.update({f"vdc_{col}": r})
+
+        ax = axs[i] if len(V.columns[:-1]) > 1 else axs
+        # use uniform color for infeasible solutions
+        color = sns.color_palette()[1]
+        sns.scatterplot(data = sample[f'VDC_{col}'], x = 'distance', y = col, ax = ax, color=color)
+        ax.set_title(f'VDC (corr = {r:.2f})')
+    
+    return corr, fig
+
+def rdc(sample: dict, compute_D_file: bool = True) -> Tuple[dict, matplotlib.axes.Axes]:
+    """Rank distance correlation
+
+    Scatter plots of ranks against distance to the nearest best solution 
+    (with rank 1) in sample. Ranks based on Pareto ranks for objectives,
+    violations or the combination, or Deb feasibility rank.
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing the at least input files V and D.
+    compute_D_file : bool, optional
+        By default `True`; when there is no D file in the sample, if 
+        `compute_D_file` is set to `True`, the whole D file is 
+        calculated. Calculating the whole D file will eliminate redundant
+        distance calculations in the future, but it can be time consuming.
+        To speed up calculation of `fdc`, set `compute_D_file` to
+        `False` so that only the required distances are calculated.
+
+    Returns
+    -------
+    corr : dict
+        Dictionary containing correlation between ranks and
+        distance to the nearest best solution.
+    fig : matplotlib.axes.Axes
+        `matplotlib` axes containing a scatter plot of ranks
+        against distance to the nearest best solution.
+
+    """
+    R: pd.DataFrame = sample['R']
+    corrs = {}
+    numR = sample['numR']
+    ncols = numR
+    # nrows = math.ceil(numR / ncols)
+    fig, axs = plt.subplots(ncols=ncols, nrows=1,  figsize=(5 * ncols, 5 * 1))
+    # for each rank...
+    axs = axs.ravel()
+    for i, col in tqdm(enumerate(R.columns[:-1]), total=numR): # exclude col 'feasible'
+        sample[f'RDC_{col}'] = pd.DataFrame()
+        RDC: pd.DataFrame = sample[f'RDC_{col}']
+        RDC[col] = R[col]
+        # check if col is a V
+        if col in sample['V'].columns:
+            # determine feasibility per constraint
+            RDC['feasible'] = sample['V'][col] = 0
+        else:
+            RDC['feasible'] = R['feasible']
+        RDC['distance'] = None
+        # get solutions with rank == 1
+        best = R.query(f'{col} == 1')
+        # for rank 1 solution set distance to 0
+        RDC.loc[best.index, 'distance'] = 0
+        # compute distance only for non-rank-1 solutions
+        for t_idx in RDC.query('distance.isna()').index:
+            d_nearest_best = pw_dist(sample, t_idx, best.index[0])
+            for b_idx in best[1:].index:
+                d = pw_dist(sample, t_idx, b_idx)
+                if d < d_nearest_best: d_nearest_best = d
+            RDC.loc[t_idx, 'distance'] = d_nearest_best
+
+        sp_corr, _ = scipy.stats.spearmanr(RDC[col], RDC['distance'])
+        corrs.update({f"rdc_{col}": sp_corr})
+
+        ax = axs[i] if numR > 1 else axs
+        sns.scatterplot(data = sample[f'RDC_{col}'], x = 'distance', y = col, hue='feasible', hue_order=[True, False], ax = ax)
+        ax.set_title(f'RDC (corr = {sp_corr:.2f})')
+
+    # if i + 1 < ncols * nrows: 
+    #     for unused_ax in axs[i + 1:]: unused_ax.set_axis_off()
+    return corrs, fig
+
+def pdc(sample: dict, metric: Union[Callable, str] = 'euclidean') -> Tuple[dict, matplotlib.figure.Figure]:
+    """Computes pairwise distance correlation and produces scatter plots.
+
+    This feature produces a visual output of scatter plots of pairwise 
+    distance on the solution space against distance on the objective 
+    space, violation space, and for each objective, constraint and rank
+    individually. The numerical output is the pairwise distance 
+    Spearman's correlation coefficient. 
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing the at least input files V and D.
+    metric : Callable or str, optional
+        A metric function or the name of a distance metric as listed 
+        ``scipy``'s ``pdist`` function 
+        <https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.distance.pdist.html>`_.
+        If a metric function is defined it must take two solutions and computes distance
+        between them of the form ``dist(Xa, Xb) -> d`` where ``Xa`` and ``Xb``
+        are ``pandas`` Series representing solutions, by default ``None``.
+        For example: ``lambda Xa, Xb: abs(Xa.sum() - Xb.sum())``. 
+
+    Returns
+    -------
+    corr : dict
+        Dictionary containing correlation between pairwise distance on the
+        solution space and pairwise distance on the objective space, on
+        the violation space, and on each objective, violation and rank 
+        individually.
+    fig : matplotlib.figure.Figure
+        `matplotlib` axes containing a scatter plot of pairwise distance 
+        on the solution space against pairwise distance on the objective 
+        space, on the violation space, and on each objective, violation 
+        and rank individually.
+
+    Examples
+    --------
+    >>> from pyxla import util, pdc
+    >>> import matplotlib
+    >>> sample = util.load_sample('cec2010_c01_2d_F1_V2', test=True)
+    >>> corr, plot = pdc(sample)
+    >>> type(corr)
+    <class 'dict'>
+    >>> isinstance(plot, matplotlib.figure.Figure)
+    True
+    """
+    util.handle_missing_D_file(sample, True, warn=False)
+
+    F = sample['F']
+    V = sample['V']
+    D = sample['D']
+    # using errors='ignore' as the `feasible` column is only present when we have V
+    R = sample['R'].drop('feasible', axis=1, errors='ignore')
+    PD = pd.DataFrame()
+
+    PD['Xd'] = D['d']
+
+    corrs = {}
+    rows = []
+
+    # objective space
+    row1 = [{'x': F, 'name':'F'}]
+
+    # violation space
+    if util.present(sample, 'V'): 
+        V = V.drop('feasible', axis=1)
+        row1.append({'x': V, 'name':'V'})
+
+    rows.extend(row1)
+
+    # objectives
+    if sample['numF'] > 1:
+        rows.extend([{'x': F[col], 'name': col} for col in F.columns])
+
+    # violations
+    if sample['numV'] > 1:
+        rows.extend([{'x': V[col], 'name': col} for col in V])
+
+    # ranks
+    rows.extend([{'x': R[col], 'name': f'{col}-rank'} for col in R])
+
+    # prepare figure
+    ncols = min(3, len(rows)) #max(2, sample['numF'], sample['numV'], sample['numR'])
+    nrows = math.ceil(len(rows) / ncols)
+    fig, axs = plt.subplots(ncols=ncols, nrows=nrows, figsize=(5 * ncols, 5 * nrows))
+    color = sns.color_palette()[2]
+    axs = axs.ravel()
+    unused_axs = []
+
+    for i, plot in enumerate(rows):
+        # for col, plot in enumerate(plots):
+        ax_lbl = f"{plot['name']}_d"
+        PD[ax_lbl] = util.calc_pairwise_dist(plot['x'], metric=metric, representation=sample['representation'])
+        corr, _ = scipy.stats.spearmanr(PD['Xd'], PD[ax_lbl])
+        corrs.update({f"pdc_{plot['name']}": corr}) # fix .item()
+
+        ax = sns.scatterplot(x=PD['Xd'], y=PD[ax_lbl], ax=axs[i], color=color)
+        ax.set(title=f"X_d vs {plot['name']}_d (corr = {corr:.2f})")
+
+        # unused_axs.extend([(i, c) for c in range(col + 1, ncols)])
+
+    # turn off unused axes
+    if i + 1 < ncols * nrows: 
+        for unused_ax in axs[i + 1:]: unused_ax.set_axis_off()
+    # for ax in unused_axs: axs[ax].set_axis_off()
+    
+    fig.suptitle(f"PDC for {sample['name']}", y=1.04)
+    plt.tight_layout()
+
+    return corrs, fig
+
+def nfc(sample: dict) -> Tuple[dict, matplotlib.axes.Axes]:
+    """Computes neighbouring solutions' objective values correlation.
+
+    This feature produces a scatter plot of the objective values between
+    neighbours for each objective (fitness cloud), for all solutions or
+    for feasible solutions only. The plot is divided a broken line through
+    origin such that lines above line are improving neighbours, those
+    below are deteriorating neighbours while those on the line are neutral
+    neighbours. The numerical output produced is a list of Spearman's 
+    correlation coefficients for each scatter plot.
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing input files i.e `F`, `N`.
+
+    Returns
+    -------
+    corr : dict
+        Dictionary containing correlation between objective values of
+        solutions and the objective values of their neighbours, for all
+        solutions and for feasible solutions only.
+    fig : matplotlib.axes.Axes
+        `matplotlib` axes each containing a scatter plot of objective
+        values of solutions against the objective values of their
+        neighbours, for all solutions and for feasible solutions only.
+        
+    Raises
+    ------
+    Exception
+        Raised if both N and X inputs are absent, as neighbourhood
+        cannot be determined without having either.
+        
+    Examples
+    --------
+    >>> from pyxla import util, nfc
+    >>> import matplotlib
+    >>> sample = util.load_sample('nk_n14_k2_id5_F1_V1', test=True)
+    >>> corrs, plot = nfc(sample)
+    >>> type(corrs)
+    <class 'dict'>
+    >>> isinstance(plot, matplotlib.figure.Figure)
+    True
+    """
+
+    util.handle_missing_N_file(sample, True, warn=False)
+
+    F = sample['F']
+    numF = sample['numF']
+    V = sample['V']
+    N = sample['N']
+
+    corrs = {}
+    rows = []
+
+    rows.append({'name': 'all', 'nfc': N})
+
+    # for feasible solutions only
+    if util.present(sample, 'V'):
+        N_indexed = N.set_index('id1', drop=False)
+        V = V.loc[N_indexed.index]
+        feas_idxs = V[V['feasible'] == True].index
+        # add plot data to rows only if there are feasible solutions
+        if len(feas_idxs) > 0:
+            feas_N = N_indexed.loc[feas_idxs]
+            feas_N.reset_index(drop=True, inplace=True)
+            rows.append({'name': 'feas.', 'nfc': feas_N})
+
+    ncols = sample['numF']
+    nrows = len(rows)
+    fig, axs = plt.subplots(ncols=ncols, nrows=nrows, figsize=(5 * ncols, 5 * nrows))
+
+    # change color palette
+    sns.set_palette('deep')
+    sns.set_palette(reversed(sns.color_palette()), 10)
+    palette = sns.color_palette()
+
+    for row, data in enumerate(rows):
+        NFC = data['nfc']
+        for col, f in enumerate(tqdm(F.columns)):
+            x, y = f'{f}', f'neighbour {f}'
+            # collate fitness values pairs for neighbour pairs
+            NFC[x] = F[f].loc[NFC['id1']].tolist()
+            NFC[y] = F[f].loc[NFC['id2']].tolist()
+
+            corr, _ = scipy.stats.spearmanr(NFC[x], NFC[y])
+            corr = corr if isinstance(corr, float) else corr.item()
+            corrs.update({f"nfc_{data['name']}_X_for_{f}": corr}) 
+
+            # determine axis coords.
+            if len(rows) > 1:
+                ax = axs[row, col] if numF > 1 else axs[row]
+            else:
+                ax = axs[col] if numF > 1 else axs
+            
+            ax = sns.scatterplot(x=NFC[x], y=NFC[y], ax=ax, color=palette[0])
+            ax.set(title=f'NFC for {f} {data['name']} X (corr = {corr:.2f})')
+            sns.regplot(x=NFC[x], y=NFC[y], ax=ax, scatter=False, color=palette[1])
+
+            limits = [
+                np.min([ax.get_xlim(), ax.get_ylim()]),  
+                np.max([ax.get_xlim(), ax.get_ylim()]), 
+            ]
+
+            # plot diagonal line
+            ax.plot(limits, limits, '--k')
+            
+            util.equalize_axes_(ax)
+
+    fig.suptitle(f"NFC for {sample['name']}", y=1.04)
+    plt.tight_layout()
+    return corrs, fig
+    
+def ncf(sample: dict) -> Tuple[dict, matplotlib.axes.Axes]:
+    """Neighbouring change in feasibility
+
+    This feature produces as visual output a bar chart of proportion of feasible solutions
+    with infeasible neighbours and infeasible solutions with feasible 
+    neighbours. The corresponding numerical outputs are the respective proportions.
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing input files i.e `F`, `N`.
+
+    Returns
+    -------
+    proportions : dict
+        Dictionary containing the numerical proportions as defined above.
+    fig : matplotlib.axes.Axes
+        `matplotlib` figure with the bar chart visually illustrating the
+        proportions defined above.
+
+    Raises
+    ------
+    Exception
+        Raises an exception if no V file is provided as feasibility is
+        undefined without the V file.
+    Exception
+        Raises an exception if the sample only has solutions belong to
+        only one class of feasibility i.e if all solutions are infeasible
+        or if all solutions are feasible.
+    Exception
+        Raised if both N and X inputs are absent, as neighbourhood
+        cannot be determined without having either.
+
+    Examples
+    --------
+    >>> from pyxla import util, ncf
+    >>> sample = util.load_sample('nk_n14_k2_id5_F1_V1', test=True)
+    >>> proportions, fig = ncf(sample)
+    >>> proportions # doctest: +SKIP
+    """
+
+    if not util.present(sample, 'V'): raise Exception('V is required. Please provide V.')
+
+    util.handle_missing_N_file(sample, True, warn=False)
+
+    proportions = {}
+
+    V = sample['V']
+
+    N = sample['N']
+    N['id1_feasible'] = V.loc[N['id1']]['feasible'].to_numpy()
+    N['id2_feasible'] = V.loc[N['id2']]['feasible'].to_numpy()
+
+    inversions = (N['id1_feasible'] ^ N['id2_feasible']).sum()
+
+    proportions['discontiguous feasbility'] = inversions / len(N)
+    proportions['contiguous feasibility'] = 1 - proportions['discontiguous feasbility']
+
+    fig = sns.barplot(x=proportions.keys(), y=proportions.values(), hue=proportions.keys())
+    fig.set_title(f'NΔFeas for {sample['name']}')
+    fig.set_ylim(0, 1)
+    fig.set_ylabel('proportion')
+
+    for container in fig.containers:
+        fig.bar_label(container, label_type='center', padding=5)
+    
+    plt.tight_layout()
+
+    return proportions, fig
+
+def n_flat(sample: dict, bounds: Union[List[float], float] = 0) -> Tuple[dict, matplotlib.axes.Axes]:
+    """Neutral degree of neighbours.
+
+    The visual output of this feature is a scatterplot of the neutral
+    degree of each solution against the neutral degree of its neighbours
+    with respect to each objective function. The numerical output is the
+    corresponding Spearman correlation coefficients for each scatterplot.
+    The neutral degree of a solution is the number of its neutral 
+    neighbors [1]_.
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing input files i.e ``F``, ``N``.
+    bound : Union[List[float], float]
+        Bound(s) for infering equality of objective values, by default ``0``.
+
+    Returns
+    -------
+    corr : dict
+        Dictionary containing correlation between the neutral degree of
+        each solutions against neutral degree of neighbours for each
+        objective.
+    fig : matplotlib.figure.Figure
+        ``matplotlib`` figure containing axes for each objective with each
+        axis containing a scatterplot of the neutral degree of each
+        solution against neutral degree of neighbours.
+
+    References
+    ----------
+    .. [1] S. Verel, G. Ochoa, and M. Tomassini, 'Local Optima Networks of NK Landscapes With Neutrality', Evolutionary Computation, IEEE Transactions on, vol. 15, Jul. 2011.
+    
+    Examples
+    --------
+    >>> from pyxla import util, n_flat
+    >>> import matplotlib
+    >>> sample = util.load_sample('nk_n14_k2_id5_F1_V1', test=True)
+    >>> corrs, plot = n_flat(sample, 0.01)
+    >>> type(corrs)
+    <class 'dict'>
+    >>> isinstance(plot, matplotlib.figure.Figure)
+    True
+    """
+    
+    util.handle_missing_N_file(sample, True, warn=False)
+
+    N = sample['N']
+    F = sample['F']
+    NDN = pd.DataFrame() # neutral degree of neighbours
+    N_indexed = N.set_index('id1')
+    numF = sample['numF']
+
+    # replicate equality range for each objective
+    if not isinstance(bounds, Iterable): bounds = [bounds] * numF
+
+    corrs = {}
+    fig, axs = plt.subplots(ncols=numF, figsize=(5 * numF, 5))
+
+    for i, f in enumerate(F.columns):
+        n_degrees = pd.DataFrame()
+        # get all soln. indices in the N file
+        n_degrees['id'] = np.unique(np.concat([N['id1'].unique(), N['id2'].unique()]))
+        n_degrees['degree'] = 0
+        n_degrees.set_index('id', inplace=True)
+
+        # compute neutral degree for each soln. with a neighbour(s)
+        for idx in N['id1'].unique():
+            obj_val = F.loc[idx][f]
+            neighbours = N_indexed.loc[idx]['id2']
+            neighbours_obj_vals = F.loc[neighbours]
+            # check obj. value equality within supplied bounds
+            neutral_neighbours = neighbours_obj_vals[abs(neighbours_obj_vals - obj_val) <= bounds[i]].dropna()
+            n_degrees.loc[idx, 'degree'] = len(neutral_neighbours)
+            # n_degrees.loc[idx, 'degree'] = math.floor((2/3) * len(neighbours_obj_vals))
+
+        x = 'neutral degree'
+        y = 'neutral degree of neighbour'
+        NDN[x] = n_degrees.loc[N['id1']]['degree'].to_numpy()
+        NDN[y] = n_degrees.loc[N['id2']]['degree'].to_numpy()
+
+        corr, _ = scipy.stats.spearmanr(NDN[x], NDN[y])
+        corrs.update({f"n_flat_{f}": corr})
+
+        ax = axs[i] if len(F.columns) > 1 else axs
+        ax = sns.scatterplot(x=NDN[x], y=NDN[y], ax=ax, alpha=0.5)
+        ax.set(title=f'N_flat for {f} X (corr = {corr:.2f})')
+        sns.regplot(x=NDN[x], y=NDN[y], ax=ax, scatter=False)
+
+    fig.suptitle(f"N_flat for {sample['name']}", y=1.04)
+
+    plt.tight_layout()
+    return corrs, fig
+
+
+def nvc(sample: dict) -> Tuple[dict, matplotlib.figure.Figure]:
+    """Computes neighbouring solutions' violation values correlation (NVC)
+
+    This feature produces as visual output, Scatter plot of the violation
+    values between neighbours for each constraint, for infeasible solutions
+    only. A regression line is plotted to indicate correlation. The plot
+    is divided a broken line through origin such that lines above line are
+    improving neighbours, those below are deteriorating neighbours while
+    those on the line are neutral neighbours. The numerical output for
+    this feature is a set of Spearman's correlation coefficients for each
+    scatter plot.
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing input files i.e `V`, `N`.
+
+    Returns
+    -------
+    corr : dict
+        Dictionary containing correlation between violation values of
+        solutions and the violation values of their neighbours, for
+        infeasible solutions only.
+    fig : matplotlib.axes.Axes
+        `matplotlib` axes each containing a scatter plot of violation
+        values of solutions against the violation values of their
+        neighbours for infeasible solutions only.
+
+    Examples
+    --------
+    >>> from pyxla import util, nvc
+    >>> import matplotlib
+    >>> sample = util.load_sample('nk_n14_k2_id5_F3_V2', test=True)
+    >>> corrs, plot = nvc(sample)
+    >>> type(corrs)
+    <class 'dict'>
+    >>> isinstance(plot, matplotlib.figure.Figure)
+    True
+    """
+
+    if not util.present(sample, 'V'): raise Exception('V is required. Please provide V.')
+
+    util.handle_missing_N_file(sample, True, warn=False)
+
+    V = sample['V'].drop('feasible', axis=1)
+    numV = sample['numV']
+    N = sample['N']
+    N_indexed = N.set_index('id1')
+
+    # get all solutions represented in N file
+    X_in_N_id1 = N['id1'].unique()
+    X_in_N_id2 = N['id2'].unique()
+    X_in_N = np.unique(np.concat([X_in_N_id1, X_in_N_id2]))
+    # filter V to only have Xs in N
+    V = V.loc[X_in_N]
+    assert len(V) == len(X_in_N)
+
+    corrs = {}
+    fig, axs = plt.subplots(ncols=numV, figsize=(5 * numV, 5))
+
+    # change color palette
+    sns.set_palette('deep')
+    sns.set_palette(reversed(sns.color_palette()), 10)
+    palette = sns.color_palette()
+
+    for i, v in enumerate(tqdm(V.columns)):
+        NVC = pd.DataFrame()
+        infeas = V.loc[X_in_N_id1].query(f"{v} != 0").index.to_numpy()
+        # reduce N to have `id1's` that are infeasible
+        N_filtered = N_indexed.loc[infeas]
+        N_filtered = N_filtered.reset_index()
+        x, y = f"{v}", f"neighbour {v}"
+        NVC[x] = V.loc[N_filtered['id1'].to_numpy()][v].to_numpy()
+        NVC[y] = V.loc[N_filtered['id2'].to_numpy()][v].to_numpy()
+        assert len(NVC[x]) == len(NVC[y]) == len(N_filtered)
+
+        corr, _ = scipy.stats.spearmanr(NVC[x], NVC[y])
+        corr = corr if isinstance(corr, float) else corr.item()
+        corrs.update({f"NVC_for_{v}": f'{corr:.4f}'}) 
+
+        ax = axs[i] if numV > 1 else axs
+        
+        ax = sns.scatterplot(x=NVC[x], y=NVC[y], ax=ax, color=palette[0])
+        ax.set(title=f'NVC for {v} (corr = {corr:.2f})')
+        sns.regplot(x=NVC[x], y=NVC[y], ax=ax, scatter=False, color=palette[1])
+        
+        # plot diagonal line
+        limits = [
+            np.min([ax.get_xlim(), ax.get_ylim()]),  
+            np.max([ax.get_xlim(), ax.get_ylim()]), 
+        ]
+        ax.plot(limits, limits, '--k')
+
+        util.equalize_axes_(ax)
+
+    
+    fig.suptitle(f"NVC for {sample['name']}", y=1.04)
+    plt.tight_layout()
+
+    return corrs, fig
+
+def nrc(sample: dict) -> Tuple[dict, matplotlib.figure.Figure]:
+    """Computes neighbouring solutions' ranks correlation (NVC)
+
+    This feature produces as visual output, Scatter plot of the ranks
+    between neighbours for each constraint, for infeasible solutions
+    only. Ranks are based on Pareto ranks for objectives, violations, the
+    combination of objectives and violations, and Deb feasibility rank.
+    A regression line is plotted to indicate correlation. The plot
+    is divided a broken line through origin such that lines above line are
+    improving neighbours, those below are deteriorating neighbours while
+    those on the line are neutral neighbours. The numerical output for
+    this feature is a set of Spearman's correlation coefficients for each
+    scatter plot.
+
+    Parameters
+    ----------
+    sample : dict
+        A sample containing input files i.e `F`, `N`.
+
+    Returns
+    -------
+    corr : dict
+        Dictionary containing correlation between ranks of
+        solutions and the ranks of their neighbours, for
+        infeasible solutions only.
+    fig : matplotlib.axes.Axes
+        `matplotlib` axes each containing a scatter plot of violation
+        values of solutions against the ranks of their
+        neighbours for infeasible solutions only.
+
+    Examples
+    --------
+    >>> from pyxla import util, nrc
+    >>> import matplotlib
+    >>> sample = util.load_sample('nk_n14_k2_id5_F3_V2', test=True)
+    >>> corrs, plot = nrc(sample)
+    >>> type(corrs)
+    <class 'dict'>
+    >>> isinstance(plot, matplotlib.figure.Figure)
+    True
+    """
+
+    util.handle_missing_N_file(sample, True, warn=False)
+
+    R = sample['R']
+    R = R if not util.present(sample, 'V') else R.drop('feasible', axis=1)
+    numR = sample['numR']
+    N = sample['N']
+
+    # get all solutions represented in N file
+    X_in_N_id1 = N['id1'].unique()
+    X_in_N_id2 = N['id2'].unique()
+    X_in_N = np.unique(np.concat([X_in_N_id1, X_in_N_id2]))
+    # filter R to only have Xs in N
+    R = R.loc[X_in_N]
+    assert len(R) == len(X_in_N)
+
+    corrs = {}
+    ncols = min(3, numR)
+    nrows = math.ceil(numR / ncols)
+    fig, axs = plt.subplots(ncols=ncols, nrows=nrows, figsize=(5 * ncols, 5 * nrows))
+    axs = axs.ravel() if numR > 1 else axs
+    # change color palette
+    sns.set_palette('deep')
+    sns.set_palette(reversed(sns.color_palette()), 10)
+    palette = sns.color_palette()
+
+    for i, r in enumerate(tqdm(R.columns)):
+        NRC = pd.DataFrame()
+        x, y = f"{r} rank", f"neighbour {r} rank"
+        NRC[x] = R.loc[N['id1'].to_numpy()][r].to_numpy()
+        NRC[y] = R.loc[N['id2'].to_numpy()][r].to_numpy()
+
+        corr, _ = scipy.stats.spearmanr(NRC[x], NRC[y])
+        corr = corr if isinstance(corr, float) else corr.item()
+        corrs.update({f"NRC_for_{r}_ranks": f'{corr:.4f}'})
+        ax = axs[i] if numR > 1 else axs
+        
+        ax = sns.scatterplot(x=NRC[x], y=NRC[y], ax=ax, color=palette[0])
+        ax.set(title=f'NRC for {r} ranks (corr = {corr:.2f})')
+        sns.regplot(x=NRC[x], y=NRC[y], ax=ax, scatter=False, color=palette[1])
+        
+        # plot diagonal line
+        limits = [
+            np.min([ax.get_xlim(), ax.get_ylim()]),  
+            np.max([ax.get_xlim(), ax.get_ylim()]), 
+        ]
+        ax.plot(limits, limits, '--k')
+
+        util.equalize_axes_(ax)
+
+    fig.suptitle(f"NRC for {sample['name']}", y=1.04)
+    
+    plt.tight_layout()
+
+    return corrs, fig
+
+def disp_best(sample: dict, init_percentage: int = 10, growth_factor: int = 2):
+    """Dispersion of best solutions
+
+    This feature analyses the dipersion amongst best solutions. It
+    producesas visual output scatter plots showing the distribution of
+    pairwise distances between solutions for increasing sample sizes of
+    best solutions, where 'best' is with respect to different objectives,
+    constraints and ranks. The corresponding numerical outputs are the
+    dispersion metrics [1]_ with respect to each objective, constrant and
+    rank.
+    Positive dispersion metric values indicates the presence of funnels while
+    negative values indicate the presence of global structure.
+
+    Parameters
+    ----------
+    sample : dict
+         A sample containing input files i.e `F`, `V`.
+
+    References
+    ----------
+    .. [1]	M. Lunacek and D. Whitley, 'The dispersion metric and the CMA evolution strategy', in Proceedings of the 8th annual conference on Genetic and evolutionary computation, 2006, pp. 477-484.
+
+    """
+
+    if init_percentage >= 100: raise Exception('Initial percentage for sub-sampling must be less than 100%.')
+
+    util.handle_missing_D_file(sample, True, warn=False)
+
+    D = sample['D']
+    R: pd.DataFrame = sample['R']
+    numR = sample['numR']
+    R = R if not util.present(sample, 'V') else R.drop('feasible', axis=1)
+
+    disp_metrics = {}
+    ncols = min(3, numR)
+    nrows = math.ceil(numR / ncols)
+    fig, axs = plt.subplots(ncols=ncols, nrows=nrows, figsize=(ncols * 5, nrows * 5))
+    axs = axs.ravel() if numR > 1 else axs
+
+    sample_sizes = [init_percentage]
+    i = 0
+    while sample_sizes[i] * growth_factor < 100:
+        sample_sizes.append(sample_sizes[i] * growth_factor)
+        i += 1
+
+    for i, r in enumerate(R.columns):
+        sorted = R.sort_values(by=r)
+        pw_distances_avgs = []
+        plot_data = pd.DataFrame(columns=['pairwise distances', 'sample size'])
+
+        for n in sample_sizes:
+            nth = int(n/100 * len(R))
+            best_n = sorted[:nth].index.sort_values()
+            pairs = itertools.combinations(best_n, 2)
+            pw_distances = D.loc[pairs]['d'].to_numpy()
+            
+            data = pd.DataFrame()
+            data['pairwise distances'] = pw_distances
+            data['sample size'] = n
+            plot_data = data if plot_data.empty else pd.concat([plot_data, data])
+
+            pw_distances_avgs.append(pw_distances.mean())
+        
+        # dispersion metrics
+        disp_metric = pw_distances_avgs[0] - pw_distances_avgs[-1]
+        disp_metrics.update({r: disp_metric})
+
+        # plot
+        ax = axs[i] if numR > 1 else axs
+        sns.scatterplot(x=plot_data['sample size'], y=plot_data['pairwise distances'], ax=ax)
+        ax.set(title=f'disp_best for {r} (metric = {disp_metric:.4f})')
+
+        # custom function scale matching growth factor
+        forward = lambda x: np.log(x / init_percentage) / np.log(growth_factor)
+        inverse = lambda x: init_percentage * (growth_factor ** x)
+        ax.set_xscale('function', functions=(forward, inverse))
+
+        # set ticks manually
+        ax.set_xticks(sample_sizes)
+        ax.set_xticklabels([str(t) for t in sample_sizes])
+        
+    # turn off unused axes
+    if i + 1 < ncols * nrows: 
+        for unused_ax in axs[i + 1:]: unused_ax.set_axis_off()
+    
+    fig.suptitle(f"disp_best for {sample['name']}", y=1.04)
+    
+    plt.tight_layout()
+
+    return disp_metrics, fig
+
+
+def X_imp(sample: dict, n_repeats=10, train_proportion = 0.7, binary: bool = False, seed: float = None):
+    if not util.present(sample, 'X'): raise Exception('X is required. Please provide an X file.')
+
+    X: pd.DataFrame = sample['X']
+    F = sample['F']
+    numF = sample['numF']
+
+    x_imp_ranks = {}
+
+    
+    # add the objectives to the X file
+    for f in F.columns:
+        X[f] = F[f]
+
+    pointbiserialr = lambda x, y: scipy.stats.pointbiserialr(y, x)[0]
+
+    corr_matrix = X.corr(method=pointbiserialr)
+    
+    # remove F cols from X file
+    X.drop(F.columns, axis=1, inplace=True)
+
+    corr_matrix = corr_matrix.drop(index=X.columns).drop(columns=F.columns)
+
+    fig, axs = plt.subplots(ncols=numF, nrows=2, figsize=(numF * 5, 10))
+
+    for i, f in enumerate(F.columns):
+        ax = axs[0, i] if numF > 1 else axs[i]
+        ax = sns.barplot(corr_matrix.loc[f], ax=ax)
+        ax.set(title=f"Correlation of X and {f}")
+    
+    for i, f in enumerate(F.columns):
+        x_imp = pd.DataFrame()
+       
+        # normalize
+        X = (X - X.min(axis=0)) / (X.max(axis=0) - X.min(axis=0))
+
+        X_train, X_test, y_train, y_test = train_test_split(X, F[f], train_size=train_proportion, random_state=seed)
+
+        model = LassoLars(alpha=0.001).fit(X_train, y_train)
+        r2 = model.score(X_test, y_test)
+
+        imp = permutation_importance(model, X_test, y_test, 
+                                     n_repeats=n_repeats, 
+                                     random_state=seed,
+                                     scoring='r2')
+        # sort importance means desc.
+        imp_idxs = imp.importances_mean.argsort()[::-1]
+
+        x_imp['X'] = X.columns[imp_idxs]
+        x_imp['importance'] = imp.importances_mean[imp_idxs]
+        x_imp['std'] = imp.importances_std[imp_idxs]
+        x_imp['rank'] = x_imp.index.to_numpy() + 1
+        x_imp_ranks[f] = x_imp
+
+        ax = sns.barplot(x_imp, x='X', y='importance', ax=axs[1, i] if numF > 1 else axs[1])
+        ax.errorbar(
+            x=range(len(x_imp)),
+            y=x_imp['importance'],
+            yerr=x_imp['std'],
+            fmt='none',
+            c='black',
+        )
+        ax.set(title=f"X_imp for {f} (Validation {r"$R^2$"} = {r2:.4f})")
+
+    fig.suptitle(f"X_imp for {sample['name']}")
+
+    plt.tight_layout()
+
+    return corr_matrix, x_imp_ranks, fig