study.character: study.character

Description

Extracts study characteristics out of a NISO-JATS coded XML file. Use CERMINE to convert PDF to CERMXML files.

Usage

study.character(
  x,
  stats.mode = "all",
  recalculate.p = TRUE,
  alternative = "auto",
  estimateZ = FALSE,
  T2t = FALSE,
  R2r = FALSE,
  selectStandardStats = NULL,
  checkP = TRUE,
  criticalDif = 0.02,
  alpha = 0.05,
  p2alpha = TRUE,
  alpha_output = "list",
  captions = TRUE,
  text.mode = 1,
  update.package.list = FALSE,
  add.software = NULL,
  quantileDF = 0.9,
  N.max.only = FALSE,
  output = "all",
  rm.na.col = TRUE
)

Value

List with extracted study characteristics.

Arguments

x: NISO-JATS coded XML file.
stats.mode: Character. Select subset of standard stats. One of: c("all", "checkable", "computable").
recalculate.p: Logical. If TRUE recalculates p values (for 2 sided test) if possible.
alternative: Character. Select sidedness of recomputed p-values for t-, r- and Z-values. One of c("auto", "undirected", "directed"). If set to "auto" 'alternative' will be be set to 'directed' if get.test.direction() detects one-directional hypotheses/tests in text. If no directional hypotheses/tests are dtected only "undirected" recomputed p-values will be returned.
estimateZ: Logical. If TRUE detected beta-/d-value is divided by reported standard error "SE" to estimate Z-value ("Zest") for observed beta/d and recompute p-value. Note: This is only valid, if Gauss-Marcov assumptions are met and a sufficiently large sample size is used. If a Z- or t-value is detected in a report of a beta-/d-coefficient with SE, no estimation will be performed, although set to TRUE.
T2t: Logical. If TRUE capital letter T is treated as t-statistic when extracting statistics with get.stats().
R2r: Logical. If TRUE capital letter R is treated as correlation when extracting statistics with get.stats().
selectStandardStats: Select specific standard statistics only (e.g.: c("t", "F", "Chi2")).
checkP: Logical. If TRUE observed and recalculated p-values are checked for consistency.
criticalDif: Numeric. Sets the absolute maximum difference in reported and recalculated p-values for error detection.
alpha: Numeric. Defines the alpha level to be used for error assignment of detected incosistencies.
p2alpha: Logical. If TRUE detects and extracts alpha errors denoted with critical p-value (what may lead to some false positive detections).
alpha_output: One of c("list", "vector"). If alpha_output = "list" a list with elements: alpha_error, corrected_alpha, alpha_from_CI, alpha_max, alpha_min is returned. If alpha_output = "vector" unique alpha errors without a distinction of types is returned.
captions: Logical. If TRUE captions text will be scanned for statistical results.
text.mode: Numeric. Defines text parts to extract statistical results from (text.mode=1: abstract and full text, text.mode=2: method and result section, text.mode=3: result section only).
update.package.list: Logical. If TRUE updates available R packages with utils::available.packages() function.
add.software: additional software names to detect as vector.
quantileDF: quantile of (df1+1)+(df2+1) to extract for estimating sample size.
N.max.only: return only maximum of estimated sample sizes.
output: output selection of specific results c("doi", "title", "year", "Nstudies",
"methods", "alpha_error", "power", "multi_comparison_correction",
"assumptions", "OutlierRemovalInSD", "InteractionModeratorMediatorEffect",
"test_direction", "sig_adjectives", "software", "Rpackage", "stats",
"standardStats", "estimated_sample_size").
rm.na.col: Logical. If TRUE removes all columns with only NA in extracted standard statistics.

References

Böschen (2023). "Evaluation of the extraction of methodological study characteristics with JATSdecoder.” Scientific Reports. doi: 10.1038/s41598-022-27085-y.

Böschen (2021). "Evaluation of JATSdecoder as an automated text extraction tool for statistical results in scientific reports.” Scientific Reports. doi: 10.1038/s41598-021-98782-3.

Examples

Run this code

# download example XML file via URL
x<-"https://journals.plos.org/plosone/article/file?id=10.1371/journal.pone.0114876&type=manuscript"
# file name
file<-paste0(tempdir(),"/file.xml")
# download URL as "file.xml" in tempdir() if a connection is possible
tryCatch({
readLines(x,n=1)
download.file(x,file)
},
warning = function(w) message(
  "Something went wrong. Check your internet connection and the link address."),
error = function(e) message(
  "Something went wrong. Check your internet connection and the link address."))
# convert full article to list with study characteristics
if(file.exists(file)) study.character(file)