Graphics.Dynamic.Plot.R2

Interactive display

plotWindow :: [DynamicPlottable] -> IO GraphWindowSpec

Plot some plot objects to a new interactive GTK window. Useful for a quick preview of some unknown data or real-valued functions; things like selection of reasonable view range and colourisation are automatically chosen.

Example:

    plotWindow [ fnPlot cos
               , tracePlot [(x,y) | x<-[-1,-0.96..1]
                                  , y<-[0,0.01..1]
                                  , abs (x^2 + y^2 - 1) < 0.01 ]]

This gives such a plot window:

And that can with the mouse wheel be zoomed/browsed, like

The individual objects you want to plot can be evaluated in multiple threads, so a single hard calculatation won't freeze the responsitivity of the whole window. Invoke e.g. from ghci +RTS -N4 to benefit from this.

Plottable objects

Class

class Plottable p where

Class for types that can be plotted in some canonical, “obvious” way. If you want to display something and don't know about any specific caveats, try just using plot!

Methods

plot :: p -> DynamicPlottable

Instances

Plottable DynamicPlottable

Plottable PlainGraphics

Plottable p => Plottable [p]

Plottable p => Plottable (ViewHeight -> p)

Plottable p => Plottable (ViewWidth -> p)

Plottable p => Plottable (ViewYCenter -> p)

Plottable p => Plottable (ViewXCenter -> p)

Plottable ((:-->) Double Double)

Plottable ((:-->) Double (Double, Double))

Simple function plots

fnPlot :: (forall m. Manifold m => AgentVal (:-->) m Double -> AgentVal (:-->) m Double) -> DynamicPlottable

Plot a continuous function in the usual way, taking arguments from the x-Coordinate and results to the y one. The signature looks more complicated than it is; think about it as requiring a polymorphic Floating function. Any simple expression like fnPlot (\x -> sin x / exp (x^2)) will work (but the view must not contain singularities).

Under the hood this uses the category of continuous functions, :-->, to prove that no details are omitted (like small high-frequency bumps). The flip side is that this does not always work very efficiently, in fact it can easily become exponentially slow for some parameters. Make sure to run multithreaded, to prevent hanging your program this way. Also consider limiting the memory: if you try to plot across singularities, the program may well eat up all available resorces before failing. (But it will never “succeed” and plot something wrong!)

In the future, we would like to switch to the category of piecewise continuously-differentiable functions. That wouldn't suffer from said problems, and should also generally be more efficient. (That category is not yet implemented in Haskell.)

paramPlot :: (forall m. Manifold m => AgentVal (:-->) m Double -> (AgentVal (:-->) m Double, AgentVal (:-->) m Double)) -> DynamicPlottable

Plot a continuous, “parametric function”, i.e. mapping the real line to a path in ℝ².

continFnPlot :: (Double -> Double) -> DynamicPlottable

Plot an (assumed continuous) function in the usual way. Since this uses functions of actual Double values, you have more liberty of defining functions with range-pattern-matching etc., which is at the moment not possible in the :--> category.

However, because Double can't really proove properties of a mathematical function, aliasing and similar problems are not taken into account. So it only works accurately when the function is locally linear on pixel scales (what most other plot programs just assume silently). In case of singularities, the naïve thing is done (extend as far as possible; vertical line at sign change), which again is common enough though not really right.

We'd like to recommend using fnPlot whenever possible, which automatically adjusts the resolution so the plot is guaranteed accurate (but it's not usable yet for a lot of real applications).

tracePlot :: [(Double, Double)] -> DynamicPlottable

Plot a sequence of points (x,y). The appearance of the plot will be automatically chosen to match resolution and point density: at low densities, each point will simply get displayed on its own. When the density goes so high you couldn't distinguish individual points anyway, we switch to a “trace view”, approximating the probability density function around a “local mean path”, which is rather more insightful (and much less obstructive/clunky) than a simple cloud of independent points.

In principle, this should be able to handle vast amounts of data (so you can, say, directly plot an audio file); at the moment the implementation isn't efficient enough and will get slow for more than some 100000 data points.

lineSegPlot :: [(Double, Double)] -> DynamicPlottable

Simply connect the points by straight line segments, in the given order. Beware that this will always slow down the performance when the list is large; there is no &201d; as in tracePlot.

type PlainGraphicsR2 = Diagram B

Use plot to directly include any Diagram. (All DynamicPlottable is internally rendered to that type.)

The exact type may change in the future: we'll probably stay with diagrams, but when document output is introduced the backend might become variable or something else but Cairo.

shapePlot :: PlainGraphicsR2 -> DynamicPlottable

Use a generic diagram within a plot.

Like with the various specialised function plotters, this will get automatically tinted to be distinguishable from other plot objects in the same window. Use diagramPlot instead, if you want to view the diagram as-is.

diagramPlot :: PlainGraphicsR2 -> DynamicPlottable

Plot a generic Diagram.

Legend captions

legendName :: String -> DynamicPlottable -> DynamicPlottable

View selection

xInterval :: (Double, Double) -> DynamicPlottable

When you “plot” xInterval / yInterval, it is ensured that the (initial) view encompasses (at least) the specified range. Note there is nothing special about these “flag” objects: any Plottable can request a certain view, e.g. for a discrete point cloud it's obvious and a function defines at least a y-range for a given x-range. Only use explicit range when necessary.

yInterval :: (Double, Double) -> DynamicPlottable

forceXRange :: (Double, Double) -> DynamicPlottable

Like xInterval, this only affects what range is plotted. However, it doesn't merely request that a certain interval should be visible, but actually enforces particular values for the left and right boundary. Nothing outside the range will be plotted (unless there is another, contradicting forceXRange).

forceYRange :: (Double, Double) -> DynamicPlottable

View dependance

newtype ViewXCenter

ViewXCenter, ViewYResolution etc. can be used as arguments to some object you plot, if its rendering is to depend explicitly on the screen's visible range. You should not need to do that manually except for special applications (the standard plot objects like fnPlot already take the range into account anyway) – e.g. comparing with the linear regression of all visible points from some sample with some function's tangent at the screen center.

plotWindow [fnPlot sin, plot $ \(ViewXCenter xc) x -> sin xc + (x-xc) * cos xc]

Constructors

ViewXCenter

Fields

getViewXCenter :: Double

Instances

Plottable p => Plottable (ViewXCenter -> p)

newtype ViewYCenter

Constructors

ViewYCenter

Fields

getViewYCenter :: Double

Instances

Plottable p => Plottable (ViewYCenter -> p)

newtype ViewWidth

Constructors

ViewWidth

Fields

getViewWidth :: Double

Instances

Plottable p => Plottable (ViewWidth -> p)

newtype ViewHeight

Constructors

ViewHeight

Fields

getViewHeight :: Double

Instances

Plottable p => Plottable (ViewHeight -> p)

newtype ViewXResolution

Constructors

ViewXResolution

Fields

getViewXResolution :: Int

newtype ViewYResolution

Constructors

ViewYResolution

Fields

getViewYResolution :: Int

Auxiliary plot objects

dynamicAxes :: DynamicPlottable

Coordinate axes with labels. For many plottable objects, these will be added automatically, by default (unless inhibited with noDynamicAxes).

noDynamicAxes :: DynamicPlottable

Plot type

data DynamicPlottable

Instances

Monoid DynamicPlottable

Semigroup DynamicPlottable

Default DynamicPlottable

Plottable DynamicPlottable

Legacy

newtype PlainGraphics

Constructors

PlainGraphics

Fields

getPlainGraphics :: PlainGraphicsR2

Instances

Monoid PlainGraphics

Semigroup PlainGraphics

Plottable PlainGraphics