rpys_bl {BibPlots} R Documentation

## Create a spectrogram with bars and lines using data from the free software CRExplorer

### Description

Provide the contents of the CSV (Graph) file from the 'CRExplorer' in a data frame, e.g. df, and the function call rpys_bl(df) creates a spectrogram. Previously, you should use the function rpys for a plain line graph to determin the proper parameters, e.g., x_offset and x_range. Determination of the proper x_offset and x_range is a bit tricky. Usage of a wrong value of x_range will cause an error. Usage of a wrong value of x_offset will produce a plot. However, the line for the median deviation and the bars might not be at the proper location. First, adjust x_range if necessary, and second, adjust x_offset so that the x axis is properly aligned with the line and bars. Comapare the plot from rpys_bl with your data and the plot from the function rpys. The function rpys_bl takes some optional arguments to modify its behaviour, see arguments and details.

### Usage

rpys_bl(
df,
py1 = min(df$Year), py2 = max(df$Year),
x_range = py2 - py1 + 1,
col_cr = "grey",
col_med = "blue",
col_ol = "red",
smoothing = TRUE,
par_mar = c(5, 5, 1, 5),
x_offset = 0,
x_min = py1,
x_max = py2,
x_step1 = 10,
x_step2 = 5,
y1_min = 0,
y1_max = max(df$NCR), y1_step = (max(df$NCR) - min(df$NCR))/5, y2_min = min(df$Median.5),
y2_max = max(df$Median.5), y2_step = (max(df$Median.5) - min(df$Median.5))/5, lx = median(df$Year),
ly = median(df$Median.5), pl_offset = (max(df$NCR) - min(df\$NCR))/50,
bar_border = "white",
outliers = 2,
lpos = 3,
pl_cex = 0.9,
TFmin = py1,
TFmax = py2,
plot_NCR = TRUE,
plot_Med = TRUE,
...
)

### Arguments

 df data frame with reference publication year, number of cited references, and median deviation as exported from the CRExplorer (File > Export > CSV (Graph)). py1 determines lowest reference publication year which should be shown on the x axis (optional parameter). The default is the minimum RPY. py2 determines highest reference publication year which should be shown on the x axis (optional parameter). The default is the maximum RPY. x_range is the range of the x axis (optional parameter). The default is py2-py1+1. col_cr is a character color name value to determine color of the bars of the number of cited references (optional parameter). The default value is "grey". col_med is a character color name value to determine color of the line of the median deviation (optional parameter). The default value is "blue". col_ol is a character color name value to determine color of the outlier labels (optional parameter). The default value is "red". smoothing boolean variable (optional parameter) which determines if the lines of the spectrogram are smoothed or not. (T: yes apply smoothing, F: no do not apply smoothing). The default value is T. par_mar integer vector to set the margins (optional parameter). The default value is c(5, 5, 1, 5). x_offset determines the x axis offset to adjust the median deviation curve properly (optional parameter). The default is 0. x_min determines lowest reference publication year which should be shown on the x axis (optional parameter). The default is the minimum RPY. x_max determines highest reference publication year which should be shown on the x axis (optional parameter). The default is the maximum RPY. x_step1 is the interval of major x tics (optional parameter). x_step2 is the interval of minor x tics (optional parameter). y1_min is the minimum left y axis value (optional parameter). y1_max is the maximum left y axis value (optional parameter). y1_step is the interval left y axis (optional parameter). y2_min is the minimum right y axis value (optional parameter). y2_max is the maximum right y axis value (optional parameter). y2_step is the interval right y axis (optional parameter). lx is the x position of the legend (optional parameter). ly is the y position of the legend according to the right y axis (optional parameter). pl_offset is the offset of the year label (optional parameter). bar_border is the color around the bars (optional parameter). outliers is an integer that indicates if outliers should be detected (optional parameter): (0: no outlier detection, 1: outliers are detected and marked, 2: only extreme outliers are detected and marked) lpos is an integer that determines the position of the outlier year label around the point (optional parameter). Values of 1, 2, 3, and 4, respectively indicate positions below, to the left of, above, and to the right of the specified coordinates. pl_cex is the cex value of the year labels (optional parameter). TFmin is the first year that should be used for outlier detection according to Tukey's fences. TFmax is the last year that should be used for outlier detection according to Tukey's fences. plot_NCR boolean variable (optional parameter) which determines the NCR curve should be plotted. plot_Med boolean variable (optional parameter) which determines the median deviation curve should be plotted. ... additional arguments to pass to the plot function.

### Details

rpys_bl(df=data_frame, py1=integer_value, py2=integer_value, x_range=integer_value, smoothing=boolean, col_cr=character_color_name, col_med=character_color_name, col_ol=character_color_name, par_mar=integer_vector, plot_NCR=boolean, plot_Med=boolean, x_offset=integer_value, x_min=integer_value, x_max=integer_value, x_step1=integer_value, x_step2=integer_value, y1_min=integer_value, y1_max=integer_value, y1_step=integer_value, y2_min=integer_value, y2_max=integer_value, y2_step=integer_value, lx=integer_value, ly=integer_value, pl_offset=integer_value, bar_border=string_value, outliers=integer_value, lpos=integer_value, pl_cex=floating_point_value, TFmin=integer_value,TFmax=integer_value, ...) Only the argument df is necessary. All other aruments are optional, but many should be provided to produce nice plots.

Literature:

- Thor, A., Bornmann, L., & Haunschild, R. (2021). Website of the free software 'CRExplorer', http://www.crexplorer.net - Thor, A., Bornmann, L., & Haunschild, R. (2018). CitedReferencesExplorer (CRExplorer) manual. Retrieved December 19, 2019, from https://andreas-thor.github.io/cre/manual.pdf - Tukey, J. W. (1977). Exploratory data analysis. Boston, MA, USA: Addison-Wesley Publishing Company.

An example data frame is provided as rpys_example_data in the package. It can be used to create an example spectrogram.

### Examples

data(rpys_example_data)

rpys_bl(rpys_example_data)

rpys_bl(rpys_example_data, x_min=1930, x_max=2020, x_range=91, x_offset=1, lx=1926, ly=135,
y1max=300, y1_step=50, y2_min=-150, y2_max=150, y2_step=25, lpos=1)

rpys_bl(rpys_example_data, py1=1930, py2=2020, x_offset=1, lx=1926, ly=135, y1max=300,
y1_step=50, y2_min=-150, y2_max=150, y2_step=25, lpos=1)

[Package BibPlots version 0.0.8 Index]