Convert Between Different Available Units That Measure Points on a Plot

Description

Convert Between Different Available Units That Measure Points on a Plot

Usage

convertUnits(from, value, to, side = NULL, axis = NULL, region = "plot")

Arguments

Value

Numeric value(s) of the input coordinates converted into the new units.

Author(s)

Jasper Watson

Examples

## Not run: 

## Illustrate where the lines fall when using mtext:

plot(1:10)
mtext(1:26, line = -(1:26), side = 1, col = 'blue')
x <- convertUnits('line', 0:(-26), 'data', side = 1)
abline(h = x, col = 'red', lty = 2)

## Show how proportions of a plot can be identified:

plot(seq(as.Date('2018-01-01'), as.Date('2019-01-01'), length.out = 10), 1:10,
     pch = 19)

## Identify the "center" of the plot.
abline(h = convertUnits('proportion', 0.5, 'data', axis = 'y'),
       col = 'red', lwd = 4)
abline(v = convertUnits('proportion', 0.5, 'data', axis = 'x'),
       col = 'blue', lwd = 4)

print(convertUnits('proportion', 0.5, 'data', axis = 'y'))
## as.Date is needed because convertUnits returns a numeric value.
print(as.Date(convertUnits('proportion', 0.5, 'data', axis = 'x'),
      origin = '1970-01-01'))

## Change the region we are defining the proportions from.
abline(v = convertUnits('proportion', 0.75, 'data', axis = 'x', region = 'plot'),
       col = 'darkgreen', lwd = 4)
abline(v = convertUnits('proportion', 0.75, 'data', axis = 'x', region = 'device'),
       col = 'orange', lwd = 4)


## End(Not run)

Determine the Boundaries of a Plot in Terms of the Data Units

Description

Determine the Boundaries of a Plot in Terms of the Data Units

Usage

getBoundaries(region, units = "data", sides = 1:4)

Arguments

Value

A numeric vector of length four giving the coordinates of the plotting boundary, in the order of bottom, left, top, right.

Author(s)

Jasper Watson

Examples

## Not run: 

par(oma = 1:4)
plot(1:10)
print(getBoundaries('data'))
print(getBoundaries('plot'))
print(getBoundaries('figure'))
print(getBoundaries('device'))

print(getBoundaries('data', units = 'lines'))
print(getBoundaries('plot', units = 'lines'))
print(getBoundaries('figure', units = 'lines'))
print(getBoundaries('device', units = 'lines'))


## End(Not run)

Find the Number of Data Points Per Inch in a Plot

Description

Find the Number of Data Points Per Inch in a Plot

Usage

getDataPerInch()

Value

Numeric vector of length two giving the number of data points per inch, for the x axis and y axis, respectively.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getDataPerInch())


## End(Not run)

Find the Number of Data Points Per Margin Line in a Plot

Description

Find the Number of Data Points Per Margin Line in a Plot

Usage

getDataPerLine()

Value

Numeric vector of length two giving the number of data points per line, for the x axis and y axis, respectively.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getDataPerLine())


## End(Not run)

Find the Number of Data Points Per Pixel in a Plot

Description

Find the Number of Data Points Per Pixel in a Plot

Usage

getDataPerPixel()

Value

Numeric vector of length two giving the number of data points per pixel, for the x axis and y axis, respectively.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getDataPerPixel())


## End(Not run)

Find the Number of Inches Per Data Point in a Plot

Description

Find the Number of Inches Per Data Point in a Plot

Usage

getInchesPerDatum()

Value

Numeric vector of length two giving the number of inches per data point, for the x axis and y axis, respectively.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getInchesPerDatum())


## End(Not run)

Find the Number of Inches Per Margin Line in a Plot

Description

Find the Number of Inches Per Margin Line in a Plot

Usage

getInchesPerLine()

Value

Numeric vector of length two giving the number of inches per line, for the x axis and y axis, respectively.

Note

The number of lines per inch is the same for both the x and y axes but we return a vector of length two to maintain consistency with all of the other getXperY style functions.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getInchesPerLine())


## End(Not run)

Find the Number of Inches Per Pixel in a Plot

Description

Find the Number of Inches Per Pixel in a Plot

Usage

getInchesPerPixel()

Value

Numeric vector of length two giving the number of inches per pixel, for the x axis and y axis, respectively.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getInchesPerPixel())


## End(Not run)

Find the Number of Margin Lines Per Data Point in a Plot

Description

Find the Number of Margin Lines Per Data Point in a Plot

Usage

getLinesPerDatum()

Value

Numeric vector of length two giving the number of lines per data point, for the x axis and y axis, respectively.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getLinesPerDatum())


## End(Not run)

Find the Number of Margin Lines Per Inch in a Plot

Description

Find the Number of Margin Lines Per Inch in a Plot

Usage

getLinesPerInch()

Value

Numeric vector of length two giving the number of lines per inch, for the x axis and y axis, respectively.

Note

The number of lines per inch is the same for both the x and y axes but we return a vector of length two to maintain consistency with all of the other getXperY style functions.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getLinesPerInch())


## End(Not run)

Find the Number of Margin Lines Per Pixel in a Plot

Description

Find the Number of Margin Lines Per Pixel in a Plot

Usage

getLinesPerPixel()

Value

Numeric vector of length two giving the number of lines per pixel, for the x axis and y axis, respectively.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getLinesPerPixel())


## End(Not run)

Find the Number of Pixels Per Data Point in a Plot

Description

Find the Number of Pixels Per Data Point in a Plot

Usage

getPixelsPerDatum()

Value

Numeric vector of length two giving the number of pixels per data point, for the x axis and y axis, respectively.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getPixelsPerDatum())


## End(Not run)

Find the Number of Pixels Per Inch in a Plot

Description

Find the Number of Pixels Per Inch in a Plot

Usage

getPixelsPerInch()

Value

Numeric vector of length two giving the number of pixels per inch, for the x axis and y axis, respectively.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getPixelsPerInch())


## End(Not run)

Find the Number of Pixels Per Margin Line in a Plot

Description

Find the Number of Pixels Per Margin Line in a Plot

Usage

getPixelsPerLine()

Value

Numeric vector of length two giving the number of pixels per line, for the x axis and y axis, respectively.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getPixelsPerLine())


## End(Not run)

Determine the Width and Height of a Plot

Description

Determine the Width and Height of a Plot

Usage

getRange(region, units)

Arguments

Value

Numeric vector of length two giving the range of the plotting region, in the order of x-axis, y-axis.

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
print(getRange('data', 'in'))
print(getRange('plot', 'px'))
print(getRange('figure', 'data'))
print(getRange('device', 'lines'))


## End(Not run)

Highlight the Data Region of a Plot

Description

Highlight the Data Region of a Plot

Usage

highlightDataRegion(border = "green", col = adjustcolor(border, 0.1))

Arguments

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
highlightDataRegion()


## End(Not run)

Highlight the Device Region of a Plot

Description

Highlight the Device Region of a Plot

Usage

highlightDeviceRegion(border = "skyblue", col = adjustcolor(border, 0.1))

Arguments

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
par(xpd = NA)
highlightDeviceRegion()


## End(Not run)

Highlight the Figure Region of a Plot

Description

Highlight the Figure Region of a Plot

Usage

highlightFigureRegion(border = "orange", col = adjustcolor(border, 0.1))

Arguments

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
par(xpd = NA)
highlightFigureRegion()


## End(Not run)

Highlight the Plotting Region of a Plot

Description

Highlight the Plotting Region of a Plot

Usage

highlightPlotRegion(border = "red", col = adjustcolor(border, 0.1))

Arguments

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
highlightPlotRegion()


## End(Not run)

Wrapper Function for convertUnits Focused on Identifying the Locations of the Margin Lines of a Plot

Description

Wrapper Function for convertUnits Focused on Identifying the Locations of the Margin Lines of a Plot

Usage

lineLocations(side, line)

Arguments

Note

No attempt is made to limit the returned values to the device region.

Author(s)

Jasper Watson

Examples

## Not run: 

## Illustrate where the lines fall when using mtext:
plot(1:10)
mtext(1:26, line = -(1:26), side = 1, col = 'blue')
x <- lineLocations(1, 0:(-26))
abline(h = x, col = 'red', lty = 2)

## End(Not run)

Generate Values for par("omi") That Will Place a New Plot in a Sub-Region of an Existing One

Description

Generate Values for par("omi") That Will Place a New Plot in a Sub-Region of an Existing One

Usage

omiForSubFigure(
  bottom,
  left,
  top,
  right,
  units = "proportion",
  region = "device"
)

Arguments

Details

The choice of accepting proportions instead of data units by default is to more easily handle empty devices, otherwise there is a risk of getting confused by the fact that par("usr") defaults to c(0, 1, 0, 1).

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10, pch = 19, col = 'black')
oldPar = par()
par(omi = omiForSubFigure(0.6, 0.25, 0.8, 0.45, region = 'device'))
par(mar = c(0,0,0,0))
plot(1:10, pch = 19, col = 'red')
par(oldPar)
par(omi = omiForSubFigure(2, 6, 5, 10, units = 'data'))
par(mar = c(0,0,0,0))
plot(1:10, pch = 19, col = 'blue')
par(oldPar)

## Illustrates how the proportions line up:

plot(1:10, pch = 19)
par(xpd = NA)
oldPar = par()

## Show where the propotions are as a reference:
abline(v = convertUnits('proportion', seq(0, 1, by = 0.1), 'data',
       region = 'device', axis = 'x'), lty = 2, col = 'red')
abline(h = convertUnits('proportion', seq(0, 1, by = 0.1), 'data',
       region = 'device', axis = 'y'), lty = 2, col = 'red')

## Create a new sub-plot.
par(omi = omiForSubFigure(0.2, 0.2, 0.8, 0.8, region = 'device'))

plot(1:10, pch = 19, col = 'red')
highlightFigureRegion()

par(oldPar)


## End(Not run)

Suite of Functions To Get Plot Elements Exactly Where You Want Them

Description

This package provides a selection of tools that make it easier to place elements onto a (base R) plot exactly where you want them. It allows users to identify points and distances on a plot in terms of inches, pixels, margin lines, data units, and proportions of the plotting space, all in a manner more simple than manipulating par(). It helps users identify where exactly the margin lines of a plot fall and to create sub-figures.

Author(s)

Jasper Watson

Add Lines to a Plot to Indicate Where the Margins Are

Description

Add Lines to a Plot to Indicate Where the Margins Are

Usage

showMarginLines(sides = 1:4, lty = 2, ...)

Arguments

Author(s)

Jasper Watson

Examples

## Not run: 

plot(1:10)
par(xpd = NA)
showMarginLines()


## End(Not run)

Add Lines to a Plot to Indicate Where the Outer Margins Are

Description

Add Lines to a Plot to Indicate Where the Outer Margins Are

Usage

showOuterMarginLines(sides = 1:4, lty = 3, col = "purple", ...)

Arguments

Author(s)

Jasper Watson

Examples

## Not run: 

par(oma = 1:4, mfrow = 2:1)
plot(1:10)
plot(1:10)
par(xpd = NA)
showOuterMarginLines()


## End(Not run)