R/citations.R

In bibliometrix: Comprehensive Science Mapping Analysis

#' Citation frequency distribution
#'
#' It calculates frequency distribution of citations.
#'
#' @param M is a bibliographic data frame obtained by the converting function \code{\link{convert2df}}.
#'        It is a data matrix with cases corresponding to manuscripts and variables to Field Tag in the original SCOPUS and Clarivate Analytics Web of Science file.
#' @param field is a character. It can be "article" or "author" to obtain frequency distribution of cited citations or cited authors (only first authors for WoS database) respectively. The default is \code{field = "article"}.
#' @param sep is the field separator character. This character separates citations in each string of CR column of the bibliographic data frame. The default is \code{sep = ";"}.
#' @return an object of \code{class} "list"  containing the following components:
#'
#' \tabular{lll}{
#' Cited \tab  \tab the most frequent cited manuscripts or authors\cr
#' Year \tab       \tab the publication year (only for cited article analysis)\cr
#' Source \tab      \tab the journal (only for cited article analysis)}
#'
#' 
#'
#' @examples
#' ## EXAMPLE 1: Cited articles
#' 
#' data(scientometrics,package = "bibliometrixData")
#'
#' CR <- citations(scientometrics, field = "article", sep = ";")
#'
#' CR$Cited[1:10]
#' CR$Year[1:10]
#' CR$Source[1:10]
#'
#' ## EXAMPLE 2: Cited first authors
#' 
#' data(scientometrics)
#'
#' CR <- citations(scientometrics, field = "author", sep = ";")
#'
#' CR$Cited[1:10]
#'
#' @seealso \code{\link{biblioAnalysis}} function for bibliometric analysis.
#' @seealso \code{\link{summary}} to obtain a summary of the results.
#' @seealso \code{\link{plot}} to draw some useful plots of the results.
#'
#' @export

citations <- function(M, field = "article", sep = ";"){
  CR=NULL
  Year=NULL
  SO=NULL
  listCR=strsplit(M$CR,sep)
  
  ## check for empty CR
  if (sum(nchar(listCR)>3, na.rm = TRUE)==0){
    cat("\nReference metadata field 'CR' is empty!!\n\n")
    return(NA)
  }
  
  
  if (field=="author"){
    #listCR=strsplit(M$CR,sep)
    if (M$DB[1]=="ISI"){ 
      listCR=lapply(listCR, function(l){
        ListL=lapply(strsplit(unlist(l),","),function(x) x[1])
        l=trimws(trimES(gsub("[[:punct:]]"," ",unlist(ListL))))
      })}
    if (M$DB[1]=="SCOPUS"){ 
      listCR=lapply(listCR, function(l){
        ListL=lapply(l,function(x) {
          a=strsplit(x,"\\., ")
          ind=which(grepl("[[:digit:]]", a[[1]]))
          if (length(ind)==0) ind=1
          x=unlist(a[[1]][1:(ind[1]-1)])
        })
        l=trimws(trimES(gsub("[[:punct:]]"," ",unlist(ListL))))
      })}
  }
  
  
  if (field=="article"){
    #listCR=strsplit(M$CR,sep)
    listCR=lapply(listCR, function(l){
      l=l[grep(",",l)]
    })
  }
  
  CR=unlist(listCR)
  #CR=gsub("\\.","",CR)
  CR=CR[nchar(CR)>=3]
  CR=trim.leading(CR)
  CR=sort(table(CR),decreasing=TRUE)
  
  
  if (field=="article"){
    switch(M$DB[1],
           ISI={
             listCR=strsplit(rownames(CR),",")
             Year=unlist(lapply(listCR, function(l){
               if (length(l)>1){
                 l=suppressWarnings(as.numeric(l[2]))} else{l=NA}
             }))
             SO=unlist(lapply(listCR, function(l){
               if (length(l)>2){
                 l=l[3]} else{l=NA}
             }))
             SO=trim.leading(SO)
           },
           SCOPUS={
             REF=names(CR)
             y=yearSoExtract(REF)
             Year=as.numeric(y$Year)
             SO=y$SO
           })
  }
  CR=list(Cited=CR,Year=Year,Source=SO)
  return(CR)
}


yearSoExtract <- function(string){
  ## for scopus references
    ind=regexpr("\\([[:digit:]]{4}\\)",string)
    ind[is.na(ind)]=-1
    string[ind==-1]="(0000)"
    ind[ind==-1]=1
    attr(ind[ind==-1],"match.length")=6
    y=unlist(regmatches(string,ind))
    Year=substr(y,2,5)
    
    SO=sub(",.*$","",substr(string,ind+7,nchar(string)))
    y=list(Year=Year,SO=SO)
  return(y)
}