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.

Get a free account on hypothesis
Optionally install the hypothesis add-on on your browser
Highlight the relevant text and select “highlight” or “annotate”
Your highlights/annotations will remain in place even if the document is updated
Check out the hypothesis icons at the upper right corner of the window of selected html files that were created with hypothesis activated

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

On the iPad, open a drawing app such as FreeForm or Notes and draw a figure
If you have a keyboard, click Cmd Shift 4, and if not, swipe diagonally from the lower left corner to take a screenshot
Using a finger to drag the boxes in the corners to crop the image
Click the share button (box with an up arrow) and click Copy
This will also copy the image into the Mac clipboard
On the Mac, select some text on an html page and click on Annotate
On the Mac open https://postimages.org and click Cmd-V to paste the iPad image into a permanent file
Click the copy icon to the right of the long markdown string (Github markdown)
In the hypothes.is annotation text box click Cmd-V to paste the markdown link to the saved image
When you click on the highlighted text you annotated, the image will show on the right

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

Open a new Freeform window on the Mac
From the top menu select Insert ... Insert from iPhone or iPad ... Add Sketch
Your other active device will automatically accept a new drawing made with your finger or iPencil
Click Done on the small device
The new drawing is inserted in the Freeform window on the Mac
Click Cmd-Shft 4 and select the area to capture from the Freeform window
Cntl-click on the captured image preview and select Save to clipboard
Proceed as above

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)