maria-experts.cljs

;; # Maria for Experts

;; This is a short tour of abstractions we've made in the process of building Maria, which are also available while using the system. It is meant for people with experience using functional programming languages who already know how to evaluate forms in Maria. If you're a beginner to Maria or to programming in general, I recommend starting [here](https://www.maria.cloud/intro).

;; (For the impatient, Command-Enter — Control-Enter on a PC — within a code block with evaluate the code before the cursor.)

;; ## Notebook interface
;;
;; In the notebook tradition exemplified by iPython Notebooks, one has a mix of prose and code with the ability to visualize the results of evaluating a particular piece of code.
;;
;; For example, `jujub-bird` evaluates to a new var containing the value `15`.
(def jujub-bird 15)

;; While `squared` evaluates to a function that returns the square of the number it receives.
(defn squared [x]
  (* x x))

;; And, finally, we can see the effect of applying the `squared` function to `jujub-bird`.
(squared jujub-bird)

;; One problem with this approach is that changes made to earlier definitions do not effect future references automatically. So, for example, changing `jujub-bird` will not result in re-computation of `(squared jujub-bird)`.

;; This can lead to strange inconsistencies between the visible output at a particular moment and the actual meaning of the code.

;; ## Dataflow notebook

;; One way to work around this situation is to use a dataflow paradigm, similar to a spreadsheet, to propagate changes through the notebook based on declared dependencies between code blocks.

;; We call the mechanism we use for this purpose a "cell", after the concept of a spreadsheet cell.

;; In this case, any change to `slithy` will cause `toves` to be re-calculated, which will -- assuming these three blocks have been evaluated once in the past -- result in a circle of the correct size being drawn.

(defcell slithy 4)

(defcell toves (squared @slithy))

(cell (circle @toves))

;; We use `defcell` for named cells, `cell` for anonymous cells, and the `@` sigil to declare references to previously defined cells. This last convention is borrowed from the syntax for clojure `atom`s, whose semantics our cells largely share.

;; Note that we use explicit declaration of cells and dependencies rather than automatically calculating dependencies over all variable references so the programmer has control over the evaluation strategy they prefer in a given situation.

;; ## Temporal Recursion (Sorensen, 2005)

;; We also provide a mechanism for temporal recursion using `interval`. This is similar to Javascript's `setInterval` with the key difference that each invocation of the function will be passed the result of the previous invocation. This can be viewed as a higher order function that converts the function passed to it into an infinite recursive function that's performed at a fixed interval.

;; So, for example, one can create an infinite stream of integers -- i.e. a counter -- that updates every half second by passing `inc` to `interval`:

(defcell counter (interval 500 inc))

;; Here we generate an infinite sequence of random color names at a 250ms interval:
(defcell a-color
  (interval 250 #(rand-nth (seq color-names))))

;; This feature is especially useful in conjuction with the dataflow properies of cells. Here we render a circle that automatically updates its color and position as `counter` and `a-color` change:

(cell (->> (circle 20)
           (position (+ 60 (* 20 (Math/sin @counter))) 
                     (+ 60 (* 20 (Math/cos @counter))))
           (colorize @a-color)))

;; ## Temporal recursion with sequences

;; Given an infinite sequence of random numbers that update once a second:

(defcell random-number
  (interval 1000 #(rand-int 30)))

;; We can use the clojure's built-in sequence functions to maintain a running window of the last ten values from that stream (note that cells provide their most recent computed value at `@self`):

(defcell last-ten 
  (take 10 (conj @self @random-number)))

;; From which we can then generate a live bar graph using only `map` and our `rectangle` drawing primitive:

(cell (map (partial rectangle 12) @last-ten))

;; # DOM and events

;; We also have a `hiccup`/`sablono`-style templating system built in. This allows someone with browser programming experience to create arbitrary HTML and SVG output that will be rendered in place:

(html [:div {:style {:color "white" 
                     :background-color "pink"
                     :font-size 42
                     :font-weight "bold"
                     :height 100
                     :width 100
                     :padding 20}}
       "Hi!"])

;; When paired a cell to maintain state:

(defcell switch false)

;; ... simple interactions are simply specified:

(cell (listen :click 
              (fn [] (swap! switch not)) 
              (if @switch 
                (colorize "red" (circle 40)) 
                (colorize "black" (circle 40)))))

;; Clicking the circle thus drawn will cause the color to toggle.

;; ## A practical example

;; Using cells one can implement a pattern similar to that seen in libraries like Reagent, where application state is stored in a single cell (similar in intent to a `ratom`). Here we create a set of controls for a visualization:

(defcell controls {:x       0
                   :y       0
                   :param-1 30 
                   :param-2 30 
                   :scale   30})

;; Changes to `controls` will be carried along to dependent cells, such that these two functions that will be re-generated as needed:

(defcell ->x
  #(+ (:x @controls) (* (:param-1 @controls) (Math/pow (Math/sin %) 3))))

(defcell ->y
  #(+ (:y @controls) 
      (- (* (:param-2 @controls) (Math/cos %))) 
      (* 5 (Math/cos (* 2 %)))
      (* 2 (Math/cos (* 3 %)))
      (Math/cos (* 4 %))))

;; This anonymous cell calculated ~1400 points by plotting the values returned by the above two functions to x/y coordinates, then converting those points into a path drawn in red with a 3px stroke width:

(cell
 (->> (mapcat #(vector (* (:scale @controls) (@->x %))
                       (* (:scale @controls) (@->y %)))
              (range 0 2200 3.146))
      polygon
      (stroke "red")
      (stroke-width 3)))

;; Any manual change to `controls` will trigger an immediate re-render of the above plot, but it's often more convenient to be able to change values more fluidly.

;; Here we build up a HTML table directly from the `controls` map, with the name of each parameter set beside a slider that updates `controls`. In these few lines of code we are able to create an _ad hoc_ user interface within our notebook and then use that to explore the data:

(->> @controls
     (mapv (fn [[k v]] 
             [:tr 
              [:td {:style {:padding-right 10}} (name k)] 
              [:td [:input {:type "range" :min "1" :max "30" :default-value v 
                            :on-change (value-to-cell! controls k)}]]]))
     (into [:table])
     html)