-- 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.4.0.0


module Graphics.Dynamic.Plot.R2

-- | Render a single view of a collection of plottable objects. This can be
--   used the same way as <a>plotWindow</a>, but does not open any GTK but
--   gives the result as-is.
--   
--   If the objects contain animations, only the initial frame will be
--   rendered.
plotPrerender :: ViewportConfig -> [DynamicPlottable] -> IO PlainGraphicsR2

-- | 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:
--   
--   
--   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.
--   
--   ATTENTION: the window may sometimes freeze, especially when displaying
--   complicated functions with <a>fnPlot</a> from ghci. This is apparently
--   a kind of deadlock problem with one of the C libraries that are
--   invoked, At the moment, we can recommend no better solution than to
--   abort and restart ghci (or what else you use – iHaskell kernel,
--   process, ...) if this occurs.
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 / cos (sqrt x))</tt> will work.
--   
--   Under the hood this uses the category of region-wise differentiable
--   functions, <a>RWDiffable</a>, to prove that no details are omitted
--   (like small high-frequency bumps). Note that this can become difficult
--   for contrived cases like <tt>cos(1/sin x)</tt> – while such functions
--   will never come out with aliasing artifacts, they also may not come
--   out quickly at all. (But for well-behaved functions, using the
--   differentiable category actually tends to be more effective, because
--   the algorithm immediately sees when it can describe an almost-linear
--   region with only a few line segments.)
--   
--   This function is equivalent to using <a>plot</a> on an
--   <a>RWDiffable</a> arrow.
fnPlot :: (forall m. Object (RWDiffable ℝ) m => AgentVal (-->) m ℝ -> AgentVal (-->) m ℝ) -> DynamicPlottable

-- | Plot a continuous, “parametric function”, i.e. mapping the real line
--   to a path in ℝ².
paramPlot :: (forall m. (WithField ℝ PseudoAffine m, SimpleSpace (Needle m)) => AgentVal (-->) m ℝ -> (AgentVal (-->) m ℝ, AgentVal (-->) m ℝ)) -> 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 <tt>:--&gt;</tt> category.
--   
--   However, because <a>Double</a> can't really prove 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
linregressionPlot :: forall x m y. (SimpleSpace m, Scalar m ~ ℝ, y ~ ℝ, x ~ ℝ) => (x -> (m +> y)) -> [(x, Shade' y)] -> (Shade' m -> DynamicPlottable -> DynamicPlottable -> DynamicPlottable) -> DynamicPlottable

-- | Plot a function that assigns every point in view a colour value.
--   
--   <pre>
--   &gt; plotWindow [colourPaintPlot $ (x,y) -&gt; case (x^2+y^2, atan2 y x) of (r,φ) -&gt; guard (sin (7*φ-2*r) &gt; r) &gt;&gt; Just (Dia.blend (tanh r) Dia.red Dia.green), unitAspect ]
--   </pre>
--   
--   
--   We try to evaluate that function no more often than necessary, but
--   since it's a plain function with no differentiability information
--   there's only so much that can be done; this requires a tradeoff
--   between rasterisation fineness and performance. It works well for
--   simple, smooth functions, but may not be adequate for functions with
--   strong edges/transients, nor for expensive to compute functions.
colourPaintPlot :: ((Double, Double) -> Maybe (Colour 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

-- | Combine multiple objects in a single plot. Each will get an individual
--   <a>tint</a> (if applicable). This is also the default behaviour of
--   <a>plotWindow</a>.
--   
--   To plot a family objects all with the <i>same</i> (but
--   automatically-chosen) tint, simply use <a>plot</a> on the list, or
--   combine them monoidally with <a>&lt;&gt;</a>.
plotMultiple :: Plottable x => [x] -> DynamicPlottable

-- | Lazily consume the list, always plotting the latest value available as
--   they arrive. Useful for displaying results of expensive computations
--   that iteratively improve some result, but also for making simple
--   animations (see <a>plotDelay</a>).
plotLatest :: Plottable x => [x] -> DynamicPlottable

-- | Colour this plot object in a fixed shade.
tint :: Colour ℝ -> DynamicPlottable -> DynamicPlottable

-- | Allow the object to be automatically assigned a colour that's
--   otherwise unused in the plot. (This is the default for most plot
--   objects.)
autoTint :: DynamicPlottable -> DynamicPlottable

-- | Set the caption for this plot object that should appear in the plot
--   legend.
legendName :: String -> DynamicPlottable -> DynamicPlottable

-- | Render the legend (if any) belonging to a collection of plottable
--   objects.
plotLegendPrerender :: LegendDisplayConfig -> [DynamicPlottable] -> IO (Maybe PlainGraphicsR2)

-- | Limit the refresh / frame rate for this plot object. Useful to slowly
--   study some sequence of plots with <a>plotLatest</a>, or to just reduce
--   processor load.
--   
--   Note: the argument will probably change to <a>NominalDiffTime</a> from
--   the <a>thyme</a> library soon.
plotDelay :: NominalDiffTime -> 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

-- | Require that both coordinate axes are zoomed the same way, such that
--   e.g. the unit circle will appear as an actual circle.
unitAspect :: DynamicPlottable
newtype MousePressed
MousePressed :: Maybe (ℝ, ℝ) -> MousePressed
[mouseIsPressedAt] :: MousePressed -> Maybe (ℝ, ℝ)
newtype MousePress
MousePress :: (ℝ, ℝ) -> MousePress
[lastMousePressedLocation] :: MousePress -> (ℝ, ℝ)
newtype MouseClicks
MouseClicks :: [(ℝ, ℝ)] -> MouseClicks

-- | A history of all clicks that were done in this window; more
--   specifically, of all <i>left mouse-button release events</i> recorded.
[getClickPositions] :: MouseClicks -> [(ℝ, ℝ)]

-- | Move through a sequence of plottable objects, switching to the next
--   whenever a click is received anywhere on the screen. Similar to
--   <a>plotLatest</a>, but does not proceed automatically.
clickThrough :: Plottable p => [p] -> DynamicPlottable
mouseInteractive :: Plottable p => (MouseEvent (ℝ, ℝ) -> s -> s) -> s -> (s -> p) -> DynamicPlottable
data MouseEvent x
clickLocation :: forall x_aETl. Lens' (MouseEvent x_aETl) x_aETl
releaseLocation :: forall x_aETl. Lens' (MouseEvent x_aETl) x_aETl
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
xAxisLabel :: String -> DynamicPlottable
yAxisLabel :: String -> DynamicPlottable
type DynamicPlottable = DynamicPlottable' RVar
tweakPrerendered :: (PlainGraphicsR2 -> PlainGraphicsR2) -> DynamicPlottable -> DynamicPlottable
data ViewportConfig
xResV :: Lens' ViewportConfig Int
yResV :: Lens' ViewportConfig Int
prerenderScaling :: Lens' ViewportConfig PrerenderScaling
data PrerenderScaling

-- | The diagram has the original coordinates of the data that's plotted in
--   it. E.g. if you've plotted an oscillation with amplitude 1e-4, the
--   height of the plot will be indicated as only 0.0002. Mostly useful
--   when you want to juxtapose multiple plots with correct scale matching.
ValuespaceScaling :: PrerenderScaling

-- | The diagram is scaled to have a range of <tt>[-1, 1]</tt> in both x-
--   and y-direction.
NormalisedScaling :: PrerenderScaling

-- | Scaled to pixel coordinates, i.e. the x range is <tt>[0, xResV-1]</tt>
--   and the y range <tt>[0, yResV-1]</tt>.
OutputCoordsScaling :: PrerenderScaling
data LegendDisplayConfig
legendPrerenderSize :: Iso' LegendDisplayConfig (SizeSpec V2 Double)
instance GHC.Base.Monoid Graphics.Dynamic.Plot.R2.PlainGraphics
instance Data.Semigroup.Semigroup Graphics.Dynamic.Plot.R2.PlainGraphics
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.R2.MousePressed -> p)
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.R2.MousePress -> p)
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.R2.MouseClicks -> p)
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.R2.ViewHeight -> 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.ViewYCenter -> p)
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.R2.ViewXCenter -> p)
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.R2.--> (Graphics.Dynamic.Plot.Internal.Types.R, Graphics.Dynamic.Plot.Internal.Types.R))
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 p => Graphics.Dynamic.Plot.R2.Plottable [p]
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable (Data.Semigroup.Option p)
instance Graphics.Dynamic.Plot.R2.Plottable p => Graphics.Dynamic.Plot.R2.Plottable (GHC.Base.Maybe 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.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.Shade.Shade Graphics.Dynamic.Plot.Internal.Types.P2)
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Shade.Shade Data.Manifold.Types.Primitive.ℝ²)
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Shade.Shade (Graphics.Dynamic.Plot.Internal.Types.R, Graphics.Dynamic.Plot.Internal.Types.R))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Shade.Shade' (Graphics.Dynamic.Plot.Internal.Types.R, Graphics.Dynamic.Plot.Internal.Types.R))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Web.ConvexSet Data.Manifold.Types.Primitive.ℝ²)
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Web.ConvexSet (Graphics.Dynamic.Plot.Internal.Types.R, Graphics.Dynamic.Plot.Internal.Types.R))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Shade.Shade' Data.Manifold.Types.Primitive.ℝ²)
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Shade.Shade' Graphics.Dynamic.Plot.Internal.Types.P2)
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.TreeCover.Shaded Math.Manifold.Core.Types.Internal.ℝ Math.Manifold.Core.Types.Internal.ℝ)
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Web.Internal.PointsWeb Math.Manifold.Core.Types.Internal.ℝ (Data.Manifold.Shade.Shade' Math.Manifold.Core.Types.Internal.ℝ))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Web.Internal.PointsWeb Data.Manifold.Types.Primitive.ℝ² (Data.Colour.Internal.Colour Math.Manifold.Core.Types.Internal.ℝ))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Web.Internal.PointsWeb (Math.Manifold.Core.Types.Internal.ℝ, Math.Manifold.Core.Types.Internal.ℝ) (Data.Colour.Internal.Colour Math.Manifold.Core.Types.Internal.ℝ))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Web.Internal.PointsWeb Data.Manifold.Types.Primitive.ℝ² (Data.Manifold.Shade.Shade (Data.Colour.Internal.Colour Math.Manifold.Core.Types.Internal.ℝ)))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Web.Internal.PointsWeb (Math.Manifold.Core.Types.Internal.ℝ, Math.Manifold.Core.Types.Internal.ℝ) (Data.Manifold.Shade.Shade (Data.Colour.Internal.Colour Math.Manifold.Core.Types.Internal.ℝ)))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Types.Cutplane (Math.Manifold.Core.Types.Internal.ℝ, Math.Manifold.Core.Types.Internal.ℝ))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.Types.Cutplane Data.Manifold.Types.Primitive.ℝ²)
instance Graphics.Dynamic.Plot.R2.Plottable x => Graphics.Dynamic.Plot.R2.Plottable (Graphics.Dynamic.Plot.Internal.Types.Latest x)
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 Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.TreeCover.Trees Graphics.Dynamic.Plot.Internal.Types.R2)
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.TreeCover.SimpleTree (Graphics.Dynamic.Plot.Internal.Types.R, Graphics.Dynamic.Plot.Internal.Types.R))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.TreeCover.Trees (Graphics.Dynamic.Plot.Internal.Types.R, Graphics.Dynamic.Plot.Internal.Types.R))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.TreeCover.SimpleTree (Data.Manifold.Shade.WithAny Graphics.Dynamic.Plot.Internal.Types.R Graphics.Dynamic.Plot.Internal.Types.R))
instance Graphics.Dynamic.Plot.R2.Plottable (Data.Manifold.TreeCover.Trees (Data.Manifold.Shade.WithAny Graphics.Dynamic.Plot.Internal.Types.R Graphics.Dynamic.Plot.Internal.Types.R))
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 Data.Semigroup.Semigroup (Graphics.Dynamic.Plot.R2.Interactions x)
instance GHC.Base.Monoid (Graphics.Dynamic.Plot.R2.Interactions x)