mosaicshade 0.1.0

Residual-based shading for mosaic plots in Python

MosaicShade

Overview

Implements residual-based shading for mosaic displays in Python.

Shading based on residuals offers a way of visualizing how your data departs from a given statistical model. Currently, MosaicShade only uses the model of independence (see Limitations).

Colour and shading intensity respectively indicate the direction and magnitude of residuals, making patterns of association between categorical variables easier to identify.

MosaicShade extends statsmodels.graphics.mosaicplot.mosaic. The shading scheme used was inspired by shading_Friendly from the vcd package in the programming language R.

Installation

Install MosaicShade from PyPI:

python -m pip install mosaicshade

Usage

Currently, data needs to be a pd.DataFrame to be accepted by the mosaic function (see Limitations). The below is a made-up pd.DataFrame that will be used for subsequent examples:

import pandas as pd

df = pd.DataFrame({
    "Treatment": ["A", "A", "A", "A", "B", "B", "B", "B"],
    "Outcome": ["Good", "Good", "Bad", "Bad"] * 2,
    "Sex": ["Female", "Male"] * 4,
    "Freq": [20, 23, 3, 4, 2, 2, 10, 72]
})

df

<style scoped> .dataframe tbody tr th:only-of-type { vertical-align: middle; } .dataframe tbody tr th { vertical-align: top; } .dataframe thead th { text-align: right; } </style>

	Treatment	Outcome	Sex	Freq
0	A	Good	Female	20
1	A	Good	Male	23
2	A	Bad	Female	3
3	A	Bad	Male	4
4	B	Good	Female	2
5	B	Good	Male	2
6	B	Bad	Female	10
7	B	Bad	Male	72

To make a mosaic from this data, we can call the mosaicshade.mosaic function, specifying the frequency column with the freq argument:

import mosaicshade
import matplotlib.pyplot as plt

mosaicshade.mosaic(df, freq='Freq')
plt.show() # Show the plot

We can optionally select specific dimensions (columns) to use in this plot, summing over those that are excluded:

mosaicshade.mosaic(
    df,
    freq='Freq',
    dims=['Treatment', 'Outcome']
)
plt.show()

Remaining keyword arguments from statsmodels.graphics.mosaicplot.mosaic also work (with the exception of the properties argument, as this is used to perform the shading). For example, here is how you may add a title to the above plot:

mosaicshade.mosaic(
    df,
    freq='Freq',
    dims=['Treatment', 'Outcome'],
    title='Shaded Mosaic'
)
plt.show()

API

mosaicshade.mosaic(df, freq, dims=None, **kwargs)

Used to construct mosaic displays. An extension of statsmodels.graphics.mosaicplot.mosaic that implements residual-based shading.

Parameters:

df : pd.Dataframe

The data to plot.

freq : str

The frequency column of your DataFrame.

dims : list[str] or tuple[str, …], optional

Two to four dimensions (column names) to use for the mosaic. Defaults to all dimensions except the frequency column.

**kwargs

Any remaining keyword arguments passed to statsmodels.graphics.mosaicplot.mosaic. Note that the properties argument is managed by mosaicshade and cannot be changed.

Returns:

fig : (matplotlib.figure.Figure)

The figure containing the mosaic plot.

ax : (matplotlib.axes.Axes)

The axes containing the mosaic plot.

Limitations

I am working to address these limitations in future versions. You are also welcome to contribute to help in this regard (see the Contributing section below).

• Data input to the mosaicshade.mosaic() function must be of type pd.DataFrame
• Residuals are currently calculated assuming a model of mutual independence
• No way to adjust shading limits (e.g., changing from magnitude 2-4 for light and 4+ for dark)
• Only labelling scheme added so far is labeling_values
• Limited to 2-4 dimensions (i.e., 5+ dimensions are untested and currently blocked by the mosaic function)

Contributing

Contributions, bug reports, and feature requests are welcome. Please open an issue or submit a pull request. Contributions addressing the above limitations are especially appreciated.

Citation

If you use MosaicShade, please cite the software using information found in CITATION.cff or GitHub’s “Cite this repository” menu.

References

Friendly, M. (1994). Mosaic Displays for Multi-Way Contingency Tables. Journal of the American Statistical Association, 89(425), 190–200. https://doi.org/10.1080/01621459.1994.10476460

Meyer, D., Zeileis, A., Hornik, K., & Friendly, M. (2024). vcd: Visualizing Categorical Data. R package version 1.4-13. https://doi.org/10.32614/CRAN.package.vcd

Zeileis, A., Meyer, D., & Hornik, K. (2007). Residual-based Shadings for Visualizing (Conditional) Independence. Journal of Computational and Graphical Statistics, 16(3), 507-525. https://doi.org/10.1198/106186007X237856

License

MosaicShade is licensed under the GNU General Public License version 3 (GPL-3.0-only). See LICENSE for details.