Metadata-Version: 2.1
Name: CanD
Version: 0.0.2
Summary: Create complex layouts for scientific figures in matplotlib
Home-page: https://github.com/mwshinn/cand
Author: Max Shinn
Author-email: m.shinn@ucl.ac.uk
Maintainer: Max Shinn
Maintainer-email: m.shinn@ucl.ac.uk
License: MIT
Description: 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
        
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Framework :: Matplotlib
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.5
Description-Content-Type: text/markdown
