README.md

mpl-multitab

Tabbed figure manager for matplotlib using pyQt

Ever struggle to navigate between a myriad of open matplotlib figures? I know your pain...

mpl-multitab is a simple application that allows you to embed mutliple figures in a tabbed figure manager, keeping everything neatly in one place.

Install

Using pip:

pip install mpl-multitab

Alternatively, clone the repo, then run the setup.py script

git clone https://github.com/astromancer/mpl-multitab.git
cd mpl-multitab
python setup.py install

Use

Interactive use

At the start of your jupyter notebook, or ipython session, run the line magic to set the qt backend

%matplotlib qt5

Then

# Example use of MplTabs
# Create a scatter plot of `n` random xy-points for each colour
from mpl_multitab import MplTabs


n = 100
colours = 'rgb'
#
ui = MplTabs()
for c in colours:
    fig = ui.add_tab(c)
    ax = fig.subplots()
    ax.scatter(*np.random.randn(2, n), color=c)

ui.set_focus(0)
ui.show()

In a script

# Example using `MplTabs` in a standalone script.
import sys
from mpl_multitab import MplTabs


n = 100
colours = 'rgb'

app = QtWidgets.QApplication(sys.argv)
ui = MplTabs()
for c in colours:
    fig = ui.add_tab(c)
    ax = fig.subplots()
    ax.scatter(*np.random.randn(2, n), color=c)

ui.set_focus(0)
ui.show()
sys.exit(app.exec_())

Groups of Figures

You can group multiple related figures together using the MplMultiTab class. This is useful for visualising, for example, multiple datasets each having multiple observations.

# Example use for MplMultiTab for 2d collection of data sets
# This dataset is equal number observations per dataset. This need not be the
# case in general.
import itertools as itt
from mpl_multitab import MplMultiTab


n = 100
colours = 'rgb'
markers = '123'
#
ui = MplMultiTab(pos='W')
for c, m in itt.product(colours, markers):
    fig = ui.add_tab(f'Dataset {c.upper()}', f'Observation {m}')
    ax = fig.subplots()
    ax.scatter(*np.random.randn(2, n), color=c, marker=f'${m}$')

ui.set_focus(0, 0)
ui.link_focus()
ui.show()

In this example all the datasets contain the same number of obervations, but this need not be the case in general.

Performance considerations - Delayed plotting

Creating all the figures in one go at startup may take unreasonably long if you have many figures or lots of data. This can be amortised by delaying the plotting of individual figures until the user switches to that tab. This is demonstrated in the following example:

# MplMultiTab with delayed plotting
import itertools as itt
from mpl_multitab import MplMultiTab


n = 10000
colours = 'rgb'
markers = '123'
#
# first create the figures, but don't do the plotting just yet
ui = MplMultiTab(pos='W')
for c, m in itt.product(colours, markers):
    ui.add_tab(f'Dataset {c.upper()}', f'Observation {m}')

# create plotting function
def plot(fig, indices):
    print('Doing plot:', indices)
    i, j = indices
    ax = fig.subplots()
    return ax.scatter(*np.random.randn(2, n),
                      color=colours[i],
                      marker=f'${markers[j]}$')

ui.add_task(plot)   # add your plot worker
ui.set_focus(0, 0)      # this will trigger the plotting for group 0 tab 0
ui.link_focus()         # keep same tab in focus across group switches
ui.show()

Arbitrary nesting

The MplMultiTab class is able to handle nested tabs to any depth. The following example demonstrates the usage pattern for datasets grouped by 3 different features. The same pattern can be used to handle data of any dimensionality. Tabs all the way down!

# MplMultiTab with 3 tab levels
import itertools as itt
from mpl_multitab import MplMultiTab


n = 10
colours = 'rgb'
markers = 'H*P'
hatch = ('xx', '**')
#
ui = MplMultiTab()
for c, m, h in itt.product(colours, markers, hatch):
    # use "&" to tag letters for keyboard shortcuts which select the tab
    #   eg: using "&x" somewhere in the tab name means you can select it with "Alt+x"
    fig = ui.add_tab(f'Colour &{c.upper()}', f'Marker &{m}', f'Hatch &{h}')
    ax = fig.subplots()
    ax.scatter(*np.random.randn(2, n),
               s=750, marker=m, hatch=h,
               edgecolor=c,  facecolor='none')

ui.link_focus()             # keep same tab in focus across group switches
ui.set_focus(0, 0, 0)
ui.show()

Test

Testing is done with pytest-qt. This will run through all examples in the examples module:

pytest -vs tests/test_multitab.py

Contribute

Contributions are welcome!

1. Fork it!
2. Create your feature branch
   git checkout -b feature/rad
3. Commit your changes
   git commit -am 'Add some cool feature 😎'
4. Push to the branch
   git push origin feature/rad
5. Create a new Pull Request

Contact

• e-mail: hannes@saao.ac.za

License

• see LICENSE

Version

This project uses semantic versioning. The latest version is

• 1.2.0