Commenting, Annotating, and Highlighting Web Pages or PDF Documents

Some of the resources on hbiostat.org and fharrell.com have specific discussion pages already set up at datamethods.org. Looks especially for special links to datamethods topics when you see a clickable blue bubble in the right margin of the screen.

If you don’t use datamethods, use annotation and highlighting capabilities of hypothesis. hypothesis allows you to post both public (visible to all users connected to hypothesis) and private (visible only to you) comments/highlights. Here are some steps to get you started.

For MacOS with Safari

Go to web.hypothes.is/start and drag the Hypothesis Bookmarklet to the plus sign at the top right of a Safari window. You can activate hypothes.is from a web page by clicking on the hypothes.is bookmark in your Safari Bookmarks tab. Previous annotations will show, and clicking on one of them will bring up the hypothes.is panel on the right. To add a new annotation, highlight some text and then select an action from the pop-up window.

Previously, the app did not show the hypothes.is sidebar on the right of the browser window unless I prefixed the URL with via.hypothes.is. I installed this shortcut to the share symbol at top right of Safari window. This shortcut is a conversion of the official bookmarklet. When running the shortcut I got a message that scripting actions must be enabled, leading me to an Open Preferences box. This opened a box with headings of General Sidebar Advanced with Advanced highlighted. I clicked to Allow Running Scripts. But I got an invalid javascript error. Removed the permission. Tried the other shortcut here but got a URL error. It didn’t seem to need script running permission though. This link worked when opening a section of a chapter. May be easiest just to manually put via.hypothes.is in front of URL.

Using MacOS and an iPad to Add Drawings in Annotations

You can also use iPhone or iPad to add to a blank drawing opened with FreeForm:

Using Hmisc drawPlot Function to Draw Illustrations for Annotations

Run code like the following in the RStudio console:

require(Hmisc)
d <- drawPlot(Points())   # click points to add, terminate with Esc
par(mar=rep(1, 4))
plot(d)
# To add x- and y-axis labels:
par(mar=c(2, 2, 0.5, 0.5), mgp=c(0.5, 0, 0))
plot(d, xlab='X', ylab='Y')

In the graphics pane, click on Export ... Copy to Clipboard ... Copy Plot then paste the graph into a new postimages.org window and proceed as above.

Using qreport makedot Function to Draw Flowcharts for Annotations

Install the qreport R package and system graphviz app if you haven’t already. Then run something like the following. The .dot and .png files are placed in the current working directory.

require(qreport)
x <- '
a:node 1
b:node 2
c:node 3
a -> {b, c}'
makedot(x, file='z.dot')
system('dot -Tpng z.dot > z.png && open z.png')

While focusing on the png viewing window that popped up, click Cmd-C or other suitable copy command. Then paste this into postimages.org using e.g. Cmd-V.

If you draw the diagram from within a Quarto report, Quarto has graphviz built-in so it will not need to be installed. You will need to view the html report and copy the diagram from within the viewer.

How to Quickly Parmanently Add a Drawing to Source Content

This is for instructors who have control over their Quarto source files who which to interactively create example graphs using the Hmisc drawPlot function. In the following example, drawPlot run once interactively (e.g., click Ctrl-Return on each line of code in RStudio), and the result is saved in mydrawing.rds. The Hmisc runifChanged function senses whether mydrawing.rds already exists, and if so does not run drawPlot again but retrieves the result from mydrawing.rds unless g changes.

```{r}
g <- function() drawPlot(Points())  # more arguments may be passed to drawPlot and Points
# Below the constant zero never changes so this is only run if mydrawing.rds doesn't
# exist yet or g changes
d <- runifChanged(g, 0, file='mydrawing.rds')
par(mar=c(1,4))
plot(d)
```

You can do the same thing with the following code, assuming you manually remove mydrawing.rds whenever the call to drawPlot changes.

if(file.exists('mydrawing.rds')) d <- readRDS('mydrawing.rds')
else {
  d <- drawPlot(Points())
  saveRDS(d, 'mydrawing.rds')
}
par(mar=c(1,4))
plot(d)