Clay 勉強メモ

Literate Programming
- code とその説明やその結果などが一覧できるプログラムのスタイルのこと
Kindly
- Kindlyの規約に従ってフォームや値をどの様に表示するかルールを決めている
- データの可視化やノートブックツールでの表示方法を定義
- ユーザはそのデフォルトを使い、必要なら上書きしてカスタマイズする
- Clojureのdependencyとして使う
Clay
- データ可視化とLiterate Programingのための小さなClojure
- Kindlyに準拠
- データ探索とドキュメンテーション作成（HTML, Book, Blog post, Report, Slideshow ... )

vscode calva で hello world

deps.edn

{:deps {org.scicloj/clay {:mvn/version "2-alpha79"}}
 :paths ["src" "notebooks"]}

notebooks/example.clj

(ns example
  (:require [scicloj.kindly.v4.kind :as kind]))

(+ 1 2)

(kind/hiccup
 [:div {:style
        {:background-color "#eeddcc"}}
  [:p "Hello"]])

(kind/md
 ["hello *hello* **hello**"])

(+ 4 5 6)

(map inc [1 2 3])

REPL起動後
コマンドパレット→ Calve : Run Custom REPL ... → n: Clay make namespace as HTML (clj)
http://localhost:1971/
🥳

[2. コマンドパレット→ Calve : Run Custom REPL ... → n: Clay make namespace as HTML (clj) ] の部分が面倒だったのでちょっとだけショートカットキー設定

これでとりあえず、 Calve : Run Custom REPL ... へのショートカットキーを作成した
ショートカットキーに関してはあとでちゃんと勉強する。

deps.edn

{:deps {org.scicloj/clay {:mvn/version "2-alpha79"}
+        scicloj/tablecloth {:mvn/version "7.021"}
+        org.scicloj/noj {:mvn/version "1-alpha25"}}
 :paths ["src" "notebooks"]}

notebooks/example.clj

(ns example
  (:require [scicloj.kindly.v4.kind :as kind]
+            [scicloj.clay.v2.api :as clay]
+            [scicloj.kindly.v4.api :as kindly]
+            [tablecloth.api :as tc]
+            [scicloj.noj.v1.datasets :as datasets]
+            [scicloj.noj.v1.stats :as noj.stats]
+            [scicloj.noj.v1.vis.hanami :as hanami]
+            [scicloj.noj.v1.vis.hanami.templates :as vht]
+            [scicloj.ml.core :as ml]
+            [scicloj.clay.v2.quarto.themes :as quarto.themes]
+            [scicloj.clay.v2.quarto.highlight-styles :as quarto.highlight-styles]
))

hiccup でレンダリング

notebooks/example.clj

(kind/hiccup
 [:div {:style {:background "#efe9e6"
                :border-style :solid}}
  [:ul
   [:li "one"]
   [:li "two"]
   [:li "three"]]])

;; ## アイリスのデータ
    
(-> datasets/iris 
 (hanami/plot vht/rule-chart 
    {:X "sepal-width" 
     :X2 "sepal-length"
     :Y "petal-width"
     :Y2 "petal-length"
     :COLOR "species"
     :SIZE 3
     :OPACITY 0.2}))

APIのエントリーポイントは、(scicloj.clay.v2.api/make!)
https://zenn.dev/link/comments/a0e8d4ffa04bc9 で行ったことを、ネームスペース内で行うには以下のようにする。

ネームスペースをHTMLにレンダリング

notebooks/example.clj


(comment
  (clay/make! {:format [:html] ;; デフォルトなのでなくてもOK
               :source-path "notebooks/example.clj"})
  :rcf)

code を表示しない方法はいくつかある
- 参照：https://scicloj.github.io/clay/#hiding-code
一番サクっとする方法はフォームに metadata を追加する

^{:kindly/hide-code true}
(ns example
  (:require [scicloj.kindly.v4.kind :as kind]
            [scicloj.clay.v2.api :as clay]))

^{:kindly/hide-code true}
(+ 1 2)

^{:kindly/hide-code true}
(kind/hiccup
 [:div {:style
        {:background-color "#eeddcc"}}
  [:p "Hello"]])

ネームスペースをHTMLにレンダリングするが、ブラウザに出力しない(reloadすれば反映される)

notebooks/example.clj

(comment
  (clay/make! {:source-path "notebooks/example.clj"
               :show false})
  :rcf)

複数のネームスペースをHTMLにレンダリングするが、ブラウザには出力しない。（Reloadすると、最後のネームスペースが反映される）

notebooks/example.clj

(comment
  (clay/make! {:source-path ["notebooks/example.clj"
                             "notebooks/test.clj"]
               :show false})
  :rcf)

https://cytoscape.org/ のレンダリングで説明していくのでデータを用意

notebooks/example.clj

(def cytoscape-example
  {:elements {:nodes [{:data {:id "a" :parent "b"} :position {:x 215 :y 85}}
                      {:data {:id "b"}}
                      {:data {:id "c" :parent "b"} :position {:x 300 :y 85}}
                      {:data {:id "d"} :position {:x 215 :y 175}}
                      {:data {:id "e"}}
                      {:data {:id "f" :parent "e"} :position {:x 300 :y 175}}]
              :edges [{:data {:id "ad" :source "a" :target "d"}}
                      {:data {:id "eb" :source "e" :target "b"}}]}
   :style [{:selector "node"
            :css {:content "data(id)"
                  :text-valign "center"
                  :text-halign "center"}}
           {:selector "parent"
            :css {:text-valign "top"
                  :text-halign "center"}}
           {:selector "edge"
            :css {:curve-style "bezier"
                  :target-arrow-shape "triangle"}}]
   :layout {:name "preset"
            :padding 5}})

一つのフォームだけ評価してレンダリング
- 私の環境ではクオート（ '(kind/cytoscape ...) ）の有無に関係なく評価されてレンダリングされる。この動作であってるのかな？

notebooks/example.clj

(comment
  (clay/make! {:source-path "notebooks/example.clj"
               :single-form '(kind/cytoscape
                              cytoscape-example {:element/style {:width "400px"
                                                                 :height "400px"}})})
  :rcf)

:single-valueにすると、
- クオートなしなら、レンダリング
- クオートありなら、式自体を表示

notebooks/example.clj

(comment
  (clay/make! {:source-path "notebooks/example.clj"
               :single-value (kind/cytoscape
                             cytoscape-example {:element/style {:width "400px"
                                                                :height "400px"}})})
  :rcf)

上記は、 :source-path を省略してもレンダリングされる。
この場合は今のネームスペース (*ns*)がレンダリングされる

notebooks/example.clj


(comment
  (clay/make! {:single-form (kind/cytoscape
                             cytoscape-example {:element/style {:width "300px"
                                                                :height "300px"}})})
  :rcf)

Quartoを生成するには、先に、Quarto CLIのインストールが必要
Quarto – Get Started
私はVSCodeを使っているので、QuartoのExtenshion も入れました
- https://marketplace.visualstudio.com/items?itemName=quarto.quarto

ネームスペースを、Quarto qmd ファイルとしてレンダリングして、HTMLファイルへレンダーして、表示

notebooks/example.clj

(comment
  (clay/make! {:format [:quarto :html]
               :source-path "notebooks/example.clj"})
  :rcf)

docs の下に qmd ファイルが生成される
表示されたHTMLが、今までみてきたHTMLとさほど変わらないので、本当にQuartoで生成されたものは分かりづらいですが、ソースみると quarto であることがわかります

スライド
すごい

example.clj


;; # Slides

;; スライドです

(partition-all 4 (range 22))

;; ## A1

(+ 1 2)

;; ## A2

;; # More Slides

(comment
  (clay/make! {:format [:quarto :revealjs]
               :source-path "notebooks/example.clj"})
  :rcf)

Quartoのカスタマイズ
このカスタマイズで右側にTOC、コードハイライトスタイルが nord デザインが適用される。

(comment
  (clay/make! {:format [:quarto :html]
               :source-path "notebooks/example.clj"
               :quarto {:highlight-style :nord
                        :format {:html {:theme :journal}}}}
:rcf)

:nordと :journalはネームスペースの指定でも可

(comment
  (require '[scicloj.clay.v2.quarto.highlight-styles :as quarto.highlight-styles]
           '[scicloj.clay.v2.quarto.themes :as quarto.themes])
  (clay/make! {:format [:quarto :html]
               :source-path "notebooks/example.clj"
               :quarto {:highlight-style quarto.highlight-styles/nord
                        :format {:html {:theme quarto.themes/journal}}}}
:rcf)

ネームスペースのソースディレクトリとファイルを分けて書く

(comment
  (clay/make! {:base-source-path "notebooks/"
               :source-path "example.clj"})
  :rcf)

Quarto Bookは、ドキュメントがまだないので後で

新規でブラウザ（タブ）を開いて描画


(comment
  (clay/browse!)
  :rcf)

設定（ドキュメント作成中だそうです。簡単に説明があったので、それだけ書いときます）
make! のタイミングで４つの設定が読み込まれる。
設定はマージされて、ネストされた一つのマップとして読み込まれる
- clay-default.edn: デフォルト設定
- clay.edn：ユーザーの設定
- :clay：ネームスペースでの設定
- make! ：make!の引数

ドキュメントが出来ていないのでまだ何とも言えないけど、ここから察するに、make!の呼び出しごとにかなり細かい設定ができそう。ネームスペースの設定なんかは便利そうな予感がします。

Kindly
- このスクラップの上記でも書いたが、Kindly は、可視化するためのルールを提供しているみたい
- 今読んでる clay ドキュメントは、Kindlyのデフォルトで作っている
- ユーザはKindlyにしたがって、自分のドキュメントやデータを表示描画させるか指定する流れ
- この流れを『Kindlyがアトバイスする (Kindly advises ...) 』と表現するみたい。なんだかややこしいな。ま、まいいけど。