Title:	Improved Access for Blind Users
Version:	1.0.2
Date:	2023-07-07
Maintainer:	A. Jonathan R. Godfrey <a.j.godfrey@massey.ac.nz>
Description:	Blind users do not have access to the graphical output from R without printing the content of graphics windows to an embosser of some kind. This is not as immediate as is required for efficient access to statistical output. The functions here are created so that blind people can make even better use of R. This includes the text descriptions of graphs, convenience functions to replace the functionality offered in many GUI front ends, and experimental functionality for optimising graphical content to prepare it for embossing as tactile images.
License:	GPL-2
URL:	https://github.com/ajrgodfrey/BrailleR, http://ajrgodfrey.github.io/BrailleR/
BugReports:	https://github.com/ajrgodfrey/BrailleR/issues
Depends:	R (≥ 3.4.0)
Imports:	devtools, dplyr, extrafont, ggplot2 (≥ 3.0.0), gridGraphics, gridSVG, hunspell, knitr, mathjaxr, moments, quarto, Rdpack, rmarkdown, roloc, rolocISCCNBS, tidyr, whisker, XML, xtable, grDevices
Suggests:	broom, emmeans, ggfortify, installr, lmtest, markdown, multcomp, nortest, rstatix, spelling, tidyverse
VignetteBuilder:	knitr
RdMacros:	mathjaxr, Rdpack
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.1.2
SystemRequirements:	Python 3 and wxPython 4.0
NeedsCompilation:	no
Packaged:	2023-07-09 09:12:35 UTC; ajgodfre
Author:	A. Jonathan R. Godfrey [aut, cre], Debra Warren [aut], Donal Fitzpatrick [ctb], Duncan Murdoch [ctb], Greg Snow [ctb], Henrik Bengtsson [ctb], James Curtis [ctb], James Thompson [aut], JooYoung Seo [ctb], Marshall Flax [ctb], Paul Murrell [aut], Sophie Banks [ctb], Timothy Bilton [aut], Tony Hirst [ctb], Tsan-Kuang Lee [ctb], Volker Sorge [aut], Yihui Xie [ctb]
Repository:	CRAN
Date/Publication:	2023-07-10 19:10:12 UTC

Improved Access for Blind Users

Description

Blind users do not have access to the graphical output from R without printing the content of graph windows to an embosser of some kind. This is not as immediate as is required for efficient access to statistical output. The functions here are created so that blind people can make even better use of R. This includes the text descriptions of graphs, convenience functions to replace the functionality offered in many GUI front ends, and experimental functionality for optimising graphical content to prepare it for embossing as tactile images.

Details

Author(s)

A. Jonathan R. Godfrey Volker Sorge, Debra Warren, Timothy P. Bilton and James Thompson with other contributions.

Maintainer: A. Jonathan R. Godfrey <a.j.godfrey@massey.ac.nz>

References

Godfrey, A.J.R. (2013) “Statistical Software from a Blind Person's Perspective: R is the Best, but we can make it better”, The R Journal 5(1), pp73-79.

Internal functions for adding the necessary XML content for accessible graphs in SVG format

Description

Mostly internal functions for adding XML content to an external file

Details

Not for use as exported functions

Value

Either the filename written to, or NULL

Author(s)

Volker Sorge and A. Jonathan R. Godfrey

Create XML files to sit alongside SVG files in order to make an accessible graph experience.

Description

Creates the necessary XML file for a graph object (as long as it has a class assigned)

Usage

AddXML(x, file)

Arguments

Details

It will create a xml file which has useful information for creating a accessible svg graph experience. However for it to work properly the SVGThis and BrowseSVG function must also be used. As can be seen in the examples it takes a bit of verbose code to use this function. To create easy exploration webpages of a graph use MakeAccessibleSVG.

Value

NULL. This function is solely for the purpose of creating XML files in the current working directory or in a path of the user's choosing.

Author(s)

Volker Sorge, A. Jonathan R. Godfrey and James Thompson

References

P. Dengler et al. (2011) Scalable vector graphics (SVG) 1.1, second edition. W3C recommendation, W3C. http://www.w3.org/TR/2011/REC-XML11-20110816/

See Also

MakeAccessibleSVG

Examples

library(ggplot2)
library(grid)

# Create a simple histogram plot
simpleHist = data.frame(x=rnorm(1e2)) |>
  ggplot(aes(x=x)) +
  geom_histogram()

# Open a new PDF device, but
#discard the output instead of saving it to a file
pdf(NULL)

# Plot the ggplot object on the current device
simpleHist

# Force the plot to be drawn on the device,
#even though the output is being discarded
grid.force()

# Export the plot to an XML file
AddXML(simpleHist, file = "histogram.xml")

# Close the current PDF graphic device
dev.off()

#Cleaning up afterwards
unlink("histogram.xml")

add additional detail to the stored object for a graph

Description

Creates the necessary details that feed into the text descriptions in the VI() function and into the descriptions used in the accessible online versions of the graphs.

Usage

Augment(x)

Arguments

Details

Ought to be treated as an internal function and not used interactively.

Value

The input object is returned with additions to the object. This does not break the S3 class.

Author(s)

A. Jonathan R. Godfrey and Volker Sorge

Examples

x=rnorm(1000)
MyHist=Augment(hist(x))
MyHist

Automatic fixing of typos

Description

Fix up all those annoying typos that come up far too often.

Usage

AutoSpellCheck(file)

Arguments

Details

The word list of typos and their corrections is called ‘AutoSpellList.csv’ and is stored in the user's MyBrailleR folder. The file can be updated to meet the user's specific needs. It should not be over-written by a new installation of BrailleR.

Value

NULL. This function only affects external files.

Author(s)

A. Jonathan R. Godfrey

Convert a graph to a pdf ready for embossing

Description

The first argument to this function must be a call to create a graph, such as a histogram. Instead of opening a new graphics device, the graph will be created in a pdf file, with all text being presented using a braille font. The function is somewhat experimental as the best braille font is not yet confirmed, and a number of examples need to be tested on a variety of embossers before full confidence in the function is given.

Usage

BRLThis(x, file)

Arguments

Details

The user's chosen braille font must be installed. This might include the default font shipped as part of the package.

Value

Nothing within the R session, but a pdf file will be created in the user's working directory.

Author(s)

A. Jonathan R. Godfrey. with contributions from JooYoung Seo and TK Lee.

Open the home page for the BrailleR Project, the Google search engine, the BrailleR in Action book, or the Let's Use R Now (LURN) book in your browser

Description

Visit the BrailleR Project home page for updates, instructions on how to join the mailing list which we call BlindRUG and get the latest downloads; or the Let's Use R Now (LURN) home page to read an online manual for using R. Other commonly used websites can be accessed quickly from the R prompt using the other convenience functions.

Usage

BrailleRHome()

BrailleRInAction()

LURN(BlindVersion = getOption("BrailleR.VI"))

Google()
google()

R4DS()
r4ds()

WriteRHome()

Arguments

Details

Google is a key resource, and so should be the R for Data Science book.

Value

NULL. These functions are for opening a web page and nothing will result in the R session.

Author(s)

A. Jonathan R. Godfrey

Merge svg and xml file in html file

Description

Creates a single HTML file that embeds an SVG diagram and its XML annotations. Then launches a browser tab to allow viewing and interactive exploration of the SVG diagram.

Usage

BrowseSVG(file="test", key=TRUE, footer = TRUE, view=interactive(), ggplot_object = NULL) 

Arguments

Details

A HTML file is written in the current working directory. This HTML file will have the embeded svg and xml files as well as the javascript (diagcess) to help with the exploration of the graph. Note that it is required that you already have a svg and xml file in the current directory for it to work.

It is much easier however to just use the MakeAccessibleSVG function directly which does it all for you

Value

NULL. This function exists for its side effects only.

Author(s)

Volker Sorge and James A. Thompson

See Also

MakeAccessibleSVG, SVGThis, AddXML

Examples

library(ggplot2)
simpleHist = data.frame(x=rnorm(1e2)) |>
  ggplot(aes(x=x)) +
    geom_histogram()
file = "histogram"
pdf(NULL)  # create non-displaying graphics device for SVGThis and AddXML
svgfile = SVGThis(simpleHist, paste0(file, ".svg"),createDevice=FALSE)
xmlfile = AddXML(simpleHist, paste0(file, ".xml")) 
dev.off()  # destroy graphics device, now that we're done with it

BrowseSVG(file)

#Cleaing up from BrowseSVG
unlink(paste0(file, ".svg"))
unlink(paste0(file, ".xml"))
unlink(paste0(file, ".html"))

Investigate data objects

Description

Investigate an object, especially useful at any stage in a pipe chain.

Usage

CheckIt(x, ...)
check_it(x, ...)

what_is(x, ...)
WhatIs(x, ...)

Arguments

Details

The VI() functionality returns a character vector and is not useful inside a pipe chain. In effect, WhatIs() just adds the pipe chain convenience to the VI() tool, while CheckIt() looks at the structure of the data object. The latter is perhaps more useful if you are uncertain that the pipe chain is delivering what you hoped for.

Value

These functions intentionally return (invisibly of course) the original input object so that they can be used within a pipe chain, as is commonly used by the Tidyverse.

Author(s)

A. Jonathan R. Godfrey

Examples

require(dplyr)
airquality %>% CheckIt() %>% arrange(Ozone) %>% head()

clean out unwanted white space from a csv file

Description

A blind user may not see the white space characters surrounding text or numbers in a csv file. These corrupt analyses and are annoying to fix.

Usage

CleanCSV(file)

Arguments

Details

Spits out the csv file in clean form, as well as a back up copy of the original file.

Value

NULL. This function only affects external files.

Author(s)

A. Jonathan R. Godfrey

Open a data object in your chosen spreadsheet software

Description

The chosen data object (data.frame, matrix, or vector) is stored in a temporary csv file. The file is opened while the R terminal/console is suspended until the <enter> key is pressed. This should be done once the spreadsheet software has been closed so that the temporary file is removed and the data object gets updated from the edited csv file. The user must save the csv file if changes are made.

Usage

DataViewer(x, Update = FALSE, New = NULL, Filename = NULL)

Arguments

Details

The following steps should be taken if the intention is to view and possibly edit a data.frame, matrix, or vector:

There are a few quirks with respect to variables that could be interpreted as factors. The process of updating is to write a csv file using code write.csv() and then read it back using code read.csv() after it has been edited. Users must be aware that factors may not register as such, or that character vectors may be interpreted as factors.

Value

If code Update=TRUE and code New=NULL, the original data object is overwritten. To create a new object the user must specify code New.

Author(s)

A. Jonathan R. Godfrey a.j.godfrey@massey.ac.nz

Examples

data(airquality)
DataViewer(airquality, Update=TRUE, New="NewAirQuality")

Deprecated functions

Description

Functions that have become redundant courtesy of development outside the BrailleR package.

Usage

GetPython27(...) 
GetWxPython27(...) 

MakeAllInOneSlide(...)
MakeSlidy(...)
MakeSlideShow(...)

Arguments

Details

These functions are redundant.

A message is printed to inform the user if they are called.

Value

NULL.

Author(s)

A. Jonathan R. Godfrey, is responsible for the deprecation.

Describe method to help visualize plot types.

Description

A function to help describe what a graph model would look like, to a vision impaired person.

Usage

Describe(x, VI=FALSE, ...)

## S3 method for class 'histogram'
Describe(x, VI=FALSE, ...)

## S3 method for class 'ggplot'
Describe(x,VI=FALSE, whichLayer=NULL, ...)

Arguments

Details

Describe() is for explaining how a given type of graph appears to a sighted person and is intended for use by blind people who do not know how the graph looks. There is room to add hints for displaying the graphs in a more visually appealing manner.

The text description will only be generic to the plot type and not specific information for specific information see VI().

Unlike VI() and ggplot Describe needs to be explicitly called to show its output.

Value

A description in the format of a list. It will have the title, general info and RHints. If multiple layers of a ggplot are being described then it will be a list of descriptions for each layer.

Author(s)

A. Jonathan R. Godfrey and James A. Thompson

Examples

# Base R
scatter = FittedLinePlot(NULL, x = rnorm(1e2), y = rnorm(1e2))
Describe(scatter)
hist = hist(rnorm(1e3))
Describe(hist)

# ggplot
if(require(ggplot2)){
simplePoint = ggplot(NULL, aes(rnorm(1e2), rnorm(1e2))) +
  geom_point()
Describe(simplePoint)
}

Prepare BrailleR settings for specific braille embossers

Description

Convenience functions for setting package options based on experimentation using specific embossers.

Usage

Premier100()

Details

These functions are only relevant for owners of the specified embossers. Ownership of these models means the user has access to fonts that are licenced to the user.

The Premier 100 embosser uses standard 11 by 11.5 inch fanfold braille paper. Printing in landscape or portrait is possible.

Value

Nothing. The functions are only used to set package options.

Author(s)

A. Jonathan R. Godfrey.

See Also

ChooseEmbosser

Examples

#Premier100() # Specify use of the Premier 100 embosser.
#ChooseEmbosser() # reset to default: using no embosser.

Find/Replace text in a file

Description

Simple wrapper functions to make it easier to replace the text in a file, possibly due to spelling errors, but perhaps to replace default text in a template file.

Usage

FindReplace(file, find, replace)

Rnw2Rmd(file)

UseTemplate(file, find=NULL, replace=NULL)

UseTemplateList(newfile, fileList, find=NULL, replace=NULL)

Arguments

Details

The FindReplace function is purely intended for use on an external file whereas UseTemplate is intended to take a template file from within the BrailleR package and return the updated text to the calling environment.

Rnw2Rmd tries to replace Standard LaTeX commands and Sweave chunk headers with R markdown ones. It is NOT comprehensive, but it does get a long way towards a useful markdown file.

Obviously the specified file must exist for these functions to work.

Value

FindReplace will replace the existing file with the updated version while UseTemplate will return a character string which will usually be pushed out to an R script or R markdown file.

Author(s)

A. Jonathan R. Godfrey

Examples

UseTemplate("DTGroupSummary.R")
UseTemplate("DTGroupSummary.R", "DataName", "MyData")

extract the example text from a help page

Description

A cut back version of example() for obtaining the text used in examples on help pages without running those examples. The function is intended to help write markdown/Sweave documents.

Usage

GetExampleText(topic, package = NULL, lib.loc = NULL, character.only = FALSE, outFile="")

Arguments

Details

The example() code was hacked back to form this utility function. It is probably a little heavy for what is needed but it works sufficiently at the time of creation.

Value

a vector of character strings each element being one line of the examples from the corresponding help topic.

Author(s)

The work of Martin Maechler and others got tampered with by A. Jonathan R. Godfrey

See Also

You may wish to compare this with example

Examples

cat(paste(GetExampleText(mean), collapse="\n"))

Set options for using brailleR

Description

An interactive question-and-answer interface suitable for blind users wanting to set the options for using the BrailleR package.

Usage

GetGoing()

Details

Defaults are offered for all questions so that pressing <Enter> means no changes are made. Users answer yes/no questions as TRUE or FALSE respectively; the short form T or F is also allowed.

The user can also choose to perform various setup tasks using this interface.

Value

NULL. This function is a tool for executing other functions that will set options and setup the package according to the user's wants.

Author(s)

A. Jonathan R. Godfrey

See Also

All options being set through this function have specific functions that achieve the same ends. For example, see GoSighted for the options that are binary settings, or SetAuthor for options requiring a specific character or numeric value to be chosen.

The setup functionality can be reviewed at MakeBatch.

Download and install software (Windows users only)

Description

Anyone wishing to make use of the WriteR application must have pandoc installed.

Users that do not have Python and wxPython installed cannot use the WriteR application file as provided by the BrailleR package. This command gets an installer that can run independently of Python.

Downloaded files will be saved into the user's MyBrailleR folder.

Usage

Get7zip()

GetCygwin(x64 = TRUE)

GetPandoc()

GetPython3(x64 = TRUE)

GetRStudio()

GetWriteR()

GetWxPython3()

Arguments

Details

This function assumes you have a current internet connection because it downloads a File.

The functions will download and install the chosen application. The installers are stored in the user's MyBrailleR folder.

Value

NULL. The downloaded file is saved in the user's MyBrailleR folder.

Note

Use of this function assumes you are happy for a file to be downloaded and saved on your hard drive. You can go to your MyBrailleR folder and delete the executable at any time.

Author(s)

A. Jonathan R. Godfrey, building on the installr package by Tal Galili

Internal functions for the BrailleR package

Description

Some functions that probably weren't really necessary, but proved useful at some stage.

Usage

FindCSSFile(file)



InQuotes(x)

nNonMissing(x)

Arguments

Value

These should be fairly obvious from the name of the function

Author(s)

A. Jonathan R. Godfrey

Send an email based on a template

Description

Template email messages have been created to help you send feedback to the package creator or to join the Blind R Users Group email list. The BlindRUG email list is a forum where we can discuss issues about using R as a blind person. List traffic is light. You can join and leave as you see fit.

Usage

JoinBlindRUG()

ThankYou()

Details

You will get an email prepared in your selected email client. If you're wanting to join the BlindRUG list, just press send without editing that message at all. Pretty soon, the server will send you a message that you will need to reply to in order to finalise the subscription. Once you have joined the list you will be sent an initial welcome message.

If you are sending in feedback, then please do tell me how you heard about BrailleR and where you are studying or working.

Value

NULL. These functions are intended for their side effects.

Author(s)

A. Jonathan R. Godfrey

Create and display a accessible exploration webpage SVG of graph

Description

Creates the necessary SVG and XML files for a graph object (as long as graph type is supported). Then turns them into a html file and opens it for viewing (if a interactive session) in your browser.

Usage

MakeAccessibleSVG(x,
file = paste0(deparse(substitute(x)), "-SVG"),
view=interactive(), cleanup = TRUE, ...)
## S3 method for class 'ggplot'
MakeAccessibleSVG(x,
file = paste0(deparse(substitute(x)), "-SVG"),
view=interactive(), cleanup = TRUE, VI_and_Describe = TRUE, ...)

Arguments

Details

This function can be thought of as just a shortcut for quickly creating a SVG webpage for exploration. Each individual step can be done with the SVGThis(), AddXML() and BrowseSVG() functions. Using this is currently the quickest workflow for accessing the SVG features of BrailleR.

More information can be found in the Exploring graphs vignette.

It has support for some of the base plots however you can consider this support deprecated.

Value

NULL. This function is solely for the purpose of creating SVG and XML files and displaying them

Author(s)

A. Jonathan R. Godfrey, Volker Sorge and James A. Thompson

References

P. Dengler et al. (2011) Scalable vector graphics (SVG) 1.1, second edition. W3C recommendation, W3C. http://www.w3.org/TR/2011/REC-XML11-20110816/

See Also

SVGThis, AddXML, BrowseSVG

Examples

#Base R
#boxplot = boxplot(rnorm(1e4))
#MakeAccessibleSVG(boxplot, view = F)

#attach(airquality)
#scatter = ScatterPlot(x=Wind, y=Ozone, pch=4, base=TRUE)
#detach(airquality)
#MakeAccessibleSVG(scatter)

#ggplot2
library(ggplot2)
tsplot = TimeSeriesPlot(airquality, x=airquality$Temp)
MakeAccessibleSVG(tsplot)

barChart = ggplot(Orange, aes(x = Tree)) +
  geom_bar()
MakeAccessibleSVG(barChart)

histogram = ggplot(attenu, aes(x=dist)) +
geom_histogram()
  histogram
MakeAccessibleSVG(histogram)

# Cleaning up
unlink("barChart-SVG.html")
unlink("histogram-SVG.html")
unlink("tsplot-SVG.html")

Prepare the options for conversion of an R markdown file.

Description

Make a pandoc options file for use with a named R markdown file.

Usage

MakeAllFormats(RmdFile, BibFile = "")

Arguments

Details

The options are based on the current best set of possible outcomes. The two html file options use different representations of any mathematical equations. The Microsoft Word file uses the native equation format which is not accessible for blind people using screen readers.

Value

Nothing in the R console/terminal. The function is used for its side effects in the working directory.

Author(s)

A. Jonathan R. Godfrey.

Create batch files for processing R scripts and markdown files under Windows

Description

Convenience function for creating batch files that can be used under Windows to process R scripts, R markdown, and quarto files. The main idea is that a user can click on the bacth files within Windows Explorer to get the desired task done faster.

Usage

MakeBatch(file=NULL, static = FALSE)


MakeAdminBatch()

Arguments

Details

These batch files are not for use in an R session. They do need to be created in an interactive session though. They are to provide users a means to process R scripts, quarto and Rmarkdown documents without needing to open an R session thereafter.

If a file is specified, the function will create a single batch file that will process the file appropriately. Processing an R script will generate a Rout file, while an Rmd file is converted into HTML. Quarto files are tied to two batch files; one renders the document and should be used first, while the other is for the continuous previewing of the document in a browser.

If no file is specified, the MakeBatch() function creates various files in the current working directory to show how the tools can be used.

Files starting with the word test are for testing the batch files. An R script and an Rmarkdown file were created as well as the batch files that will process them into a Rout file and an HTML document respectively. Pressing <enter> on these test*.bat files will process the test files appropriately.

The other three batch files (ending in .bat) and any created using MakeAdminBatch() need to be moved to a folder on the user's path so that they can be called from anywhere. They could also be manually edited to suit the user's needs.

The path.txt file shows the user what folders are already on the path list. The user can review this list and decide to alter the system variable if they so choose. The path.txt file has no value otherwise.

Value

NULL. The user is informed about the files that are created by way of message().

Further instructions

Once the RBatch.bat file has been moved to the desired folder that is included in the path for your system you can follow the steps below to get full value from this functionality.

1. Open windows explorer, and browse to the folder containing the test files.

2. Select the test.R script.

3. Under the File menu, look for the item Open with... (This might already be a submenu for some users; if so, the last item is Choose default program.)

4. We are going to choose to use a program on our computer. Do not go looking on the internet to see which program we need.

5. You may be able to write a description of the file type. This is an R script but it may not yet be registered as such. Providing this detail is optional.

6. When given the chance to browse for the program to open the test.R script, browse to the folder where you placed Rbatch.bat and select it.

7. When you select OK, the test.R script will be processed by RBatch.bat and a new file test.Rout will be created.

8. Open test.Rout in any text editor you like. This file has the appearance of an R session window except for some processing time detail at the end. You will be able to read the commands that were originally in test.R as well as the output from these commands.

Author(s)

A. Jonathan R. Godfrey with testing by JooYoung Seo

Convert line breaks in vignette documentation

Description

The Rnw files used for vignettes use Linux style line breaks that make reading vignette source files difficult for Windows users. A Python script is called which converts the line breaks and saves the vignette source in the user's MyBrailleR folder.

Usage

MakeReadable(pkg)

Arguments

Details

Must have Python 3.8 installed for this function to work.

Value

Nothing in the workspace. All files are stored in a vignettes folder within MyBrailleR.

Author(s)

A. Jonathan R. Godfrey

Work flow convenience functions

Description

Time-saving functions that help create files in more useful formats for later use.

Usage

History2Rmd(file = "History.Rmd")
History2Qmd(file = "History.Qmd")

R2Rmd(ScriptFile)
R2Qmd(ScriptFile)

ProcessAllMd(dir =".")
ProcessAllRmd(dir =".", method = "render")

RemoveBOM(file)

Arguments

Details

The History2Rmd() function was intended for turning a short interactive R session into an R markdown file. Lines of code are all separated into distinct code chunks in the Rmd file. the resulting file will need to be edited if commands have spanned more than one line.

The R2Rmd() function does try to limit the number of blank lines copied from the R script into the Rmarkdown file. The Rmd file may need some editing.

Once all Rmd files have been edited, the user can have all the Rmd files in a folder processed using ProcessAllRmd(). A similar function ProcessAllMd() exists to process any plain markdown files which do not need knitting.

Value

NULL. These functions are for creating files in the current working directory.

Author(s)

A. Jonathan R. Godfrey

See Also

These functions were inspired by the spin functionality of the knitr package. You may wish to move onto using it for more features.

Load BrailleR on Startup in Current Working Directory

Description

Writes the single command “library(BrailleR)” to a .First() function in .Rprofile in the current working directory. This forces the BrailleR package to be automatically loaded when R is opened in this working directory.

Usage

MakeRprofile(Overwrite = FALSE)

Arguments

Value

Nothing. This function is used for its side effect of creation of a file in the current working directory. A warning message is created if the file exists and Overwrite=FALSE.

Author(s)

A. Jonathan R. Godfrey.

Create a template for a new function

Description

An R script for a new function is created in the working directory. It includes Roxygen commented lines for the documentation with sensible defaults where possible.

Usage

NewFunction(FunctionName, args = NULL, NArgs = 0)

Arguments

Details

A file is saved in the current working directory that has a template for a function with a set of arguments (if supplied). The file still needs serious editing before insertion into a package.

Value

No objects are created in the workspace. The only outcome is the template file and a message to let the user know the job was completed.

Author(s)

A. Jonathan R. Godfrey.

Open standard Windows tools quickly

Description

Many standard Windows tools can be opened from the Run dialogue, but this starts them in the standard locations, when R users may want them opened or saved in the current working directory.

Usage

Notepad(file = "")

Arguments

Details

If a file specified does not yet exist in the current folder, the standard notepad editor asks the user if a new file is wanted.

Value

NULL. The functions are for their external effects only. Control is still available in the R console/terminal.

Author(s)

A. Jonathan R. Godfrey

Analysis for a continuous response for one group factor

Description

A convenience function that creates an analysis for a continuous response variable with one grouping factor. The function creates a number of graphs and tables relevant for the analysis.

Usage

OneFactor(Response, Factor, Data = NULL, HSD = TRUE, AlphaE = 0.05, 
Filename = NULL, Folder = NULL, 
VI = getOption("BrailleR.VI"), Latex = getOption("BrailleR.Latex"), 
View = getOption("BrailleR.View"), Modern=TRUE)

Arguments

Details

This function writes an R markdown file that is knitted into HTML and purled into an R script. All graphs are saved in subdirectories in png, eps, pdf and svg formats. Tabulated results are stored in files suitable for importing into LaTeX documents.

Value

This function is used for creation of the files saved in the working directory and a few of its subdirectories.

Author(s)

A. Jonathan R. Godfrey and Timothy P. Bilton

See Also

Other convenience functions can be investigated via their help pages. See UniDesc, OnePredictor, and TwoFactors

Examples

DIR = getwd()
setwd(tempdir())
data(airquality)
library(dplyr)
library(knitr)
# the following line  returns an error:
## OneFactor("Ozone", "Month", airquality, View=FALSE)
# so we make a copy of the data.frame, and fix that:
airquality2 = airquality |> mutate(Month = as.factor(Month))
# and now all is good to try:
OneFactor("Ozone", "Month", airquality2)
# N.B. Various files and a folder were created in a temporary directory. 
# Please investigate them to see how this function worked.
setwd(DIR)

Exploration of the relationship between a response and a single predictor

Description

A convenience function for generating exploratory graphs and numeric summaries, regression analysis output, and the residual analysis of the simple linear model.

Usage

OnePredictor(Response, Predictor, Data = NULL, 
    Filename = NULL, Folder = NULL, 
    VI = getOption("BrailleR.VI"), Latex = getOption("BrailleR.Latex"), 
   View = getOption("BrailleR.View"), Modern=TRUE)

Arguments

Details

This function writes an R markdown file that is knitted into HTML and purled into an R script. All graphs are saved in subdirectories in png, eps, pdf and svg formats. Tabulated results can be stored in files suitable for importing into LaTeX documents.

Value

This function is used for creation of the files saved in the working directory and a few of its subdirectories.

Author(s)

A. Jonathan R. Godfrey and Timothy P. Bilton

See Also

Other convenience functions can be investigated via their help pages. See UniDesc, OneFactor, and TwoFactors

Examples

if(require(nortest)){ # used in a dependent function's Rmd file
library(knitr)
DIR = getwd()
setwd(tempdir())
data(airquality)
OnePredictor("Ozone", "Wind", airquality)
# N.B. Various files and a folder were created in a temporary directory. 
# Please investigate them to see how this function worked.
setwd(DIR)
}

Set package options

Description

A set of convenience functions to alter the settings that control how much output is generated and displayed by other BrailleR functions.

Usage

GoBlind()
GoSighted()


GoAdvanced()
GoNovice()

LatexOn()
LatexOff()

ViewOn()
ViewOff()

Details

The function names should be fairly self explanatory. GoBlind() and GoSighted() control use of the VI() method which provides extra information about graphical objects for the assistance of blind users; GoAdvanced (less verbose) and GoNovice() (more verbose) control how much output a user will be given; ViewOn() and ViewOff() are for the automatic opening of HTML pages created by BrailleR functions; and LatexOn() and LatexOff() control the production of tables into LaTeX via the xtable package.

Value

Nothing is returned. These functions are only used for their side effects.

Author(s)

A. Jonathan R. Godfrey

See Also

See these settings applied as default arguments to UniDesc

Convert files using pandoc.

Description

Convert all files in the current working directory of one type into another type using Pandoc.

Usage

PandocAll(intype = "docx", outtype = "html")

Arguments

Details

This will over-write existing files. It was intended to take MS Word files and convert to HTML, but other conversions are possible. See the pandoc documentation for full details.

Value

Files will be created in the current working directory. CRAN policy says you must have been informed that this is happening. This help file is your warning.

Author(s)

A. Jonathan R. Godfrey

References

Extensive guidance on using pandoc is available

Save a transcript of commands and/or output to a text file.

Description

These functions save a transcript of your commands and their output to a script file.

They work as combinations of sink and history with a couple of extra bells and whistles.

Usage

txtStart(file, commands=TRUE, results=TRUE, append=FALSE, cmdfile,
          visible.only=TRUE)

txtOut(Filename=NULL)

txtStop()

txtComment(txt,cmdtxt)

txtSkip(expr)

Arguments

Details

These functions are used to create transcript/command files of your R session. In the original TeachingDemos package from which the functions were obtained, there are 3 sets of functions. Those starting with "txt",those starting with "etxt", and those starting with wdtxt.

The "txt" functions create a plain text transcript while the "etxt" functions create a text file with extra escapes and commands so that it can be post processed with enscript (an external program) to create a postscript file and can include graphics as well. The postscript file can be converted to pdf or other format file. The "wdtxt" functions will insert the commands and results into a Microsoft Word document.

Users wishing to have the additional functionality that the "etxt" and "wdtxt" functions provide are advised to make use of the TeachingDemos package.

If results is TRUE and commands is FALSE then the result is similar to the results of sink. If commands is true as well then the results will show both the commands and results similar to the output on the screen. If both commands and results are FALSE then pretty much the only thing these functions will accomplish is to waste some computing time.

If cmdfile is specified then an additional file is created with the commands used (similar to the history command), this file can be used with source or copied and pasted to the terminal.

The Start function specifies the file/directory to create and starts the transcript, The prompts are changed to remind you that the commands/results are being copied to the transcript. The Stop function stops the recording and resets the prompts.

The txtOut function is a short cut for the txtStart command that uses the current date and time in the filenames for the transcript and command files. This function is not part of the TeachingDemos package.

The R parser strips comments and does some reformatting so the transcript file may not match exactly with the terminal output. Use the txtComment functions to add a comment. This will show up as a line offset by whitespace in the transcript file. If cmdtxt is specified then that line will be inserted into cmdfile preceded by a hash symbol so it will be skipped if sourced or copied.

The txtSkip function will run the code in expr but will not include the commands or results in the transcript file (this can be used for side computations, or requests for help, etc.).

Value

Most of these commands do not return anything of use. The exception is:

txtSkip returns the value of expr.

Note

These commands do not do any fancy formatting of output, just what you see in the regular terminal window. If you want more formatted output then you should look into Sweave or the use of markdown documents..

Do not use these functions in combination with the R2HTML package or sink.

Author(s)

Greg Snow, greg.snow@imail.org is the original author, but Jonathan Godfrey a.j.godfrey@massey.ac.nz is responsible for the implementation in the BrailleR package (including the txtOut() function), and should therefore be your first point of contact with any problems. If you find the functions useful, you may wish to send a vote of thanks in Greg's direction.

See Also

sink, history, Sweave, the odfWeave package, the R2HTML package, the R2wd package

Examples

## Not run: 
txtStart()
txtComment('This is todays transcript')
date()
x <- rnorm(25)
summary(x)
stem(x)
txtSkip(?hist)
hist(x)
Sys.Date()
Sys.time()

## End(Not run)

Load a package by installing it if necessary

Description

It is easier to run a script if we know the packages will be installed if this additional step is necessary. Installation uses the RStudio mirror of CRAN.

Usage

Require(pkg)

Arguments

Value

logical: to say that the package has been successfully loaded (invisible)

Author(s)

A. Jonathan R. Godfrey

See Also

require from the base package

Save commonly used graphs as structured SVG files.

Description

Converts a graph object (as long as it has a class assigned) to an SVG file that can be viewed using a browser (not IE). At present, the SVG needs manual editing using the Tiger Transformer software before viewing in the Tiger Player.

Usage

SVGThis(x, file = "test.svg", ...)
## S3 method for class 'ggplot'
SVGThis(x, file = "test.svg", createDevice = TRUE, ...)

Arguments

Details

Most of the work of the function is done gridSVG::grid.export function. After this there is a rewrite of the SVG so that it can work better with the XML and create a easy accessible experience of the graph.

The produced SVG can also be used as just that a SVG. However note that quite possibly some rewriting will of been done. The rewriting does not change how the graph looks.

To view your graph as a accessible svg you can use the MakeAccessibleSVG() function.

The Cairo SVG device found in the gr.devices package does not create a structured SVG file that includes the semantics of the graphic being displayed. The SVG created by the gridSVG package does meet this need, but only works on graphs drawn using the grid package. Any graph created using functions from the more common graphics package can be converted to the grid package system using the gridGraphics package.

Value

NULL. This function is solely for the purpose of creating SVG files in the current working directory or in a path of the user's choosing.

Author(s)

A. Jonathan R. Godfrey, Paul Murrell and James Thompson

References

P. Murrell and S. Potter (2014) “The gridSVG package” The R Journal 6/1, pp. 133-143. http://journal.r-project.org/archive/2014-1/RJournal_2014-1_murrell-potter.pdf

P. Murrell (2015) “The gridGraphics package”, The R Journal 7/1 pp. 151-162. http://journal.r-project.org/archive/2015-1/murrell.pdf

P. Dengler et al. (2011) Scalable vector graphics (SVG) 1.1, second edition. W3C recommendation, W3C. http://www.w3.org/TR/2011/REC-SVG11-20110816/

See Also

MakeAccessibleSVG

Examples

# Save a custom ggplot object to an SVG file
library(ggplot2)
p = ggplot(mtcars, aes(x=wt, y=mpg)) + geom_point()
SVGThis(p)

# Cleaning up afterwards
unlink("test.svg")

Create a standard scatter plot with a few extra elements added to the output object

Description

This function is a wrapper to the standard plott() function in the graphics package. It is tailored to generating a scatter plot, and adds detail to the stored object so that a better text description can be formulated using the VI() method in the BrailleR package. The function will become redundant once all other BrailleR functionality is working well with ggplot style graphics.

Usage

ScatterPlot(.data, x, y, base=FALSE, ...)

FittedLinePlot(.data, x, y, line.col=2, base=FALSE, ...)

Arguments

Details

These wrapper functions will draw the graphics plots for a set of points. The only difference is that the fitted line is added for the FittedLinePlot()

The original style used base graphics. Given the improved interaction of ggplot graphics for BrailleR users, the preferred style from v0.33.0 onwards was the ggplot style.

Value

Either:

1. An object of class scatterplot of fittedlineplot, with the addition of any calls to the main title or axis labels being explicitly stored even if a zero length character string, or

2. a ggplot object.

Author(s)

A. Jonathan R. Godfrey

References

Godfrey, A.J.R. (2013) ‘Statistical Software from a Blind Person's Perspective: R is the Best, but we can make it better’, The R Journal 5(1), pp73-79.

Examples

attach(airquality)
op = par(mfcol=c(3,2))
plot(x=Wind, y=Ozone, pch=4)
test1 = ScatterPlot(x=Wind, y=Ozone, pch=4, base=TRUE)
test1 #does the plot method work?
plot(x=Wind,y= Ozone)
abline(coef(lm(Ozone~Wind)), col=4)
test2 = FittedLinePlot(x=Wind, y=Ozone, line.col=4, base=TRUE)
test2 #does the plot method work?
par(op)
detach(airquality)

Functions for setting package options.

Description

Some package options have arguments which need validation. Setting the default significance level for analyses was the first function of this kind. Setting the name of the user to be inserted into documents was the second. Others are detailed further below.

Usage

ChooseEmbosser(Embosser = "none", Permanent = interactive(), Local = interactive())

ChooseStyle(css = "BrailleR.css", Permanent = interactive(), Local = interactive())
ChooseSlideStyle(css = "JGSlides.css", Permanent = interactive(), Local = interactive())

ResetDefaults(Local = interactive())

SetAuthor(name = "BrailleR", Permanent = interactive(), Local = interactive())

SetBRLPointSize(pt, Permanent = FALSE, Local = interactive())
SetPaperHeight(Inches, Permanent = FALSE, Local = interactive())
SetPaperWidth(Inches, Permanent = FALSE, Local = interactive())

SetLanguage(Language = "en_us", Permanent = interactive(), Local = interactive())

SetMakeUpper(Upper, Permanent = interactive(), Local = interactive())

SetPValDigits(digits, Permanent = interactive(), Local = interactive())

SetSigLevel(alpha, Permanent = interactive(), Local = interactive())

Arguments

Details

More convenience functions for BrailleR users. Most are self explanatory, but the following details should be noted.

The Choose...() functions are used for establishing default parameters for other details. The ChooseStyle() command can be used to alter the appearance of HTML output by way of cascading style sheets. You can create your own css file and add it to your user folder called MyBrailleR before calling this function.

The ChooseEmbosser() will look for the default settings recommended for particular types of embosser. Initial testing was done on a Tiger Premier 100 embosser manufactured by ViewPlus Inc. The default paper size is 11 by 11.5 inches, but the recommended embossing area for graphics is 10 by 10 inches. Please submit your preferences for any embosser to the package maintainer.

The Set..() commands will let the user specify any desired value for the options as long as it is valid: Options assumed to be character strings are checked to be so, integers must be integers and a proportion must be between zero and one.

SetPaperHeight and SetPaperWidth are temporary changes by default because some types of images are not meant to use the maximum area set down by the original default settings for an embosser. Careful experimentation may be required to get optimal results. If permanent changes are desired, then please contact the package maintainer to explain why you have made these changes so that we can help other users get the best from a wide range of embossers.

SetPValDigits() is used for rounding purposes to avoid the use of scientific notation. It is not used for determining significance.

Value

NULL. These functions set package options.

Author(s)

A. Jonathan R. Godfrey

Examples

# SetSigLevel(5) # not a valid alpha
SetSigLevel(0.05, Local=FALSE) # valid alpha value
SetAuthor(Local=FALSE)
SetAuthor("Jonathan Godfrey", Local=FALSE)

Establish the BrailleR folder for the user

Description

Creates a permanent folder if the user agrees.

Usage

SetupBrailleR()

Details

The user can establish a permanent folder if the BrailleR package is loaded in an interactive session. If only used in batch mode, the user will only be able to use the default BrailleR settings.

Value

The path to the folder is returned invisibly.

Author(s)

A. Jonathan R. Godfrey with suggestions from Henrik Bengtsson and Brian Ripley.

A spell checking interface

Description

An terminal-based interface for dealing with words that appear to be misspelled in the specified files. Files for lists of words to ignore at local and global levels are augmented, or replacement text can be supplied.

Usage

SpellCheck(file)

Arguments

Details

A backup file is created before any changes are made. This file is not overwritten each time the spell checking is done so it may end up becoming out of date. Users can delete the backup file anytime.

Value

NULL. This function is intended to affect only external files.

Author(s)

A. Jonathan R. Godfrey

Spell checking a file or all files within a specified folder

Description

Check spelling using hunspell. A new print method is also used.

Usage

SpellCheckFiles(file = ".", ignore = character(), 
    local.ignore = TRUE, global.ignore = TRUE) 

## S3 method for class 'wordlist'
print(x, ...)

Arguments

Details

The global list of words to be ignored needs to be saved in the user's MyBrailleR folder. It can be updated as often as the user likes. It should have one word per line, and contain no space, tab or punctuation characters.

Value

A list object with each item of the list being the findings from spell checking each file. The words not found in the dictionary are given as well as the line numbers where they were found.

Author(s)

A. Jonathan R. Godfrey wrote these functions but leaned heavily on functions found in the devtools package.

See Also

The hunspell package and functions therein.

Create a standard time series plot with a few extra elements added to the output object

Description

This function is a wrapper to the standard plott() function in the graphics package. It is tailored to generating a time series plot, and adds detail to the stored object so that a better text description can be formulated using the VI() method in the BrailleR package. The function will become redundant once all other BrailleR functionality is working well with ggplot style graphics.

Usage

TimeSeriesPlot(.data, x, time=NULL, base=FALSE, ...)

Arguments

Details

This function was originally designed to be a wrapper that would draw the base graphics plot for a time series. The saved object can be plotted later with a call to plot.

From v0.33.0 onwards, the function can complete the original intention, but the ggplot2 package's improved interaction with BrailleR means this is the now the preferred style of plot. This plot wont be plotted by default so you need to expressly call the plot or print method.

Value

Either:

1. An object of class tsplot, with the addition of any calls to the main title or axis labels being explicitly stored even if a zero length character string, or

2. A ggplot object.

Author(s)

A. Jonathan R. Godfrey and James A. Thompson

References

Godfrey, A.J.R. (2013) ‘Statistical Software from a Blind Person's Perspective: R is the Best, but we can make it better’, The R Journal 5(1), pp73-79.

Examples

# with base
attach(airquality)
op = par(mfcol=c(3,2))
plot(as.ts(Wind), ylab="Wind", col=4)
test1 = TimeSeriesPlot(x=Wind, col=4, base=TRUE)
test1 #does the plot method work?
plot(as.ts(Ozone), ylab="Ozone")
test2 = TimeSeriesPlot(x=Ozone, base=TRUE)
test2 # does the plot method work?
par(op)
detach(airquality)

# with ggplot
if(require(ggplot2)){
   basic = TimeSeriesPlot(airquality, x=airquality$Temp)
   basic
   # ts data
   withTitle = TimeSeriesPlot(UKDriverDeaths,  
    main = "UK driver deaths",
    sub = "For the month Januaray")
   withTitle
   withLabs = TimeSeriesPlot(sunspots, ylab="Number of spots", xlab="Year")
   withLabs
}

A convenience function for a Three-way analysis

Description

Prepares an analysis of a data set with one response and three predictors that are all factors. Interactions between the Three factors are also allowed for. The function creates a number of graphs and tables relevant for the analysis.

Usage

ThreeFactors(Response, Factor1, Factor2, Factor3, Data = NULL, Filename = NULL, 
    Folder = NULL, VI = getOption("BrailleR.VI"), Latex = getOption("BrailleR.Latex"), 
    View = getOption("BrailleR.View"), Modern=TRUE)

Arguments

Details

to complete

Value

This function is used for creation of the files saved in the working directory and a few of its subdirectories.

Author(s)

A. Jonathan R. Godfrey and Timothy P. Bilton

See Also

The OneFactor script was the basis for this function;.

Examples

DIR = getwd()
setwd(tempdir())
TestData=data.frame(Resp=sample(54), expand.grid(F1=c("a","b","c"), 
    F2=c("d","e","f"), F3=c("g","h","i"), rep=c(1,2)))
attach(TestData)
ThreeFactors(Resp,F1,F2,F3)
detach(TestData)
rm(TestData)
# N.B. Various files and a folder were created in a temporary directory. 
# Please investigate them to see how this function worked.
setwd(DIR)

A convenience function for a two-way analysis

Description

Prepares an analysis of a data set with one response and two predictors that are both factors. An interaction between the two factors is also allowed for. The function creates a number of graphs and tables relevant for the analysis.

Usage

TwoFactors(Response, Factor1, Factor2, Inter = FALSE, HSD = TRUE, 
   AlphaE = getOption("BrailleR.SigLevel"), Data = NULL, Filename = NULL, 
    Folder = NULL, VI = getOption("BrailleR.VI"), Latex = getOption("BrailleR.Latex"), 
    View = getOption("BrailleR.View"), Modern=TRUE)

Arguments

Details

to complete

Value

This function is used for creation of the files saved in the working directory and a few of its subdirectories.

Author(s)

Timothy P. Bilton and A. Jonathan R. Godfrey

See Also

The OneFactor script was the basis for this function;.

Examples

DIR = getwd()
setwd(tempdir())
if(require(dplyr)){
TG <- ToothGrowth |> mutate(dose = as.factor(dose))

# Without interaction
TwoFactors('len','supp','dose',Data=TG, Inter=FALSE)

# With two-way interaction
TwoFactors('len', 'supp', 'dose', Data=TG, Inter=TRUE)

rm(TG); rm(TG)
# N.B. Various files and a folder were created in a temporary directory. 
# Please investigate them to see how this function worked.
}
setwd(DIR)

Descriptive statistics and graphs for univariate data

Description

This function is a convenience function for analyzing univariate data. It provides histograms, boxplots and tabulated results for normality tests as well as those for skewness and kurtosis. The intended use of this function is principally for a blind user of R who also has the advantage of retrieving textual descriptions of the graphs created along the way, via the VI() methods.

Usage

UniDesc(Response = NULL, ResponseName = as.character(match.call()$Response), 
    Basic = TRUE, Graphs = TRUE, Normality = TRUE, Tests = TRUE, 
    Title = NULL, Filename = NULL, Folder = ResponseName, Process = TRUE,
VI = getOption("BrailleR.VI"), Latex = getOption("BrailleR.Latex"), 
View = getOption("BrailleR.View"), PValDigits=getOption("BrailleR.PValDigits"))

Arguments

Value

Saves an R markdown file, (and then if Process=TRUE) an R script file, and an html file (which may be opened automatically) in the current working folder. Graphs are saved in png, eps, pdf, and SVG formats (if requested) in (optionally) a subfolder of the current working directory.

Author(s)

A. Jonathan R. Godfrey a.j.godfrey@massey.ac.nz

Examples

if(require(nortest)){ # used in the Rmd file, not the UniDesc function
DIR = getwd()
setwd(tempdir())
Ozone=airquality$Ozone
UniDesc(Ozone)
rm(Ozone)
# N.B. Various files and a folder were created in a temporary directory. 
# Please investigate them to see how this function worked.
setwd(DIR)
}

extract or alter graph parameters

Description

Either grabs the specified label or sets it to a newly specified value. In this case the graph is re-drawn and the graph object is updated.

Usage

UpdateGraph(object, ...)

Main(graph, label = NULL)

XLab(graph, label = NULL)

YLab(graph, label = NULL)

Arguments

Details

Specify the label to be an empty text string if the desire is to delete the current label.

Value

The graph object will be updated in the global environment if a new value is assigned.

Author(s)

A. Jonathan R. Godfrey

Examples

attach(airquality)
op = par(mfcol=c(3,2))
#test1 = TimeSeriesPlot(x=Wind, col=4, base=TRUE)
#XLab(test1, "Day")
# check the change is permanent by doing another change
#test1 |> Main("titles are important") # nice that the pipe works!

#test2 = TimeSeriesPlot(x=Ozone, base=TRUE)
# using the update method
#update(test2, main="important title", sub="subtitles aren't always present", ylab="Ozone (ppb)") 
# finally, change the graph to use different plotting characters/line types
#update(test2) # to fix
par(op)
detach(airquality)

Extract information from a graphical object

Description

A method that extracts the most relevant information from a graphical object (or implied set of graphical objects) and display the interpreted results in text or HTML form.

The method includes representations of summary methods that are more suitable for blind users. For example, the method for a data.frame uses a single line for each variable instead of the normal column layout used by the summary method.

Usage

VI(x, Describe=FALSE, ...)

## S3 method for class 'histogram'
VI(x, Describe=FALSE, ...)

## S3 method for class 'aov'
VI(x, Describe=FALSE, ...)

## S3 method for class 'htest'
VI(x, Describe=FALSE, digits = getOption("digits"),  ...) 

## S3 method for class 'lm'
VI(x, Describe=FALSE, ...)

## S3 method for class 'ggplot'
VI(x, Describe=FALSE, threshold=10, 
   template=system.file("whisker/VIdefault.txt", package="BrailleR"),
   ...)

Arguments

Details

VI() is intended to extract the specific details for the particular graph or output.

It will provide the information as a printout to the console/terminal window.

Value

Nothing is returned when working with most of the functions functionality.

The VI.lm() method is the first to move away from this idea and use a process that builds on the UniDesc() function. In this case, the method creates an R markdown file and compiles it into HTML. The HTML document is opened if the R session is interactive.

VI.ggplot returns a structure containing a hierarchical representation of the graph as well as the text description as a character vector. When run interactively, the text description is printed.

Note

The VI.lm method fails if you use the one line VI(lm(...)) even if the model is named using VI(Model1 <- lm(...)). It does work if two explicit commands are used. For example Model1 = lm(...) followed by VI(Model1).

The ggplot2 package contains many layers and not all of them have a VI output yet. However most of the commonly used ones do. Regardless the VI output should be considered experimental with some results being potenitally misleading.

Author(s)

A. Jonathan R. Godfrey, Debra Warren, Sophie Banks, Tony Hirst, Timothy P. Bilton and James A. Thompson

Examples

# Base R
RandomX=rnorm(500)
PlottedFig=hist(RandomX)
VI(PlottedFig)

# ggplot
if(require(ggplot2)){
ggplot(economics_long, aes(date, value01, colour = variable)) +
  geom_line() +
  ggtitle('dummy title')
}

Create the necessary files to allow interactive viewing of SVG

Description

Copy files from the package folders to the current working directory and write a markdown file that contains the links to all accessible SVG files in the current directory.

Usage

ViewSVG(file = "index")

Arguments

Details

This will create a html file that has a list of the available svg in the current directory. This only supports the current working directory at the moment. However this is planned on changing in the future. To make the files you can use the MakeAccessibleSVG() function

Value

NULL. This function exists for its side effects only.

Author(s)

A. Jonathan R. Godfrey and James A. Thompson

References

Godfrey, A.J.R. (2013) ‘Statistical Software from a Blind Person's Perspective: R is the Best, but we can make it better’, The R Journal 5(1), pp73-79.

See Also

MakeAccessibleSVG

Examples

library(ggplot2)

# Make a few svg webpages
tsplot = TimeSeriesPlot(airquality, x=airquality$Temp)
MakeAccessibleSVG(tsplot, file = "tsplot")

barChart = ggplot(Orange, aes(x = Tree)) +
  geom_bar()
MakeAccessibleSVG(barChart, file = "barChart")

histogram = ggplot(attenu, aes(x=dist)) +
geom_histogram()
  histogram
MakeAccessibleSVG(histogram, file="histogram")

# Display the 'home' page
ViewSVG()

# Cleaning up afterwards
# Created by the MakeAccessibleSVG (xml and svg are auto deleted)
unlink("histogram.html")
unlink("barChart.html")
unlink("tsplot.html")
unlink("index.html") # Created by the ViewSVG function

What's this figure?

Description

Determine what the current graphics device has on it so the blind user can be sure they have something they want, or find out what it might be that is contained in a graphics device.

Usage

WTF()

Value

Text describing what BrailleR was able to detect in the graphics window.

Author(s)

A. Jonathan R. Godfrey and Paul Murrell.

Examples

attach(airquality)
hist(Ozone)
WTF()
plot(Ozone~Wind)
WTF()
detach(airquality)

Count points in a scatter plot

Description

count the number of points that fall into various sized subparts of a scatter plot. The graphing region can be split into cells based on a uniform or normal marginal distribution separately for the x and y variables.

Usage

WhereXY(x, y = NULL, grid = c(4, 4), xDist = "uniform", 
       yDist = xDist, addmargins=TRUE)

Arguments

Value

A text description of the number of points in each subregion of the scatter plot. The table of counts can then be compared to the expected number of points in each subregion.

Author(s)

A. Jonathan R. Godfrey

Examples

x=rnorm(50)
y=rnorm(50)
WhereXY(x,y)
WhereXY(x,y, c(3,4))
WhereXY(x,y, xDist="other")

Find a text string in files

Description

Which files in a folder (and its subfolders) include/exclude a given text string

Usage

WhichFile(String, Folder, fixed = TRUE, DoesExist = TRUE)

Arguments

Details

Finding a given search string in a pile of text files is time-consuming. Finding which files lack that search string is even harder.

Value

A vector of filenames returned as character strings.

Note

This search uses readLines() which throws plenty of warnings if the files being searched across do not all end in a blank line.

Author(s)

A. Jonathan R. Godfrey in response to a request from CRAN to add missing text to help documentation.

Getting started with WriteR

Description

The WriteR application was written in wxPython so that blind users can process Rmarkdown documents. This functionality is offered because RStudio is not an accessible application for screen reader users.

Usage

WriteR(file = NULL, math = c("webTeX", "MathJax"))

TestPython()
TestWX()

PrepareWriteR(Author = getOption("BrailleR.Author"))

Arguments

Details

WriteR needs python and wxPython to run. Error handling for users without these packages installed is not yet incorporated in these functions. Please use TestWX() because it calls TestPython() as its first test.

The PrepareWriteR() function writes the settings file (called WriteROptions) for WriteR and copies the files that were part of the BrailleR installation into the current working directory. You will be able to run the WriteR application from there, or move to a folder of your choosing.

Value

NULL. The WriteR function is for your convenience and not for doing any work inside an R session. The TestWX() function prints results but returns nothing. The TestPython() function returns a logical to say Python can be seen by your system.

Note

You must have Python and the associated wxPython installation on your system to use the WriteR application.

Author(s)

A. Jonathan R. Godfrey

Create a standard boxplot with a few extra elements added to the output object

Description

This function is a wrapper to the standard boxplot() function in the graphics package. It adds detail to the stored object so that a better text description can be formulated using the VI() method in the BrailleR package.

Usage

boxplot(x, ...)

Arguments

Details

This function masks the function of the same name in the graphics package. The base R implementation does create an object, but does not give it a class attribute, the object does not store all graphical arguments that are passed to the boxplot() function. The functionality should be no different at all for anyone who is not using the VI() function to gain a more detailed text description of the boxplot. See the help page for the graphics::boxplot() function to get a more complete description of boxplot creation.

Value

An object of class boxplot. This class is just a placeholder for the contents of the object used to create a boxplot which would otherwise not be stored in a usable format. The class is not intended for the user; it is a tool that enables the BrailleR package to deliver a readable text version of the plot.

Note

I would love to see this function become redundant. This will happen if the extra functionality is included in the boxplot() function in the graphics package. This should be possible as the user experience will not be any different, no matter if the user is blind or sighted.

Author(s)

A. Jonathan R. Godfrey

References

The problem of not including class attributes for graphs was identified in: Godfrey, A.J.R. (2013) ‘Statistical Software from a Blind Person's Perspective: R is the Best, but we can make it better’, The R Journal 5(1), pp73-79.

See Also

The base R implementation of the boxplot function should be consulted; see the entry in the graphics package

Examples

x=rnorm(1000)
op = par(mfcol=c(2,1))
# the stamdard boxplot function returns
MyBoxplot=graphics::boxplot(x, main="Example boxplot (graphics package)", horizontal=TRUE)
MyBoxplot

# while this version returns
MyBoxplot=boxplot(x, main="Example boxplot (BrailleR package)", horizontal=TRUE)
MyBoxplot
par(op)

# The VI() method then uses the extra information stored
VI(MyBoxplot)

create a dotplot using stripchart

Description

A method for creating dotplots. The functions call the stripchart command from the graphics package and assign the output to have the class dotplot.

Usage

dotplot(x, ...)

## S3 method for class 'formula'
dotplot(x, ...)

Arguments

Details

This function was created as a result of being unable to assign all graphical parameters that are created when a formula is used in stripchart. Users not intending to use the VI method should use stripchart instead.

Value

An object of class dotplot. This class is just a placeholder for the contents of the object used to create a boxplot which would otherwise not be stored in a usable format. The class is not intended for the user; it is a tool that enables the BrailleR package to deliver a readable text version of the plot.

Author(s)

A. Jonathan R. Godfrey

See Also

This function is dependent on the stripchart function from the graphics package. Consult its help page for more information.

Examples

VI(with(airquality, dotplot(Ozone~Month)))

String manipulation of the output produced by VI.ggplot

Description

Allows the output from VI.ggplot to be searched and replaced based on a search pattern.

Usage

## S3 method for class 'VIgraph'
grep(pattern, x, ...)
## S3 method for class 'VIgraph'
gsub(pattern, replacement, x, ...)

Arguments

Details

The BrailleR package redefines the grep and gsub functions as generic functions (that dispatch on the x argument), with base::grep and base::gsub as the default methods. This grep.VIgraph method behaves like base::grep with value=TRUE (i.e., it returns the matched values, not the indices).

Value

Returns a new object of the same type as that returned by VI.ggplot, but with the text component restricted to only those lines that matched the pattern or with the text component replaced.

Author(s)

Debra Warren and Paul Murrell

Examples

if (require(ggplot2)) {
    grep("axis", VI(qplot(1,1)))
    gsub("labels", "tick labels", VI(qplot(1,1)))
}

Create a standard histogram with a few extra elements added to the output object

Description

This function is a wrapper to the standard hist() function in the graphics package. It adds detail to the stored object so that a better text description can be formulated using the VI() method in the BrailleR package.

Usage

hist(x, ...)

Arguments

Details

This function masks the function of the same name in the graphics package. Even though the base R implementation does create an object of class histogram, the object does not store all graphical arguments that are passed to the hist() function. The functionality should be no different at all for anyone who is not using the VI() function to gain a more detailed text description of the histogram. See the help page for the graphics::hist() function to get a more complete description of histogram creation.

Value

An object of class histogram as per the hist() function from the graphics package, with the addition of any calls to the main title or axis labels.

Author(s)

A. Jonathan R. Godfrey

References

Godfrey, A.J.R. (2013) ‘Statistical Software from a Blind Person's Perspective: R is the Best, but we can make it better’, The R Journal 5(1), pp73-79.

See Also

The base R implementation of the hist function should be consulted, using the entry in the graphics package

Examples

x=rnorm(1000)
# the stamdard hist function returns
MyHist=graphics::hist(x, xlab="random normal values", main="Example histogram (graphics package)")
MyHist

# while this version returns
MyHist=hist(x, xlab="random normal values", main="Example histogram (BrailleR package)")
MyHist

# The VI() method then uses the extra information stored
VI(MyHist)

View the history of the current workspace

Description

A substitute for the history function from the utils package.

Usage

history(max.show = 25, reverse = FALSE, pattern, ...)

Arguments

Details

This function exists because the standard history function in the utils package opens the internal pager that cannot be used by a blind person's screen reading software.

Value

Nothing is returned to the workspace. This function exists for the creation and viewing of the temporary file that holds the list of commands issued in the current workspace.

Author(s)

Duncan Murdoch, with testing by A. Jonathan R. Godfrey.

See Also

the original history function.

Convert a pdf file to html

Description

A blind user often has difficulty reading the content provided in pdf files. This tool is quite experimental at this stage.

Usage

pdf2html(pdffile, htmlfile=sub(".pdf", ".html", pdffile), HeadingLevels=4, PageTag="h6")

Arguments

Details

A Python 2.7 module is the basis for the conversion. Some post-processing can be done to further enhance the readability of the resulting html file.

Value

Logical: Has the conversion completed. Note that this does not mean the result is totally useful as this will depend on the quality of the input file.

Author(s)

A. Jonathan R. Godfrey

Sort VI.ggplot points list

Description

Allows the list of data points listed by VI.ggplot to be sorted by x or y values, ascending or descending. Currently only implemented for geom_points. This function is experimental and has not been extensively tested.

Usage

## S3 method for class 'VIgraph'
sort(x, decreasing = FALSE, by = "x", ...)

Arguments

Value

Returns a new object of the same type as that returned by VI.ggplot, but with data re-ordered.

Author(s)

Debra Warren and Paul Murrell

Examples

if (require(ggplot2)) {
    sort(VI(qplot(x=1:5, y=c(2,5,1,4,3))), decreasing=TRUE, by="y")
}

Unfinished Methods to help vision impaired useRs

Description

A set of methods that will (once coded) extract the most relevant information from a graphical object (or implied set of graphical objects) and display the interpreted results in text form.

The method includes representations of summary methods that are more suitable for blind useRs. For example, the method for a data.frame uses a single line for each variable instead of the normal column layout used by the summary method.

Details

This is the help page for the VI() functions that are not fully functional or below par in some way.

Value

This will vary according to the needs of vision impaired useRs and the specific objects that need to be interpreted.

In general, the output is a series of text strings printed in the console/terminal window in addition to the embedded command's normal functionality.

These functions do not create objects as do many R commands. Manipulations on the objects created by regular R expressions will need those regular expressions issued in addition to those of the VI family of functions.

Author(s)

Jonathan Godfrey