ConvergenceClubs (version 2.2.5)

plot.convergence.clubs: Plot method for S3 class convergence.clubs

Description

Plot the transition paths of units in the convergence clubs and the average transition paths of those clubs.

Usage

# S3 method for convergence.clubs
plot(
  x,
  y = NULL,
  nrows = NULL,
  ncols = NULL,
  clubs,
  avgTP = TRUE,
  avgTP_clubs,
  y_fixed = FALSE,
  legend = FALSE,
  save = FALSE,
  filename,
  path,
  width = 20,
  height = 15,
  device = c("pdf", "png", "jpeg"),
  res,
  plot_args,
  legend_args,
  breaks,
  ...
)

Arguments

x

an object of class convergence.clubs.

y

unused, added for compatibility with function plot

nrows

number of rows of the graphical layout, if NULL, it is automatically defined

ncols

number of columns of the graphical layout, if NULL, it is automatically defined

clubs

numeric scalar or vector, indicating for which clubs the transition path plot should be generated. Optional, if omitted, plots for all clubs are produced. If clubs=NULL, transition path are not plotted for any club.

avgTP

logical, indicates if a plot with the average transition paths of each convergence club should be produced. Default is TRUE.

avgTP_clubs

numeric scalar or vector, indicating for which clubs the average transition path should be displayed. Optional, if omitted, average transition paths for all clubs are plotted.

y_fixed

logical, should the scale of the y axis be the same for all plots? Default is FALSE.

legend

logical, should a legend be displayed? Default is FALSE.

save

logical, should the plot be saved as a file?

filename

optional, a string indicating the name of the file where the plot should be saved; must include the extension (e.g. "plot.pdf")

path

optional, a string representing the path of the directory where the plot should be saved; the path should not end with a slash symbol ("/")

width

the image width when saving the plot, in inches.

height

the image height when saving the plot, in inches.

device

string indicating the format to be used to save the plot; one of "pdf", "png" or "jpeg". The default is "pdf".

res

the resolution of the image, in ppi; only used with device="png" and device="jpeg"

plot_args

optional, a named list with the graphical parameters for the plot, see Details section.

legend_args

optional, a named list with the graphical parameters for the legend, see Details section.

breaks

a vector of integer values representing the columns (time periods) to be plotted. Accepted values are integers from 1 to T, that is the number of time periods included in the convergence procedure. Optional, if omitted, all periods are plotted.

...

other parameters to pass to function plot().

Details

nrows and ncols are optional parameters used to define the row and column number for the plot layout. Both or just one of them may be specified. If none of them is specified, the layout dimension is chosen automatically.

If legend=TRUE and a column with units' names is available in the x object, those names are truncated to fit the plot's legend. The graphical parameter cex may be used to modify the size of the legend's labels, default is 0.8

Note that, when using RStudio, one may incur in an error if the plot window is too small. Enlarging the plot window usually solves the problem.

List of argument that could be included in plot_args as a list:

• lty numeric scalar or vector indicating the line type (values available range from 1 to 6)

• type a string indicating whether the points (markers) should be displayed. If 'l' no markers are displayed; if 'o' markers are displayed;

• pch numeric scalar or vector to specify symbols to use when plotting points (markers). If omitted, customized markers are used for each line. If fixed (e.g. pch=1) the same marker is used for each line. (Values available range from 0 to 25)

• cex number indicating the amount by which plotting text and symbols should be scaled relative to the default. 1=default, 1.5 is 50% larger, 0.5 is 50% smaller, and so on. Default is 1.

• lwd number indicating the line width. Default is 1.

• xlab string indicating x-axis label. If omitted, 'Time', is displayed

• ylab string indicating y-axis label. If omitted, 'Relative transition path', is displayed

• cex.lab number indicating the amount by which plotting x and y labels should be scaled relative to cex. Default is 1.

• col option to specify colors for each line. Colors could be specified by index, name, hexadecimal, or RGB. For example col=1, col="white", and col="#FFFFFF" are equivalent. If omitted, colors are chosen randomly.

• col_hline color of the horizontal line for h=1. Default is 'black'.

• xmarks vector with tic marks to be displayed in the x axis.

• xlabs vector with labels of marks to be displayed in the x axis.

• xlabs_dir number indicating the direction of x-axis labels. For horizontal labels xlabs_dir=0; for vertical labels xlabs_dir=2.

List of argument that could be included in legend_args as a list:

• cex number indicating the amount by which plotting text and symbols should be scaled relative to the default. Default is 0.9

• lwd Number indicating the line width. Default is 1.

• y.intersp number indicating the space between each legend entry. Default is 1.

• max_length_labels maximum length of the labels displayed for each legend entry.

Note that, when using RStudio, one may incur in an error if the plot window is too small. Enlarging the plot window usually solves the problem. We suggest to export plots in the available formats ("pdf", "png" or "jpeg") using adequate values of width and height.

Examples

data("filteredGDP")

clubs <- findClubs(filteredGDP, dataCols=2:35, unit_names = 1, refCol=35, time_trim = 1/3,
                   cstar = 0, HACmethod = "FQSB")



### Plot transition paths for all clubs
plot(clubs)
plot(clubs, y_fixed=TRUE)
plot(clubs, nrows=2,ncols=4)

plot(clubs, ncols=3, lty='dotdash', lwd=3, col="blue")
plot(clubs, ncols=3, y_fixed=TRUE, lty='dotdash', lwd=3, col="blue")

### Plot transition paths only for some clubs
plot(clubs, clubs=c(2,4,5))
plot(clubs, nrows=1, ncols=3, clubs=c(2,4,5), avgTP = FALSE)
plot(clubs, nrows=1, ncols=3, clubs=c(2,4,5), avgTP = FALSE, legend=TRUE)
plot(clubs, clubs=c(2,4,5), avgTP_clubs = c(1,3))
plot(clubs, clubs=c(2,4,5), avgTP_clubs = c(1,3), legend=TRUE)


### Export customized plots
#Only plot average transition paths
plot(clubs, clubs=NULL, avgTP = TRUE, legend=TRUE)

#only lines, without markers and legend
plot(clubs, save = TRUE, filename ="name.pdf" , path = tempdir(), width = 15, height = 10)

#markers and legend (up to the fourth characther is shown)
plot(clubs, legend=TRUE, plot_args=list(type='o'),
    legend_args=list(max_length_labels=4, y.intersp=1),
    save = TRUE, filename ="name.pdf", path = tempdir(), width = 15, height = 10)

#for large samples the legend could be better displayed by plotting each club
#in turn and by increasing the plot dimension (through width and height)
plot(clubs, clubs=1, avgTP=FALSE, legend=TRUE, plot_args=list(type='o'),
    legend_args=list(max_length_labels=8, y.intersp=1),
    save = TRUE, filename ="name.pdf", path = tempdir(), width = 20, height = 15)

#customize x-labels - 1
plot(clubs, legend=TRUE, plot_args=list(type='o', xmarks=seq(1,34),xlabs=seq(1970,2003),
    xlabs_dir=0), legend_args=list(max_length_labels=4, y.intersp=1),
    save = TRUE, filename ="name.pdf" , path = tempdir(), width = 15, height = 10)

#customize x-labels - 2
plot(clubs, legend=TRUE, plot_args=list(type='o', xmarks=seq(1,34,1), xlabs=seq(1970,2003,1),
    xlabs_dir=2), legend_args=list(max_length_labels=4, y.intersp=1),
    save = TRUE, filename ="name.pdf" , path = tempdir(), width = 15, height = 10)

#show only the plot with the average transition paths of each club
plot(clubs, clubs=NULL, avgTP=TRUE, legend=TRUE,
    plot_args=list(type='o', xmarks=seq(1,34), xlabs=seq(1970,2003), xlabs_dir=0),
    save = TRUE, filename ="name.pdf" , path = tempdir(), width = 15, height = 10)

#markers and legend - png format
plot(clubs, legend=TRUE, plot_args=list(type='o'),
    legend_args=list(max_length_labels=4, y.intersp=1),
    save = TRUE, filename ="name.png" , path = tempdir(), width = 15, height = 10,
    device= "png", res=100)