Class Histogram

Object
UIObject
Widget
Composite
AbstractView<HistoGraph>
Histogram
All Implemented Interfaces:
HasAttachHandlers, HasHandlers, EventListener, HasVisibility, IsRenderable, IsWidget, ProvidesResize, RequiresResize, ChangeListener, LifecycleListener, RunListener, SampleListener
public class Histogram extends AbstractView<HistoGraph>
Histogram view for displaying binned distributions of model quantities.

This class implements a graphical view that manages one or more HistoGraph instances to display histograms for different types of data produced by the simulation model. The view supports a variety of Data types:

  • TRAIT - histograms of continuous trait distributions (uses CModel APIs)
  • FITNESS - histograms of fitness/payoff values (continuous or discrete)
  • DEGREE - degree distributions of interaction and competition graphs
  • STATISTICS_FIXATION_PROBABILITY - per-node fixation probability samples
  • STATISTICS_FIXATION_TIME - fixation time samples and absorption times
  • STATISTICS_STATIONARY - stationary distributions / visit-count histograms

Responsibilities

  • Allocate and layout the required number of HistoGraph panels for each module and data type, taking into account multi-species modules and module-specific settings (traits, vacant indices, population size, etc.).
  • Configure default and data-specific GraphStyle settings (axis labels, normalization, color, autoscaling, custom y-levels).
  • Manage histogram buffers and binning parameters (bin size, scale factors, max bins) and ensure data arrays are allocated with proper dimensions.
  • Periodically update histogram contents by querying the underlying model (e.g., fetching trait/fitness/degree histogram data, mean traits for stationary statistics, fixation sample callbacks).
  • Handle special cases such as PDE/DE/ODE/SDE models and well-mixed populations (display messages instead of histograms where appropriate).
  • Support context menu actions and export types appropriate for the chosen Data type (SVG/PNG and CSV for statistics).

Lifecycle

  • The view is constructed with an EvoLudoGWT engine and a Data type indicating which histogram to display.
  • load() registers listeners for statistical sample events when displaying fixation statistics.
  • allocateGraphs() is responsible for creating HistoGraph instances based on the currently configured modules; it avoids unnecessary rebuilds by comparing required and existing graph counts.
  • reset(boolean) recomputes graph-specific configuration (axis ranges, markers, normalization flags) and may force a full repaint when axis limits change. It delegates type-specific reset logic to helper methods (resetTrait, resetFitness, resetDegree, resetFixationProbability, resetFixationTime, resetStationary).
  • update(boolean) pulls fresh histogram data from the model and triggers painting of all graphs. For performance, updates are skipped when the view is inactive for dynamic data.
  • modelSample(boolean) receives fixation-sample callbacks and increments the appropriate histogram bins; it also handles per-sample bookkeeping to avoid double-counting.
  • modelSettings() and modelDidInit() are used to reapply module-specific settings and to initialize HistoGraph objects after model initialization.

Implementation details

  • scale2bins and binSize are used to map model values (counts, densities, or node indices) to histogram bins. Their values depend on the Data type and the population/graph size.
  • For stationary and fixation statistics the view chooses a sensible bin count that honors HistoGraph.MAX_BINS and per-graph max bin limits.
  • For degree distributions, the view computes a displayable maximum degree with maxDegree(int) (rounding up to human-friendly magnitudes) and limits the resulting bin count to HistoGraph.MAX_BINS.
  • Directed graphs create separate histograms for in-degree, out-degree, and total degree. When interaction and competition geometries differ, histograms are created for both structures.
  • For PDE/DE model types that are regular or lattice-like the view may display a short explanatory message instead of a histogram.
  • The class caches whether degree distributions have been processed and re-computes them only when geometries are dynamic or when not yet processed.
  • Frequent status calculations and graph paints are throttled to avoid excessive CPU usage (see MIN_MSEC_BETWEEN_UPDATES and timestamp checks).

Fixation statistics

  • For STATISTICS_FIXATION_PROBABILITY the view accumulates counts per node (possibly binned) and reports normalized probabilities in the y-axis.
  • For STATISTICS_FIXATION_TIME the view supports two modes:
    • a per-node fixation time histogram (node index on x-axis and average/weighted time in y), or
    • a distribution of fixation times aggregated across nodes (binned times on x-axis).
  • A special absorption histogram collects fixation times irrespective of initial node (displayed as an extra graph when applicable).
  • The view produces human-readable status strings that summarize average fixation probability and fixation time statistics for display in the UI.

Export and context menu

  • Depending on the Data type, export formats include SVG and PNG for all histograms, and CSV (tabular statistical data) for statistical views.
  • The context menu includes a Clear action for STATISTICS_STATIONARY to reset accumulated stationary counts.
Author:
Christoph Hauert
See Also:

  • Field Details

    • scale2bins

      double scale2bins
      The scaling factor to map the data onto bins.

    • binSize

      int binSize
      The size of the bins in pixels.

    • isMultispecies

      protected boolean isMultispecies
      Flag to indicate whether the model entertains multiple species, i.e. nSpecies&gt;1. Convenience field. Reduces calls to Module.

    • degreeProcessed

      protected boolean degreeProcessed
      The flag to indicate whether the properties of the gemetric structure have been processed.

    • status

      protected String status
      The status of the view.

    • clearMenu

      private ContextMenuItem clearMenu
      The clear context menu.

  • Constructor Details

    • Histogram

      public Histogram(EvoLudoGWT engine, Data type)
      Construct a new view to display the histogram of various quantities.
      Parameters:
      engine - the pacemaker for running the model
      type - the type of data to display

  • Method Details

    • load

      public boolean load()
      Description copied from class: AbstractView
      Load the view. This is called for modules and models that implement this view. This is called early on when initializing the view and is independent of the activation of the view.
      Overrides:
      load in class AbstractView<HistoGraph>
      Returns:
      true if view had not been loaded
      See Also:

    • getMode

      public Mode getMode()
      Description copied from class: AbstractView
      Get the mode required by this view.
      Overrides:
      getMode in class AbstractView<HistoGraph>
      Returns:
      the mode required by this view

    • getName

      public String getName()
      Description copied from class: AbstractView
      Get the name of this view. This is used to dynamically build the view selector.
      Specified by:
      getName in class AbstractView<HistoGraph>
      Returns:
      the name of this view

    • allocateGraphs

      protected boolean allocateGraphs()
      Description copied from class: AbstractView
      Allocate all graphs managed by this view. This is called when loading the view. Once all views are attached to the browser DOM a call to the graph's calcBounds(int, int) is triggered through setBounds(int, int) to properly calculate the layout.
      Specified by:
      allocateGraphs in class AbstractView<HistoGraph>
      Returns:
      true if graphs were (re)allocated
      See Also:

    • countGraphs

      private int countGraphs()
      Count how many graphs are required based on current Data type and module settings.
      Returns:
      number of histogram panels required

    • createGraphs

      private int createGraphs(int nGraphs)
      Create and configure graphs for all species; returns the number of x-label rows that should be considered when computing layout.
      Parameters:
      nGraphs - total number of graphs to create across species
      Returns:
      the number of x-label rows created

    • addTraitGraphs

      private int addTraitGraphs(List<? extends Module<?>> species)
      Add trait histogram for the given module. Makes sense only for modules with continuous traits.
      Parameters:
      species - the list of modules to consider
      Returns:
      the number of x-label rows added

    • addFitnessGraphs

      private int addFitnessGraphs(List<? extends Module<?>> species, int nGraphs)
      Add fitness graphs for the given module.
      Parameters:
      species - the list of modules to consider
      nGraphs - total number of graphs being created
      Returns:
      the number of x-label rows added

    • addDegreeGraphs

      private int addDegreeGraphs(List<? extends Module<?>> species, int nGraphs)
      Add degree graphs for the given module.
      Parameters:
      species - the list of modules to consider
      nGraphs - total number of graphs being created
      Returns:
      the number of x-label rows added

    • addFixationProbabilityGraphs

      private int addFixationProbabilityGraphs(List<? extends Module<?>> species, int nGraphs)
      Add fixation probability graphs for the given module.
      Parameters:
      species - the list of modules to consider
      nGraphs - total number of graphs being created
      Returns:
      the number of x-label rows added

    • addFixationTimeGraphs

      private int addFixationTimeGraphs(List<? extends Module<?>> species, int nGraphs)
      Add fixation time graphs for the given module.
      Parameters:
      species - the list of modules to consider
      nGraphs - total number of graphs being created
      Returns:
      the number of x-label rows added

    • addStationaryGraphs

      private int addStationaryGraphs(List<? extends Module<?>> species, int nGraphs)
      Add stationary distribution graphs for the given module.
      Parameters:
      species - the list of modules to consider
      nGraphs - total number of graphs being created
      Returns:
      the number of x-label rows added

    • applyDefaultStyle

      private void applyDefaultStyle(GraphStyle style)
      Apply default style settings to the given graph style.
      Parameters:
      style - the graph style to modify

    • applyTraitStyle

      private boolean applyTraitStyle(HistoGraph graph, int n)
      Apply style settings for trait histograms.
      Parameters:
      graph - the graph to style
      n - the index of the graph
      Returns:
      true if hard reset is required

    • applyFitnessStyle

      private boolean applyFitnessStyle(HistoGraph graph, int n, int xdeco)
      Apply style settings for fitness histograms. The x-axis decorations are determined by the xdeco parameter: 0 no decorations, 1 tick labels only, 2 x-label and tick labels.
      Parameters:
      graph - the graph to style
      n - the index of the graph
      xdeco - specify x-axis decorations
      Returns:
      true if hard reset is required

    • applyDegreeStyle

      private void applyDegreeStyle(HistoGraph graph, int n, int nGraphs, int xdeco)
      Apply style settings for degree histograms.
      Parameters:
      graph - the graph to style
      n - the index of the graph
      nGraphs - the total number of graphs
      xdeco - decoration level: 0 none, 1 show tick labels, 2 show labels

    • applyFixationProbabilityStyle

      private void applyFixationProbabilityStyle(HistoGraph graph, int n, int xdeco)
      Apply style settings for fixation probability histograms.
      Parameters:
      graph - the graph to style
      n - the index of the graph
      xdeco - decoration level: 0 none, 1 show tick labels, 2 show labels

    • applyFixationTimeStyle

      private void applyFixationTimeStyle(HistoGraph graph, int n, int xdeco, boolean isDistribution)
      Apply style settings for fixation time histograms.
      Parameters:
      graph - the graph to style
      n - the index of the graph
      xdeco - decoration level: 0 none, 1 show tick labels, 2 show labels
      isDistribution - true when plotting fixation-time distributions

    • applyStationaryStyle

      private void applyStationaryStyle(HistoGraph graph, int n, int xdeco)
      Apply style settings for stationary distribution histograms.
      Parameters:
      graph - the graph to style
      n - the index of the graph
      xdeco - decoration level: 0 none, 1 show tick labels, 2 show labels

    • reset

      public void reset(boolean hard)
      Description copied from class: AbstractView
      Called when a module has been reset. All graphs are reset and updated if needed, unless hard is true.
      Overrides:
      reset in class AbstractView<HistoGraph>
      Parameters:
      hard - the flag to indicate whether to do a hard reset

    • resetTraitGraphs

      private boolean resetTraitGraphs()
      Reset trait graphs.
      Returns:
      true if hard reset is required

    • resetFitnessGraphs

      private boolean resetFitnessGraphs()
      Reset fitness graphs.
      Returns:
      true if hard reset is required

    • resetDegreeGraphs

      private void resetDegreeGraphs()
      Reset degree graphs.

    • resetFixationProbabilityGraphs

      private void resetFixationProbabilityGraphs()
      Reset fixation probability graphs.

    • resetFixationTimeGraphs

      private void resetFixationTimeGraphs()
      Reset fixation time graphs. Depending on the population size either the fixation times are show for each node or as a distribution.

    • resetStationaryGraphs

      private void resetStationaryGraphs()
      Reset stationary distribution graphs.

    • modelSettings

      public void modelSettings()
      Description copied from interface: RunListener
      Called when the settings of the EvoLudo model changed but no reset was necessary.

    • modelDidInit

      public void modelDidInit()
      Description copied from interface: RunListener
      Called after the EvoLudo model got re-initialized.
      Specified by:
      modelDidInit in interface RunListener
      Overrides:
      modelDidInit in class AbstractView<HistoGraph>

    • modelSample

      public void modelSample(boolean success)
      Description copied from interface: SampleListener
      Called whenever the EvoLudo model finished generating a statistics sample.
      Parameters:
      success - indicates whether the sampling was successful.

    • update

      public void update(boolean force)
      Description copied from class: AbstractView
      Called when the view needs updating. This gets called when the selected view changed or new data is available from the model. Views may ignore updating requests unless force is true.
      Specified by:
      update in class AbstractView<HistoGraph>
      Parameters:
      force - true to force the update

    • updateTrait

      private void updateTrait()
      Update trait histograms (continuous models).

    • updateFitness

      private void updateFitness()
      Update fitness histograms.

    • updateDegree

      private void updateDegree()
      Update degree histograms, delegating to getDegreeHistogramData where needed.

    • handleDEGraph

      private boolean handleDEGraph(HistoGraph graph, ModelType mt, Module<?> module)
      Handle messaging for DE/PDE models; returns true if a message was set on the graph and further processing should be skipped.
      Parameters:
      graph - target histogram
      mt - current model type
      module - module owning the histogram
      Returns:
      true if the graph now displays a message

    • ensureDegreeData

      private double[][] ensureDegreeData(HistoGraph graph, AbstractGeometry inter, AbstractGeometry comp, double[][] data)
      Ensure the provided data buffer is sized appropriately for the given interaction/competition geometries, update the histogram data and set axis limits on the graph; returns the (possibly new) data buffer.
      Parameters:
      graph - target histogram
      inter - interaction geometry
      comp - competition geometry
      data - current data buffer
      Returns:
      data buffer ready to be reused by the histogram

    • updateStationary

      private void updateStationary()
      Update stationary statistics histograms.

    • doFixtimeDistr

      private boolean doFixtimeDistr(Module<?> module)
      Helper method to check whether to show the fixation time distribution or the fixation times for each node.
      Parameters:
      module - the module of the graph
      Returns:
      true to show the fixation time distribution

    • getStatus

      public String getStatus(boolean force)
      Description copied from class: AbstractView
      Get the status of this view. Views that aggregate data may want to provide custom status information. HTML formatting is acceptable. Some status updates may be expensive to compute and views may decide to ignore the getStatus request, except if force is true.
      Overrides:
      getStatus in class AbstractView<HistoGraph>
      Parameters:
      force - whether to force an update of the status
      Returns:
      the status of this view

    • getFixationProbabilityStatus

      private String getFixationProbabilityStatus()
      Build status string for fixation probabilities.
      Returns:
      formatted status text

    • getFixationTimeStatus

      private String getFixationTimeStatus()
      Build status string for fixation times.
      Returns:
      formatted status text

    • formatDistributionMean

      private String formatDistributionMean(double[] dist, GraphStyle style)
      Format mean ± sdev for a distribution stored in data (assumed normalized counts).
      Parameters:
      dist - the distribution data
      style - the graph style for scaling
      Returns:
      the formatted string

    • formatWeightedMean

      private String formatWeightedMean(double[] dat, double[] sam)
      Compute weighted mean ± sdev from node-wise times (dat) and sample counts (sam).
      Parameters:
      dat - the data array
      sam - the sample counts
      Returns:
      the formatted string

    • maxDegree

      private static int maxDegree(int max)
      Calculate the maximum degree for displaying the degree distribution. This rounds max up to 10, 20, 50, 100, 200, 500, 1000 etc.
      Parameters:
      max - the maximum degree of the graph
      Returns:
      the maximum degree to display

    • getDegreeHistogramData

      private void getDegreeHistogramData(double[][] data, AbstractGeometry inter, AbstractGeometry comp)
      Generate the degree histogram data for the given interaction and competition geometries.
      Parameters:
      data - the data array for storing the histograms
      inter - the interaction graph
      comp - the competition graph

    • getDegreeHistogramData

      private void getDegreeHistogramData(double[][] data, AbstractGeometry geometry, int idx, double ibinwidth)
      Generate the degree histogram data for the given geometry.
      Parameters:
      data - the data array for storing the histograms
      geometry - the interaction graph
      idx - the index for placing the histogram data
      ibinwidth - the scaling factor to map degrees to bins

    • getDegreeGraphs

      private int getDegreeGraphs(AbstractGeometry inter, AbstractGeometry comp)
      Determine the number of histograms required for the degree distributions of the interaction and competition geometries.
      Parameters:
      inter - the interaction geometry
      comp - the competition geometry
      Returns:
      the number of histograms required

    • getDegreeBins

      private int getDegreeBins(AbstractGeometry inter, AbstractGeometry comp)
      Determine the number of bins required for the degree distributions of the interaction and competition geometries.
      Parameters:
      inter - the interaction geometry
      comp - the competition geometry
      Returns:
      the number of histograms required

    • getDegreeLabels

      private String[] getDegreeLabels(int nTraits, boolean interUndirected)
      Get the labels for the degree distributions of the interaction and competition geometries.
      Parameters:
      nTraits - the number of traits
      interUndirected - true if the interaction graph is undirected
      Returns:
      the labels for the degree distributions

    • populateContextMenu

      public void populateContextMenu(ContextMenu menu)
      Description copied from class: AbstractView
      Opportunity for the controller to add functionality to the context menu (optional implementation).
      Overrides:
      populateContextMenu in class AbstractView<HistoGraph>
      Parameters:
      menu - the context menu

    • exportTypes

      protected AbstractView.ExportType[] exportTypes()
      Description copied from class: AbstractView
      Return the list of export types that are acceptable for _all_ graphs in this view.
      Overrides:
      exportTypes in class AbstractView<HistoGraph>
      Returns:
      the list of viable export types

    • exportStatData

      protected void exportStatData()
      Description copied from class: AbstractView
      Export the statistics data.

      Important: Must be overridden by subclasses that return AbstractView.ExportType.CSV_STAT among their export data types.

      Overrides:
      exportStatData in class AbstractView<HistoGraph>
      See Also: