-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Interactive diagram windows
--   
--   Haskell excels at handling data like continuous functions in a nice
--   way, i.e. without discretising anything to finite arrays as is
--   typically done in languages like Matlab. Instead, you can simply pass
--   around functions or infinite data structures (or <i>very</i>
--   high-resolution data that would be infeasible to handle in a strict
--   language).
--   
--   However when you want to <i>view</i> the data, it will eventually need
--   to be exported out of Haskell in some finite form. The purpose of this
--   library is to delay this discretisation as long as possible: it
--   implements an interactive plotting window that accepts
--   continuous/recursive data and only “flattens” it according to the
--   specific view configuration. You can then zoom in to a shown diagram
--   and it will automatically calculate the features more detailedly, or
--   zoom out and discover previosly unexpected features. You don't need to
--   worry about specifying the range and/or resolution beforehand: the
--   program will try to find a suitable default view based on <i>all</i>
--   data your displaying, and you can always still zoom, resize or move
--   later.
--   
--   <a>http://projects.haskell.org/diagrams</a> are used as the
--   “pre-rendered” type. This makes the output usable in a very wide range
--   of applications, though at the moment only the GTK window view is
--   implemented.
@package dynamic-plot
@version 0.1.1.1


module Graphics.Dynamic.Plot.R2

-- | 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:
--   
--   <pre>
--   plotWindow [ fnPlot cos
--              , tracePlot [(x,y) | x&lt;-[-1,-0.96..1]
--                                 , y&lt;-[0,0.01..1]
--                                 , abs (x^2 + y^2 - 1) &lt; 0.01 ]]
--   </pre>
--   
--   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 <tt>ghci +RTS
--   -N4</tt> to benefit from this.
plotWindow :: [DynamicPlottable] -> IO GraphWindowSpec

-- | 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 <a>plot</a>!
class Plottable p
plot :: Plottable p => p -> 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
--   <a>Floating</a> function. Any simple expression like <tt><a>fnPlot</a>
--   (\x -&gt; sin x / exp (x^2))</tt> will work (but the view must not
--   contain singularities).
--   
--   Under the hood this uses the category of continuous functions,
--   <a>:--&gt;</a>, 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.)
fnPlot :: (forall m. Manifold m => AgentVal (:-->) m Double -> AgentVal (:-->) m Double) -> DynamicPlottable

-- | Plot a continuous, “parametric function”, i.e. mapping the real line
--   to a path in ℝ².
paramPlot :: (forall m. Manifold m => AgentVal (:-->) m Double -> (AgentVal (:-->) m Double, AgentVal (:-->) m Double)) -> DynamicPlottable

-- | Plot an (assumed continuous) function in the usual way. Since this
--   uses functions of actual <a>Double</a> values, you have more liberty
--   of defining functions with range-pattern-matching etc., which is at
--   the moment not possible in the <a>:--&gt;</a> category.
--   
--   However, because <a>Double</a> 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 <a>fnPlot</a> 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).
continFnPlot :: (Double -> Double) -> DynamicPlottable

-- | Plot a sequence of points <tt>(x,y)</tt>. 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.
tracePlot :: [(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 &amp;201d; as in <a>tracePlot</a>.
lineSegPlot :: [(Double, Double)] -> DynamicPlottable

-- | Use <a>plot</a> to directly include any <a>Diagram</a>. (All
--   <a>DynamicPlottable</a> is internally rendered to that type.)
--   
--   The exact type may change in the future: we'll probably stay with
--   <tt>diagrams</tt>, but when document output is introduced the backend
--   might become variable or something else but <a>Cairo</a>.
type PlainGraphicsR2 = Diagram B

-- | 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 <a>diagramPlot</a> instead, if you want to view
--   the diagram as-is.
shapePlot :: PlainGraphicsR2 -> DynamicPlottable

-- | Plot a generic <a>Diagram</a>.
diagramPlot :: PlainGraphicsR2 -> DynamicPlottable
legendName :: String -> DynamicPlottable -> DynamicPlottable

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

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

-- | <a>ViewXCenter</a>, <a>ViewYResolution</a> etc. can be used as
--   arguments to some object you <a>plot</a>, 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 <a>fnPlot</a> already take the range into account anyway)
--   – e.g. comparing with the linear regression <i>of all visible
--   points</i> from some sample with some function's tangent <i>at the
--   screen center</i>.
--   
--   <pre>
--   plotWindow [fnPlot sin, plot $ \(ViewXCenter xc) x -&gt; sin xc + (x-xc) * cos xc]
--   </pre>
--   
newtype ViewXCenter
ViewXCenter :: Double -> ViewXCenter
[getViewXCenter] :: ViewXCenter -> Double
newtype ViewYCenter
ViewYCenter :: Double -> ViewYCenter
[getViewYCenter] :: ViewYCenter -> Double
newtype ViewWidth
ViewWidth :: Double -> ViewWidth
[getViewWidth] :: ViewWidth -> Double
newtype ViewHeight
ViewHeight :: Double -> ViewHeight
[getViewHeight] :: ViewHeight -> Double
newtype ViewXResolution
ViewXResolution :: Int -> ViewXResolution
[getViewXResolution] :: ViewXResolution -> Int
newtype ViewYResolution
ViewYResolution :: Int -> ViewYResolution
[getViewYResolution] :: ViewYResolution -> Int

-- | Coordinate axes with labels. For many plottable objects, these will be
--   added automatically, by default (unless inhibited with
--   <a>noDynamicAxes</a>).
dynamicAxes :: DynamicPlottable
noDynamicAxes :: DynamicPlottable
data DynamicPlottable
newtype PlainGraphics
PlainGraphics :: PlainGraphicsR2 -> PlainGraphics
[getPlainGraphics] :: PlainGraphics -> PlainGraphicsR2
instance GHC.Enum.Enum Graphics.Dynamic.Plot.R2.KeyAction
instance GHC.Classes.Ord Graphics.Dynamic.Plot.R2.KeyAction
instance GHC.Classes.Eq Graphics.Dynamic.Plot.R2.KeyAction
instance GHC.Base.Monoid Graphics.Dynamic.Plot.R2.PlainGraphics
instance Data.Semigroup.Semigroup Graphics.Dynamic.Plot.R2.PlainGraphics
instance Graphics.Dynamic.Plot.R2.Plottable Graphics.Dynamic.Plot.R2.DynamicPlottable
instance Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.Internal.Types.R -> Graphics.Dynamic.Plot.Internal.Types.R)
instance Graphics.Dynamic.Plot.R2.Plottable (GHC.Types.Double Data.Manifold.:--> GHC.Types.Double)
instance Graphics.Dynamic.Plot.R2.Plottable (GHC.Types.Double Data.Manifold.:--> (GHC.Types.Double, GHC.Types.Double))
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable [p]
instance Graphics.Dynamic.Plot.R2.Plottable Graphics.Dynamic.Plot.R2.PlainGraphics
instance Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.Internal.Types.R Graphics.Dynamic.Plot.R2.--> Graphics.Dynamic.Plot.Internal.Types.R)
instance Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.Internal.Types.R Graphics.Dynamic.Plot.Internal.Types.-.^> Graphics.Dynamic.Plot.Internal.Types.R)
instance Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.Internal.Types.RecursiveSamples GHC.Types.Int Graphics.Dynamic.Plot.Internal.Types.P2 (Graphics.Dynamic.Plot.Internal.Types.DevBoxes Graphics.Dynamic.Plot.Internal.Types.P2))
instance Graphics.Dynamic.Plot.R2.Plottable (GHC.Types.Int Graphics.Dynamic.Plot.Internal.Types.-.^> Graphics.Dynamic.Plot.Internal.Types.P2)
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.TreeCover.Shade Graphics.Dynamic.Plot.Internal.Types.P2)
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.TreeCover.SimpleTree Graphics.Dynamic.Plot.Internal.Types.P2)
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.TreeCover.Trees Graphics.Dynamic.Plot.Internal.Types.P2)
instance Data.Semigroup.Semigroup Graphics.Dynamic.Plot.R2.Plot
instance GHC.Base.Monoid Graphics.Dynamic.Plot.R2.Plot
instance Data.Semigroup.Semigroup Graphics.Dynamic.Plot.R2.DynamicPlottable
instance GHC.Base.Monoid Graphics.Dynamic.Plot.R2.DynamicPlottable
instance Data.Default.Class.Default Graphics.Dynamic.Plot.R2.DynamicPlottable
instance GHC.Classes.Ord r => Data.Semigroup.Semigroup (Graphics.Dynamic.Plot.R2.RangeRequest r)
instance GHC.Classes.Ord r => GHC.Base.Monoid (Graphics.Dynamic.Plot.R2.RangeRequest r)
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.R2.ViewXCenter -> p)
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.R2.ViewYCenter -> p)
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.R2.ViewWidth -> p)
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.R2.ViewHeight -> p)