CanD - Easily create complex layouts in Matplotlib
--------------------------------------------------

<img align="right" src="https://raw.githubusercontent.com/mwshinn/CanD/master/cand-logo.png" width="30%" padding="50px">

*Do you plot in Matplotlib, build your diagrams in Inkscape or
Illustrator, and then lay out your figures in InDesign or Powerpoint?
Do you wish you could easily generate scientific figures exclusively
in a single Python script?  CanD gives you the best of all possible worlds.*

CanD features
============

CanD (CANvas Designer) is a system for laying out axes and plot
elements in a figure within Python and Matplotlib.  It provides:

- **A framework for precisely specifying the position of subplots.** Axes may be
  individually positioned, positioned in grids, or a combination.
- **Improved font management.** Alternative to the matplotlib font manager.  Any
  system font may be easily used.  Fonts are synchronized across all text
  present in the figure, including mathematical equations.  Currently this is
  the only reliable cross-platform method for synchronizing fonts in matplotlib
  to our knowledge.
- **An affine algebra system for specifying positions.** Points and
  vectors from different coordinate systems may be used
  interchangeably.  This allows for unprecedented control over element
  positioning.
- **A unified interface for plot elements**.  This allows lines,
  arrows, polygons, and text to be drawn with a single line of code.
  For example, it is easy to draw an arrow from a data point in a
  scatterplot to a plot in a different subpanel.
- **Easy positioning of raster (.png) images.** Currently, importing
  an image directly into matplotlib is difficult and results in
  aliasing artifacts.  CanD allows .png images to be positioned just
  like any other plot element.

CanD does **not** provide:

- Methods for plotting data.  CanD gives you a reference to the axis
  object, with which you may use any of matplotlib's standard plotting
  functions. [Seaborn](https://seaborn.pydata.org/) is a popular
  library which creates elegant and attractive plots with
  little effort, and is mostly compatible with CanD.
- Zero-thought layouts.  CanD will not find a good layout for you.
  If you want automatically-positioned subplots, CanD is not the
  right choice for you. CanD will, however, make it easy to
  implement a layout you have in your mind.

CanD is currently pre-alpha software.  Examples and documentation will be
available eventually.  [Draft documentation on
readthedocs](https://cand.readthedocs.io/en/latest/tutorial.html) is currently
available.

Example
=======

```python
from cand import Canvas, Vector, Point
import matplotlib.pyplot as plt
import seaborn as sns
import numpy as np

# Create a canvas 10 cm x 15 cm.  Use Lucida as the font.
c = Canvas(15, 10, "cm")
c.set_font("Lucida Std")

# Add an axis from the point (2,2) to (14,8) in centimeters.  Name it "sinewave", 
# and plot a sine wave on it.
c.add_axis("sinewave", Point(2, 2, "cm"), Point(14, 8, "cm"))
ax = c.ax("sinewave")
ax.plot(np.linspace(0, 2*np.pi, 500), np.sin(np.linspace(0, 2*np.pi, 500)))
sns.despine(ax=ax)

# Create an inset axis which is 1 x 1 inch, positioned on the right side of the 
# plot, 75% of the way across and 60% up on the "sinewave" axis.  Name it "sineinset".
insetsize = Vector(1, 1, "inches")
insetloc = Point(.75, .6, "axis_sinewave")
c.add_axis("sineinset", insetloc, insetloc+insetsize)
c.ax("sineinset").plot(np.linspace(0, np.pi), np.sin(np.linspace(0, np.pi)))

# Add a arrow pointing to the peak of one sine wave to the other, i.e. (pi/2,1) 
# in data coordinates (i.e. units of the "sinewave" or "sineinset" axis).
c.add_arrow(Point(np.pi/2, 1, "sinewave"), Point(np.pi/2, 1, "sineinset"))

# Add a watermark of the CanD logo in the lower right corner.
c.add_image("cand-logo.png", Point(1, 0, "figure"), width=Vector(2, 0, "cm"), 
            ha="right", va="bottom")

# Save as a .pdf file, and then show the result
c.save("demo_plot.pdf")
c.show()
```



Why CanD?
=========

Matplotlib is a powerful plotting library, but as a result of this
power comes complexity.  Publication-quality figures require complex
layouts with tight positioning and alignment of multiple display
elements across different axes.  They also often require mixing raster
and vector images, and tight control over font size and style.  These
are in practice quite difficult in matplotlib, not only because of the
amount of code required for these tasks, but also due to the
difficulty of keeping the different parts of the figure in sync with
respect to alignment and style.

Due to this difficulty, users will often export plots from matplotlib
and manually position them within PowerPoint, Inkscape, InDesign, or
other software.  Without extra care, font sizes and line thicknesses
may not be consistent, and figures can easily get out of sync with one
another.


Installation
============

CanD depends on:

- numpy
- matplotlib
- seaborn
- paranoid-scientist (version 0.2.1 or greater)
- PyMuPDF
- Pillow

Install with:

    pip install CanD

or by downloading the package from github and running:

    python setup.py install

