diff --git a/chart-unit.cabal b/chart-unit.cabal --- a/chart-unit.cabal +++ b/chart-unit.cabal @@ -1,16 +1,23 @@ name: chart-unit -version: 0.5.0 +version: 0.5.1 synopsis: Native haskell charts. description: - See for chart bling and usage. . + <> . - ![example](other/mainExample.svg) + chart-unit is a native haskell charting library designed: . - These charts are designed to be scale independent and amenable to combinatory busywork (hence the unit suffix). + - as a chart DSL and algebra . + - towards a minimalist look and feel . + - to provide a set of default values that are robust across differet data and physical chart scales + . + - around provision of a small but core set of chart types. + . + See for a chart gallery. + . extra-source-files: readme.md, stack.yaml, @@ -113,7 +120,8 @@ protolude, tdigest, text, - diagrams-rasterific + diagrams-rasterific, + diagrams-svg default-extensions: DeriveGeneric, DeriveTraversable, diff --git a/examples/sourceExamples.hs b/examples/sourceExamples.hs --- a/examples/sourceExamples.hs +++ b/examples/sourceExamples.hs @@ -7,13 +7,14 @@ {-# OPTIONS_GHC -fno-warn-incomplete-patterns #-} import Chart -import Control.Lens hiding (beside, (#), at) +import Control.Lens hiding (beside) import qualified Data.Text as Text import NumHask.Prelude import Data.List (zipWith3, zipWith4) -import Diagrams.Prelude hiding ((*.), scaleX, scaleY, width) +import Diagrams.Prelude hiding ((*.), scaleX, scaleY, (<>)) import FakeData -import Diagrams.Backend.Rasterific (Rasterific, animatedGif, GifLooping(..)) +import Diagrams.Backend.Rasterific (renderRasterific, Rasterific, animatedGif, GifLooping(..)) +import Diagrams.Backend.SVG (B) hudbits :: Text -> Maybe Text -> [Text] -> [LegendType b] -> HudOptions b -> HudOptions b hudbits t subt ts ls x = @@ -83,7 +84,8 @@ glyphsExample = glyphs def [Pair (x / 10) (sin x / 10) | x <- [0 .. 10]] gopts :: [GlyphOptions b] -gopts = [def, def {glyphBorderColor = ured, glyphShape = triangle}] +gopts = [def, def { glyphBorderColor = rybColor 0 `withOpacity` 0.5 + , glyphShape = triangle}] gdata :: [[Pair Double]] gdata = [p_1, p_2] @@ -266,7 +268,7 @@ asquare [ [ Pixel (Rect x (x + 0.05) y (y + 0.05)) - (blend (x * y + x * x) ured ublue) + (blend (x * y + x * x) (rybColor 0 `withOpacity` 1) ublue) | x <- grid MidPos (one :: Range Double) 20 , y <- grid MidPos (one :: Range Double) 20 ] @@ -360,7 +362,7 @@ legendExample :: Chart b legendExample = legend $ def {legendChartType = legends} -mainExample :: Diagram B +mainExample :: Chart b mainExample = withHud opts (lineChart lopts) ls where opts = @@ -397,10 +399,12 @@ , "bottom right, non-essential note") ] +scaleExample :: IO () +scaleExample = + fileSvg "other/scaleExample.svg" (300,120) $ withHud (hudAspect_ .~ widescreen $ hudRange_ .~ Just (Rect 0 12 0 0.2) $ def) (lineChart (repeat def)) ((\x -> [Pair x 0, Pair x (x/100)]) <$> [0..10]) -- gallery - -scatterHistExample :: [[Pair Double]] -> Diagram B +scatterHistExample :: [[Pair Double]] -> Chart b scatterHistExample xys = beside (r2 (1,0)) (beside (r2 (0,-1)) @@ -433,7 +437,7 @@ hy = makeHist 50 . fmap (view _y) <$> xys -labelledBarExample :: Diagram B +labelledBarExample :: Chart b labelledBarExample = rectChart_ [def] sixbyfour @@ -474,7 +478,7 @@ def] skinny r [zipWith (\x y -> (x,Pair y 0.05)) ["min","3rd Q","median","1st Q","max"] qs'] - let ticks' = glyphChart [def] skinny r [(\x -> Pair x 0.02) <$> qs] + let ticks' = glyphChart [def] skinny r [(`Pair` 0.02) <$> qs] pure $ hud' <> ticks' <> labels' histDiffExample :: ([Rect Double],[Rect Double]) -> Chart b @@ -516,42 +520,40 @@ scaleY (yu - yl) $ scaleX (xu - xl) $ moveOriginTo (p2(-0.5,-0.5)) - unitSquare) $ c + unitSquare) c grp :: Int -> [a] -> [[a]] grp n = unfoldr (\x -> let y = splitAt n x in - if length (fst y) == 0 then Nothing else Just y) + if null (fst y) then Nothing else Just y) -exampleClipping :: RectOptions -> Double -> Int -> QDiagram B V2 Double Any -> QDiagram B V2 Double Any -exampleClipping rcfg p n ch = - foldl' vert mempty $ (foldl' hori mempty) <$> qb +-- | chop a chart extent into a double list of Rects +chop :: Pair Int -> QDiagram b V2 Double Any -> [[Rect Double]] +chop p@(Pair _ n) ch = grp n $ gridSpace (Rect xl xu yl yu) p where - hori x a = beside (r2 (0,1)) x (pad p $ bound rcfg 1 $ centerXY $ clip a ch) - vert x a = beside (r2 (1,0)) x (pad p $ centerXY $ a) - qb :: [[Rect Double]] = grp n $ gridSpace (Rect xl xu yl yu) (Pair n n) (xl,xu) = fromMaybe (-0.5,0.5) (extentX ch) (yl,yu) = fromMaybe (-0.5,0.5) (extentY ch) +exampleClipping :: RectOptions -> Double -> Int -> QDiagram B V2 Double Any -> QDiagram B V2 Double Any +exampleClipping rcfg p n ch = + stack (Pair 0 1) (pad p . centerXY) $ + hori (\a -> pad p $ bound rcfg 1 $ centerXY $ clip a ch) <$> chop (Pair n n) ch + exampleClipping' :: RectOptions -> Double -> Double -> Int -> QDiagram Rasterific V2 Double Any -> QDiagram Rasterific V2 Double Any exampleClipping' rcfg rot p n ch = - foldl' vert mempty $ (foldl' hori mempty) <$> qb - where - hori x a = beside (r2 (0,1)) x (Diagrams.Prelude.rotate (rot @@ deg) $ pad p $ bound rcfg 1 $ centerXY $ clip a ch) - vert x a = beside (r2 (1,0)) x (pad p $ centerXY $ a) - qb :: [[Rect Double]] = grp n $ gridSpace (Rect xl xu yl yu) (Pair n n) - (xl,xu) = fromMaybe (-0.5,0.5) (extentX ch) - (yl,yu) = fromMaybe (-0.5,0.5) (extentY ch) + stack (Pair 0 1) (pad p . centerXY) $ + hori (\a -> Diagrams.Prelude.rotate (rot @@ deg) $ + pad p $ bound rcfg 1 $ centerXY $ clip a ch) <$> chop (Pair n n) ch animationExample :: FilePath -> IO () animationExample f = do - let c = ((\x -> bound (rectColor_ .~ ucolor 1 1 1 0.1 $ def) 1 $ + let c = (\x -> bound (rectColor_ .~ ucolor 1 1 1 0.1 $ def) 1 $ exampleClipping' (rectBorderSize_ .~ 0.001 $ rectColor_ .~ ucolor 1 1 1 0.1 $ def) - (x*12) 1 5 lineChart_Example) <$> [0..30]) + (x*12) 1 5 lineChart_Example) <$> [0..30] animatedGif f (mkSizeSpec (Just <$> r2 (600,400))) LoopingNever 20 c -schoolbookExample :: Diagram B +schoolbookExample :: Chart b schoolbookExample = pad 1.1 $ lineChart_ @@ -559,7 +561,7 @@ lineColor_ .~ ucolor 0.4 0.5 0.2 0.8 $ lineSize_ .~ 0.001 $ def) asquare $ - (\x -> [Pair -10.0 (-10 + 2*x), Pair 10.0 (-10 + 2*x)]) <$> + (\x -> [Pair -10.0 (-10 + 2*x), Pair 10.0 (-10 + 2*x)]) . fromIntegral <$> ([0..10] :: [Int]) main :: IO () @@ -608,9 +610,7 @@ fileSvg "other/arrowHudExample.svg" (600, 400) $ arrowHudExample <> arrowChart_Example - -- gallery - xys <- mkScatterData putStrLn ("scatterHistExample" :: Text) fileSvg "other/scatterHistExample.svg" (600,400) (scatterHistExample xys) @@ -631,3 +631,8 @@ animationExample "other/animationExample.gif" putStrLn ("schoolbookExample" :: Text) fileSvg "other/schoolbookExample.svg" (400,400) schoolbookExample + + -- small hud examples + renderRasterific "other/hud.png" (dims (r2(100,100))) (showOrigin $ hud def :: QDiagram Rasterific V2 Double Any) + fileSvg "other/hud.svg" (100,100) (showOrigin $ hud def) + scaleExample diff --git a/other/clippingExample.svg b/other/clippingExample.svg --- a/other/clippingExample.svg +++ b/other/clippingExample.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/glineHudExample.svg b/other/glineHudExample.svg --- a/other/glineHudExample.svg +++ b/other/glineHudExample.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/glyphChart_Example.svg b/other/glyphChart_Example.svg --- a/other/glyphChart_Example.svg +++ b/other/glyphChart_Example.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/glyphHudExample.svg b/other/glyphHudExample.svg --- a/other/glyphHudExample.svg +++ b/other/glyphHudExample.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/glyph_Example.svg b/other/glyph_Example.svg --- a/other/glyph_Example.svg +++ b/other/glyph_Example.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/glyphsExample.svg b/other/glyphsExample.svg --- a/other/glyphsExample.svg +++ b/other/glyphsExample.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/hud.svg b/other/hud.svg new file mode 100644 --- /dev/null +++ b/other/hud.svg @@ -0,0 +1,3 @@ + + diff --git a/other/labelledExample.svg b/other/labelledExample.svg --- a/other/labelledExample.svg +++ b/other/labelledExample.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/legendExample.svg b/other/legendExample.svg --- a/other/legendExample.svg +++ b/other/legendExample.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/lglyphChart_Example.svg b/other/lglyphChart_Example.svg --- a/other/lglyphChart_Example.svg +++ b/other/lglyphChart_Example.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/lglyphHudExample.svg b/other/lglyphHudExample.svg --- a/other/lglyphHudExample.svg +++ b/other/lglyphHudExample.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/lglyphsExample.svg b/other/lglyphsExample.svg --- a/other/lglyphsExample.svg +++ b/other/lglyphsExample.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/mainExample.svg b/other/mainExample.svg --- a/other/mainExample.svg +++ b/other/mainExample.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/pixelChart_Example.svg b/other/pixelChart_Example.svg --- a/other/pixelChart_Example.svg +++ b/other/pixelChart_Example.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/pixelHudExample.svg b/other/pixelHudExample.svg --- a/other/pixelHudExample.svg +++ b/other/pixelHudExample.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/other/scaleExample.svg b/other/scaleExample.svg new file mode 100644 --- /dev/null +++ b/other/scaleExample.svg @@ -0,0 +1,3 @@ + + diff --git a/other/scratchpad.svg b/other/scratchpad.svg new file mode 100644 --- /dev/null +++ b/other/scratchpad.svg @@ -0,0 +1,3 @@ + + diff --git a/other/skinnyExample.svg b/other/skinnyExample.svg --- a/other/skinnyExample.svg +++ b/other/skinnyExample.svg @@ -1,3 +1,3 @@ + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> diff --git a/readme.md b/readme.md --- a/readme.md +++ b/readme.md @@ -1,13 +1,9 @@ -```include -other/header.md -``` - [chart-unit](https://github.com/tonyday567/chart-unit) === [![Build Status](https://travis-ci.org/tonyday567/chart-unit.svg)](https://travis-ci.org/tonyday567/chart-unit) [![Hackage](https://img.shields.io/hackage/v/chart-unit.svg)](https://hackage.haskell.org/package/chart-unit) [![lts](https://www.stackage.org/package/chart-unit/badge/lts)](http://stackage.org/lts/package/chart-unit) [![nightly](https://www.stackage.org/package/chart-unit/badge/nightly)](http://stackage.org/nightly/package/chart-unit) -`chart-unit` is a haskell chart library focusing on a small set of high-quality charts using native haskell. Here's a recent example, chock-a-block fill of titles and legends, since they've just been added: +`chart-unit` is a haskell chart library focusing on a small set of high-quality charts using native haskell. Here's a recent example, chock-a-block full of titles and legends (that needed testing): ![](other/mainExample.svg) @@ -32,10 +28,33 @@ ![](other/arrowHudExample.svg) +Why the name chart-unit? +=== + +Most of the behind-the-scenes grunt work is scaling data, projecting points from one range to another, and computing position. A key to making these computations neat was `one = Range -0.5 0.5` and `one = Rect -0.5 0.5 -0.5 0.5` as the (multiplicative) units of a chart range. See [numhask-range](https://github.com/tonyday567/numhask-range) for a monologue. + +What's with the funny names? +=== + +Charting is an age-old craft, and stuffed to the brim with cliche and jargon. I wanted to cut through the cruft of what is thought of as a chart (and charting has been dominated by excel for 30 years), and approach charting from a haskelly perspective. The funny names were the cohorts that popped out. A rough translation: + + +| ye-old Chart type | chart-unit type | +|------------------------------------------------------|-----------------------| +| line | LineChart | +| line chart with markers | GLineChart | +| scatter | GlyphChart | +| pie | pull requests welcome | +| heatmap | PixelChart | +| [Bar](https://en.wikipedia.org/wiki/Bar_chart) | RectChart | +| [Histogram](https://en.wikipedia.org/wiki/Histogram) | RectChart | +| sparkline | a skinny Aspect | +| | | + Gallery === -The main chart types and the power of diagrams make it easy to invent new charts. Hrere's some inspiration (all code for these charts is in [examples/sourceExamples.hs](examples/sourceExamples.hs)). +The main chart types and the power of diagrams make it easy to invent new charts. Hrere's some inspiration (all code for these charts is in [examples/sourceExamples.hs](https://github.com/tonyday567/chart-unit/blob/master/examples/sourceExamples.hs)). schoolbook --- @@ -80,9 +99,5 @@ === ~~~ -stack build --test --exec "$(stack path --local-install-root)/bin/chart-source-examples" --exec "$(stack path --local-bin)/pandoc -f markdown -i readme.md -t html -o index.html --filter pandoc-include --mathjax" --file-watch +stack build --test --exec "$(stack path --local-install-root)/bin/chart-source-examples" --exec "$(stack path --local-bin)/pandoc -f markdown -i other/header.md readme.md other/footer.md -t html -o index.html --filter pandoc-include --mathjax" --file-watch ~~~ - -```include -other/footer.md -``` diff --git a/src/Chart.hs b/src/Chart.hs --- a/src/Chart.hs +++ b/src/Chart.hs @@ -1,18 +1,19 @@ {-# OPTIONS_GHC -Wall #-} {-# OPTIONS_HADDOCK prune, not-home #-} --- | native haskell charts +-- | The Chart module exports all of the chart-unit functionality, and most of what you need from outside libraries. -- +-- Chart is designed to be used in conjunction with both the numhask and diagrams preludes. Diagrams.Prelude conatins much of the lens library and many re-exports that clash with NumHask, so best to import qualified. +-- -- > {-# NoImplicitPrelude #-} -- > {-# OverloadedString #-} -- > import NumHask.Prelude +-- > import qualified Diagrams.Prelude as D -- > import Chart -- --- chart-unit is designed to be used in conjunction with the numhask prelude. --- - module Chart - ( module Chart.Core + ( -- * chart-unit + module Chart.Core , module Chart.Arrow , module Chart.Glyph , module Chart.Hud @@ -20,24 +21,25 @@ , module Chart.Rect , module Chart.Text , module Chart.Lenses + + -- * numhask-range , module NumHask.Pair , module NumHask.Space , module NumHask.Range , module NumHask.Rect + + -- * color , module Data.Colour , module Data.Colour.Palette.Harmony , module Data.Colour.Palette.ColorSet - , Diagram - , triangle - , square - , circle - , SVG - , B - , Renderable - , Path - , V2 + + -- * Default , Default(..) + + -- * Text , Text + + -- * scratch pad , scratch ) where @@ -54,7 +56,7 @@ import Data.Colour.Palette.Harmony import Data.Default (Default(..)) import Data.Text -import Diagrams.Backend.SVG (SVG, B) +import Diagrams.Backend.SVG (SVG) import Diagrams.Prelude import NumHask.Pair import NumHask.Range diff --git a/src/Chart/Arrow.hs b/src/Chart/Arrow.hs --- a/src/Chart/Arrow.hs +++ b/src/Chart/Arrow.hs @@ -1,6 +1,6 @@ {-# OPTIONS_GHC -Wall #-} --- | Charts that depict gradients and similar, using arrows +-- | Charts that depict gradients and similar data, using arrows in positions module Chart.Arrow ( Arrow(..) @@ -22,6 +22,7 @@ import Data.Ord (max) import Diagrams.Prelude hiding (width, D, Color, project) +-- | todo: quite a clunky specification of what an arrow is (or could be) data ArrowOptions a = ArrowOptions { arrowMinLength :: a , arrowMaxLength :: a @@ -36,7 +37,7 @@ instance Default (ArrowOptions Double) where def = ArrowOptions 0.02 0.2 0.01 0.1 0.002 0.005 ublue dart --- | equalize the arrow space width with the data space one. +-- | Equalize the arrow space width with the data space one. -- this creates the right arrow sizing in physical chart space normArrows :: [Arrow] -> [Arrow] normArrows xs = @@ -52,17 +53,20 @@ width (space $ arrowDir <$> xs :: Rect Double)) <$> as --- | an arrow structure contains position, direction and size information +-- | An arrow structure contains position, direction and size information data Arrow = Arrow { arrowPos :: Pair Double -- position of arrow tail , arrowDir :: Pair Double -- direction and strength of arrow } deriving (Eq, Show) --- | arrows rescale data across position, and between position and arrow direction --- note that, due t0 all this scaling stuff, there is no such thing as a single arrow_ chart +-- | Rescale data across position, and between position and arrow direction. -- --- > arrows (def {arrowMaxLength=0.5,arrowMaxHeadLength=0.2,arrowMaxStaffWidth=0.01}) [Arrow (Pair x (sin (5*x))) (Pair x (cos x)) | x<-grid MidPos (one::Range Double) 100] +-- note that, due to this auto-scaling, there is no such thing as a single arrow_ chart -- +-- > arrows (def {arrowMaxLength=0.5,arrowMaxHeadLength=0.2,arrowMaxStaffWidth=0.01}) +-- > [Arrow (Pair x (sin (5*x))) (Pair x (cos x)) | +-- > x<-grid MidPos (one::Range Double) 100] +-- -- ![arrows example](other/arrowsExample.svg) -- arrows :: (Traversable f) => ArrowOptions Double -> f Arrow -> Chart b @@ -117,9 +121,11 @@ (\(Arrow d arr) -> Arrow (project r asp d) (project r asp arr)) <$> xs) optss xss --- | an arrow chart scaled to its own range +-- | An arrow chart scaled to its own range -- --- > let as = normArrows [Arrow (Pair x y) (Pair (sin 1/x+0.0001) (cos 1/y+0.0001)) | x<-grid MidPos (one::Range Double) 20, y<-grid MidPos (one::Range Double) 20] +-- > let as = normArrows [Arrow (Pair x y) (Pair (sin 1/x+0.0001) (cos 1/y+0.0001)) | +-- > x<-grid MidPos (one::Range Double) 20, +-- > y<-grid MidPos (one::Range Double) 20] -- > arrowChart_ [def] asquare [as] -- -- ![arrowChart_ example](other/arrowChart_Example.svg) diff --git a/src/Chart/Core.hs b/src/Chart/Core.hs --- a/src/Chart/Core.hs +++ b/src/Chart/Core.hs @@ -5,16 +5,29 @@ {-# OPTIONS_GHC -fno-warn-incomplete-patterns #-} #endif +-- | In making a chart, there are three main size domains you have to be concerned about: +-- +-- - the range of the data being charted. This range is often projected onto chart elements such as axes and labels. A data range in two dimensions is a 'Rect' a. +-- +-- - the scale of various chart primitives and elements. The overall dimensions of the chart canvas - the rectangular shape on which the data is represented - is referred to as an 'Aspect' in the api, and is a wrapped 'Rect' to distinguish aspects from rect ranges. The default chart options tend to be callibrated to Aspects around widths of one. +-- +-- - the size of the chart rendered as an image. Backends tend to shrink charts to fit the rectangle shape specified in the render function, and a loose sympathy is expected between the aspect and a chart's ultimate physical size. +-- +-- Jumping ahead a bit, the code snippet below draws vertical lines using a data range of "Rect 0 12 0 0.2" (slightly different to the actual data range), using a widescreen (3:1) aspect, and renders the chart as a 300 by 120 pixel svg: +-- +-- > fileSvg "other/scaleExample.svg" (300,120) $ +-- > withHud (hudAspect_ .~ widescreen $ hudRange_ .~ Just (Rect 0 12 0 0.2) $ def) +-- > (lineChart (repeat def)) ((\x -> [Pair x 0, Pair x (x/100)]) <$> [0..10]) +-- +-- ![scale example](other/scaleExample.svg) +-- module Chart.Core - ( -- * chart - -- - -- $chart + ( -- * Chart types Chart , UChart(..) , combine - -- * scaling - -- - -- $scaling + + -- * Scaling , range , projectss , Aspect(..) @@ -29,37 +42,35 @@ , alignHU , alignHTU , alignVU - -- * combinator + + -- * Combinators -- - -- $combinator + -- | The concept of a point on a chart is the polymorphic 'R2' from the 'linear' library. Diagrams most often uses 'Point', which is a wrapped 'V2'. The 'Pair' type from 'numhask-range' is often used as a point reference. , positioned , p_ , r_ + , stack , vert , hori , sepVert , sepHori + -- * IO - -- - -- $io , fileSvg - -- * color + + -- * Color -- - -- $color + -- | chart-unit exposes the 'colour' and 'palette' libraries for color combinators , ucolor , ublue , ugrey - , ugreen - , ured - -- * errata - -- - -- $errata + + -- * Compatability , scaleX , scaleY , scale ) where -import Data.Colour.Palette.ColorSet import Diagrams.Backend.SVG (SVG, renderSVG) import Diagrams.Prelude hiding (Color, D, aspect, project, scale, scaleX, scaleY, zero) @@ -69,16 +80,14 @@ import NumHask.Rect import NumHask.Space --- $chart +-- | A Chart is simply a type synonym for a typical Diagrams object. A close relation to this type is 'Diagram' 'B', but this usage tends to force a single backend (B comes from the backend libraries), so making Chart b's maintains backend polymorphism. -- --- base chart type --- | A Chart is simply a type synonym for a typical Diagrams object. A close relation to this type is 'Diagram' 'B', but this usage tends to force a single backend (B comes from the backend libraries), so this is preferred to maintain backend polymorphism. --- Just about everything - text, circles, lines, triangles, charts, axes, titles, legends etc - are 'Chart's, which means that most things are amenable to full use of the 'diagrams-lib' library. +-- Just about everything - text, circles, lines, triangles, charts, axes, titles, legends etc - are 'Chart's, which means that most things are amenable to full use of the combinatorially-inclined diagrams-lib. type Chart b = (Renderable (Path V2 Double) b) => QDiagram b V2 Double Any --- | a UChart is mostly a late binding of the Chart Aspect that is to be projected on to and the data. +-- | a UChart provides a late binding of a chart Aspect so multiple charts can be rendered using the same range. data UChart a b = UChart { uchartRenderer :: () => Aspect -> Rect Double -> a -> Chart b @@ -92,9 +101,7 @@ where rall = fold $ (\(UChart _ r1 _) -> r1) <$> qcs --- $scaling --- --- scaling functionality +-- | project a double-containered set of data to a new Rect range projectss :: (Functor f, Functor g) => Rect Double @@ -103,23 +110,27 @@ -> g (f (Pair Double)) projectss r0 r1 xyss = map (project r0 r1) <$> xyss +-- | determine the range of a double-containered set of data range :: (Foldable f, Foldable g) => g (f (Pair Double)) -> Rect Double range xyss = foldMap space xyss --- | the rendering plane -newtype Aspect = Aspect - { aspectRect :: Rect Double - } +-- | a wrapped Rect specifying the shape od the chart canvas. +-- +-- The Aspect tends to be: +-- +-- - independent of the data range +-- - expressed in terms around a width magnitude of one. chart default options are callibrated to this convention. +newtype Aspect = Aspect (Rect Double) -- | the rendering aspect of a chart expressed as a ratio of x-plane : y-plane. aspect :: Double -> Aspect aspect a = Aspect $ Ranges ((a *) <$> one) one --- | 1:1 +-- | a 1:1 aspect asquare :: Aspect asquare = aspect 1 --- | 1.5:1 +-- | a 1.5:1 aspect sixbyfour :: Aspect sixbyfour = aspect 1.5 @@ -127,11 +138,11 @@ golden :: Aspect golden = aspect 1.61803398875 --- | 3:1 +-- | a 3:1 aspect widescreen :: Aspect widescreen = aspect 3 --- | 5:1 +-- | a skinny 5:1 aspect skinny :: Aspect skinny = aspect 5 @@ -147,7 +158,7 @@ | AlignMid | AlignBottom --- | conversion of horizontal alignment to one :: Range Double +-- | conversion of horizontal alignment to (one :: Range Double) limits alignHU :: AlignH -> Double alignHU a = case a of @@ -163,7 +174,7 @@ AlignCenter -> -0.5 AlignRight -> -1 --- | conversion of vertical alignment to one :: Range Double +-- | conversion of vertical alignment to (one :: Range Double) limits alignVU :: AlignV -> Double alignVU a = case a of @@ -171,10 +182,7 @@ AlignMid -> 0 AlignBottom -> 0.5 --- $combinator --- --- chart combinators --- | position an element +-- | position an element at a point positioned :: (R2 r) => r Double -> Chart b -> Chart b positioned p = moveTo (p_ p) @@ -186,21 +194,30 @@ r_ :: R2 r => r a -> V2 a r_ r = V2 (r ^. _x) (r ^. _y) +-- | foldMap for beside; stacking chart elements in a direction, with a premap +stack :: + (R2 r, V a ~ V2, Foldable t, Juxtaposable a, Semigroup a, N a ~ Double, Monoid a) + => r Double + -> (b -> a) + -> t b + -> a +stack dir f xs = foldr (\a x -> beside (r_ dir) (f a) x) mempty xs + -- | combine elements vertically, with a premap vert :: - (V a ~ V2, Foldable t, Juxtaposable a, Semigroup a, Num (N a), Monoid a) - => (a -> a) - -> t a + (V a ~ V2, Foldable t, Juxtaposable a, Semigroup a, N a ~ Double, Monoid a) + => (b -> a) + -> t b -> a -vert f xs = foldr (\a x -> beside (r2 (0, -1)) (f a) x) mempty xs +vert = stack (Pair 0 -1) -- | combine elements horizontally, with a premap hori :: - (V a ~ V2, Foldable t, Juxtaposable a, Semigroup a, Num (N a), Monoid a) - => (a -> a) - -> t a + (V a ~ V2, Foldable t, Juxtaposable a, Semigroup a, N a ~ Double, Monoid a) + => (b -> a) + -> t b -> a -hori f xs = foldr (\a x -> beside (r2 (1, 0)) (f a) x) mempty xs +hori = stack (Pair 1 0) -- | horizontal separator sepHori :: Double -> Chart b -> Chart b @@ -210,31 +227,23 @@ sepVert :: Double -> Chart b -> Chart b sepVert s x = beside (r2 (1, 0)) x (strutY s) --- $io --- -- | write an svg to file fileSvg :: FilePath -> (Double, Double) -> Diagram SVG -> IO () fileSvg f s = renderSVG f (mkSizeSpec (Just <$> r2 s)) --- $color --- +-- | convert an rgba spec to an AlphaColour ucolor :: (Floating a, Ord a) => a -> a -> a -> a -> AlphaColour a ucolor r g b o = withOpacity (sRGB r g b) o +-- | the official chart-unit blue ublue :: AlphaColour Double ublue = ucolor 0.365 0.647 0.855 0.5 -ugreen :: AlphaColour Double -ugreen = rybColor 11 `withOpacity` 0.5 - -ured :: AlphaColour Double -ured = rybColor 0 `withOpacity` 0.5 - +-- | the official chart-unit grey ugrey :: AlphaColour Double -ugrey = ucolor 0.5 0.5 0.5 0.5 +ugrey = ucolor 0.4 0.4 0.4 1 --- $errata --- +-- | These are difficult to avoid instance R1 Pair where _x f (Pair a b) = (`Pair` b) <$> f a @@ -242,10 +251,10 @@ _y f (Pair a b) = Pair a <$> f b _xy f p = fmap (\(V2 a b) -> Pair a b) . f . (\(Pair a b) -> V2 a b) $ p --- avoiding the diagrams throw on zero divides eps :: N [Point V2 Double] eps = 1e-8 +-- | the diagrams scaleX with a zero divide guard to avoid error throws scaleX :: (N t ~ Double, Transformable t, R2 (V t), Diagrams.Additive (V t)) => Double @@ -257,6 +266,7 @@ then eps else s) +-- | the diagrams scaleY with a zero divide guard to avoid error throws scaleY :: (N t ~ Double, Transformable t, R2 (V t), Diagrams.Additive (V t)) => Double @@ -268,6 +278,7 @@ then eps else s) +-- | the diagrams scale with a zero divide guard to avoid error throws scale :: (N t ~ Double, Transformable t, R2 (V t), Diagrams.Additive (V t)) => Double diff --git a/src/Chart/Glyph.hs b/src/Chart/Glyph.hs --- a/src/Chart/Glyph.hs +++ b/src/Chart/Glyph.hs @@ -1,5 +1,6 @@ {-# OPTIONS_GHC -Wall #-} +-- | Glyphs are (typically) small shapes symbolically representing a data point. module Chart.Glyph ( GlyphOptions(..) , hline_ @@ -11,6 +12,9 @@ , glyphChart_ , lglyphChart , lglyphChart_ + , circle + , square + , triangle ) where import Chart.Core @@ -32,15 +36,15 @@ instance Default (GlyphOptions b) where def = GlyphOptions 0.03 ublue ugrey 0.015 circle --- | vertical line glyph shape +-- | Vertical line glyph shape with a reasonable thickness at "vline_ 1" vline_ :: Double -> Double -> Chart b vline_ fatness x = vrule x # scaleX (1.6 / 0.5 * fatness) --- | horizontal line glyph shape +-- | Horizontal line glyph shape with a reasonable thickness as "hline_ 1" hline_ :: Double -> Double -> Chart b hline_ fatness x = hrule x # scaleY (1.6 / 0.5 * fatness) --- | create a glyph from a configuration +-- | Create a glyph. -- -- > let glyph_Example = glyph_ def -- @@ -49,7 +53,7 @@ glyph_ :: GlyphOptions b -> Chart b glyph_ (GlyphOptions s c bc bs shape) = shape s # fcA c # lcA bc # lwN bs --- | positioned glyphs +-- | Create positioned glyphs. -- -- > let ps = [Pair (x/10) ((sin x)/10) | x<-[0..10]] -- > glyphs def ps @@ -59,7 +63,7 @@ glyphs :: (R2 r, Traversable f) => GlyphOptions b -> f (r Double) -> Chart b glyphs opts xs = mconcat $ toList $ (\x -> positioned x (glyph_ opts)) <$> xs --- | a chart of glyphs +-- | A chart of glyphs glyphChart :: (Traversable f) => [GlyphOptions b] @@ -70,7 +74,7 @@ glyphChart optss (Aspect asp) r xyss = mconcat $ zipWith glyphs optss (projectss r asp xyss) --- | a chart of glyphs scaled to its own range +-- | A chart of glyphs scaled to its own range -- -- > let gopts = [def,def {glyphBorderColor=withOpacity red 0.2, glyphShape=triangle}] -- > let p_1 = [Pair x (sin (x/10)) | x<-[0..100]] @@ -87,7 +91,7 @@ -> Chart b glyphChart_ optss asp xyss = glyphChart optss asp (range xyss) xyss --- | labelled, positioned glyphs +-- | Create labelled, positioned glyphs. -- -- > lglyphs def def $ zip (show <$> [0..]) ps -- @@ -103,7 +107,7 @@ mconcat $ toList $ (\(t, x) -> moveTo (p_ x) $ labelled lopts t (glyph_ gopts)) <$> xs --- | a chart of labelled glyphs +-- | A chart of labelled glyphs lglyphChart :: (Traversable f) => [LabelOptions] @@ -122,7 +126,7 @@ (map fst . toList <$> xyss) (projectss r asp (map snd . toList <$> xyss))) --- | a chart of labelled glyphs scaled to its own range +-- | A chart of labelled glyphs scaled to its own range -- -- > let g = Pair <$> [0..5] <*> [0..5] :: [Pair Int] -- > let xs = [(\(p@(Pair x y)) -> ((show x <> "," <> show y), fromIntegral <$> p)) <$> g] diff --git a/src/Chart/Hud.hs b/src/Chart/Hud.hs --- a/src/Chart/Hud.hs +++ b/src/Chart/Hud.hs @@ -4,11 +4,13 @@ {-# OPTIONS_GHC -fno-warn-incomplete-patterns #-} #endif --- | collective noun for axes, titles & legends +-- | Hud (Heads up display) is a collective noun for axes, titles & legends +-- +-- todo: refactor me please. A hud for a chart uses 'beside' to combine elements, and this restricts the hud to the outside of the chart canvas. This tends to make hud elements (such as gridlines) harder to implement than they should be. module Chart.Hud ( HudOptions(..) - , withHud , hud + , withHud , Orientation(..) , Place(..) , placeOutside @@ -36,7 +38,7 @@ import Data.List (nub) import Data.Ord (max) import Diagrams.Prelude - hiding (Color, D, (*.), (<>), project, width, zero) + hiding (Color, D, (*.), (<>), project, width, zero, (<>)) import qualified Diagrams.TwoD.Size as D import Formatting import NumHask.Pair @@ -45,8 +47,9 @@ import NumHask.Rect import NumHask.Space --- | various options for a hud --- Defaults to an x- and y-axis, sixbyfour aspect, no titles and no legends +-- | Various options for a hud. +-- +-- Defaults to the classical x- and y-axis, a sixbyfour aspect, no titles and no legends data HudOptions b = HudOptions { hudPad :: Double , hudAxes :: [AxisOptions b] @@ -60,7 +63,7 @@ instance Default (HudOptions b) where def = HudOptions 1.1 [defXAxis, defYAxis] [] [] Nothing sixbyfour clear --- | create a hud based upon HudOptions +-- | Create a hud. -- -- > hud def -- @@ -104,7 +107,8 @@ -- > withHudExample = withHud hopts (lineChart lopts) ls -- > where -- > hopts = def {hudTitles=[(def,"withHud Example")], --- > hudLegends=[def {legendChartType=zipWith (\x y -> (LegendLine x 0.05, y)) lopts ["line1", "line2", "line3"]}]} +-- > hudLegends=[def {legendChartType=zipWith (\x y -> +-- > (LegendLine x 0.05, y)) lopts ["line1", "line2", "line3"]}]} -- -- ![withHud example](other/withHudExample.svg) -- @@ -129,7 +133,7 @@ [] ] --- | placement of hud elements around (what is implicity but maybe shouldn't just be) a rectangular canvas +-- | Placement of hud elements around (what is implicity but maybe shouldn't just be) a rectangular canvas data Place = PlaceLeft | PlaceRight @@ -137,7 +141,7 @@ | PlaceBottom deriving (Eq, Show) --- | direction to place stuff on the outside of the built-up chart +-- | Direction to place stuff on the outside of the built-up hud placeOutside :: Num n => Place -> V2 n placeOutside pl = case pl of @@ -146,7 +150,7 @@ PlaceLeft -> r2 (-1, 0) PlaceRight -> r2 (1, 0) --- | a strut to add to a placement +-- | A gap to add when placing elements. placeGap :: (Monoid m, Semigroup m, Ord n, Floating n) => Place @@ -160,12 +164,12 @@ strut' PlaceLeft = strutX strut' PlaceRight = strutX --- | orientation for a hud element. Watch this space for curvature! +-- | Orientation for a hud element. Watch this space for curvature! data Orientation = Hori | Vert --- | axes are somewhat complicated. For instance, they contain a range within which tick marks need to be supplied or computed. +-- | Axes are somewhat complicated. For instance, they contain a range within which tick marks need to be supplied or computed. data AxisOptions b = AxisOptions { axisPad :: Double , axisOrientation :: Orientation @@ -220,12 +224,14 @@ -- | create an axis, based on AxisOptions, a physical aspect, and a range -- --- Under-the-hood, the axis function has gone through many a re-factor, and still has a ways to go. A high degree of technical debt tends to acrue here. +-- Under-the-hood, the axis function has gone through many a refactor, and still has a ways to go. A high degree of technical debt tends to acrue here. -- -- > axisExample :: Chart b -- > axisExample = axis aopts one (Range 0 100000) -- > where --- > aopts = def {axisLabel=(axisLabel def) {labelGap=0.0001,labelText=(labelText (axisLabel def)) {textSize=0.06,textAlignH=AlignLeft,textRotation=(-45)}}} +-- > aopts = def {axisLabel=(axisLabel def) { +-- > labelGap=0.0001, labelText=(labelText (axisLabel def)) { +-- > textSize=0.06, textAlignH=AlignLeft, textRotation=(-45)}}} -- -- ![axis example](other/axisExample.svg) -- @@ -279,7 +285,7 @@ , ls) TickPlaced xs -> (project r asp . fst <$> xs, snd <$> xs) --- | style of tick marks on an axis +-- | Style of tick marks on an axis. data TickStyle = TickNone -- ^ no ticks on axis | TickLabels [Text] -- ^ specific labels @@ -287,7 +293,7 @@ | TickExact Int -- ^ exactly n equally spaced ticks | TickPlaced [(Double, Text)] -- ^ specific labels and placement --- | provide a formatted text from a list of numbers so that they are just distinguished. 'precision 2 ticks' means give the tick labels as much precision as is needed for them to be distinguished, but with at least 2 significant figues. +-- | Provide formatted text for a list of numbers so that they are just distinguished. 'precision 2 ticks' means give the tick labels as much precision as is needed for them to be distinguished, but with at least 2 significant figues. precision :: Int -> [Double] -> [Text] precision n0 xs | foldr max 0 xs < 0.01 = precLoop Formatting.expt n0 xs @@ -307,7 +313,7 @@ then s else precLoopInt f (n + 1) xs' --- | options for titles. Defaults to center aligned, and placed at Top of the hud +-- | Options for titles. Defaults to center aligned, and placed at Top of the hud data TitleOptions = TitleOptions { titleText :: TextOptions , titleAlign :: AlignH @@ -338,7 +344,7 @@ pos AlignRight PlaceLeft = Pair 0 (upper aspy) pos AlignRight PlaceRight = Pair 0 (lower aspy) --- | the LegendType reuses all the various chart option types to help formulate a legend +-- | LegendType reuses all the various chart option types to help formulate a legend data LegendType b = LegendText TextOptions | LegendGlyph (GlyphOptions b) @@ -354,7 +360,7 @@ | LegendPixel RectOptions Double --- | legend options. The main missing piece here is to allow for horizontal concatenation. +-- | Legend options. todo: allow for horizontal concatenation. data LegendOptions b = LegendOptions { legendChartType :: [(LegendType b, Text)] , legendInnerPad :: Double diff --git a/src/Chart/Lenses.hs b/src/Chart/Lenses.hs --- a/src/Chart/Lenses.hs +++ b/src/Chart/Lenses.hs @@ -1,10 +1,10 @@ {-# LANGUAGE TemplateHaskell #-} {-# OPTIONS_GHC -Wall #-} --- | Lenses for all the options. Note the trailing underscore naming convention, rather than the more obnoxious _prefixed conventions. +-- | Lenses for all the options. Note the trailing underscore_ naming convention, rather than the more obnoxious prefixed _underscore convention. module Chart.Lenses - -- * tea anyone? - ( arrowMinLength_ + ( -- cup of tea? + arrowMinLength_ , arrowMaxLength_ , arrowMinHeadLength_ , arrowMaxHeadLength_ diff --git a/src/Chart/Line.hs b/src/Chart/Line.hs --- a/src/Chart/Line.hs +++ b/src/Chart/Line.hs @@ -4,11 +4,9 @@ {-# OPTIONS_GHC -fno-warn-incomplete-patterns #-} #endif +-- | Points on a chart connected by lines. module Chart.Line - ( -- * line - -- - -- $line - LineOptions(..) + ( LineOptions(..) , oneline , lines , glines @@ -26,11 +24,10 @@ import NumHask.Prelude import NumHask.Rect --- $line +-- | The main features of a line (that distinguish it from a glyph say) is that: -- --- line chart elements --- The main features of a line (that distinguish it from a glyph say) is that: -- - it exists over multiple points (a line can't exist at a single point) +-- -- - line rendering is normalized to the eventual physical chart -- data LineOptions = LineOptions @@ -41,7 +38,7 @@ instance Default LineOptions where def = LineOptions 0.02 ublue --- | a line connecting a series of points +-- | A line connecting a series of points -- -- > lines def [Pair (10*x/100.0) (cos (x * (10 / 100.0))) | x <- fromIntegral <$> [0..n]] -- @@ -55,12 +52,12 @@ trailLike (trailFromVertices (toList $ p_ <$> xs) `at` p_ p) # lcA c # lwN s --- a single line connecting 2 points +-- | A single line connecting 2 points oneline :: (R2 r) => LineOptions -> Pair (r Double) -> Chart b oneline (LineOptions s c) (Pair x0 x1) = stroke (trailFromVertices [p_ x0, p_ x1] `at` p_ x0) # lcA c # lwN s --- | a chart of lines +-- | A chart of lines lineChart :: (Traversable f) => [LineOptions] @@ -71,11 +68,13 @@ lineChart optss (Aspect asp) r xyss = mconcat $ zipWith lines optss (projectss r asp xyss) --- | a chart of lines scaled to its own range +-- | A chart of lines scaled to its own range -- -- > import Data.Colour.Palette.Harmony (tetrad) --- > ls = map (uncurry Pair) <$> [[(0.0,1.0),(1.0,1.0),(2.0,5.0)], [(0.0,0.0),(3.0,3.0)], [(0.5,4.0),(0.5,0)]] --- > lopts = zipWith (\x y -> LineOptions x (withOpacity y 0.6)) [0.01,0.02,0.005] (tetrad blue) +-- > ls = map (uncurry Pair) <$> [[(0.0,1.0),(1.0,1.0),(2.0,5.0)], +-- > [(0.0,0.0),(3.0,3.0)], [(0.5,4.0),(0.5,0)]] +-- > lopts = zipWith (\x y -> LineOptions x (withOpacity y 0.6)) [0.01,0.02,0.005] +-- > (tetrad blue) -- > lineChart_ lopts sixbyfour ls -- -- ![lineChart_ example](other/lineChart_Example.svg) @@ -84,7 +83,7 @@ (Traversable f) => [LineOptions] -> Aspect -> [f (Pair Double)] -> Chart b lineChart_ optss asp xyss = lineChart optss asp (range xyss) xyss --- | lines with glyphs atop +-- | Lines with glyphs atop eack point glines :: (Traversable f, R2 r) => LineOptions @@ -93,7 +92,7 @@ -> Chart b glines opts gopts xs = glyphs gopts xs <> lines opts xs --- | a chart of glines +-- | A chart of glines glineChart :: (Traversable f) => [LineOptions] @@ -107,9 +106,11 @@ getZipList $ glines <$> ZipList ls <*> ZipList gs <*> ZipList (projectss r asp xyss) --- | a chart of glyphs_lines scaled to its own range +-- | A chart of glyphs_lines scaled to its own range -- --- > let gopts = zipWith (\x y -> def {glyphColor=transparent, glyphBorderColor=withOpacity x 0.6, glyphShape=y}) (tetrad green) [triangle, square, circle] +-- > let gopts = zipWith (\x y -> def {glyphColor=transparent, +-- > glyphBorderColor=withOpacity x 0.6, glyphShape=y}) (tetrad green) +-- > [triangle, square, circle] -- > -- > glineChart_ lopts gopts sixbyfour ls -- diff --git a/src/Chart/Rect.hs b/src/Chart/Rect.hs --- a/src/Chart/Rect.hs +++ b/src/Chart/Rect.hs @@ -29,13 +29,14 @@ ) where import Chart.Core -import Diagrams.Prelude hiding (Color, D, scaleX, scaleY) +import Diagrams.Prelude hiding (Color, D, scaleX, scaleY, (<>)) import NumHask.Pair import NumHask.Prelude import NumHask.Range import NumHask.Rect import NumHask.Space +-- | Just about everything on a chart is a rectangle. data RectOptions = RectOptions { rectBorderSize :: Double , rectBorderColor :: AlphaColour Double @@ -43,9 +44,9 @@ } instance Default RectOptions where - def = RectOptions 0.005 (ucolor 0.4 0.4 0.4 1) ublue + def = RectOptions 0.005 ugrey ublue --- | solid rect, no border +-- | solid rectangle, no border blob :: AlphaColour Double -> RectOptions blob c = RectOptions 0 transparent c @@ -57,19 +58,21 @@ box :: AlphaColour Double -> RectOptions box c = RectOptions 0.015 c transparent --- | place a rect around an Chart +-- | place a rect around an Chart, with a size equal to the chart range bound :: RectOptions -> Double -> Chart b -> Chart b bound (RectOptions bs bc c) p x = (boundingRect x' # lcA bc # lwN bs # fcA c) <> x' where x' = pad p x --- | a single rectangle specified using a Rect x z y w where +-- | A single rectangle specified using a Rect x z y w where -- (x,y) is location of lower left corner -- (z,w) is location of upper right corner -- --- > let opts o = def {labelText = (labelText def) {textColor=withOpacity black 0.8, textSize = 0.3}, labelOrientation=o} --- > labelled (opts (Pair 2 1)) ("z,w") $ labelled (opts (Pair -2 -1)) ("x,y") (rect_ def (Ranges (2*.one) one)) +-- > let opts o = def {labelText = (labelText def) {textColor=withOpacity black 0.8, +-- > textSize = 0.3}, labelOrientation=o} +-- > labelled (opts (Pair 2 1)) ("z,w") $ labelled (opts (Pair -2 -1)) ("x,y") +-- > (rect_ def (Ranges (2*.one) one)) -- -- ![rect_ example](other/rect_Example.svg) -- @@ -91,7 +94,7 @@ lcA bc # lwN bs --- | rectangles with the same configuration +-- | Create rectangles (with the same configuration). -- -- > rects def $ zipWith (\x y -> Rect x (x+1) 0 y) [0..] [1,2,3,5,8,0,-2,11,2,1] -- @@ -113,7 +116,7 @@ -> a rects opts xs = mconcat $ toList $ rect_ opts <$> xs --- | a chart of rects +-- | A chart of rects rectChart :: (Traversable f) => [RectOptions] @@ -124,10 +127,12 @@ rectChart optss (Aspect asp) r rs = mconcat . zipWith rects optss $ fmap (projectRect r asp) <$> rs --- | a chart of histograms scaled to its own range +-- | A chart of rectangles scaled to its own range -- --- > let ropts = [def {rectBorderSize=0}, def {rectBorderSize=0,rectColor=ucolor 0.3 0.3 0.3 0.2}] --- > let pss = transpose [[exp (-(x**2)/2), 0.5 * exp (-(x**2)/8)] | x <- grid LowerPos (Range -5 5) 1000] +-- > let ropts = [def {rectBorderSize=0}, def +-- > {rectBorderSize=0,rectColor=ucolor 0.3 0.3 0.3 0.2}] +-- > let pss = transpose [[exp (-(x**2)/2), 0.5 * exp (-(x**2)/8)] | +-- > x <- grid LowerPos (Range -5 5) 1000] -- > let rss = (zipWith (\x y -> Rect x (x+1) 0 y) [0..]) <$> pss -- > rectChart_ ropts widescreen rss -- @@ -137,13 +142,13 @@ (Traversable f) => [RectOptions] -> Aspect -> [f (Rect Double)] -> Chart b rectChart_ optss asp rs = rectChart optss asp (fold $ fold <$> rs) rs --- | at some point, a color of a rect becomes more about data than stylistic option, hence the pixel. Echewing rect border leaves a Pixel with no stylistic options to choose. +-- | At some point, a color of a rect becomes more about data than stylistic option, hence the pixel. Echewing rect border leaves a Pixel with no stylistic options to choose. data Pixel = Pixel { pixelRect :: Rect Double , pixelColor :: AlphaColour Double } --- | a pixel is a rectangle with a color. +-- | A pixel is a rectangle with a color. -- -- > let opt = def {textColor=withOpacity black 0.8, textSize = 0.2} -- > text_ opt "I'm a pixel!" <> pixel_ (Pixel one ublue) @@ -158,7 +163,7 @@ lcA transparent # lw 0 --- | render multiple pixels +-- | Render multiple pixels -- -- > pixels $ [Pixel (Rect (5*x) (5*x+0.1) (sin (10*x)) (sin (10*x) + 0.1)) (dissolve (2*x) ublue) | x <- grid OuterPos (Range 0 1) 100] -- @@ -167,7 +172,7 @@ pixels :: (Traversable f) => f Pixel -> Chart b pixels ps = mconcat $ toList $ pixel_ <$> ps --- | a chart of pixels +-- | A chart of pixels pixelChart :: (Traversable f) => Aspect -> Rect Double -> [f Pixel] -> Chart b pixelChart (Aspect asp) r pss = mconcat $ pixels . projectPixels r asp . toList <$> pss @@ -175,16 +180,18 @@ projectPixels r0 r1 ps = zipWith Pixel (projectRect r0 r1 . pixelRect <$> ps) (pixelColor <$> ps) --- | a chart of pixels scaled to its own range +-- | A chart of pixels scaled to its own range -- --- > pixelChart_ asquare [[Pixel (Rect x (x+0.05) y (y+0.05)) (blend (x*y+x*x) ugrey ublue) | x <- grid OuterPos (one::Range Double) 20, y <- grid OuterPos (one::Range Double) 20]] +-- > pixelChart_ asquare [[Pixel (Rect x (x+0.05) y (y+0.05)) (blend (x*y+x*x) ugrey ublue) +-- > | x <- grid OuterPos (one::Range Double) 20, +-- > y <- grid OuterPos (one::Range Double) 20]] -- -- ![pixelChart_ example](other/pixelChart_Example.svg) -- pixelChart_ :: (Traversable f) => Aspect -> [f Pixel] -> Chart b pixelChart_ asp ps = pixelChart asp (fold $ fold . map pixelRect <$> ps) ps --- | options to pixelate a Rect using a function +-- | Options to pixelate a Rect using a function data PixelationOptions = PixelationOptions { pixelationGradient :: Range (AlphaColour Double) , pixelationGrain :: Pair Int @@ -193,7 +200,7 @@ instance Default PixelationOptions where def = PixelationOptions (Range ugrey ublue) (Pair 20 20) --- | transform a Rect into Pixels using a function over a Pair +-- | Transform a Rect into Pixels using a function over a Pair pixelate :: PixelationOptions -> Rect Double -> (Pair Double -> Double) -> [Pixel] pixelate (PixelationOptions (Range lc0 uc0) grain) xy f = zipWith Pixel g cs @@ -203,7 +210,7 @@ (Range lx ux) = space xs cs = (\x -> blend ((x - lx) / (ux - lx)) lc0 uc0) <$> xs --- | chart pixels using a function +-- | Chart pixels using a function -- This is a convenience function, and the example below is equivalent to the pixelChart_ example -- -- > pixelateChart def asquare one (\(Pair x y) -> x*y+x*x) diff --git a/src/Chart/Text.hs b/src/Chart/Text.hs --- a/src/Chart/Text.hs +++ b/src/Chart/Text.hs @@ -1,5 +1,5 @@ {-# OPTIONS_GHC -Wall #-} --- | text chart elements +-- | textual chart elements module Chart.Text ( TextOptions(..) , text_ @@ -31,7 +31,7 @@ instance Default TextOptions where def = TextOptions 0.08 AlignCenter (withOpacity black 0.33) EvenOdd 0 --- | create a text primitive +-- | Create a textual chart element -- -- > let text_Example = text_ def "Welcome to chart-unit!" -- @@ -44,7 +44,7 @@ where path = textSVG_ (TextOpts lin2 INSIDE_H KERN False s s) (Text.unpack t) --- | positioned svg text from a list +-- | Creatye positioned text from a list -- -- > let ts = map (Text.singleton) ['a'..'z'] -- > texts def ts [Pair (0.05*x) 0 |x <- [0..5]] @@ -54,7 +54,7 @@ texts :: (R2 r) => TextOptions -> [Text] -> [r Double] -> Chart b texts opts ts ps = mconcat $ zipWith (\p t -> positioned p (text_ opts t)) ps ts --- | a chart of text +-- | A chart of text textChart :: (Traversable f) => [TextOptions] @@ -68,7 +68,7 @@ texts <$> ZipList optss <*> ZipList (map fst . toList <$> xyss) <*> ZipList (projectss r asp (fmap snd . toList <$> xyss)) --- | a chart of text scaled to its own range +-- | A chart of text scaled to its own range -- -- > import qualified Data.Text as Text -- > let ps = [Pair (sin (x*0.1)) x | x<-[0..25]] @@ -80,7 +80,7 @@ textChart_ optss asp xyss = textChart optss asp (range $ fmap snd . toList <$> xyss) xyss --- | a label is a text element attached to a chart element +-- | A label is a text element attached to a chart element data LabelOptions = LabelOptions { labelText :: TextOptions , labelOrientation :: Pair Double -- ^ direction of label @@ -90,7 +90,7 @@ instance Default LabelOptions where def = LabelOptions def (Pair 0 1) 0.05 --- | label a chart element with some text +-- | Label a chart element with some text -- -- > let lopts = def {textAlignH = AlignLeft, textRotation=45} -- > labelled (LabelOptions lopts (Pair 1 1) 0.05) "a label" (glyph_ def) diff --git a/stack.yaml b/stack.yaml --- a/stack.yaml +++ b/stack.yaml @@ -6,14 +6,15 @@ extra-deps: - numhask-0.1.2 - numhask-range-0.1.1 - #- SVGFonts-1.6.0.1 - #- diagrams-lib-1.4.1.2 - #- diagrams-svg-1.4.1 - #- palette-0.1.0.4 - #- diagrams-core-1.4 - #- diagrams-solve-0.1.1 - #- cereal-vector-0.2.0.1 - #- dual-tree-0.2.1 - #- svg-builder-0.1.0.2 + - SVGFonts-1.6.0.2 + - diagrams-lib-1.4.1.2 + - diagrams-svg-1.4.1 + - palette-0.1.0.5 + - diagrams-rasterific-1.4 + - diagrams-core-1.4.0.1 + - diagrams-solve-0.1.1 + - cereal-vector-0.2.0.1 + - dual-tree-0.2.1 + - svg-builder-0.1.0.2 allow-newer: true