The cl-spark Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-spark Reference Manual

This is the cl-spark Reference Manual, version 0.1.13, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:24:05 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

ver.0.1.13

Build Status

cl-spark

cl-spark generates a sparkline string for a list of numbers. It is a common lisp implementation of Zach Holman's spark and Gil Gonçalves' vspark with little extension.

The goal of cl-spark is quick data visualization for:

  1. quick-and-dirty tasks (e.g. check the number of http-requests, github-commits, temperature, etc.),
  2. deciding whether the data is worth to real data mining (e.g. monitoring Fukushima Nuclear Power Station),
  3. grasping the secret aesthetic beauty (e.g. visualizing the fibonacci sequence, you can feel the golden ratio).

Note:

Depends-on

Installation

cl-test-grid results:

Auto:

  1. CL-REPL> (ql:quickload :cl-spark)

Manual:

  1. SHELL$ git clone https://github.com/tkych/cl-spark
  2. CL-REPL> (push #p"/path-to-cl-spark/cl-spark/" asdf:*central-registry*)
  3. CL-REPL> (ql:quickload :cl-spark) or (asdf:load-system :cl-spark)

Examples

;;; Spark

(spark '(1 1 2 3 5 8)) => "▁▁▂▃▅█"

;; float, minus
(spark '(1 0 1 0))    => "█▁█▁"
(spark '(1 0 1 0 .5)) => "█▁█▁▄"
(spark '(1 0 1 0 -1)) => "█▄█▄▁"

;; min, max
(spark '(0 30 55 80 33 150))                 => "▁▂▃▅▂█"
(spark '(0 30 55 80 33 150) :min -100)       => "▃▄▅▆▄█"
(spark '(0 30 55 80 33 150) :max 50)         => "▁▅██▅█"
(spark '(0 30 55 80 33 150) :min 30 :max 80) => "▁▁▄█▁█"

;; key
(spark '(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4))))
=> "▄▆█▆▄▂▁▂▄"
(spark '(0 1 2 3 4 5 6 7 8) :key (lambda (x) (cos (* x pi 1/4))))
=> "█▆▄▂▁▂▄▆█"

;; in function
(defun look-bits (n)
  (spark (map 'list #'digit-char-p (write-to-string n :base 2))))

(look-bits 42) => "█▁█▁█▁"
(look-bits 43) => "█▁█▁██"
(look-bits 44) => "█▁██▁▁"
(look-bits 45) => "█▁██▁█"

;; *ticks*
(defvar ternary '(-1 0 1 -1 1 0 -1 1 -1))

(spark ternary)              => "▁▄█▁█▄▁█▁"

(let ((*ticks* #(#\_ #\- #\¯)))
  (spark ternary))           => "_-¯_¯-_¯_"

(let ((*ticks* #(#\▄ #\⎯ #\▀)))
  (spark ternary))           => "▄⎯▀▄▀⎯▄▀▄"


;;; Vspark

;; Life expectancy by WHO region, 2011, bothsexes
;; see. http://apps.who.int/gho/data/view.main.690
(defvar life-expectancies '(("Africa" 56)
                            ("Americans" 76)
                            ("South-East Asia" 67)
                            ("Europe" 76)
                            ("Eastern Mediterranean" 68)
                            ("Western Pacific" 76)
                            ("Global" 70)))

(vspark life-expectancies :key #'second)
=>
"
56                      66                      76
˫-----------------------+------------------------˧
▏
██████████████████████████████████████████████████
███████████████████████████▌
██████████████████████████████████████████████████
██████████████████████████████▏
██████████████████████████████████████████████████
███████████████████████████████████▏
"

(vspark life-expectancies :key #'second
                          :min 50 :max 80
                          :labels (mapcar #'first life-expectancies)
                          :title "Life Expectancy")
=>
"
                 Life Expectancy                  
                      50           65           80
                      ˫------------+-------------˧
               Africa █████▋
            Americans ████████████████████████▎
      South-East Asia ███████████████▉
               Europe ████████████████████████▎
Eastern Mediterranean ████████████████▊
      Western Pacific ████████████████████████▎
               Global ██████████████████▋
"

;; labels, size
(vspark '(1 0 .5) :labels '("on" "off" "unknown") :size 1)
=>
"
     on █
    off ▏
unknown ▌
"

(vspark '(1 0 .5) :labels '("on" "off") :size 1)
=>
"
 on █
off ▏
    ▌
"

(vspark '(1 0) :labels '("on" "off" "unknown") :size 1)
=>
"
 on █
off ▏
"

;; auto-scale
(vspark '(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4)))
                             :size 20)
=>
"
-1.0     0.0     1.0
˫--------+---------˧
██████████▏
█████████████████▏
████████████████████
█████████████████▏
██████████▏
██▉
▏
██▉
█████████▉
"

(vspark '(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4)))
                             :size 10)
=>
"
-1.0   1.0
˫--------˧
█████▏
████████▏
██████████
████████▏
█████▏
█▏
▏
█▏
████▏
"
(vspark '(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4)))
                             :size 7)
=>
"
███▌
█████▉
███████
█████▉
███▌
█▏
▏
█▏
███▌
"

For more examples, see cl-spark/test.lisp

Referece Manual

[Function] SPARK numbers &key min max key

Generates a sparkline string for a list of real numbers.

[Special Variable] *TICKS*

A simple-vector of characters for representation of sparklines. Default


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-spark

Author

Takaya OCHIAI <tkych.repl@gmail.com>

License

MIT License

Description

CL-Spark generates sparkline string for a list of the numbers. CL-spark is a Common Lisp implementation of Zach Holman’s ‘spark’ and Gil Gonçalves’ ‘vspark’ with little extention.

* spark: https://github.com/holman/spark
* vspark: https://github.com/LuRsT/vspark
* cl-spark: https://github.com/tkych/cl-spark

Version

0.1.13

Source

cl-spark.asd (file)

Component

spark.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-spark.asd

Location

cl-spark.asd

Systems

cl-spark (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-spark/spark.lisp

Parent

cl-spark (system)

Location

spark.lisp

Packages

cl-spark

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-spark

Source

spark.lisp (file)

Nickname

spark

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *ticks*

A simple-vector of characters for representation of sparklines. Default is #(#▁ #▂ #▃ #▄ #▅ #▆ #▇ #█).

Examples:

(defvar ternary ’(-1 0 1 -1 1 0 -1 1 -1))

(spark ternary) => "▁▄█▁█▄▁█▁"

(let ((*ticks* #(#_ #- #¯)))
(spark ternary)) => "_-¯_¯-_¯_"

(let ((*ticks* #(#▄ #⎯ #▀)))
(spark ternary)) => "▄⎯▀▄▀⎯▄▀▄"

Package

cl-spark

Source

spark.lisp (file)

Special Variable: *vticks*

A simple-vector of characters for representation of vartical sparklines. Default is #(#▏ #▎ #▍ #▌ #▋ #▊ #▉ #█).

Examples:

;; Japan GDP growth rate, annal
;; see. http://data.worldbank.org/indicator/NY.GDP.MKTP.KD.ZG (defparameter growth-rate
’((2007 . 2.192186) (2008 . -1.041636) (2009 . -5.5269766) (2010 . 4.652112) (2011 . -0.57031655) (2012 . 1.945)))

(vspark growth-rate :key #’cdr :labels (mapcar #’car growth-rate)) =>
"
-5.5269766 -0.4374323 4.652112 ˫———————+———————˧
2007 ██████████████████████████████████▏
2008 ███████████████████▊
2009 ▏
2010 ████████████████████████████████████████████
2011 █████████████████████▉
2012 █████████████████████████████████▏
"

(let ((*vticks* #(#- #0 #+)))
(vspark growth-rate :key (lambda (y-r) (float-sign (cdr y-r))) :labels (mapcar #’car growth-rate)
:size 1))
=>
"
2007 +
2008 -
2009 -
2010 +
2011 -
2012 +
"

Package

cl-spark

Source

spark.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: spark NUMBERS &key MIN MAX KEY

Generates a sparkline string for a list of real numbers.

Usage: SPARK <numbers> &key <min> <max> <key>

* <numbers> ::= <list> of <real-number>
* <min> ::= { <null> | <real-number> }, default is NIL
* <max> ::= { <null> | <real-number> }, default is NIL
* <key> ::= <function>

* <numbers> ~ data.
* <min> ~ lower bound of output.
NIL means the minimum value of the data.
* <max> ~ upper bound of output.
NIL means the maximum value of the data.
* <key> ~ function for preparing data.

Examples:

(spark ’(1 0 1 0)) => "█▁█▁"
(spark ’(1 0 1 0 0.5)) => "█▁█▁▄"
(spark ’(1 0 1 0 -1)) => "█▄█▄▁"

(spark ’(0 30 55 80 33 150)) => "▁▂▃▅▂█" (spark ’(0 30 55 80 33 150) :min -100) => "▃▄▅▆▄█" (spark ’(0 30 55 80 33 150) :max 50) => "▁▅██▅█" (spark ’(0 30 55 80 33 150) :min 30 :max 80) => "▁▁▄█▁█"

(spark ’(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4)))) => "▄▆█▆▄▂▁▂▄"
(spark ’(0 1 2 3 4 5 6 7 8) :key (lambda (x) (cos (* x pi 1/4)))) => "█▆▄▂▁▂▄▆█"

For more examples, see cl-spark/spark-test.lisp

Package

cl-spark

Source

spark.lisp (file)

Function: vspark NUMBERS &key MIN MAX KEY SIZE LABELS TITLE SCALE? NEWLINE?

Generates a vartical sparkline string for a list of real numbers.

Usage: VSPARK <numbers> &key <min> <max> <key> <size>
<labels> <title> <scale?> <newline?>

* <numbers> ::= <list> of <real-number>
* <min> ::= { <null> | <real-number> }, default is NIL
* <max> ::= { <null> | <real-number> }, default is NIL
* <key> ::= <function>
* <size> ::= <integer 1 *>, default is 50
* <labels> ::= <list>
* <title> ::= <object>, default is NIL
* <scale?> ::= <generalized-boolean>, default is T
* <newline?> ::= <generalized-boolean>, default is T

* <numbers> ~ data.
* <min> ~ lower bound of output.
NIL means the minimum value of the data.
* <max> ~ upper bound of output.
NIL means the maximum value of the data.
* <key> ~ function for preparing data.
* <size> ~ maximum number of output columns (contains label). * <labels> ~ labels for data.
* <title> ~ If title is too big for size, it is not printed. * <scale?> ~ If T, output graph with scale for easy to see.
If string length of min and max is too big for size, the scale is not printed.
* <newline?> ~ If T, output graph with newlines for easy to see.

Examples:

;; Life expectancy by WHO region, 2011, bothsexes
;; see. http://apps.who.int/gho/data/view.main.690
(defvar life-expectancies ’(("Africa" 56)
("Americans" 76)
("South-East Asia" 67)
("Europe" 76)
("Eastern Mediterranean" 68) ("Western Pacific" 76)
("Global" 70)))

(vspark life-expectancies :key #’second :scale? nil :newline? nil) =>
"▏
██████████████████████████████████████████████████ ███████████████████████████▌ ██████████████████████████████████████████████████ ██████████████████████████████▏ ██████████████████████████████████████████████████ ███████████████████████████████████▏"

(vspark life-expectancies :min 50 :max 80
:key #’second
:labels (mapcar #’first life-expectancies) :title "Life Expectancy")
=>
"
Life Expectancy
50 65 80 ˫————+————-˧
Africa █████▋
Americans ████████████████████████▎
South-East Asia ███████████████▉
Europe ████████████████████████▎
Eastern Mediterranean ████████████████▊
Western Pacific ████████████████████████▎
Global ██████████████████▋
"

(vspark ’(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4))) :size 20)
"
-1.0 0.0 1.0
˫——–+———˧
██████████▏
█████████████████▏
████████████████████
█████████████████▏
██████████▏
██▉

██▉
█████████▉
"

(vspark ’(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4))) :size 10)
=>
"
-1.0 1.0
˫——–˧
█████▏
████████▏
██████████
████████▏
█████▏
█▏

█▏
████▏
"

(vspark ’(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4))) :size 1)
=>
"









"

For more examples, see cl-spark/spark-test.lisp

Package

cl-spark

Source

spark.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Macros

Macro: aif TEST TRUE-CLAUSE &optional FALSE-CLAUSE
Package

cl-spark

Source

spark.lisp (file)

Macro: awhen TEST &body BODY
Package

cl-spark

Source

spark.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: at-least-two-chars-p X
Package

cl-spark

Source

spark.lisp (file)

Function: ensure-non-double-float X
Package

cl-spark

Source

spark.lisp (file)

Function: generate-bar NUMBER UNIT MIN MAX NUM-CONTENT-TICKS
Package

cl-spark

Source

spark.lisp (file)

Function: generate-scale MIN MAX SIZE MAX-LENGETH-LABEL
Package

cl-spark

Source

spark.lisp (file)

Function: generate-title TITLE SIZE MAX-LENGETH-LABEL
Package

cl-spark

Source

spark.lisp (file)

Function: string-concat &rest STRINGS
Package

cl-spark

Source

spark.lisp (file)

Function: to-string N
Package

cl-spark

Source

spark.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Types

Type: <ticks> ()
Package

cl-spark

Source

spark.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-spark.asd: The cl-spark<dot>asd file
cl-spark/spark.lisp: The cl-spark/spark<dot>lisp file

F
File, Lisp, cl-spark.asd: The cl-spark<dot>asd file
File, Lisp, cl-spark/spark.lisp: The cl-spark/spark<dot>lisp file

L
Lisp File, cl-spark.asd: The cl-spark<dot>asd file
Lisp File, cl-spark/spark.lisp: The cl-spark/spark<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   E   F   G   M   S   T   V  
Index Entry  Section

A
aif: Internal macros
at-least-two-chars-p: Internal functions
awhen: Internal macros

E
ensure-non-double-float: Internal functions

F
Function, at-least-two-chars-p: Internal functions
Function, ensure-non-double-float: Internal functions
Function, generate-bar: Internal functions
Function, generate-scale: Internal functions
Function, generate-title: Internal functions
Function, spark: Exported functions
Function, string-concat: Internal functions
Function, to-string: Internal functions
Function, vspark: Exported functions

G
generate-bar: Internal functions
generate-scale: Internal functions
generate-title: Internal functions

M
Macro, aif: Internal macros
Macro, awhen: Internal macros

S
spark: Exported functions
string-concat: Internal functions

T
to-string: Internal functions

V
vspark: Exported functions

Jump to:   A   E   F   G   M   S   T   V  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*ticks*: Exported special variables
*vticks*: Exported special variables

S
Special Variable, *ticks*: Exported special variables
Special Variable, *vticks*: Exported special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   <  
C   P   S   T  
Index Entry  Section

<
<ticks>: Internal types

C
cl-spark: The cl-spark system
cl-spark: The cl-spark package

P
Package, cl-spark: The cl-spark package

S
System, cl-spark: The cl-spark system

T
Type, <ticks>: Internal types

Jump to:   <  
C   P   S   T