fsleyes.plotting.histogramseries

This module provides the HistogramSeries,

ImageHistogramSeries, ComplexHistogramSeries, and MeshHistogramSeries classes, used by the HistogramPanel for plotting histogram data.

Two standalone functions are also defined in this module:

histogram	Calculates a histogram of the given data.
autoBin	Calculates the number of bins which should be used for a histogram of the given data.

class fsleyes.plotting.histogramseries.HistogramSeries(overlay, overlayList, displayCtx, plotCanvas)

Bases: fsleyes.plotting.dataseries.DataSeries

A HistogramSeries generates histogram data from an overlay. It is the base class for the ImageHistogramSeriess and MeshHistogramSeries classes.

nbins = <MagicMock name='mock.Int()' id='4116300320'>

Number of bins to use in the histogram. This value is overridden by the autoBin setting.

autoBin = <MagicMock name='mock.Boolean()' id='4117273880'>

If True, the number of bins used for each HistogramSeries is calculated automatically. Otherwise, HistogramSeries.nbins bins are used.

ignoreZeros = <MagicMock name='mock.Boolean()' id='4117273880'>

If True, zeros are excluded from the calculated histogram.

includeOutliers = <MagicMock name='mock.Boolean()' id='4117273880'>

If True, values which are outside of the dataRange are included in the histogram end bins.

dataRange = <MagicMock name='mock.Bounds()' id='4116394552'>

Specifies the range of data which should be included in the histogram. See the includeOutliers property.

__init__(overlay, overlayList, displayCtx, plotCanvas)

Create a HistogramSeries.

Parameters

• overlay – The overlay from which the data to be plotted is retrieved.

• overlayList – The OverlayList instance.

• displayCtx – The DisplayContext instance.

• plotCanvas – The HistogramPanel that owns this HistogramSeries.

destroy()

This needs to be called when this HistogramSeries instance is no longer being used.

setHistogramData(data, key)

Must be called by sub-classes whenever the underlying histogram data changes.

Parameters

• data – A numpy array containing the data that the histogram is to be calculated on. Pass in None to indicate that there is currently no histogram data.

• key – Something which identifies the data, and can be used as a dict key.

onDataRangeChange()

May be implemented by sub-classes. Is called when the dataRange changes.

getData()

Overrides DataSeries.getData().

Returns a tuple containing the (x, y) histogram data.

property binWidth

Returns the width of one bin for this HistogramSeries.

getVertexData()

Returns a numpy array of shape (N, 2), which contains a set of “vertices” which can be used to display the histogram data as a filled polygon.

property numHistogramValues

Returns the number of values which were used in calculating the histogram.

__dataRangeChanged(*args, **kwargs)

Called when the dataRange property changes, and also by the __initProperties() and __volumeChanged() methods.

__histPropsChanged(*a)

Called internally, and when any histogram settings change. Re-calculates the histogram data.

__module__ = 'fsleyes.plotting.histogramseries'

class fsleyes.plotting.histogramseries.ImageHistogramSeries(*args, **kwargs)

Bases: fsleyes.plotting.histogramseries.HistogramSeries

An ImageHistogramSeries instance manages generation of histogram data for an Image overlay.

showOverlay = <MagicMock name='mock.Boolean()' id='4117273880'>

If True, a mask ProxyImage overlay is added to the OverlayList, which highlights the voxels that have been included in the histogram. The mask image is managed by the HistogramProfile instance, which manages histogram plot interaction.

showOverlayRange = <MagicMock name='mock.Bounds()' id='4116394552'>

Data range to display with the showOverlay mask.

__init__(*args, **kwargs)

Create an ImageHistogramSeries. All arguments are passed through to HistogramSeries.__init__().

destroy()

Must be called when this ImageHistogramSeries is no longer needed. Removes some property listeners, and calls HistogramSeries.destroy().

redrawProperties()

Overrides DataSeries.redrawProperties(). The HistogramSeries data does not need to be re-plotted when the showOverlay or showOverlayRange properties change.

onDataRangeChange()

Overrides HistogramSeries.onDataRangeChange(). Makes sure that the showOverlayRange limits are synced to the HistogramSeries.dataRange.

__volumeChanged(*args, **kwargs)

Called when the volume property changes, and also by the __init__() method.

Passes the data to the HistogramSeries.setHistogramData() method.

__overlayTypeChanged(*a)

Called when the Display.overlayType changes. When this happens, the DisplayOpts instance associated with the overlay gets destroyed and recreated. This method de-registers and re-registers property listeners as needed.

__module__ = 'fsleyes.plotting.histogramseries'

class fsleyes.plotting.histogramseries.ComplexHistogramSeries(*args, **kwargs)

Bases: fsleyes.plotting.histogramseries.ImageHistogramSeries

Thre ComplexHistogramSeries class is a specialisation of the ImageHistogramSeries for images with a complex data type.

See also the ComplexTimeSeries and ComplexPowerSpectrumSeries classes.

plotReal = <MagicMock name='mock.Boolean()' id='4117273880'>

plotImaginary = <MagicMock name='mock.Boolean()' id='4117273880'>

plotMagnitude = <MagicMock name='mock.Boolean()' id='4117273880'>

plotPhase = <MagicMock name='mock.Boolean()' id='4117273880'>

__init__(*args, **kwargs)

Create a ComplexHistogramSeries. All arguments are passed through to the ImageHistogramSeries constructor.

extraSeries()

Returns a list containing an ImaginaryHistogramSeries, MagnitudeHistogramSeries, and/or PhaseHistogramSeries, depending on the values of the plotImaginary, plotMagnitude, and plotPhase properties.

getData()

Overrides HistogramSeries.setHistogramData(). If plotReal is False, returns (None, None). Otherwise returns the parent class implementation.

setHistogramData(data, key)

Overrides HistogramSeries.setHistogramData(). The real component of the data is passed to the parent class implementation.

__module__ = 'fsleyes.plotting.histogramseries'

class fsleyes.plotting.histogramseries.ImaginaryHistogramSeries(*args, **kwargs)

Bases: fsleyes.plotting.histogramseries.ImageHistogramSeries

Class which plots the histogram of the imaginary component of a complex-valued image.

setHistogramData(data, key)

Must be called by sub-classes whenever the underlying histogram data changes.

Parameters

• data – A numpy array containing the data that the histogram is to be calculated on. Pass in None to indicate that there is currently no histogram data.

• key – Something which identifies the data, and can be used as a dict key.

__module__ = 'fsleyes.plotting.histogramseries'

class fsleyes.plotting.histogramseries.MagnitudeHistogramSeries(*args, **kwargs)

Bases: fsleyes.plotting.histogramseries.ImageHistogramSeries

Class which plots the histogram of the magnitude of a complex-valued image.

setHistogramData(data, key)

Must be called by sub-classes whenever the underlying histogram data changes.

Parameters

• data – A numpy array containing the data that the histogram is to be calculated on. Pass in None to indicate that there is currently no histogram data.

• key – Something which identifies the data, and can be used as a dict key.

__module__ = 'fsleyes.plotting.histogramseries'

class fsleyes.plotting.histogramseries.PhaseHistogramSeries(*args, **kwargs)

Bases: fsleyes.plotting.histogramseries.ImageHistogramSeries

Class which plots the histogram of the phase of a complex-valued image.

setHistogramData(data, key)

Must be called by sub-classes whenever the underlying histogram data changes.

Parameters

• data – A numpy array containing the data that the histogram is to be calculated on. Pass in None to indicate that there is currently no histogram data.

• key – Something which identifies the data, and can be used as a dict key.

__module__ = 'fsleyes.plotting.histogramseries'

class fsleyes.plotting.histogramseries.MeshHistogramSeries(*args, **kwargs)

Bases: fsleyes.plotting.histogramseries.HistogramSeries

A MeshHistogramSeries instance manages generation of histogram data for a Mesh overlay.

__module__ = 'fsleyes.plotting.histogramseries'

__init__(*args, **kwargs)

Create a MeshHistogramSeries. All arguments are passed through to HistogramSeries.__init__().

destroy()

Must be called when this MeshHistogramSeries is no longer needed. Calls HistogramSeries.destroy() and removes some property listeners.

__vertexDataChanged(*a)

Called when the MeshOpts.vertexData or MeshOpts.vertexDataIndex properties change. Updates the histogram data via HistogramSeries.setHistogramData().

fsleyes.plotting.histogramseries.histogram(data, nbins, histRange, dataRange, includeOutliers=False, count=True)

Calculates a histogram of the given data.

Parameters

• data – The data to calculate a histogram foe

• nbins – Number of bins to use

• histRange – Tuple containing the (low, high) data range that the histogram is to be calculated on.

• dataRange – Tuple containing the (min, max) range of values in the data

• includeOutliers – If True, the outermost bins will contain counts for values which are outside the histRange. Defaults to False.

• count – If True (the default), the raw histogram counts are returned. Otherwise they are converted into probabilities.

Returns

A tuple containing:

• The x histogram data (bin edges)

• The y histogram data

• The total number of values that were used in the histogram calculation

fsleyes.plotting.histogramseries.autoBin(data, dataRange)

Calculates the number of bins which should be used for a histogram of the given data. The calculation is identical to that implemented in the original FSLView.

Parameters

• data – The data that the histogram is to be calculated on.

• dataRange – A tuple containing the (min, max) histogram range.