Metadata-Version: 2.4
Name: faceted
Version: 0.2.2
Summary: Figures with precise control over overall width, plot aspect ratio, between-plot spacing, and colorbar dimensions.
Author-email: Spencer Clark <spencerkclark@gmail.com>
License: MIT License
        
        Copyright (c) 2018 Spencer Clark
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Documentation, https://faceted.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/spencerkclark/faceted.git
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=1.5
Requires-Dist: numpy>=1.7
Provides-Extra: dev
Requires-Dist: cartopy; extra == "dev"
Requires-Dist: coveralls; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: docs
Requires-Dist: cartopy; extra == "docs"
Requires-Dist: cftime; extra == "docs"
Requires-Dist: ipython; extra == "docs"
Requires-Dist: jupyter; extra == "docs"
Requires-Dist: nc-time-axis; extra == "docs"
Requires-Dist: netCDF4; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: pooch; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-gallery; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: xarray; extra == "docs"
Dynamic: license-file

faceted
=======

[![tests](https://github.com/spencerkclark/faceted/actions/workflows/tests.yml/badge.svg)](https://github.com/spencerkclark/faceted/actions/workflows/tests.yml) [![codecov](https://codecov.io/gh/spencerkclark/faceted/branch/master/graph/badge.svg?token=H1DBBSTQ2V)](https://codecov.io/gh/spencerkclark/faceted) [![Documentation
Status](https://readthedocs.org/projects/faceted/badge/?version=latest)](https://faceted.readthedocs.io/en/latest/?badge=latest) [![PyPI](https://img.shields.io/pypi/v/faceted.svg)](https://pypi.python.org/pypi/faceted/)

Figures with precise control over overall width, overall height,
plot aspect ratio, between-plot spacing, and colorbar dimensions.

Description
-----------

The purpose of this module is to make it easy to produce single-or-multi-panel
figures in `matplotlib` with strict dimensional constraints.  For example,
perhaps you would like to make a figure that fits exactly within a column of a
manuscript *without any scaling*, and you would like the panels to be as large
as possible, but retain a fixed aspect ratio (height divided by width).  Maybe
some (or all) of your panels require an accompanying colorbar.  With
out of the box `matplotlib` tools this is actually somewhat tricky.

![readme-example.png](readme-example.png?raw=true)

Internally, this module uses the flexible [`matplotlib` `AxesGrid` toolkit](https://matplotlib.org/2.0.2/mpl_toolkits/axes_grid/users/overview.html#axes-grid1),
with some additional logic to enable making these kinds of
dimensionally-constrained
panel plots with precise padding and colorbar size(s).

Another project with a similar motivation is [panel-plots](
https://github.com/ajdawson/panel-plots); however it does not have support
for adding colorbars to a dimensionally-constrained figure.  One part of the 
implementation there that inspired part of what is done here is the ability 
to add user-settable padding to the edges of the figure (to add space for 
axes ticks, ticklabels, and labels).  This eliminates the need for using 
`bbox_inches='tight'` when saving the figure, and enables you 
to make sure that your figures are *exactly* the dimensions you need for your use.

I intend to keep the scope of this project quite limited. I want the results it
produces to remain extremely easy to understand and control.  For more
complicated figure layouts, e.g. multiple panels with different sizes and
aspect ratios, and a more magical approach to setting figure boundary padding
and between-panel spacing, a library worth checking out is
[proplot](https://github.com/lukelbd/proplot).  The ["smart tight layout" feature
it provides](https://proplot.readthedocs.io/en/stable/why.html#id5) is an impressive 
automated method of solving some of the same problems addressed by this library.

For information on how to use `faceted`, see the documentation:
https://faceted.readthedocs.io/en/latest/.

Installation
------------

You can install `faceted` either from PyPI:
```
$ pip install faceted
```
or directly from source:
```
$ git clone https://github.com/spencerkclark/faceted.git
$ cd faceted
$ pip install -e .
```
