Clay 勉強メモ

しんせいたろう

https://scicloj.github.io/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 ...) 』と表現するみたい。なんだかややこしいな。ま、まいいけど。

しんせいたろう

kindlyには kind というネームスペースがある。
namespace 的には

scicloj
└── kindly
    └── v4
        ├── api  # kind の補助作業ネームスペース？
        └── kind # 可視化用ネームスペース

api と kind の関数を確認すると

scicloj.kindly.v4.api

attach-kind-to-value
attach-meta-to-value
consider
hide-code
known-kinds

scicloj.kindly.v4.kind

code
cytoscape
dataset
echarts
edn
fragment
hiccup
hidden
html
image
map
md
observablei
plotly
portal
pprint
reagent
seq
set
smile-model
table
test
var
vector
vega
vega-lite
video