ivpy: Iconographic Visualization in Python

Read the journal article here.

Tutorial Dataset

A detailed guide to using ivpy is included here, in the tutorial notebooks. To avoid data access issues, I've written the tutorials using the publicly available Oxford Flower 17 dataset. It contains 80 images each of 17 different flower types. I've included a data table, oxfordflower.csv, in the ivpy repo, but you'll need to download the images themselves here. The filename column in oxfordflower.csv corresponds to the filenames in the linked archive.

Basic Install

I recommend cloning this repo into your home directory, creating and activating a Python virtual environment, and pip installing the dependencies:

$ git clone https://github.com/damoncrockett/ivpy
$ python3 -m venv ivpy_env
$ source ivpy_env/bin/activate
$ pip install numpy notebook pandas Pillow

Custom CSS theme

If you want to use my custom jupyter theme, optimized for viewing image visualizations:

$ mkdir ~/.jupyter/custom
$ cp ~/ivpy/style/custom.css ~/.jupyter/custom

Fonts

Some of the plots include text labels, and for that, I include a directory of fonts, because the defaults in PIL are pretty bad. You'll need to copy the font directory to your home directory:

$ cp -r ~/ivpy/fonts ~

Basic Usage

import pandas as pd
import sys,os
sys.path.append(os.path.expanduser("~") + "/ivpy/src")
from ivpy import *

df = pd.DataFrame(...)
imagecol = '...'

attach(df, imagecol)

# scrollable panel of images / glyphs
show()

# by default, a square montage of images
montage()

# image histogram
histogram(xcol='foo')

# image scatterplot
scatter(xcol='foo', ycol='bar')

Additional functionality

There is a great deal more in ivpy, including image feature extraction (requires additional dependencies, like scikit-image and others); glyph drawing; line plots; clustering algorithms and dimension reduction (with scikit-learn under the hood); image resizing and slicing; image signal processing; and even nearest neighbor search (using annoy).