src/tutorial0_basics.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting started with ivpy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "ivpy is a Python module for plotting iconographic data. For now, this means anything stored as an image file. The basic module API is extremely simple. Once users have their data loaded (using pandas), they can attach a dataframe to the global environment using attach( ) and then visualize it using one of four plot functions: show( ), montage( ), histogram( ), and scatter( ). "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, we'll need to import Python's data management module, pandas, which gives us a dataframe object. If you've used the statistical programming language R, pandas will seem very familiar."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will then load the Oxford Flower dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = pd.read_csv(\"oxfordflower.csv\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Localizing image paths"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see, by peeking at the dataframe using the 'head( )' method, that our image filenames are not full, local file paths. We'll need to modify the column 'filename' so that it contains full paths: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "DIR = os.path.expanduser(\"~\") + \"/ivpy/datasets/oxfordflower/\" # replace this path with your local Oxford Flower folder"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.filename = [DIR+item for item in df.filename]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Okay good. We can see that the column 'filename' has been changed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Attaching dataframe to global environment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that our data is loaded and ready, let's attach our dataframe to the global environment. You don't have to do this, but it will allow us to refer to the columns of our dataframe ('df') more concisely. But first, we'll need to import the attach( ) function from ivpy, and while we're at it, we'll also import the plotting functions, too."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ivpy import attach,show,montage,histogram,scatter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "attach(df,'filename')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that in calling attach( ), we specify not only the dataframe itself but also the column that has the filepaths."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plotting basics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Okay, we are ready to plot! In this notebook, we'll only cover basic usage. Tutorials 1 through 4 will explore each plot type in detail."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### show( )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "show( ) generates a scrollable, rectangular montage of images. If you pass no arguments to the function, it just plots every image in the attached dataframe."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### montage( )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Passed without any special settings, montage( ) generates a square montage of images, in whatever way they are ordered in the dataframe."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "montage()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### histogram( )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Unlike show( ) and montage( ), histogram( ) plots along a proper axis, and so we'll need to pass an argument to the function that tells it which column to use as an axis. The resulting plot will show the binned distribution of values on that axis. Though we don't have to, we'll tell it how many bins to use as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "histogram(xcol='brightness',bins=100)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### scatter( )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "scatter( ) generates a scatterplot, so we'll need to specify both an x-axis and a y-axis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scatter(xcol='hue',ycol='saturation')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Composing and Saving"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Two final operations bear mentioning here: compose( ) and .save( ):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### compose( )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the user wants to see plots side-by-side, or several together in a grid, she will use compose( ). This function takes plots as arguments and outputs a metaplot:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ivpy import compose"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "compose(scatter('brightness','saturation'),scatter('hue','saturation'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also assign any plot to a variable and pass those to compose( ):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot1 = scatter('brightness','saturation')\n",
    "plot2 = scatter('hue','saturation')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "compose(plot1,plot2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### .save(  )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because ivpy is built atop the Python Imaging Library, and all ivpy plots are instances of its Image class, all ivpy plots are saveable using its .save( ) method. The user can append .save( ) to any plot function call or any plot saved as a variable: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "HOMEDIR = os.path.expanduser(\"~\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scatter('hue','saturation').save(HOMEDIR + \"/Desktop/myplot1.png\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "myplot = scatter('hue','saturation')\n",
    "myplot.save(HOMEDIR + \"/Desktop/myplot2.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One way this might be particularly useful is in generating plots using a loop and saving them to disk. For example, we might want to look at histograms across 100 different variables, which, done \"manually\", would be rather onerous. In big data analysis, this kind of mass exploration is common, and ivpy makes it easy. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Ahead"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That's it for basic usage, but these plots are highly customizable. See subsequent tutorials for the finer points of usage."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}