Vignette tweaks

[njahn82]

Please find some suggestions to improve the vignette made during the rOpenSci software review. See the commit messages for more details.

[bmkramer]

Hi all,

Wow, following this process has shown me a lot about the large effort that goes into creating a full package, including making sure it builds right. Really impressed by all the work and commitment!

Going through the package's workflow from a user perspective, I noticed that there a still a few inconsistencies/omissions in the description of the functions in the vignette, mostly to do with the arguments listed and the code examples given. I've listed these below.

I was able to run all functionality with the test dataset (example_data.txt), including all visualizations. When I tested with a user-generated dataset from Web of Science (.txt file, 490 records), I encountered two instances that gave error messages:

1. In the step 'splitting author records' in authors_clean, the following error message was encountered at 48% progress and execution was halted:

_Error in data.frame(names = unique(unlist(strsplit(C1names, "; "))), : row names contain missing values

When using only a subset of the file (1st 100 records), this error did not occur.

2. Running plot_net_country() gave the following error: Error in Ops.data.frame(fromC, toC) : ‘+’ only defined for equally-sized data frames

Let me know if you want to have those files for testing (can't link them here b/c of WoS restrictions)

Below my comments on my observations on the vignette for the different functions in the package:

2.1 references_read()

• differences in arguments listed: -- arguments in vignette: data, dir, filename_root [NB filename_root gives error: unused argument] -- arguments in vignette example: data, package, dir -- arguments in help: data, dir, include_all -- arguments in help example: data, package
• example given in vignette does not correspond to recommended workflow for working with example data (creating directory 'data' and save the sample data ‘example_data.txt’ file in the ‘data’ folder)

Appendix 1

• export to Endnote (ciw) is positioned as the preferred/primary export format, but example data are given as .txt)
• export to .txt (Other file formats) is mentioned in step 4b only (not step 4)
• export to other file formats requires some additional parameters to be set (record content, file format)

2.2. authors_clean()

• vignette states 2 arguments, while function seems to have only one (references)
• argument for filename_root (or similar) is implied in the vignette text
• make clear how to include output as csv

2.2.1-2.2.3 authors_refine()

• In 2.2.1 vignette says function has 4 arguments, but only mentions review and prelim,
• In 2.2.3, vignette does list all 4 arguments for authors_refine()

2.4.1 plot_addresses_country()

• In vignette, argument mapRegion not mentioned
• In vignette, no example code line provided

2.4.2 plot_addresses_points()

• In vignette, argument mapCountry not mentioned
• In vignette, not specified that argument data is addresses element of the authors_georef() object, nor that that is NOT default in this function.

2.4.3 plot_net_coauthor()

• vignette lacks example code line

2.4.5 plot_net_address()

• only one of 3 additional arguments (lineAlpha) explained in vignette

Hope this is still helpful!