ChernoffFace 0.1.4
Makes of Chernoff face diagrams.
Requires Python: >=3.7
Keywords: chernoff,face,chernoff face,chernoff face diagram,multi-dimensional,visualization

# ChernoffFace Python package

## Introduction

This Python package implements the function `chernoff_face` that
generates [Chernoff face diagrams](https://en.wikipedia.org/wiki/Chernoff_face).

The design, implementation *strategy*, and unit tests closely resemble
the Wolfram Repository Function (WFR)
[`ChernoffFace`](https://resources.wolframcloud.com/FunctionRepository/resources/ChernoffFace),
\[AAf1\], and the original Mathematica package
[“ChernoffFaces.m”](https://github.com/antononcube/MathematicaForPrediction/blob/master/ChernoffFaces.m),
\[AAp1\].

------------------------------------------------------------------------

## Installation

To install from GitHub use the shell command:

    python -m pip install git+https://github.com/antononcube/Python-packages.git#egg=ChernoffFace\&subdirectory=ChernoffFace

To install from PyPI:

    python -m pip install ChernoffFace

------------------------------------------------------------------------

# Usage examples

## Setup

    from ChernoffFace import *
    import numpy
    import matplotlib.cm

## Random data

Here is an example of generating a table (`matplotlib` `figure` object) of Chernoff faces over 
the rows of a two-dimensional array of real numbers:

    # Generate data
    numpy.random.seed(32)
    data = numpy.random.rand(16, 12)

    # Make Chernoff faces
    fig = chernoff_face(data=data, 
                        titles=[str(x) for x in list(range(len(data)))], 
                        color_mapper=matplotlib.cm.Pastel1)

    # Display
    fig.tight_layout()
    matplotlib.pyplot.show()

<img src="https://github.com/antononcube/Python-packages/raw/main/ChernoffFace/docs/img/random-data-1.png" width="672" />

(To be clear, each face represents a row of the given array.)

## Employee attitude data

Get Employee attitude data

    dfData=load_employee_attitude_data_frame()
    dfData.head()

    ##    Rating  Complaints  Privileges  Learning  Raises  Critical  Advancement
    ## 0      43          51          30        39      61        92           45
    ## 1      63          64          51        54      63        73           47
    ## 2      71          70          68        69      76        86           48
    ## 3      61          63          45        47      54        84           35
    ## 4      81          78          56        66      71        83           47

Rescale the variables (columns):

    dfData2 = variables_rescale(dfData)
    dfData2.head()

    ##      Rating  Complaints  Privileges  Learning    Raises  Critical  Advancement
    ## 0  0.066667    0.264151    0.000000  0.121951  0.400000  1.000000     0.425532
    ## 1  0.511111    0.509434    0.396226  0.487805  0.444444  0.558140     0.468085
    ## 2  0.688889    0.622642    0.716981  0.853659  0.733333  0.860465     0.489362
    ## 3  0.466667    0.490566    0.283019  0.317073  0.244444  0.813953     0.212766
    ## 4  0.911111    0.773585    0.490566  0.780488  0.622222  0.790698     0.468085

Make the corresponding Chernoff faces:

    fig = chernoff_face(data=dfData2,
                        n_columns=5,
                        long_face=False,
                        color_mapper=matplotlib.cm.tab20b,
                        figsize=(8, 8), dpi=200)

Display:

    fig.tight_layout()
    matplotlib.pyplot.show()

<img src="https://github.com/antononcube/Python-packages/raw/main/ChernoffFace/docs/img/employee-chernoff-faces-figure-3.png" width="768" />

## USA arrests data

Get USA arrests data:

    dfData=load_usa_arrests_data_frame()
    dfData.head()

    ##     StateName  Murder  Assault  UrbanPopulation  Rape
    ## 0     Alabama    13.2      236               58  21.2
    ## 1      Alaska    10.0      263               48  44.5
    ## 2     Arizona     8.1      294               80  31.0
    ## 3    Arkansas     8.8      190               50  19.5
    ## 4  California     9.0      276               91  40.6

Rescale the variables:

    dfData2 = variables_rescale(dfData)
    dfData2.head()

    ##     StateName    Murder   Assault  UrbanPopulation      Rape
    ## 0     Alabama  0.746988  0.654110         0.440678  0.359173
    ## 1      Alaska  0.554217  0.746575         0.271186  0.961240
    ## 2     Arizona  0.439759  0.852740         0.813559  0.612403
    ## 3    Arkansas  0.481928  0.496575         0.305085  0.315245
    ## 4  California  0.493976  0.791096         1.000000  0.860465

Make the corresponding Chernoff faces using USA state names as titles:

    fig = chernoff_face(data=dfData2,
                        n_columns=5,
                        long_face=False,
                        color_mapper=matplotlib.cm.tab20c_r,
                        figsize=(12, 12), dpi=200)

Display:

    fig.tight_layout()
    matplotlib.pyplot.show()

<img src="https://github.com/antononcube/Python-packages/raw/main/ChernoffFace/docs/img/usa-arrests-data-to-chernoff-faces-figure-5.png" width="1152" />

------------------------------------------------------------------------

# Additional comments

- In order to have "prettier" and "tighter" looking diagrams (Chernoff faces) by default 
`chernoff_face` makes wide faces. 
   - The argument `long_face` controls the shape of the faces.
   - `ChernoffFace` in [AAf1] makes long faces.
- Additional functions *have to be* implemented that *summarize* datasets using Chernoff faces.
   - Such summary diagrams are given in [AA1, AAf1].
- For a given dataset certain color palettes (color mappers) would provide more insightful views.
  - For example: 
    - Florida is a clear outlier in the USA arrests plot above
    - Certain clustering of the states is also hinted by faces with similar colors.
  
------------------------------------------------------------------------

## References

### Articles

\[AA1\] Anton Antonov, [“Making Chernoff faces for data
visualization”](https://mathematicaforprediction.wordpress.com/2016/06/03/making-chernoff-faces-for-data-visualization),
(2016), [MathematicaForPrediction at
WordPress](https://mathematicaforprediction.wordpress.com).

### Functions and packages

\[AAf1\] Anton Antonov,
[`ChernoffFace`](https://resources.wolframcloud.com/FunctionRepository/resources/ChernoffFace),
(2019), [Wolfram Function
Repository](https://resources.wolframcloud.com/FunctionRepository).

\[AAp1\] Anton Antonov, [Chernoff faces implementation in
Mathematica](https://github.com/antononcube/MathematicaForPrediction/blob/master/ChernoffFaces.m),
(2016), [MathematicaForPrediction at
GitHub](https://github.com/antononcube/MathematicaForPrediction).