04a-VIInAction.Rmd

# Some basic examples {#VI}

This chapter presents some examples of text output generated by the `VI()` command of the `BrailleR` package. These examples generate output that is displayed in the R session just like any output from standard R commands. Please note however that not all `VI()` commands behave in this fashion; some more advanced uses of `VI()` are discussed in later chapters. 

```{r setup, include=FALSE}
library(knitr)
opts_chunk$set(fig.width=7, fig.height=5, comment="")
library(BrailleR)
```

You will need the `BrailleR` package to be ready for use to follow along with the examples in this chapter. Do this by issuing the command `library(BrailleR)` now.


## Accessibility of graphics in statistical software

Access to graphical representations of information from mathematical or statistical software is quite limited, and therefore limits the blind user's capacity. To this author's knowledge, no mathematical or statistical software has the capability of directly linking to any hardware or software solutions that make the information presented in graphs immediately available. The scalable vector graphic (SVG) format can be used to present a graphic with text embedded into the file for creating access for a blind user [@BulatovGardner2004SVG; @GardnerBulatov2010SVG]. 
Only a small number of statistical software applications have the capacity to create SVG files, but this capacity does not in itself create access because the text that makes them accessible must be added somehow; generally this is a  manual process. The World Wide Web Consortium has a recommendation on the use of SVGs in web content [@SVGStandard] and a number of add-on packages for R make use of SVG because of the opportunity to enrich a graphic's interactivity in webpages; see  [@MurrellPotter2014] for a more detailed discussion of these packages and their functionality. Of particular note is that there are different ways to create an SVG and care must be taken if the maximum accessibility for blind users is ever to be achieved.

In R, a graph can be saved as an SVG using the `svg()` command, but this approach  uses the Cairo SVG format; this has the unfortunate outcome that text is not always preserved as a string, and some shapes are represented by an unstructured set of straight lines [@GardnerBulatov2010SVG]. 
Retention of text as strings is crucial if modifications such as changing the font of any text to the  braille font of a user's choosing is to be managed easily. 
Use of the `gridSVG` package [@MurrellPotter2014] does lead to creation of SVG files that do keep strings of text intact and a hierarchy of graphical elements. These SVG files are more easily modified to create accessibility for blind users that have the technology to interpret them [@GardnerBulatov2010SVG].  
Any graph created in R using functions from the `graphics` package will need to be converted to the `grid` package system for generating graphics through use of the `gridGraphics` [@Murrell2015GridGraphics] package before they are exported in SVG format. Existence of the `gridSVG` and `gridGraphics`  packages means that it should be possible to automate the creation and addition of the necessary text information to the SVG so that the need for  human intervention is minimised.


Add-on scripts for screen reader software, such as JAWS [@JAWS], that attempt to interpret the graphs created by common spreadsheet software has been tried in the past. 
One major problem that results from the creation of these add-on scripts is that of maintenance; unfortunately, the add-on scripts for screen reader software support of spreadsheet applications has not kept pace with the developments of those applications sufficiently enough to give blind people access to the full range of graphs. Sporadic effort has been made at providing access to statistical software through the creation of add-on scripts for screen readers, but little effort was ever given to creating access to the content of graphics. It is unfortunate that these have also not been sufficiently maintained. In this respect the use of R or SAS currently hold an advantage over other commonly used software (notably SPSS and Minitab) for the blind user because no additional scripts for the screen reading software are required. [@GodfreyLoots2014JSS]. R and SAS also work well with the open source screen reader called NVDA [@NVDA].


In conclusion, it seems  that until such time as adaptive technology for creating immediate access via tactile images is commonly available, other solutions will continue to be relevant. In fact, even once the immediacy issue is overcome, there will be a place for solutions such as the `BrailleR` package as a complementary solution rather than a substitute.


At each of the Summer University and Blind Science Conference  events I have shown students that they could use R to gain access to graphed information in a manner almost unparalleled by other statistical software --- the obvious exception to this rule is S-PLUS [@SPLUS-Soft]. 
This advantage comes from the fact that the S language, on which R is built, implicitly stores the data needed to create many  graphs, and this data can be assigned to an object for further manipulation. 
This is not true for graphs created using the ubiquitous `plot()` function however, and many other plotting functions that explicitly return a `NULL` object. We will first look at a graph object that can be explicitly stored. 

## Histograms

The first and most commonly used example demonstrating the value of the BrailleR  package to a blind user is the creation of a histogram. For example, a sighted user wanting a histogram of 1000 randomly chosen values from a standard normal distribution would type

```{r hist, fig.cap="A histogram of 1000 random values from a normal distribution"}
Y = rnorm(1000)
HIST = hist(Y)
```
A simple way for blind users to access the information used to create a graph is to ask R to print the object, using the `print()` command. 
```{r printHist}
print(HIST)
```

The `print()` command can be wrapped around the `hist()` command which avoids explicit storage of the object, but still creates the histogram. This approach can be taken for many graph types where the option of suppressing the graph is not available. The `hist` command gives the user an explicit way of generating the information a blind user may want. Similar functionality exists using the `boxplot.stats()` command for example. Such workhorse functionality is useful but not well-documented.

Given the user has stored the output from the `hist()` function in an object, they can interpret the text to gain some idea of what appears in the histogram. As the object is designed for compatibility and flexibility,  not all of the printed information is relevant to the end user however so some further education or perhaps further processing is still required. I found that some blind users had no appreciation for what a histogram actually looks like. In hindsight, this was reasonable because the way R presents a histogram (and many other graphs) does differ from presentations of the same data in other software.

This "print it out" approach is workable but is far from elegant. On some occasions the data structure listed is just a list of the actual data itself and is therefore not giving blind users the same information as sighted users get from a graph. Blind users need some sort of summarisation tool to replace the graph, and in many instances, are unlikely to have the skill to develop a sound statistical solution for themselves. It is also reliant on users knowing what the various elements printed out are, and how they link to the visual object created for the sighted world. The initial aim of the `BrailleR` package was to take the information created by various functions in R and create a text printout that reduces the amount of information that needs to be processed by blind users. 
In cases like that for the histogram example just introduced, this is a fairly simple task.
For other situations, some further work needs to be done so that the textual information is a useful summary of the graphical information without crossing over the line of interpreting the information for the user.  

So let's see what `BrailleR` is going to offer a blind user instead of the verbose printout seen above. First, the `Describe()` function describes a histogram in a  general sense.
```{r DescribeThatHistogram}
Describe(HIST)
```

Then, we can find out what is shown in the specific histogram using the `VI()` function.
```{r VIThatHistogram}
VI(HIST)
```

The `Describe()` and `VI()` commands actually call the `Describe.histogram()` and `VI.histogram()` commands because R knows it is a histogram that was generated by `hist()` earlier. 

### Important features

The commands used above explicitly stored the histogram. A blind user could use `VI(hist(y))` instead to get the same outcome. In that case, 
the `VI()` command would add to the impact of issuing the `hist()` command because the graphic is still generated for the sighted audience. 
The blind user can then read from the text description so that they can interpret the information that the histogram offers the sighted world.

### Warning

The `VI()` function is partially reliant on the use of the `hist()` function that is included in the `BrailleR` package. If a histogram is created using a command that directly links to the original `hist()` command found in the `graphics` package, then the `VI()` command's output will not be as useful to the blind user. This mainly affects the presentation of the title and axis labels; it should not affect the details of the counts etc. within the histogram itself.

This behaviour could arise if the histogram is sought indirectly. If for example, a function offers (as a side effect) to create a histogram, the author of the function may have explicitly stated use of the `hist()` function from the `graphics` package using `graphics::hist()` instead of `hist()`. Use of `graphics::hist()` will bypass the `BrailleR::hist()` function that the `VI()` command needs. This should not create error messages, but may result in some strange and possibly undesirable output.



## Basic numerical summaries

The standard presentation of a summary of a data frame where each variable is given its own column is difficult for a screen reader user to read as the processing of information is done line by line. For example:

```{r UseSummary}
summary(airquality)
```

The `VI()` command actually calls the `VI.data.frame()` command. It then processes each variable one by one so that the results are printed  variable by variable instead of summary statistic by summary statistic. For example:
```{r UseVI}
VI(airquality)
```



### Important features

Note that in this case, the blind user could choose to present the summary of each variable as generated by the `VI()` command, or the output from the standard `summary()` command. There is no difference in the information that is ultimately presented in this case.


## BrailleR commands used in this chapter

The only explicit commands from the `BrailleR` package used in this chapter were the `Describe()` and `VI()` commands.