diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog for `hgg-custom` +## 0.2.0.0 — 2026-08-13 + +- Version lockstep with hgg-core 0.2 (no API changes). +- Bilingual (English / Japanese) haddock. + ## 0.1.0.0 — 2026-07-18 First public release on Hackage. diff --git a/hgg-custom.cabal b/hgg-custom.cabal --- a/hgg-custom.cabal +++ b/hgg-custom.cabal @@ -1,6 +1,6 @@ cabal-version: 3.0 name: hgg-custom -version: 0.1.0.0 +version: 0.2.0.0 extra-doc-files: CHANGELOG.md synopsis: Non-standard / advanced custom marks for hgg (dendrogram, ...) description: @@ -10,7 +10,7 @@ hgg-core's Primitive / customMark API. Add it as a dependency only when you need these specialized visualizations (e.g. for random forests or hierarchical clustering). - . + Currently ships a dendrogram mark (tree diagrams for hierarchical clustering), using pre-baked segments for easy cross-backend parity. license: BSD-3-Clause @@ -31,7 +31,7 @@ import: warnings exposed-modules: Graphics.Hgg.Custom.Dendrogram build-depends: base >= 4.16 && < 5 - , hgg-core ^>= 0.1 + , hgg-core ^>= 0.2 , aeson >= 2.0 && < 3 , text >= 1.2 && < 3 , vector >= 0.12 && < 0.14 diff --git a/src/Graphics/Hgg/Custom/Dendrogram.hs b/src/Graphics/Hgg/Custom/Dendrogram.hs --- a/src/Graphics/Hgg/Custom/Dendrogram.hs +++ b/src/Graphics/Hgg/Custom/Dendrogram.hs @@ -1,20 +1,36 @@ -- | -- Module : Graphics.Hgg.Custom.Dendrogram --- Description : 階層クラスタリングの樹形図 (dendrogram) を custom mark で描く +-- Description : Draws a hierarchical-clustering dendrogram as a custom mark -- Copyright : (c) 2026 Aelysce Project (Toshiaki Honda) -- License : BSD-3-Clause -- --- Phase 48: dendrogram を Phase 51 の **custom mark** で本実装する。 core (@MarkKind@) は +-- [日本語]: dendrogram を __custom mark__ で本実装する。 core (@MarkKind@) は -- 触らない (add-on package)。 -- --- 設計 = __焼き込み (baked segments)__: 樹形図の U 字リンクを「計算済みの線分列 ('DendroSeg')」 +-- [English]: Implements the dendrogram proper as a __custom mark__. It does +-- not touch core (@MarkKind@) — this is an add-on package. +-- +-- [日本語]: 設計 = __焼き込み (baked segments)__: 樹形図の U 字リンクを「計算済みの線分列 ('DendroSeg')」 -- として 'DendroPayload' に持ち、 それを @cmOptions@ (JSON) に焼き込む。 HS の draw closure は -- payload を直接使い、 PS (canvas) の registry は同じ payload JSON を読む — どちらも「線分を -- proj して 'PLine' で描くだけ」なので HS=PS parity が自明。 clustering/レイアウト算法は -- __呼び出し側 (analyze の @dendrogramOf@ 等)__ が行い、 その結果の線分だけをここへ渡す。 -- --- 葉ラベル・軸は本 mark の外 (呼び出し側が数値 x 軸 + @axisBreaksLabeled@ で付ける)。 本 mark は +-- [English]: The design is __baked segments__: the U-shaped links of the tree +-- are held in 'DendroPayload' as a precomputed segment list ('DendroSeg'), +-- which is then baked into @cmOptions@ (JSON). The HS draw closure consumes +-- the payload directly, and the PS (canvas) registry reads the same payload +-- JSON — since both merely project the segments and draw them with 'PLine', +-- HS=PS parity is self-evident. The clustering and layout algorithms are run +-- by __the caller (for example analyze's @dendrogramOf@)__, which passes only +-- the resulting segments here. +-- +-- [日本語]: 葉ラベル・軸は本 mark の外 (呼び出し側が数値 x 軸 + @axisBreaksLabeled@ で付ける)。 本 mark は -- __U 字リンクの線分のみ__を描く。 +-- +-- [English]: Leaf labels and axes live outside this mark (the caller adds them +-- with a numeric x axis plus @axisBreaksLabeled@). This mark draws +-- __only the U-link segments__. {-# LANGUAGE DeriveGeneric #-} {-# LANGUAGE OverloadedStrings #-} module Graphics.Hgg.Custom.Dendrogram @@ -39,8 +55,11 @@ import Graphics.Hgg.Spec (ColRef (ColNum), Layer, RenderCtx (..), customMarkWith, encX, encY) --- | dendrogram の 1 線分 (data 座標)。 x = 葉 slot / node 中点、 y = マージ高 (height)。 +-- | [日本語]: dendrogram の 1 線分 (data 座標)。 x = 葉 slot / node 中点、 y = マージ高 (height)。 -- JSON キーは prefix @seg@ を落とす: @x1/y1/x2/y2/color/width@。 +-- [English]: A single dendrogram segment (in data coordinates). x is the +-- leaf slot / node midpoint, y is the merge height. The JSON keys drop the +-- @seg@ prefix: @x1/y1/x2/y2/color/width@. data DendroSeg = DendroSeg { segX1 :: !Double , segY1 :: !Double @@ -59,12 +78,20 @@ instance FromJSON DendroSeg where parseJSON = Aeson.genericParseJSON segOptions --- | dendrogram 全体の焼き込みペイロード。 線分列 + 軸 range (葉方向 / height 方向)。 +-- | [日本語]: dendrogram 全体の焼き込みペイロード。 線分列 + 軸 range (葉方向 / height 方向)。 -- JSON キーは prefix @dp@ を落とす: @segments/xRange/yRange@ (range は @[lo,hi]@ 配列)。 +-- [English]: The baked payload for the whole dendrogram: the segment list +-- plus the axis ranges (leaf direction / height direction). The JSON keys +-- drop the @dp@ prefix: @segments/xRange/yRange@ (each range is a +-- @[lo,hi]@ array). data DendroPayload = DendroPayload { dpSegments :: ![DendroSeg] - , dpXRange :: !(Double, Double) -- ^ 葉方向 range (例 -0.6 .. n-0.4) - , dpYRange :: !(Double, Double) -- ^ height 方向 range (例 0 .. maxH*1.05) + , dpXRange :: !(Double, Double) + -- ^ [日本語]: 葉方向 range (例 -0.6 .. n-0.4)。 + -- [English]: Leaf-direction range (e.g. -0.6 .. n-0.4). + , dpYRange :: !(Double, Double) + -- ^ [日本語]: height 方向 range (例 0 .. maxH*1.05)。 + -- [English]: Height-direction range (e.g. 0 .. maxH*1.05). } deriving (Show, Eq, Generic) payloadOptions :: Aeson.Options @@ -80,12 +107,16 @@ lowerFirst (c : cs) = Char.toLower c : cs lowerFirst [] = [] --- | PS registry (canvas) と共有する安定 mark id。 +-- | [日本語]: PS registry (canvas) と共有する安定 mark id。 +-- [English]: The stable mark id shared with the PS registry (canvas). dendrogramMarkId :: Text dendrogramMarkId = "dendrogram" --- | dendrogram を 'Layer' として返す (= 普通の mark 同様 @layer (...)@ に入れて使う)。 +-- | [日本語]: dendrogram を 'Layer' として返す (= 普通の mark 同様 @layer (...)@ に入れて使う)。 -- 線分を @cmOptions@ に焼き込み、 'encX'/'encY' で軸 range を束ねる (不可視 anchor 不要)。 +-- [English]: Returns the dendrogram as a 'Layer' (used inside @layer (...)@ +-- just like an ordinary mark). Bakes the segments into @cmOptions@ and +-- binds the axis range via 'encX'/'encY' (no invisible anchor needed). dendrogramMark :: DendroPayload -> Layer dendrogramMark p = customMarkWith dendrogramMarkId (toJSON p) (drawDendro p) @@ -94,8 +125,11 @@ where rangeCol (lo, hi) = ColNum (V.fromList [lo, hi]) --- | payload の線分を 'RenderCtx' で proj して 'PLine' を emit する draw 関数 +-- | [日本語]: payload の線分を 'RenderCtx' で proj して 'PLine' を emit する draw 関数 -- (HS closure が源。 PS registry も同型の draw を手登録する = parity)。 +-- [English]: The draw function that projects the payload's segments via +-- 'RenderCtx' and emits 'PLine's. The HS closure is the source of truth; +-- the PS registry hand-registers an equivalent draw function (for parity). drawDendro :: DendroPayload -> RenderCtx -> [Primitive] drawDendro p ctx = [ PLine (proj (segX1 s) (segY1 s)) (proj (segX2 s) (segY2 s))