colorview2d documentation

colorview2d is a plotting tool intended to be used with scientific data (with dimensionful axes) with an easily extendable data modification (or filtering) toolbox.

Tested with Python 2.7 and Python 3.

Dependencies

numpy, scipy, matplotlib, pyyaml, scikit.image

Homepage

https://github.com/Loisel/colorview2d

Copyright (c) 2016 Alois Dirnaichner <alo.dir@gmail.com>

This documentation is not complete. It includes only the central classes of colorview2d, which are

  • the colorview2d.View class which hosts the pipeline, the data and the configuration objects.
  • the colorview2d.Data class which hosts the 2d numpy array and the axes bounds.

colorview2d Readme

Use colorview2d to visualize and analize 2d data with (linear) axes.

Features:

  • Interactive colorbar adjustment.
  • Wide range of adjustable filters (mods) using routines from numpy, scipy and scikit.images:
    • interpolation,
    • Gaussian and median filters,
    • scale, rotate, flip, crop
    • thresholding to extract features,
    • absolute value, natural logarithm, derivation
    • something missing? Add a mod easily.
  • Plot to pdf or just use the matplotlib figure.
  • Annoyed of matplotlib.pyplots 2d colorplot interface? Simple and convenient plot configuration.
    • Adjust axis labels, their size and font as well as the plot size.
    • Easily adapt the colorbar to your needs.
  • Mass extract linetraces (to depict feature evolution).
  • Save cv2d config files and restore any modifications easily.
  • Save and load data to and from plain text files (gnplot format).

Installation

You can use the python package index via pip

sudo pip2.7 install --upgrade colorview2d

Note: If you receive a ‘Could not find a version that satisfies...’ error, try to upgrade pip, pip install --upgrade pip

If you are considering writing your own mods then installation into the userspace is preferable (access to colorview2d/mods to place the mod file).

pip2.7 install --user <username> --upgrade colorview2

Usage

I stronlgy recommend to use ipython interactive shell for this tutorial. We initialize some random data with x and y ranges:

import numpy as np
data = np.random.random((100, 100))
xrange = (0., np.random.random())
yrange = (0., np.random.random())

Obtain a colorview2d.Data instance to initialize the colorview2d.View object:

import colorview2d
data = colorview2d.Data(data, (yrange, xrange))
view = colorview2d.View(data)

Note that the order of the ranges (y range first) is not a typo. It is reminiscent of the rows-first order of the 2d array.

What is the data about? We add some labels:

view.config['Xlabel'] = 'foo (f)'
view.config['Ylabel'] = 'bar (b)'
view.config['Cblabel'] = 'nicyness (n)'

Let us have a look.

view.show_plt_fig()

You should see two figures opening, one containing the plot, the other two simple matplotlib slider widgets to control the colorbar interactively.

We do not like the font and the ticks labels are too small

view.config.update({'Font': 'Ubuntu', 'Fontsize': 16})

Also, the colormap, being default matplotlib’s jet, is not greyscale-compatible, so we change to ‘Blues’ (have a look at the matplotlib documentation to get a list of colormaps).

view.config['Colormap'] = 'Blues'

Its time to plot a pdf and save the config

view.plot_pdf('Nice_unmodified.pdf')
view.save_config('Nice_unmodified.cv2d')

Note: Have a look at the plain text Nice_unmodified.cv2d. The config is just read as a dict. If you modify this file, changes get applied accordingly upon calling load_config if you do not misspell parameter names or options.

If you want to reuse the config next time, just use it upon initialization of the view:

view = cv2d.View(original_data, cfgfile='Nice_unmodified.cv2d')

We realize that there is some (unphysical :) noise in the data. Nicyness does not fluctuate so much along foo or bar and our cheap nice-intstrument produced some additional fluctuations.

view.add_Smooth(1, 1)

This call is a shortcut to view.add_mod('Smooth', (1, 1)). Note that all mods found in the colorview2d/mods folder can be called by add_<Modname>(arg1, arg2, ...). Now we are interested more in the change of our nice landscape and not in its absolute values so we derive along the bar axis

view.add_Derive()

Have a look at the mods/ folder for other mods and documentation on the arguments. It is also straightforward to create your own mod there. Just have a look at the other mods in the folder.

We are interested especially in the nicyness between 0.0 and 0.1.

view.config.update({'Cbmin':0.0, 'Cbmax':0.1})

Alternatively, just use the slider in the second matplotlib figure to control the colorbar limits.

To re-use this data later (without having to invoke colorview2d again), we can store the data to a gnuplot-style plain text file.

colorview2d.fileloaders.save_gpfile('Nice_smooth_and_derived.dat', view.data)

Extending colorview2d

fileloaders

Have a look at the colorview2d.Data definition in the :module:`colorview2d.data` module. To create Data we have to provide the 2d array and the bounds of the y and x ranges.

data = colorview2d.Data(
    array,
    ((bottom_on_y_axis, top_on_y_axis),
    (left_on_x_axis, right_on_x_axis)))

To save data, just use the Data attributes, e.g.

my_array = my_view.data.zdata # 2d numpy.array
my_x_range = my_view.data.x_range # 1d numpy.array (left-to-right)
my_y_range = my_view.data.y_range # 1d numpy.array (bottom-to-top)

mods

If you want to apply your own modifications to the data, just put a module inside the colorview2d/mods directory (or package, if you wish). The module should contain a class (with the class name becoming the name of the mod) which inherits from colorview2d.IMod and implements the method do_apply(self, data, modargs).

This method is also the right place to document your mods usage, i.e., the required arguments. The docstring of <Modname>.do_apply, where <Modname> is the class’s name, is displayed when you call

help(view.add_<Modname>())

In do_apply(self, data, modargs) you can modifiy the datafile freely, there is no error-checking done on the consistency of the data (axes bounds, dimensions). Have a look at the mods/Derive.py module for a minimal example.

To see if your mod is added successfully, have a look at my_view.modlist.

6.10.2015, A. Dirnaichner

colorview2d classes

View: A colored 2d View on Data.

class colorview2d.View(data=None, cfgfile=None, config=None, pipeline=None)[source]

A class to handle a 2d numpy.ndarray with (linearly scaled) _axes, apply a (extendable) range of filters (mods) to the data while keeping track of the modifications.

Hosts a matplotlib.pyplot.Figure of the data. Customization of this figure is simplified with respect to the matplotlib library. Provides interactive colorbar controls.

Undocumented methods:
 

The class provides methods that are not documented because they are generated on-init.

  • add_<Modname>(arg1, ...) and rm_<Modname>().

    There is one such method for each mod in modlist. This simplfies calls add_mod(<Modname>, (arg1, ...)).

  • set_<Parametername>(Parameter) as shortcut to

    View.config[<Parametername>] = Parameter.
Example: 
data = colroview2d.Data(np.random.random((100, 100)))
fig = colorview2d.View(data)
fig.add_Smooth(2, 2)
fig.plot_pdf('Test.pdf')
modlist

A (autogenerated) list of all mods that can be found in the mods/ subfolder.

data

A colorview2d.Data. It encapsulates the 2d data.

config

Holds information on the plot layout, ticks, fonts etc. Can be accessed via myview.set_<Parametername>(<Parameter>) and in a dict-like fashion myview.config['Parametername'] = <Parameter>. Also an config.update(dict) function is available. The attribute is initialized with a fixed set of parameters read from default.cv2d config file in the package directory.

Important: Does not fully implement a dictionary interface.

update(dict)

update the configuration with a dictionary containing valid parameters. Note that the plot, if there is any, is updated when the config is changed via update

update_raw(dict)

update the configuration without updating any existing plot.

fig

The matplotlib.pyplot.figure.

pipeline

A dictionary with mod identifiers (strings) and their arguments (tuples).

plotting

Boolean. Are we showing any plot at the moment?

show_plt_fig()[source]

Show two interactive matplotlib.pyplot.Figure plots. The first displays the data with config and pipeline applied. The second provides two matplotlib slider widgets to control the limits of the colorbar interactively and a Reset button to apply the default (full-range) colorbar limits.

hide_plt_fig()[source]

Hide the interactive matplotlib.pyplot.Figure.

add_mod(modname, modargs=(), pos=-1, do_apply=True)[source]

Add a mod to the pipeline by its title string and its arguments either to the end of the pipeline or at a specified postion.

Parameters:
  • modname (string) – The type of the mod.
  • modargs (tuple) – A tuple containing the arguments of the mod.
  • pos (int) – Where to add the mod in the pipeline. Default is last.
  • do_apply (boolean) – Trigger modification of the data (True) or just add mod to the pipeline.
remove_mod(modtype=None, pos=-1, do_apply=True)[source]

Removes the last mod from the pipeline, or the mod at position pos or the last mod in the pipeline with the type modtype.

Parameters:
  • modtype (string) – The identifier of the mod type.
  • pos (int) – The position of the mod in the pipeline.
  • do_apply (bool) – Is the pipeline applied after the element is removed?
clear_pipeline()[source]

Clear the pipeline and update the plot.

get_arraydata()[source]

Shortcut for the 2d data contained int the data.

Returns:2d numpy.ndarray
replace_data(newdata)[source]

Replace the data.

In contrast to calling myview.data = newdata, the method replace_data also replaces the copy of the raw data.

Warning: Some modifications may not be applicable to the new data.

Parameters:newdata (colorview2d.Data) – the new data.
load_config(cfgpath)[source]

Load the configuration and the pipeline from a config file specified in the YAML format.

Parameters:cfgpath (string) – The path to a cv2d configuration file.
save_config(cfgpath)[source]

Save the configuration and the pipeline to a config file.

Parameters:cfgpath (string) – the path to the config file
plot_pdf(filename)[source]

Redraw the figure and plot it to a pdf file.

draw_plot()[source]

(Re-)draw the matplotlib.pyplot.figure.

This method is intended to be used directly when you are only interested in the figure object itself which can be obtained by myview.fig attribute.

It includes an axes object containing the (imshow generated) 2d color plot with labels, ticks and colorbar as specified in the config dictionary.

Data: A container for the array and the axes bounds.

class colorview2d.Data(data, range_bounds=None)[source]

Data hosts, well, the data and its axes.

Data is stored in a 2d numpy-ndarray. For the axes, only the bounds are stored. We assume linear scaling of the axes. If no bounds are specified, we use (0, n) as boundaries, n being the number of rows and columns, respectively.

xleft

Right boundary value of the x-axis.

xright

Left boundary value of the x-axis.

xmin

Minimum value of the x-axis range.

xmax

Maximum value of the x-axis range.

dx

Spacing of x-axis values.

ytop

Top boundary value of the y-axis.

ybottom

Bottom boundary value of the y-axis.

ymin

Minimum value of the y-axis range.

ymax

Maximum value of the y-axis range.

dy

Spacing of y-axis values.

zmin

Minimum value of the 2d numpy.ndarray.

zmax

Maximum value of the 2d numpy.ndarray.

xwidth

Size of the array along the x-axis.

ywidth

Size of the array along the y-axis.

zdata

2d numpy.ndarray.

y_range

A linear y-range array.

x_range

A linear x-range array.

xrange_bounds

Boundary values on the x-axis as a tuple (left, right).

yrange_bounds

Boundary values on the y-axis as a tuple (bottom, top).

report()[source]

Print a data report to the standart output.

deep_copy()[source]

Deep copy the colorview2d.Data object and return the copy.

Returns:A copy of the Colorview2d.Data instance.
rotate_cw()[source]

Rotate the data clockwise. The axes are updated as well.

rotate_ccw()[source]

Rotate the data counter-clockwise. The axes are updated as well.

flip_lr()[source]

Flip the left and the right side of the data. The axes are updated as well.

flip_ud()[source]

Flip the up and the down side of the data. The axes are updated as well.

is_within_xbounds(val)[source]

Check if the given value is within the xrange.

Returns:a boolean.
is_within_ybounds(val)[source]

Check if the given value is within the yrange.

Returns:a boolean.
is_within_bounds(coordinate)[source]

Check if the given coordinate (y, x) is within the ranges of the axes.

Returns:a boolean.
crop(boundaries)[source]

Crop the data to a subset of the array specifiying the corners of the subset in units of the axes ranges.

Parameters:boundaries (tuple) – (bottom boundary, top boundary, left boundary, right boundary)
x_range_idx_by_val(value)[source]

Return the nearest index of a value within the x axis range.

Parameters:value – A value in the range of the x axis
Returns:The closest index on the x axis range.
y_range_idx_by_val(value)[source]

Return the nearest index of a value within the y axis range.

Parameters:value – A value in the range of the y axis
Returns:The closest index on the y axis range.
idx_by_val_coordinate(coordinate)[source]

Return the nearest index pair for a coordinate pair (y, x) along the two axes.

Parameters:coordinate (tuple) – y-axis value, x-axis value (inverse order!)
Returns:(y-axis index, x-axis index) – both integer
extract_ylinetrace(xval, ystartval, ystopval)[source]

Extract a linetrace along a given y-axis range vor a specific value on the x axis.

Parameters:
  • xval (float) – Position of the linecut along the x-axis.
  • ystartval (float) – First and ...
  • ystopval (float) – last value of the range along the y-axis.
Returns:

numpy array with two rows [0] linecutdata [1] y-axis range
extract_xlinetrace(yval, xstartval, xstopval)[source]

Extract a linetrace along a given y-axis range vor a specific value on the x axis.

Parameters:
  • yval (float) – Position of the linecut along the y-axis.
  • xstartval (float) – Start and ...
  • xstopval (float) – stop value of the range along the x-axis.
Returns:

numpy array with two rows [0] linecutdata [1] x-axis range
extract_ylinetrace_series(x_first, x_last, x_interval, ystart, ystop)[source]

Extract linetraces along a given y-axis range for values on the x axis within a given range and separated by a given interval.

Parameters:
  • x_first (float) – value on the x-axis for the first line trace in the series.
  • x_last (float) – value on the x-axis for the last line trace in the series.
  • x_interval (float) – the (positive) interval between two linecuts on the x-axis.
  • ystart (float) – Start and ...
  • ystop (float) – stop value of the range along the y-axis.
Returns:

a numpy array with n + 1 rows with the length equal to the y-dimensions of zdata. n is the number of linecuts, i.e., abs(x_last - x_first) / x_interval. The last row contains the y-axis range.
extract_xlinetrace_series(y_first, y_last, y_interval, xstart, xstop)[source]

Extract linetraces along a given x-axis range for values on the y axis within a given range and separated by a given interval.

Parameters:
  • y_first (float) – value on the y-axis for the first line trace in the series.
  • y_last (float) – value on the y-axis for the last line trace in the series.
  • y_interval (float) – the (positive) interval between two linecuts on the y-axis.
  • xstart (float) – Start and ...
  • xstop (float) – stop value of the range along the x-axis.
Returns:

a numpy array with n + 1 rows with the length equal to the x-dimensions of zdata. n is the number of linecuts, i.e., abs(y_last - y_first) / y_interval. The last row contains the x-axis range.
extract_arbitrary_linetrace(coordinate_one, coordinate_two)[source]

Extract a linetrace between two arbitrary points.

Parameters:
  • coordinate_one (tuple) – coordinate in the coordinate system of the axis. The order is (yval, xval)!
  • coordinate_two (tuple) – coordinates in the coordinate system of the x and y axes. The order is (yval, xval)!
Returns:

Array with the linetrace. No axis range is supplied since it does not make sense along any arbitrary direction.
resize(new_ywidth, new_xwidth, order=1)[source]

Interpolate the array to a new, larger size.

Uses scipy.misc.imresize. The ranges are interpolated accordingly.

Parameters:
  • new_ywidth (int) – new dimensions along the y-axis.
  • new_xwidth (int) – new dimensions along the x-axis.
  • order (int) – order of the interpolation. See scipy.misc.imresize()

Configuration

The colorview2d.View class has a config attribute. The parameters stored in its dictionary are read from colorview2d/default.cv2d config file.

# Config file for colorview2d (YAML)
---
# Default colormap
# Print a list of available fonts with colorview2d.utils.colormaplist()
Colormap: jet
# Minimum and maximum for the colorbar
Cbmin: auto
Cbmax: auto

# Labels for the x- and y-axis
Xlabel: x-axis
Ylabel: y-axis
# Label for the colorbar
Cblabel: colorscale

# Format of ticklabels
# Use c-style printf format
# e.g. %.2f for two digits after the point
Xtickformat: auto
Ytickformat: auto
Cbtickformat: auto

# Fontstyle and size
# Print a list of available fonts with colorview2d.utils.fontlist()
Font:  default
Fontsize: 12

# Ticksize for x- and y-axis
Xticklength: 4
Yticklength: 4
# Linewidth of lines that are drawn in the plot
Linewidth: 1

# Default Size of the plot and dpi
# Note that these are *only* applied when the plot is printed to pdf.
Width: 8
Height: 6
Dpi: 80

Indices and tables