Skip to content

Documenting Fastmath in Clay

Jump to bottom
genmeblog edited this page Oct 20, 2024 · 10 revisions

Introduction

We are documenting all of the functions in Fastmath using Clay (Quarto) book replacing all existing pieces in Codox, Metadoc and Clerk. We document 3.x version (3.x branch).

Cloning

git clone --recurse-submodules git@github.com:generateme/fastmath.git
cd fastmath
git checkout 3.x

Prerequisites

To work on documentation you have to install locally:

  • Quarto (see more about the setup here)
  • R (see more about the setup here)

Quarto is used to build documentation in a book format. R with ggplot2 to render charts.

R and clojisr

You need to install some R packages to make it work:

install.packages(c("tidyverse","svglite","paletteer"), dependencies=T)
install.packages("Rserve",,"http://rforge.net")

Problems

  • When you hit the problem with connecting to R (there can be a case on MacOS and when using Calva) please start the REPL manualy and jack into it.

Goals

By creating a documentation in Clay, we want to:

  • Build consistent documentation based on logical structure + docstrings
  • Add more use cases and give good examples for more complicated functions
  • Perform sanity test of fastmath
  • Illustrate examples with charts, formulas
  • Describe pitfalls

Source

The source of the book is in the clay folder. Code used in generating the book is located in utils/fastmath/dev folder and contains (currently) three namespaces:

  • fastmath/dev/clay - building a book, examples/callouts/tables helpers
  • fastmath/dev/ggplot - charts
  • fastmath/dev/codox - API reference documentation in the Codox style

Building

To build whole book call a code snippet defined in utils/fastmath/dev/clay.clj (the bottom comment section)

Target folder is: docs/clay

Chapters

General structure of the chapter looks like the following example which contains all elements used in documentation.

Some remarks:

^:kindly/hide-code
(ns transform
  (:require [fastmath.transform :as t]

            [fastmath.dev.ggplot :as gg]
            [fastmath.dev.clay :as utls]
            [fastmath.dev.codox :as codox]

            [fastmath.core :as m]))

;; # Transforms {.unnumbered}

;; General description of the topic

;; ::: {.callout-tip title="Defined functions"}
;; * `transformer`
;; * `forward-1d`, `forward-2d`
;; * `reverse-1d`, `reverse-2d`
;; :::

;; ## FFT

;; Details about FFT and use-cases

;; Some examples:

(def fft-real (t/transformer :real :fft ))

(utls/examples-note
  (seq (t/forward-1d fft-real [1 2 -10 1]))
  (seq (t/reverse-1d fft-real [-6 -12 11 -1])))

;; ## Wavelets

;; ## Compression and denoising

;; An use case with charts

(def domain (m/slice-range 0 10 512))
(def signal (map (fn [x] (+ (Math/sin x)
                         (* 0.1 (- (rand) 0.5)))) ;; add some noise
               domain))
(def denoised-signal (t/denoise fft-real signal {:method :hard}))

^:kind/table
[[(gg/->image (gg/line domain signal {:title "Original signal"}))
  (gg/->image (gg/line domain denoised-signal {:title "Denoised signal"}))]]

;; ## Reference

(codox/make-public-fns-table-clay 'fastmath.transform)

image

Charts

Charts are created with ggplot2 R package, however ready to use Clojure charting functions are defined in fastmath.dev.ggplot namespace.

NOTE Please consult before introducing new chart type!

Common options

Most charts accept following common options:

  • :title - chart title
  • :xlab - x-axis label
  • :ylab - y-axis label
  • :xlim - limit x axis
  • :ylim - limit y axis

File or image

There are two helper functions:

  • ->file - save chart to a file (default: img.png)
  • ->image - create BufferedImage which will be embedded in the notebook

Function

(function fn options)

where options include:

  • :x - domain
  • :steps - number of sampled values
  • :color - line color
(gg/function m/tan {:x [m/-TWO_PI m/TWO_PI]
                    :title "tan(x)"
                    :ylab "y=tan(x)"
                    :ylim [-2 2] ;; we need to limit y axis
                    :steps 500})

img

Functions

Multiple functions in one chart with a legend. Accepts sequence of pairs [name function]

(gg/functions [["tan" m/tan]
               ["cot" m/cot]
               ["sin" m/sin]
               ["cos" m/cos]]
              {:x [m/-TWO_PI m/TWO_PI]
               :title "Basic trigonometric functions"
               :ylim [-2 2]
               :steps 500
               :palette gg/palette-blue-1})

img

To show some minor variants or background functions use palette-blue-0

(gg/functions [["basic" m/sin]
                          ["noisy" (fn [x] (+ (m/sin x) (* 0.2 (- (rand) 0.5))))]]
                         {:x [m/-TWO_PI m/TWO_PI]
                          :ylim [-2 2]
                          :steps 500
                          :palette gg/palette-blue-0})

img

Function 2d

(gg/function2d (fn [[x y]] (m/sin (m/* x (m/cos y)))) {:x [m/-TWO_PI m/TWO_PI]
                                                      :y [m/-TWO_PI m/TWO_PI]
                                                      :title "sin(x*cos(y))"
                                                      :legend-name "value"})

img

Lollipop

Line

Scatter

(let [xs (repeatedly 2000 r/grand)
      ys (map (fn [x] (+ (r/grand (+ 0.1 (* x 0.5))) (m/sin (* 2 x)))) xs)]
  (gg/scatter xs ys {:title "Scatter"}))

img

(let [xy (take 1000 (r/sequence-generator :r2 2))]
  (gg/scatter xy nil {:title "R2 low-discrepancy sequence generator"}))

img

Colors and palettes

We use the following colors and palettes:

  • color-main - default dark blue color
  • color-light - light blue
  • palette-blue-0 - blue palette with first color set to color-main
  • palette-blue-1 - only color-main, used for functions chart where lines have different styles (dotted/dashed)
  • :pals/ocean.ice - palette used in function2d

API Reference

API documentation is generated by make-public-fns-table-clay function for given namespace symbol. Use it at the end of the notebook in a reference chapter.

Clone this wiki locally