jot

The goal of jot is to improve reproducability by allowing you to track statistics needed for an Rmd but are too big to open. Some statistics require summarizing large datasets or take a long time to calculate.

jot approaches this with the following organizing principles: 1. Notes should be lockable, so that tests don’t accidentally overwrite existing statistics. 2. We want to know when each statistic was last updated. 3. For collaborative projects, we want to know who last updated each statistic. 4. Records should play well with GitHub, which is done by representing notes as yaml.

Installation

You can install the development version of jot like so:

remotes::install_github('christopherkenny/jot')

You can also install the stable version of jot from CRAN:

install.packages('jot')

Example

The normal workflow with jot is two staged, first is creating notes and second is reading them.

To create notes:

First, we make a notepad, giving it a location and a title.

library(jot)

path <- tempfile(fileext = '.yaml')

jot_new_pad(pad = path, title = 'example')

The contents of the new pad will look like:

title: example
locked: FALSE
home: the_path.yaml

By creating a new notepad, we set it to be the active notepad. The active notepad is represented as a path.

jot_active()
#> [1] "C:\\Users\\chris\\AppData\\Local\\Temp\\RtmpY3ZkIQ\\file67e01bfb40.yaml"

To write to the notepad can use jot():

jot(note = 3, name = 'estimate')

By default, it writes to the active notepad, which is now:

title: example
locked: no
home: the\path.yaml
estimate:
  last_update: 1659545779
  user: chris
  content: 3.0
  quoted: no

jot(note = 4, name = 'estimate')
#> Warning: `name` already exists and `overwrite` is "FALSE". No updates were
#> made.

So, the notepad will still say:

title: example
locked: no
home: the\path.yaml
estimate:
  last_update: 1659545779
  user: chris
  content: 3.0
  quoted: no

We can fix that by explicitly overwriting.

jot(note = 4, name = 'estimate', overwrite = TRUE)

This gives us:

title: example
locked: no
home: the\path.yaml
estimate:
  last_update: 1659545993
  user: chris
  content: 4.0
  quoted: no

We can add other values as long as they have a different name:

jot(note = list(a = 1, b = 2, c = 3), name = 'list_abc', overwrite = TRUE)

We can even add fancier things like data.frames, but this should be limited to small things! The goal of jot is to store summaries and statistics, not all of your data.

jot(data.frame(col1 = 1, col2 = 2, col3 = 3), 'df')

Once we’re happy with the notes, we should lock the notepad.

jot_lock()

This sets the locked value to TRUE (and yes in the yaml).

title: example
locked: yes
home: the\path.yaml
estimate:
  last_update: 1659545993
  user: chris
  content: 4.0
  quoted: no
list_abc:
  last_update: 1659546469
  user: chris
  content:
    a: 1.0
    b: 2.0
    c: 3.0
  quoted: no

To read notes:

In the setup chunk for an Rmd, we add:

library(jot)
jot_activate(pad = path)

Here, we use the same temp path that we were writing to above, but generally this should be something within the project.

Now, we can read out values.

We can skim the note and report back everything:

jot_skim()
#> $estimate
#> [1] 4
#> 
#> $list_abc
#> $list_abc$a
#> [1] 1
#> 
#> $list_abc$b
#> [1] 2
#> 
#> $list_abc$c
#> [1] 3
#> 
#> 
#> $df
#>   col1 col2 col3
#> 1    1    2    3

Or, we can select a specific element that we’ve stored.

jot_read(name = 'estimate')
#> [1] 4

It returns the object of the same type as was inputted, so list_abc is a list:

jot_read(name = 'list_abc')
#> $a
#> [1] 1
#> 
#> $b
#> [1] 2
#> 
#> $c
#> [1] 3