carpentries / carpentries/pegboard

[validation] alt-text: check for RMarkdown chunks with plotting commands

Open
#95 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
R
Stars
6
Forks
5
PR merge metrics
No merged PRs in 30d

Description

It should be possible to spot the majority of plot-producing functions in an RMarkdown document:

1. check for chunks that have figure options
1. parse the code in chunks and search for the `plot()` or common plotters such as `ggplot()`
1. warn on chunks that do not have alt and have plot parameters

Here's some example parse data for a ggplot:

``` r
getParseData(parse(text = "ggplot(mpg, aes(x = hwy, y = cty, fill = cyl)) + geom_point()"))
#> line1 col1 line2 col2 id parent token terminal text
#> 51 1 1 1 61 51 0 expr FALSE
#> 42 1 1 1 46 42 51 expr FALSE
#> 1 1 1 1 6 1 3 SYMBOL_FUNCTION_CALL TRUE ggplot
#> 3 1 1 1 6 3 42 expr FALSE
#> 2 1 7 1 7 2 42 '(' TRUE (
#> 4 1 8 1 10 4 6 SYMBOL TRUE mpg
#> 6 1 8 1 10 6 42 expr FALSE
#> 5 1 11 1 11 5 42 ',' TRUE ,
#> 37 1 13 1 45 37 42 expr FALSE
#> 10 1 13 1 15 10 12 SYMBOL_FUNCTION_CALL TRUE aes
#> 12 1 13 1 15 12 37 expr FALSE
#> 11 1 16 1 16 11 37 '(' TRUE (
#> 13 1 17 1 17 13 37 SYMBOL_SUB TRUE x
#> 14 1 19 1 19 14 37 EQ_SUB TRUE =
#> 15 1 21 1 23 15 17 SYMBOL TRUE hwy
#> 17 1 21 1 23 17 37 expr FALSE
#> 16 1 24 1 24 16 37 ',' TRUE ,
#> 21 1 26 1 26 21 37 SYMBOL_SUB TRUE y
#> 22 1 28 1 28 22 37 EQ_SUB TRUE =
#> 23 1 30 1 32 23 25 SYMBOL TRUE cty
#> 25 1 30 1 32 25 37 expr FALSE
#> 24 1 33 1 33 24 37 ',' TRUE ,
#> 29 1 35 1 38 29 37 SYMBOL_SUB TRUE fill
#> 30 1 40 1 40 30 37 EQ_SUB TRUE =
#> 31 1 42 1 44 31 33 SYMBOL TRUE cyl
#> 33 1 42 1 44 33 37 expr FALSE
#> 32 1 45 1 45 32 37 ')' TRUE )
#> 38 1 46 1 46 38 42 ')' TRUE )
#> 43 1 48 1 48 43 51 '+' TRUE +
#> 49 1 50 1 61 49 51 expr FALSE
#> 44 1 50 1 59 44 46 SYMBOL_FUNCTION_CALL TRUE geom_point
#> 46 1 50 1 59 46 49 expr FALSE
#> 45 1 60 1 60 45 49 '(' TRUE (
#> 47 1 61 1 61 47 49 ')' TRUE )
```

Created on 2022-08-15 by the [reprex package](https://reprex.tidyverse.org) (v2.0.1)

We could also use the {xmlparsedata} package to get it in XML format, which will make it easier to parse within the context of this package.

That being said, there are ways this can fail:

1. If the chunk creates a plot and does not immediately display it, then we have to consider tracking outputs or check if the output of the next chunk is the same as the assignment from the previous chunk
2. If the above situation happens, but they do not show the plot until later.
3. Situations that my former self created: functions that create plots as a "bonus" feature (e.g. [`poppr::info_table()`](https://grunwaldlab.github.io/poppr/reference/info_table.html).

For situation 3, we may be able to add in keywords for use in the `SYMBOL_FUNCTION_CALL` parsedata to check, but it should be relatively rare (famous last words).

That also being said, we can not implement this for python code chunks at the moment because we don't know about the parsing rules.

In any case, it

Contributor guide

Open the contributing guide

Research direction

The issue does not name a file or test; start by locating the validation entry point that inspects RMarkdown chunks and review how figure options and alt text are represented. Use R parse data or xmlparsedata for R code, then verify warnings for plot-producing chunks without alt text. Python chunks remain out of scope, and done means the stated R cases are detected without requiring output tracking.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, r
Domain
content, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.