hvega-0.10.0.0: src/Graphics/Vega/VegaLite/Scale.hs
{-# LANGUAGE OverloadedStrings #-}
{-|
Module : Graphics.Vega.VegaLite.Scale
Copyright : (c) Douglas Burke, 2018-2020
License : BSD3
Maintainer : dburke.gw@gmail.com
Stability : unstable
Portability : OverloadedStrings
Scale-related functionality.
-}
module Graphics.Vega.VegaLite.Scale
( ScaleDomain(..)
, ScaleRange(..)
, ScaleNice(..)
, NTimeUnit(..)
-- not for external export
, scaleDomainSpec
, scaleNiceSpec
) where
import qualified Data.Text as T
import Data.Aeson ((.=), object, toJSON)
import Graphics.Vega.VegaLite.Foundation
( Channel
, FieldName
, fromT
, channelLabel
)
import Graphics.Vega.VegaLite.Specification
( VLSpec
, SelectionLabel
)
import Graphics.Vega.VegaLite.Time
( DateTime
, dateTimeProperty
)
{-|
Describes the scale domain (type of data in scale). For full details see the
<https://vega.github.io/vega-lite/docs/scale.html#domain Vega-Lite documentation>.
-}
data ScaleDomain
= DNumbers [Double]
-- ^ Numeric values that define a scale domain.
| DStrings [T.Text]
-- ^ String values that define a scale domain.
| DDateTimes [[DateTime]]
-- ^ Date-time values that define a scale domain.
| DSelection SelectionLabel
-- ^ Scale domain based on a named interactive selection.
-- See also 'DSelectionField' and 'DSelectionChannel', which should
-- be used when a selection is
-- [projected](https://vega.github.io/vega-lite/docs/project.html)
-- over multiple fields or encodings.
--
-- In @0.7.0.0@ the argument type was changed to @SelectionLabel@
-- (which is a type synonym for @Text@).
| DSelectionField SelectionLabel FieldName
-- ^ Use the given selection /and/ associated field, when the selection
-- is projected over multiple fields or encodings.
--
-- @since 0.7.0.0
| DSelectionChannel SelectionLabel Channel
-- ^ Use the given selection /and/ associated encoding, when the selection
-- is projected over multiple fields or encodings.
--
-- @since 0.7.0.0
| DUnionWith ScaleDomain
-- ^ Combine the domain of the data with the provided domain.
--
-- The following example will use a range of at least 0 to 100,
-- but this will be increased if the data (either initially or
-- via any updates to the Vege-Lite visualization) exceeds this:
--
-- @'Graphics.Vega.VegaLite.PScale' ['Graphics.Vega.VegaLite.SDomain' (DUnionWith ('DNumbers' [0, 100]))]@
--
-- Note that 'DUnionWith' should not be nested, but this
-- is not enforced by @hvega@.
--
-- @since 0.6.0.0
| Unaggregated
-- ^ Indicate that a domain of aggregated data should be scaled to
-- the domain of the data prior to aggregation.
scaleDomainSpec :: ScaleDomain -> VLSpec
scaleDomainSpec (DNumbers nums) = toJSON (map toJSON nums)
scaleDomainSpec (DDateTimes dts) = toJSON (map (object . map dateTimeProperty) dts)
scaleDomainSpec (DStrings cats) = toJSON (map toJSON cats)
scaleDomainSpec (DSelection selName) = object ["selection" .= selName]
scaleDomainSpec (DSelectionField selName field) = object [ "selection" .= selName
, "field" .= field ]
scaleDomainSpec (DSelectionChannel selName ch) = object [ "selection" .= selName
, "encoding" .= channelLabel ch ]
scaleDomainSpec (DUnionWith sd) = object ["unionWith" .= scaleDomainSpec sd]
scaleDomainSpec Unaggregated = "unaggregated"
{-|
Describes the way a scale can be rounded to \"nice\" numbers. For full details see the
<https://vega.github.io/vega-lite/docs/scale.html#continuous Vega-Lite documentation>.
Prior to version @0.10.0.0@ the time units were included in the constructors
for @ScaleNice@.
-}
data ScaleNice
= NTU NTimeUnit
-- ^ Time range.
| NInterval NTimeUnit Int
-- ^ \"Nice\" temporal interval values when scaling.
| IsNice Bool
-- ^ Enable or disable nice scaling.
| NTickCount Int
-- ^ Desired number of tick marks in a \"nice\" scaling.
{-|
The time intervals that can be rounded to \"nice\" numbers.
Prior to @0.10.0.0@ these were part of 'ScaleNice'.
-}
data NTimeUnit
= NMillisecond
-- ^ Nice time intervals that try to align with rounded milliseconds.
| NSecond
-- ^ Nice time intervals that try to align with whole or rounded seconds.
| NMinute
-- ^ Nice time intervals that try to align with whole or rounded minutes.
| NHour
-- ^ Nice time intervals that try to align with whole or rounded hours.
| NDay
-- ^ Nice time intervals that try to align with whole or rounded days.
| NWeek
-- ^ Nice time intervals that try to align with whole or rounded weeks.
| NMonth
-- ^ Nice time intervals that try to align with whole or rounded months.
| NYear
-- ^ Nice time intervals that try to align with whole or rounded years.
nTimeUnitSpec :: NTimeUnit -> VLSpec
nTimeUnitSpec NMillisecond = fromT "millisecond"
nTimeUnitSpec NSecond = fromT "second"
nTimeUnitSpec NMinute = fromT "minute"
nTimeUnitSpec NHour = fromT "hour"
nTimeUnitSpec NDay = fromT "day"
nTimeUnitSpec NWeek = fromT "week"
nTimeUnitSpec NMonth = fromT "month"
nTimeUnitSpec NYear = fromT "year"
scaleNiceSpec :: ScaleNice -> VLSpec
scaleNiceSpec (NTU tu) = nTimeUnitSpec tu
scaleNiceSpec (NInterval tu step) =
object ["interval" .= nTimeUnitSpec tu, "step" .= step]
scaleNiceSpec (IsNice b) = toJSON b
scaleNiceSpec (NTickCount n) = toJSON n
{-|
Describes a scale range of scale output values. For full details see the
<https://vega.github.io/vega-lite/docs/scale.html#range Vega-Lite documentation>.
For color scales you can also specify a color [scheme](https://vega.github.io/vega-lite/docs/scale.html#scheme)
instead of range.
Any directly specified range for @x@ and @y@ channels will be ignored. Range can be customized
via the view's corresponding [size](https://vega.github.io/vega-lite/docs/size.html)
('Graphics.Vega.VegaLite.width' and 'Graphics.Vega.VegaLite.height') or via range steps and paddings properties (e.g. 'Graphics.Vega.VegaLite.SCRangeStep')
for band and point scales.
-}
data ScaleRange
= RPair Double Double
-- ^ The minimum and maximum values.
--
-- @since 0.9.0.0
| RHeight Double
-- ^ Specify the width as a number and height as the string @"height"@.
--
-- @since 0.9.0.0
| RWidth Double
-- ^ Specify the height as a number and width as the string @"width"@.
--
-- @since 0.9.0.0
| RNumbers [Double]
-- ^ For [continuous scales](https://vega.github.io/vega-lite/docs/scale.html#continuous),
-- a two-element array indicating minimum and maximum values, or an array with more than
-- two entries for specifying a
-- [piecewise scale](https://vega.github.io/vega-lite/docs/scale.html#piecewise).
--
-- Support for the two-element version may be removed (ie this left only
-- for piecewise scales).
| RNumberLists [[Double]]
-- ^ A scale range comprising of numeric lists, such as custom dash styles for
-- the 'Graphics.Vega.VegaLite.strokeDash' channel encoding.
--
-- @since 0.6.0.0
| RStrings [T.Text]
-- ^ Text scale range for discrete scales.
| RName T.Text
-- ^ Name of a [pre-defined named scale range](https://vega.github.io/vega-lite/docs/scale.html#range-config)
-- (e.g. \"symbol\" or \"diverging\").
{-
TODO:
* TickCount accepts number or TimeInterval but this is a subset of ScaleNice
-}