A literate programming tutorial using my book reading habits

I keep data about my reading habits in Calibre, where I defined a couple of meta data fields, which allow me to record start and end date of each book I read. Other information is read directly from Calibre, which keeps title, authors, genre, and has a plugin to compute the number of pages based on the book length.

Calibre has a function to export all data in CSV. I have a function which makes it into a YAML file, which is the input file for this page. The following code reads the YAML with the books I read and defines a couple of functions which will be useful later.

The first line declares various execution parameters. The code is written in Ruby and executed in a :session, so that values are persisted and share among all other blocks written in the same language. We do not care about outputting the results of the code evaluation in the buffer, hence we can declare :results none.

require 'yaml'
require 'date'
books  = YAML::load_file "../_data/bookstream.yml",
                         permitted_classes: [Date]

# group an array of hashes according to the values of a key and add
# some data, such as the number of books belonging to each group and
# the total number of pages
def group_and_array(key, books)
  grouped = books.group_by { |x| x[key] }
  grouped.map { |k, v| 
    [ k, v.size, v.map { |p| p["pages"] }.inject(&:+) ] 
  }
end

# convert an aoh (= array of hashes) into a csv file.
# assume all entries have the same keys, although not necessarily in
# the same order (do not expect Hash.values to return the values in
# the same order among all entries of the array)
def aoh_to_a aoh
  keys = aoh[0].keys
  array = []
  aoh.each do |entry|
    array << keys.map { |key| entry[key].to_s } 
  end
  array
end

The books variable contains data which we can use to compute various statistics.

Simple answer: science fiction and crime. Is it true, however? To answer this question we use the group_and_array we defined above, which groups book data according to a field, computes the number of items per category, the sum of books per category and returns an array of arrays.

The following piece of code, thus, groups books by genre and returns a table, which can be nicely shown by Org Mode. Notice that we attach a header ([ ["Genre", "Books", "Pages"] ]) and a separation line [nil]. I learned the trick about the separation line here. It allows us to output column headers.

We export both the code and the results of the execution and that we ask Org Mode to show, as results, the value returned from executing the code, that is, an array of arrays, in our case. A nice explanation of the values :results can assume is available in the Org Mode Manual.

header = [["Genre", "Books", "Pages"]] + [nil] 

body = group_and_array("category", books)
# remove books with no genre
body = body.select { |x| x[0] != "" }
# fix Genre string to improve output
body = body.map { |x| [x[0].gsub("_", " ").capitalize, x[1], x[2]] }
# sort it by frequency
body = body.sort { |x, y| x[1] <=> y[1] }.reverse

header + body

The number of pages is computed by a Calibre plugin whose results I cannot check and which could not run on some my entries, since the electronic version of the book was missing.

More precisely: of the books I read, how many books did I start reading in a given year?

Once again, we can use the group_and_array function, grouping by year. This allows to show a table, which we enrich with a textual barplot, built using "-" * N, a Ruby construct to build strings of N repetitions of the given char.

header = [["Year", "Books", "Pages", "Avg. Pages/Day", "Plot" ]] + [nil]

body = group_and_array("started_year", books)
# remove books with no year
body = body.select { |x| x[0] }
# add some stats
body = body.map { |x| [ x[0], x[1], x[2], x[2] / 365, "-" * x[1] ] }
# sort
body = body.sort { |x, y| x[0] <=> y[0] }

header + body

We can plot the data using Gnuplot, passing as input the data of the table built by Ruby. This is achieved by the following source block, which takes as input the table above, through the :var barplot = books-per-year declaration. Notice that we also need to give a name to the table, with the #+NAME: books-per-year declaration.

The reset command in the Gnuplot script is rather useful, as it ensures that all settings are reset to their default values, otherwise Gnuplot will use any setting defined in previous blocks in this buffer.

reset 

set boxwidth 0.5
set grid ytics linestyle 0
set style fill solid 0.20 border 

set terminal svg size 1200,800 font 'Arial,10'

set title "Books Read"
set xlabel "Year"
set ylabel "Number of Books"

plot barplot using 1:2:xtic(1) with boxes lc rgb "#0045FF" title "Books read", \
     barplot using 1:($2+0.25):2 with labels title ""