feyn.plots

This module contains functions to help plotting evaluation metrics for feyn and other models.

Sub-modules

• feyn.plots.interactive

function plot_activation_flow

def plot_activation_flow(
    model: feyn._model.Model,
    data: pandas.core.frame.DataFrame,
    sample: Union[pandas.core.frame.DataFrame, pandas.core.series.Series],
    filename: Optional[str] = None
) -> feyn.tools._display.SVG

Plot a model of a model displaying the flow of activations.

Arguments:
    model {feyn.Model}   -- A feyn.Model we want to describe given some data.
    data {DataFrame} -- A Pandas DataFrame to compute on.
    sample {Iterable} - The single sample you want to visualize.
    filename {Optional[str]} - The filename to use for saving the plot as svg.

Raises:
    TypeError: if inputs don't match the correct type.
    ValueError: If columns needed for the model are not present in the data or sample.

Returns:
    SVG -- SVG of the model activation flow.

function plot_confusion_matrix

def plot_confusion_matrix(
    y_true: Iterable[Union[bool, float]],
    y_pred: Iterable[Union[bool, float]],
    labels: Optional[Iterable] = None,
    title: str = 'Confusion matrix',
    color_map: str = 'feyn-primary',
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    figsize: Optional[tuple] = None,
    filename: Optional[str] = None
) -> Union[matplotlib.axes._axes.Axes, str]

Compute and plot a Confusion Matrix.

Arguments:
    y_true -- Expected values (Truth) as boolean or 0/1 values.
    y_pred -- Predicted values, rounded as boolean or 0/1 values.
    labels -- List of labels to index the matrix
    title -- Title of the plot.
    color_map -- Color map from matplotlib to use for the matrix
    ax -- matplotlib axes object to draw to, default None
    figsize -- Size of figure when  is None, default None
    filename -- Path to save plot. If axes is passed then only plot is saved. If no extension is given then .png is used, default None

Raises:
    TypeError: if inputs don't match the correct type.
    ValueError: if y_true is not bool-like (bool or 0/1).
    ValueError: if y_pred is not bool-like (bool or 0/1).
    ValueError: if y_true and y_pred are not same size.

Returns:
    Union[matplotlib.axes.Axes, str] -- matplotlib confusion matrix or path to where plot is saved when filename is specified

function plot_model_response_1d

def plot_model_response_1d(
    model: feyn._model.Model,
    data: pandas.core.frame.DataFrame,
    by: Optional[str] = None,
    input_constraints: Optional[dict] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    figsize: tuple = (8, 8),
    filename: Optional[str] = None
) -> Union[Tuple[matplotlib.axes._axes.Axes, matplotlib.axes._axes.Axes, matplotlib.axes._axes.Axes], str]

Plot the response of a model to a single input given by `by`.
The remaining model inputs are fixed by default as the middle
quantile (median). Additional quantiles are added if the model has
a maximum of 3 inputs. You can change this behavior by determining
`input_constraints` yourself. Any number of model inputs can be added to it.

Arguments:
    model {feyn.Model} -- Model to be analysed
    data {DataFrame} -- DataFrame
    by {str} -- Model input to plot model response

Keyword Arguments:
    input_contraints {Optional[dict]} -- Input values to be fixed (default: {None})
    ax {matplotlib.axes} -- matplotlib axes object to draw to (default: {None})
    figsize {tuple} -- size of figure when  is None (default: {(8,8)})
    filename {str} -- Path to save plot. If axes is passed then only plot is saved. If no extension is given then .png is used (default: {None})

Raises:
    TypeError: if inputs don't match the correct type.
    ValueError: if by is not in the columns of data or inputs to the model.
    ValueError: if by is also in input_constraints.
    ValueError: if input_constraints contains a name that is not in data.
    ValueError: if model.output is not in data.

Returns:
    Union[(ax, ax_top, ax_right), str] -- The three axes (main, top, right) that make up the plot or path to where plot is saved when filename is specified

function plot_model_response_2d

def plot_model_response_2d(
    model: feyn._model.Model,
    data: pandas.core.frame.DataFrame,
    fixed: Optional[Dict[str, Any]] = None,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    resolution: int = 1000,
    cmap: str = 'feyn-diverging',
    figsize: Optional[tuple] = None,
    filename: Optional[str] = None
) -> Union[matplotlib.axes._axes.Axes, str]

Visualize the response of a model to numerical inputs. Works for both classification and regression problems. The plot comes in two parts:

1. A colored background indicating the response of the model in a 2D space given the fixed values. A lighter color corresponds to a bigger output from the model.
2. Scatter-plotted data on top of the background. In a classification scenario, green corresponds to positive class, and pink corresponds to the negative class.

For regression, the color gradient shows the true distribution of the output value.
Two sizes are used in the scatterplot:
- Larger dots correspond to the data that matches the values in fixed. (inclusive within one half of the standard deviation)
- Smaller dots have data different from the values in fixed. (outside one half of the standard deviation)

Arguments:
    model {feyn.Model} -- The feyn Model we want to plot the response.
    data {DataFrame} -- The data that will be scattered in the model.

Keyword Arguments:
    fixed {Optional[Dict[str, Any]]} -- Dictionary with values we fix in the model. The key is an input name in the model and the value is a number that the input is fixed to. (default: {None})
    ax {Optional[plt.Axes.axes]} -- Optional matplotlib axes in which to make the partial plot. (default: {None})
    resolution {int} -- The resolution at which we sample the 2D input space for the background. (default: {1000})
    figsize {Optional[tuple]} -- Size of figure when  is None. (default: {None})
    filename {str} -- Path to save plot. If axes is passed then only plot is saved. If no extension is given then .png is used (default: {None})

Raises:
    TypeError: if inputs don't match the correct type.
    ValueError: if the model input names minus the fixed value names are more than two, meaning that you need to fix more values to reduce the dimensionality and make a 2D plot possible.
    ValueError: if fixed contains a name not in the model inputs.
    ValueError: If columns needed for the model are not present in the data.

Returns:
    Union[Axes, str]: Axes object or path to where plot is saved when filename is specified

function plot_model_response_auto

def plot_model_response_auto(
    model: feyn._model.Model,
    data: pandas.core.frame.DataFrame,
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    figsize: Optional[Tuple[int, int]] = None,
    filename: Optional[str] = None
) -> Union[matplotlib.axes._axes.Axes, Tuple[matplotlib.axes._axes.Axes, matplotlib.axes._axes.Axes, matplotlib.axes._axes.Axes], str]

Plot the response plot by automatically determining the most interesting inputs to display and which to fix.
Calls the functions plot_model_response_1d or plot_model_response_2d depending on number of inputs in the model.

Arguments:
    model {feyn.Model} -- The model to plot for
    data {pandas.DataFrame} -- The dataset to plot for

Keyword Arguments:
    ax {Optional[plt.Axes.axes]} -- Optional matplotlib axes in which to make the plot. (default: {None})
    figsize {Optional[Tuple[int, int]]} -- A matplotlib compatible figsize tuple (i.e. (8, 8)) (default: {None})
    filename {Optional[str]} -- Path to save plot. If no extension is given then .png is used (default: {None})

Returns:
    Union[Axes, Tuple[Axes, Axes, Axes], str] -- Singular Axes if the plot returns a 2d response plot, Axes Tuple with 3 elements for the 1d plot or the filepath if filename was given.

function plot_model_signal

def plot_model_signal(
    model: feyn._model.Model,
    dataframe: pandas.core.frame.DataFrame,
    corr_func: Optional[str] = None,
    filename: Optional[str] = None
) -> feyn.tools._display.SVG

Plot a model displaying the signal path for the provided feyn.Model and DataFrame.

Arguments:
    model {feyn.Model}   -- A feyn.Model we want to describe given some data.
    dataframe {DataFrame} -- A Pandas DataFrame for showing metrics.

Keyword Arguments:
    corr_func {Optional[str]} -- A name for the correlation function to use as the node signal, either 'mutual_information', 'pearson' or 'spearman' are available. (default: {None} defaults to 'pearson')
    filename {Optional[str]} - The filename to use for saving the plot as svg.

Raises:
    TypeError: if inputs don't match the correct type.
    ValueError: if the name of the correlation function is not understood.
    ValueError: if invalid dataframe is passed.
    ValueError: If columns needed for the model are not present in the data.

Returns:
    Union[SVG, str] -- SVG of the model signal or path to where the file is saved when filename is specified.

function plot_model_summary

def plot_model_summary(
    model: feyn._model.Model,
    dataframe: pandas.core.frame.DataFrame,
    compare_data: Union[pandas.core.frame.DataFrame, List[pandas.core.frame.DataFrame], NoneType] = None,
    labels: Optional[Iterable[str]] = None,
    filename: Optional[str] = None
) -> feyn.tools._display.HTML

Plot a model and summary metrics for the provided feyn.Model and DataFrame with performance plots underneath.

Arguments:
    model {feyn.Model}   -- A feyn.Model we want to describe given some data.
    dataframe {DataFrame} -- A Pandas DataFrame for showing metrics.

Keyword Arguments:
    compare_data {Optional[Union[DataFrame, List[DataFrame]]]} -- A Pandas DataFrame or list of DataFrames for showing additional metrics. (default: {None})
    labels {Optional[Iterable[str]]} - A list of labels to use instead of the default labels. Should match length of comparison data + 1.
    filename {Optional[str]} - The filename to use for saving the plot as html.

Raises:
    TypeError: if inputs don't match the correct type.
    ValueError: if the name of the correlation function is not understood.
    ValueError: if invalid dataframes are passed.
    ValueError: If columns needed for the model are not present in the data.

Returns:
    HTML -- HTML of the model summary.

function plot_probability_scores

def plot_probability_scores(
    y_true: Iterable[Union[bool, float]],
    y_pred: Iterable[float],
    nbins: int = 10,
    title: str = 'Predicted Probabilities',
    legend: List[str] = ['Positive Class', 'Negative Class'],
    legend_loc: Optional[str] = 'upper center',
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    figsize: Optional[tuple] = None,
    filename: Optional[str] = None,
    **kwargs
) -> Union[matplotlib.axes._axes.Axes, str]

Plots the histogram of predicted probability scores in binary
classification problems, highlighting the negative and
positive classes. Order of truth and prediction matters.

Arguments:
    y_true {array_like} -- Expected values (Truth)
    y_pred {array_like} -- Predicted values

Keyword Arguments:
    nbins {int} -- number of bins (default: {10})
    title {str} -- plot title (default: {''})
    legend {List[str]} -- labels to use in the legend for the positive and negative class (default: ["Positive Class", "Negative Class"])
    legend_loc {str} -- the location (mpl style) to use for the label. If None, legend is hidden
    ax {Axes} -- axes object (default: {None})
    figsize {tuple} -- size of figure when  is None (default: {None})
    filename {str} -- Path to save plot. If axes is passed then only plot is saved. If no extension is given then .png is used (default: {None})
    kwargs -- histogram kwargs (default: {None})

Raises:
    TypeError: if inputs don't match the correct type.
    ValueError: if y_true is not bool-like (boolean or 0/1).
    ValueError: if y_pred is not bool-like (boolean or 0/1).
    ValueError: if y_pred and y_true are not same size.
    ValueError: If fewer than two labels are supplied for the legend.

Returns:
    Union[matplotlib.axes.Axes, str] -- The axes to plot or path to where plot is saved when filename is specified

function plot_regression

def plot_regression(
    y_true: Iterable[float],
    y_pred: Iterable[float],
    title: str = 'Actuals vs Predictions',
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    figsize: Optional[tuple] = None,
    filename: Optional[str] = None
) -> Union[matplotlib.axes._axes.Axes, str]

This plots this true values on the x-axis and the predicted values on the y-axis.
On top of the plot is the line of equality y=x.
The closer the scattered values are to the line the better the predictions.
The line of best fit between y_true and y_pred is also calculated and plotted. This line should be close to the line y=x

Arguments:
    y_true {Iterable} -- True values
    y_pred {Iterable} -- Predicted values

Keyword Arguments:
    title {str} -- (default: {"Actuals vs Predictions"})
    ax {AxesSubplot} -- (default: {None})
    figsize {tuple} -- Size of figure when  is None (default: {None})
    filename {str} -- Path to save plot. If axes is passed then only plot is saved. If no extension is given then .png is used (default: {None})

Raises:
    TypeError: if inputs don't match the correct type.
    ValueError: if y_pred and y_true are not same size.

Returns:
    Union[AxesSubplot, str] -- Scatter plot of y_pred and y_true with line of best fit and line of equality or path to where plot is saved when filename is specified

function plot_residuals

def plot_residuals(
    y_true: Iterable[float],
    y_pred: Iterable[float],
    title: str = 'Residual plot',
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    figsize: Optional[tuple] = None,
    filename: Optional[str] = None
) -> Union[matplotlib.axes._axes.Axes, str]

This plots the predicted values against the residuals (y_true - y_pred).

Arguments:
    y_true {Iterable} -- True values
    y_pred {Iterable} -- Predicted values

Keyword Arguments:
    title {str} -- (default: {"Residual plot"})
    ax {Axes} -- (default: {None})
    figsize {tuple} -- Size of figure when  is None (default: {None})
    filename {str} -- Path to save plot. If axes is passed then only plot is saved. If no extension is given then .png is used (default: {None})

Raises:
    TypeError: if inputs don't match the correct type.
    ValueError: if y_pred and y_true are not same size.

Returns:
    Union[AxesSubplot, str] -- Scatter plot of residuals against predicted values or path to where plot is saved when filename is specified

function plot_roc_curve

def plot_roc_curve(
    y_true: Iterable[Union[bool, float]],
    y_pred: Iterable[float],
    threshold: Optional[float] = None,
    title: str = 'ROC curve',
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    figsize: Optional[tuple] = None,
    filename: Optional[str] = None,
    **kwargs
) -> Union[matplotlib.axes._axes.Axes, str]

Plot a ROC curve for a classification model.

A receiver operating characteristic curve, or ROC curve, is an illustration of the diagnostic ability of a binary classifier. The method was developed for operators of military radar receivers, which is why it is so named.

Arguments:
    y_true -- Expected values (Truth).
    y_pred -- Predicted values.
    threshold -- Plots a point on the ROC curve of the true positive rate and false positive rate at the given threshold. Default is None
    title -- Title of the plot.
    ax -- matplotlib axes object to draw to, default None
    figsize -- size of figure when  is None, default None
    filename -- Path to save plot. If axes is passed then only plot is saved. If no extension is given then .png is used, default is None
    **kwargs -- additional keyword arguments to pass to Axes.plot function

Raises:
    TypeError: if inputs don't match the correct type.
    ValueError: When y_true is not boolean (or 0/1).
    ValueError: When y_true and y_pred do not have same shape.
    ValueError: When threshold is not between 0 and 1.

Returns:
    Union[matplotlib.axes.Axes, str] -- Axes or path to where plot is saved when filename is specified

function plot_segmented_loss

def plot_segmented_loss(
    model: Union[feyn._model.Model, feyn.reference.BaseReferenceModel],
    data: pandas.core.frame.DataFrame,
    by: Optional[str] = None,
    loss_function: str = 'squared_error',
    title: str = 'Segmented Loss',
    legend: List[str] = ['Samples in bin', 'Mean loss for bin'],
    legend_loc: Optional[str] = 'lower right',
    ax: Optional[matplotlib.axes._axes.Axes] = None,
    figsize: Optional[tuple] = None,
    filename: Optional[str] = None
) -> Union[List[matplotlib.axes._axes.Axes], str]

Plot the loss by segment of a dataset.

This plot is useful to evaluate how a model performs on different subsets of the data.

Example:
> models = qlattice.sample_models(["age","smoker","heartrate"], output="heartrate")
> models = feyn.fit_models(models, data)
> best = models[0]
> feyn.plots.plot_segmented_loss(best, data, by="smoker")

This will plot a histogram of the model loss for smokers and non-smokers separately, which can help evaluate wheter the model has better performance for euther of the smoker sub-populations.

You can use any column in the dataset as the `by` parameter. If you use a numerical column, the data will be binned automatically.

Arguments:
    model -- The model to plot.
    data -- The dataset to measure the loss on.

Keyword Arguments:
    by -- The column in the dataset to segment by.
    loss_function -- The loss function to compute for each segmnent,
    title -- Title of the plot.
    legend {List[str]} -- legend to use on the plot for bins and loss line (default: ["Samples in bin", "Mean loss for bin"])
    legend_loc {str} -- the location (mpl style) to use for the legend. If None, legend is hidden
    ax -- matplotlib axes object to draw to
    figsize -- Size of figure when  is None, default None
    filename -- Path to save plot. If axes is passed then only plot is saved. If no extension is given then .png is used, default None

Raises:
    TypeError: if inputs don't match the correct type.
    ValueError: if by is not in data.
    ValueError: If columns needed for the model are not present in the data.
    ValueError: If fewer than two labels are supplied for the legend.

Returns:
    Union[List[matplotlib.axes.Axes], str] -- the axes for plotting or path to where plot is saved when filename is specified

class Theme

def __init__(
    /,
    *args,
    **kwargs
) -> Theme

static method Theme.cmap

def cmap(
    name
)

Helper to get a colormap from the current theme
Arguments:
    name {str} -- A colormap from the theme

Returns:
    matplotlib.colors.LinearSegmentedColormap

static method Theme.color

def color(
    color
)

Helper to get a color from the current theme

Arguments:
    color {str} -- A color from the theme, either among:
    ['highlight', 'primary', 'secondary', 'accent', 'light', 'dark', 'neutral']
    a color among AbzuColors,
    Colors defined in the theme,
    Hex code (will pass through if not defined)

Returns:
    [str] -- a string with a color hex code, i.e. '#FF1EC8'

static method Theme.cycler

def cycler(
    pos: Optional[int] = None
) -> Union[str, List[str]]

Helper to get a color from the current theme's cycler

Arguments:
    pos {Optional[str]} -- position in the cycler for the color to return. Will return a list of colors if None {default: None}

Returns:
    [str] -- a string with a color hex code, i.e. '#FF1EC8'

static method Theme.flip_cmap

def flip_cmap(
    cmap: str
)

Reverse the specified colormap belonging to a theme. Any subsequent plots using the colormap will now use the reversed version instead.
Flipping it multiple times or changing the theme will revert it back to its original order.

static method Theme.flip_diverging_cmap

def flip_diverging_cmap(
    
)

Reverse the gradient used in the feyn-diverging colormap. Any subsequent plots using the colormap will now use the reversed version instead.
Useful for flipping the color scheme for classification tasks where 1 is a negative outcome and 0 is a positive outcome.
Flipping it multiple times or changing the theme will revert it back to its original order.

It does not affect the order of the gradient returned by Theme.gradient.

static method Theme.font_size

def font_size(
    size
)

Helper to get a font size in pixels from a t-shirt size definition such as:
    ['small', 'medium', 'large']

Arguments:
    size {str} -- A size in t-shirt sizing

Returns:
    int -- font size in pixels corresponding to the provided t-shirt size

static method Theme.gradient

def gradient(
    
)

Helper to get a three-step gradient from the current theme

Returns:
    [Array(str)] -- An array of diverging colors [, , ]

static method Theme.set_theme

def set_theme(
    theme='default'
)

Sets the theme for visual output in Feyn.

Arguments:
    theme {str} -- Choose amongst: ['default', 'light', 'dark', 'mono', 'mono_dark']