Package 'CiteSource'

Description

The CiteSource package supports evidence aggregation by helping with the processing of results of various searches in different sources. It allows to deduplicate results while retaining meta-data on where those results were found and then enables users to compare the contribution of different sources.

Author(s)

Maintainer: Trevor Riley [email protected] (ORCID)

Authors:

• Trevor Riley [email protected] (ORCID)

• Kaitlyn Hair [email protected] (ORCID)

• Lukas Wallrich [email protected] (ORCID)

• Matthew Grainger [email protected] (ORCID)

• Sarah Young [email protected] (ORCID)

• Chris Pritchard [email protected] (ORCID)

• Neal Haddaway [email protected] (ORCID)

Other contributors:

• Martin Westgate (Author of included synthesisr fragments) [copyright holder]

• Eliza Grames (Author of included synthesisr fragments) [copyright holder]

• Kaitlyn Hair (Author of included ASySD deduplication code) [copyright holder]

• CAMARADES Group (Authors of ASySD (github.com/camaradesuk/ASySD)) [copyright holder]

See Also

Useful links:

• https://eshackathon.github.io/CiteSource/

• Report bugs at https://github.com/ESHackathon/CiteSource/issues

Description

This function processes a dataset and expands the 'cite_source' column, filters on user-specified labels (if provided), and calculates detailed counts such as the records imported, distinct records, unique records, non-unique records, and several percentage contributions for each citation source/method it also adds a total row summarizing these counts.

Usage

calculate_detailed_records(
  unique_citations,
  n_unique,
  labels_to_include = NULL
)

Arguments

Details

The function first checks if the required columns are present in the input data frames. It then expands the cite_source column, filters the data based on the provided labels (if any), and calculates various counts and percentages for each citation source. The function also adds a total row summarizing these counts across all sources.

Value

A data frame with detailed counts for each citation source, including:

• ⁠Records Imported⁠: Total number of records imported.

• ⁠Distinct Records⁠: Number of distinct records after deduplication.

• ⁠Unique Records⁠: Number of unique records specific to a source.

• ⁠Non-unique Records⁠: Number of records found in other sources.

• ⁠Source Contribution %⁠: Percentage contribution of each source to the total distinct records.

• ⁠Source Unique Contribution %⁠: Percentage contribution of each source to the total unique records.

• ⁠Source Unique %⁠: Percentage of unique records within the distinct records for each source.

Examples

# Example usage with a sample dataset
unique_citations <- data.frame(
  cite_source = c("Source1, Source2", "Source2", "Source3"),
  cite_label = c("Label1", "Label2", "Label1"),
  duplicate_id = c(1, 2, 3)
)
n_unique <- data.frame(
  cite_source = c("Source1", "Source2", "Source3"),
  cite_label = c("search", "search", "search"),
  unique = c(10, 20, 30)
)
calculate_detailed_records(unique_citations, n_unique, labels_to_include = "search")

Description

This function processes a dataset of unique citations, expands the cite_source column, filters based on user-specified labels (if provided), and then calculates the number of records imported and distinct records for each citation source. It also adds a total row summarizing these counts.

Usage

calculate_initial_records(unique_citations, labels_to_include = NULL)

Arguments

Details

The function first checks if the required columns are present in the input data frame. It then expands the cite_source column to handle multiple sources listed in a single row and filters the dataset based on the provided labels (if any). The function calculates the number of records imported (total rows) and the number of distinct records (unique duplicate_id values) for each citation source. Finally, a total row is added to summarize the counts across all sources.

Value

A data frame containing the counts of ⁠Records Imported⁠ and ⁠Distinct Records⁠ for each citation source. The data frame also includes a "Total" row summing the counts across all sources.

Examples

# Example usage with a sample dataset
unique_citations <- data.frame(
  cite_source = c("Source1", "Source2", "Source3"),
  cite_label = c("Label1", "Label2", "Label3"),
  duplicate_id = c(1, 2, 3)
)
calculate_initial_records(unique_citations)

Description

This function calculates counts for different phases and calculates precision and recall for each source based on unique citations and citations dataframe. The phases should be labeled as 'screened' and 'final' (case-insensitive) in the input dataframes. The function will give a warning if these labels are not present in the input dataframes.

Usage

calculate_phase_count(unique_citations, citations, db_colname)

Arguments

Details

The function will give a warning if 'screened' and 'final' labels are not present in the 'cite_label' column of the input dataframes.

Value

A dataframe containing distinct counts, counts for different phases, precision, and recall for each source, as well as totals.

Examples

unique_citations <- data.frame(
db_source = c("Database1", "Database1", "Database2", "Database3", "Database3", "Database3"),
cite_label = c("screened", "final", "screened", "final", "screened", "final"),
duplicate_id = c(102, 102, 103, 103, 104, 104),
other_data = 1:6
)

citations <- data.frame(
db_source = c("Database1", "Database1", "Database1", "Database2", "Database2", "Database3"),
cite_label = c("screened", "final", "screened", "final", "screened", "final"),
other_data = 7:12
)

result <- calculate_phase_count(unique_citations, citations, "db_source")
result

Description

This function calculates the distinct record counts, as well as screened and final record counts, for each citation source across different phases (e.g., "screened", "final"). It also calculates precision and recall metrics for each source.

Usage

calculate_phase_records(unique_citations, n_unique, db_colname)

Arguments

Details

The function starts by calculating the total distinct records, as well as the total "screened" and "final" records across all sources. It then calculates distinct counts for each source, followed by counts for "screened" and "final" records. Finally, it calculates precision and recall metrics and adds a total row summarizing these counts across all sources.

Value

A data frame with phase counts and calculated precision and recall for each citation source, including:

• ⁠Distinct Records⁠: The count of distinct records per source.

• screened: The count of records in the "screened" phase.

• final: The count of records in the "final" phase.

• Precision: The precision metric calculated as ⁠final / Distinct Records⁠.

• Recall: The recall metric calculated as ⁠final / Total final records⁠.

Examples

# Example usage with a sample dataset
unique_citations <- data.frame(
  cite_source = c("Source1", "Source2", "Source3"),
  cite_label = c("screened","screened", "final"),
  duplicate_id = c(1, 2, 3)
)
n_unique <- data.frame(
  cite_source = c("Source1", "Source2", "Source3"),
  unique = c(10, 20, 30)
)
calculate_phase_records(unique_citations, n_unique, "cite_source")

Description

This function calculates the counts of distinct records, records imported, and unique records for each database source. It combines these counts into one dataframe and calculates several ratios and percentages related to the unique and distinct counts. It also calculates the total for each count type.

Usage

calculate_record_counts(unique_citations, citations, n_unique, db_colname)

Arguments

Value

A dataframe with counts of distinct records, imported records, and unique records for each source, including total counts and several calculated ratios and percentages.

Examples

unique_citations <- data.frame(
  db_source = c("Database1", "Database1", "Database2", "Database3", "Database3", "Database3"),
  other_data = 1:6
)

citations <- data.frame(
  db_source = c("Database1", "Database1", "Database1", "Database2", "Database2", "Database3"),
  other_data = 7:12
)

n_unique <- data.frame(
  cite_source = c("Database1", "Database2", "Database2", "Database3", "Database3", "Database3"),
 cite_label = c("search", "final", "search", "search", "search", "final"),
  unique = c(1, 0, 1, 1, 1, 0)
)

result <- calculate_record_counts(unique_citations, citations, n_unique, "db_source")
print(result)

Description

Create a summary table to show the contribution of each source and the overall performance of the search. For this to work, labels need to be used that contrast a "search" stage with one or more later stages.

Usage

citation_summary_table(
  citations,
  comparison_type = "sources",
  search_label = "search",
  screening_label = "final",
  top_n = NULL
)

Arguments

Value

A tibble containing the contribution summary table, which shows the contribution of each source and the overall performance of the search

Examples

if (interactive()) {
# Load example data from the package
examplecitations_path <- system.file("extdata", "examplecitations.rds", package = "CiteSource")
examplecitations <- readRDS(examplecitations_path)

# Deduplicate citations and compare sources
unique_citations <- dedup_citations(examplecitations)

unique_citations |> 
dplyr::filter(stringr::str_detect(cite_label, "final"))  |> 
record_level_table(return = "DT")
citation_summary_table(unique_citations, screening_label = c("screened", "final"))
}

Description

Compare duplicate citations across sources, labels, and strings

Usage

compare_sources(
  unique_data,
  comp_type = c("sources", "strings", "labels"),
  include_references = FALSE
)

Arguments

Value

dataframe with indicators of where a citation appears, with sources/labels/strings as columns

Examples

if (interactive()) {
  # Load example data from the package
  examplecitations_path <- system.file("extdata", "examplecitations.rds", package = "CiteSource")
  examplecitations <- readRDS(examplecitations_path)

  # Deduplicate citations and compare sources
  dedup_results <- dedup_citations(examplecitations)
  compare_sources(dedup_results, comp_type = "sources")
}

Description

Count number of unique and non-unique citations from different sources, labels, and strings

Usage

count_unique(unique_data, include_references = FALSE)

Arguments

Value

dataframe with indicators of where a citation appears, with source/label/string as column

Examples

# Load example data from the package
examplecitations_path <- system.file("extdata", "examplecitations.rds", package = "CiteSource")
examplecitations <- readRDS(examplecitations_path)

# Deduplicate citations
dedup_results <- dedup_citations(examplecitations)

# Count unique and non-unique citations
count_unique(dedup_results)

Description

This function generates a formatted summary table using the gt package, which displays detailed counts for each citation source. The table includes columns for the number of records imported, distinct records, unique records, non-unique records, and various contribution percentages. Data from the function calculate_detailed_records is pre-formatted for this table.

Usage

create_detailed_record_table(data)

Arguments

Value

A gt table object summarizing the detailed record counts for each citation source.

Examples

sample_data <- data.frame(
  Source = c("Source1", "Source2", "Total"),
  `Records Imported` = c(100, 150, 250),
  `Distinct Records` = c(90, 140, 230),
  `Unique Records` = c(50, 70, 120),
  `Non-unique Records` = c(40, 70, 110),
  `Source Contribution %` = c("39.1%", "60.9%", "100%"),
  `Source Unique Contribution %` = c("41.7%", "58.3%", "100%"),
  `Source Unique %` = c("55.6%", "50%", "52.2%"),
  check.names = FALSE
)
create_detailed_record_table(sample_data)

Description

This function generates a formatted table displaying the record counts for each citation source, including the number of records imported and the distinct records after deduplication.

Usage

create_initial_record_table(data)

Arguments

Details

The function checks if the input data frame is empty and returns an empty gt table if no data is present. Otherwise, it generates a formatted table with labeled columns and adds footnotes explaining the meaning of each column.

Value

A gt table object summarizing the record counts for each citation source.

Examples

sample_data <- data.frame(
  Source = c("Source1", "Source2", "Source3"),
  Records_Imported = c(100, 150, 250),
  Distinct_Records = c(90, 140, 230)
)
create_initial_record_table(sample_data)

Description

This function generates a formatted table that displays the precision and sensitivity (recall) metrics for each citation source, along with distinct records and phase-specific counts such as "screened" and "final".

Usage

create_precision_sensitivity_table(data)

Arguments

Details

The function first checks whether all values in the screened column are zero. If so, the column is removed from the table. The table is then generated using the gt package, with labeled columns and footnotes explaining the metrics.

Value

A gt table object summarizing the precision and sensitivity metrics for each citation source, with relevant footnotes and labels.

Examples

sample_data <- data.frame(
  Source = c("Source1", "Source2", "Total"),
  Distinct_Records = c(100, 150, 250),
  final = c(80, 120, 200),
  Precision = c(80.0, 80.0, 80.0),
  Recall = c(40.0, 60.0, 100.0),
  screened = c(90, 140, 230)
)
create_precision_sensitivity_table(sample_data)

Description

Deduplicates citation data. Duplicates are assumed to be published in the same journal, so pre-prints vs. their published versions will not be merged.

Usage

dedup_citations(raw_citations, manual = FALSE, show_unknown_tags = FALSE)

Arguments

Value

When manual = FALSE: a dataframe of unique citations. When manual = TRUE: a list with ⁠$unique⁠ (unique citations), ⁠$manual_dedup⁠ (potential pairs for review), and ⁠$auto_pairs⁠ (pairs that were merged automatically - feed to dedup_log() together with confirmed manual pairs to build a full provenance log).

Examples

# Load example data from the package
examplecitations_path <- system.file("extdata", "examplecitations.rds",
                                      package = "CiteSource")
examplecitations <- readRDS(examplecitations_path)

# Deduplicate citations
dedup_results <- dedup_citations(examplecitations)

# Return potential pairs for manual review
dedup_results_manual <- dedup_citations(examplecitations, manual = TRUE)

Description

Add manually identified duplicate pairs to a deduplicated dataset

Usage

dedup_citations_add_manual(unique_citations, additional_pairs)

Arguments

Value

Updated unique citations dataframe with manual duplicates merged.

Examples

# Load example data from the package
examplecitations_path <- system.file("extdata", "examplecitations.rds",
                                      package = "CiteSource")
examplecitations <- readRDS(examplecitations_path)

# Deduplicate and retrieve manual pairs
dedup_results <- dedup_citations(examplecitations, manual = TRUE)
# (user reviews dedup_results$manual_dedup and sets result == "match" for true dups)
# final <- dedup_citations_add_manual(dedup_results$unique, dedup_results$manual_dedup)

Description

Adds further citations (e.g. an additional database search) to a set that was already deduplicated, and deduplicates the new records against both the existing set and each other - without discarding the work already done. Each existing unique record enters as a single row, so prior automatic and manual merge decisions are preserved; the new records are integrated and full provenance (the original record_ids behind every merged record) is carried through.

Usage

dedup_citations_add_sources(
  existing_citations,
  new_citations,
  manual = FALSE,
  show_unknown_tags = FALSE
)

Arguments

Details

This is the incremental counterpart to running dedup_citations() on all sources from scratch and, for the same data, produces the same unique set.

Value

When manual = FALSE: a dataframe of unique citations across both sets. When manual = TRUE: a list with ⁠$unique⁠, ⁠$manual_dedup⁠ and ⁠$auto_pairs⁠ (as in dedup_citations()). In both cases record_ids retains the original record IDs behind every merged record.

See Also

dedup_citations(), dedup_citations_add_manual()

Examples

if (interactive()) {
  existing <- dedup_citations(read_citations(old_files, cite_sources = old_srcs))
  new_raw  <- read_citations(new_files, cite_sources = new_srcs)
  combined <- dedup_citations_add_sources(existing, new_raw)
}

Description

Combines automatically merged pairs and user-confirmed manual pairs into a single tibble with a method column ("auto" / "manual"). Useful for reporting and auditing - e.g. as supplementary material for a systematic review.

Usage

dedup_log(dedup_result, confirmed_manual_pairs = NULL)

Arguments

Value

Tibble with columns method, record_id1, record_id2, and the common bibliographic fields (title1/2, author1/2, year1/2, journal1/2, doi1/2) when available.

Examples

examplecitations_path <- system.file("extdata", "examplecitations.rds",
                                      package = "CiteSource")
examplecitations <- readRDS(examplecitations_path)
dedup_results <- dedup_citations(examplecitations, manual = TRUE)
# Log of just the auto-merged pairs
dedup_log(dedup_results)
# Or include user-confirmed manual pairs
# dedup_log(dedup_results, confirmed_manual_pairs = my_confirmed_pairs)

Description

Bibliographic data can be stored in a number of different file types, meaning that detecting consistent attributes of those files is necessary if they are to be parsed accurately. These functions attempt to identify some of those key file attributes. Specifically, detect_parser determines which parse_ function to use; detect_delimiter and detect_lookup identify different attributes of RIS files; and detect_year attempts to fill gaps in publication years from other information stored in a data.frame.

Usage

detect_parser(x)

detect_delimiter(x)

detect_lookup(tags)

detect_year(df)

Arguments

Value

detect_parser and detect_delimiter return a length-1 character; detect_year returns a character vector listing estimated publication years; and detect_lookup returns a data.frame.

Description

This function saves deduplicated citations as a BibTex file with sources, labels and strings included in the note field (if they were initially provided for any of the citations). Therefore, beware that any note field that might be included in citations will be overwritten. Also note that existing files are overwritten without warning.

Usage

export_bib(citations, filename, include = c("sources", "labels", "strings"))

Arguments

Value

No return value, called for side effects. Saves deduplicated citations as a 'BibTeX' file to the specified location.

Examples

if (interactive()) {
  # Load example data from the package
  examplecitations_path <- system.file("extdata", "examplecitations.rds", package = "CiteSource")
  examplecitations <- readRDS(examplecitations_path)
  dedup_results <- dedup_citations(examplecitations, merge_citations = TRUE)
  export_bib(dedup_results$unique, tempfile(fileext = ".bib"), include = "sources")
}

Description

This function saves deduplicated citations as a CSV file for further analysis and/or reporting. Metadata can be separated into one column per source, label or string, which facilitates analysis. Note that existing files are overwritten without warning.

Usage

export_csv(
  unique_citations,
  filename,
  fields = "full",
  separate = NULL,
  trim_abstracts = 32000,
  manual_dedup_complete = FALSE
)

Arguments

Value

No return value, called for side effects. Saves the deduplicated citations as a 'CSV' file to the specified location.

Examples

if (interactive()) {
  # Load example data from the package
  examplecitations_path <- system.file("extdata", "examplecitations.rds", package = "CiteSource")
  examplecitations <- readRDS(examplecitations_path)
  dedup_results <- dedup_citations(examplecitations, merge_citations = TRUE)
  export_csv(dedup_results, tempfile(fileext = ".csv"), separate = "cite_source")
  # Standard export for RELApp / screening tools (not reimportable into CiteSource):
  export_csv(dedup_results, tempfile(fileext = ".csv"), fields = "standard")
}

Description

Saves the candidate duplicate pairs returned as the ⁠$manual_dedup⁠ element of dedup_citations(manual = TRUE) so that manual review can be completed later. Combine with export_csv() to defer manual deduplication: export the automatically deduplicated unique citations and these candidate pairs now, then re-import both later with reimport_csv() and reimport_dedup_candidates() to finish the review. Note that existing files are overwritten without warning.

Usage

export_dedup_candidates(manual_dedup, filename)

Arguments

Value

No return value, called for side effects. Saves the candidate pairs as a 'CSV' file to the specified location.

See Also

reimport_dedup_candidates(), dedup_citations_add_manual()

Examples

if (interactive()) {
  examplecitations_path <- system.file("extdata", "examplecitations.rds", package = "CiteSource")
  examplecitations <- readRDS(examplecitations_path)
  dedup_results <- dedup_citations(examplecitations, manual = TRUE)
  export_dedup_candidates(dedup_results$manual_dedup, tempfile(fileext = ".csv"))
}

Description

This function saves a data frame as a RIS file with specified columns mapped to RIS fields. Note that existing files are overwritten without warning.

Usage

export_ris(
  citations,
  filename,
  source_field = "DB",
  label_field = "C7",
  string_field = "C8"
)

Arguments

Value

No return value, called for side effects. Saves the citations as a 'RIS' file to the specified location.

Examples

if (interactive()) {
  # Load example data from the package
  examplecitations_path <- system.file("extdata", "examplecitations.rds", package = "CiteSource")
  examplecitations <- readRDS(examplecitations_path)
  dedup_results <- dedup_citations(examplecitations, merge_citations = TRUE)
  export_ris(dedup_results$unique, tempfile(fileext = ".ris"))
}

Description

Takes two or more data.frames with different column names or different column orders and binds them to a single data.frame.

Usage

merge_columns(x, y)

Arguments

Value

Returns a single data.frame with all the input data frames merged.

Description

Text in standard formats - such as imported via readLines - can be parsed using a variety of standard formats. Use detect_parser to determine which is the most appropriate parser for your situation.

Usage

parse_pubmed(x)

parse_ris(x, tag_naming = "best_guess")

parse_bibtex(x)

parse_csv(x)

parse_tsv(x)

Arguments

Value

Returns an object of class bibliography (ris, bib, or pubmed formats) or data.frame (csv or tsv).

Description

Create a faceted plot that shows unique contributions and duplicated records across two metadata dimensions. Most typical use-case might be to show the contributions of each source across different screening stages.

Usage

plot_contributions(
  data,
  facets = cite_source,
  bars = cite_label,
  color = type,
  center = FALSE,
  bar_order = "keep",
  facet_order = "keep",
  color_order = "keep",
  totals_in_legend = FALSE
)

Arguments

Value

A ggplot2 object showing source contributions as a faceted bar chart. The object can be further customized using ggplot2 functions or saved with ggsave.

Examples

data <- data.frame(
  article_id = 1:100,
  cite_source = sample(c("DB 1", "DB 2", "DB 3"), 100, replace = TRUE),
  cite_label = sample(c("2020", "2021", "2022"), 100, replace = TRUE),
  type = c("unique", "duplicated")[rbinom(100, 1, .7) + 1]
)

plot_contributions(data,
  center = TRUE, bar_order = c("2022", "2021", "2020"),
  color_order = c("unique", "duplicated")
)

Description

Show overlap between different record sources, either by showing the number or the percentages of shared records between any pair of sources.

Usage

plot_source_overlap_heatmap(
  data,
  cells = "source",
  facets = NULL,
  plot_type = c("counts", "percentages"),
  sort_sources = TRUE,
  interactive = FALSE,
  show_labels = "auto",
  log_scale = FALSE
)

Arguments

Value

The requested plot as a either a ggplot2 object (when interactive = FALSE), which can then be further formatted or saved using ggplot2::ggsave(), or a plotly object when interactive = TRUE

Examples

data <- data.frame(
  article_id = 1:500,
  source__source1 = rbinom(500, 1, .5) == 1,
  source__source2 = rbinom(500, 1, .2) == 1,
  source__source3 = rbinom(500, 1, .1) == 1,
  source__source4 = rbinom(500, 1, .6) == 1,
  source__source5 = rbinom(500, 1, .7) == 1
)

plot_source_overlap_heatmap(data)
plot_source_overlap_heatmap(data, plot_type = "percentages")

Description

Show records found in specific sets of sources to identify the unique contribution of each source and of any subsets

Usage

plot_source_overlap_upset(
  data,
  groups = "source",
  nsets = NULL,
  sets.x.label = "Number of records",
  mainbar.y.label = "Overlapping record count",
  order.by = c("freq", "degree"),
  ...
)

Arguments

Value

No return value, called for side effects. Renders an UpSet plot showing record overlap between sources to the current graphics device.

References

Conway, J. R., Lex, A., & Gehlenborg, N. (2017). UpSetR: an R package for the visualization of intersecting sets and their properties. Bioinformatics.

Examples

data <- data.frame(
  article_id = 1:500,
  source__source1 = rbinom(500, 1, .5) == 1,
  source__source2 = rbinom(500, 1, .2) == 1,
  source__source3 = rbinom(500, 1, .1) == 1,
  source__source4 = rbinom(500, 1, .6) == 1,
  source__source5 = rbinom(500, 1, .7) == 1
)

plot_source_overlap_upset(data)

# To start with the records shared among the greatest number of sources, use

plot_source_overlap_upset(data, decreasing = c(TRUE, TRUE))

Description

This function imports RIS and Bibtex files with citations and merges them into one long tibble with one record per line.

Usage

read_citations(
  files = NULL,
  cite_sources = NULL,
  cite_strings = NULL,
  cite_labels = NULL,
  metadata = NULL,
  verbose = TRUE,
  tag_naming = "best_guess",
  only_key_fields = TRUE
)

Arguments

Value

A tibble with one row per citation

Examples

if (interactive()) {
  # Import only key fields from the RIS files
  read_citations(c("res.ris", "res.bib"),
    cite_sources = c("CINAHL", "MEDLINE"),
    cite_strings = c("Search1", "Search2"),
    cite_labels = c("raw", "screened"),
    only_key_fields = TRUE
  )

  # or equivalently
  metadata_tbl_key_fields <- tibble::tribble(
   ~files,     ~cite_sources, ~cite_strings, ~cite_labels, ~only_key_fields,
  "res.ris",  "CINAHL",      "Search1",     "raw",        TRUE,
  "res.bib",  "MEDLINE",     "Search2",     "screened",   TRUE
  )

  read_citations(metadata = metadata_tbl_key_fields)
}

Description

This function calculates the counts of distinct records and records imported for each database source. It combines these counts into one dataframe and calculates the total for each count type.

Usage

record_counts(unique_citations, citations, db_colname)

Arguments

Value

A dataframe with counts of distinct records and imported records for each source, including total counts.

Examples

# Create synthetic data for example
unique_citations <- data.frame(
  title = paste("Article", 1:10),
  db_source = sample(c("Database 1", "Database 2", "Database 3"), 10, replace = TRUE),
  stringsAsFactors = FALSE
)

citations <- data.frame(
  title = paste("Article", 1:20),
  db_source = sample(c("Database 1", "Database 2", "Database 3"), 20, replace = TRUE),
  stringsAsFactors = FALSE
)

# Use the synthetic data with the function
result <- record_counts(unique_citations, citations, "db_source")
result

Description

Creates a per-record table that shows which sources (and/or labels/strings) each item was found in.

Usage

record_level_table(
  citations,
  include = "sources",
  include_empty = TRUE,
  return = c("tibble", "DT"),
  indicator_presence = NULL,
  indicator_absence = NULL
)

Arguments

Value

A tibble or DataTable containing the per-record table that shows which sources (and/or labels/strings) each item was found in.

Examples

# Load example data from the package
examplecitations_path <- system.file("extdata", "examplecitations.rds", package = "CiteSource")
examplecitations <- readRDS(examplecitations_path)

# Deduplicate citations and compare sources
unique_citations <- dedup_citations(examplecitations)

unique_citations |> 
dplyr::filter(stringr::str_detect(cite_label, "final"))  |> 
record_level_table(return = "DT")

Description

This function reimports a csv file that was tagged and deduplicated by CiteSource. It allows to continue with further analyses without repeating that step, and also allows users to make any manual corrections to tagging or deduplication. Note that this function only works on CSV files that were written with export_csv(..., separate = NULL)

Usage

reimport_csv(filename)

Arguments

Value

A data frame containing the imported citation data if all required columns are present.

Examples

if (interactive()) {
  citations <- reimport_csv("path/to/citations.csv")
}

Description

Reads a CSV of candidate duplicate pairs previously written by export_dedup_candidates() (i.e. the ⁠$manual_dedup⁠ element of dedup_citations(manual = TRUE)). This supports a deferred workflow: run automatic deduplication now, export both the unique citations and the candidate pairs, and complete the manual review later after re-importing.

Usage

reimport_dedup_candidates(filename)

Arguments

Details

After review, set the result column to "match" for confirmed duplicates and pass the result, together with the reimported unique citations, to dedup_citations_add_manual().

Value

A data frame of candidate pairs with duplicate_id.x / duplicate_id.y read as character (matching the unique citations from reimport_csv()), ready for review and dedup_citations_add_manual().

See Also

export_dedup_candidates(), dedup_citations_add_manual()

Examples

if (interactive()) {
  candidates <- reimport_dedup_candidates("path/to/candidates.csv")
  # mark confirmed duplicates, then merge into the reimported unique set
  candidates$result <- ifelse(candidates$result == "match", "match", "no_match")
  final <- dedup_citations_add_manual(reimport_csv("unique.csv"), candidates)
}

Description

This function reimports a RIS file that was tagged and deduplicated by CiteSource. It allows to continue with further analyses without repeating that step, and also allows users to make any manual corrections to tagging or deduplication. The function can also be used to replace the import step (for instance if tags are to be added to individual citations rather than entire files) - in this case, just call dedup_citations() after the import.

Usage

reimport_ris(
  filename = "citations.ris",
  source_field = "DB",
  label_field = "C7",
  string_field = "C8",
  duplicate_id_field = "C1",
  record_id_field = "C2",
  tag_naming = "ris_synthesisr",
  verbose = TRUE
)

Arguments

Details

Note that this functions defaults' are based on those in export_ris() so that these functions can easily be combined.

Value

A data frame containing the reimported citation data, with 'CiteSource' metadata columns (cite_source, cite_label, cite_string, duplicate_id, record_ids) restored from the 'RIS' fields.

Examples

if (interactive()) {
  dedup_results <- dedup_citations(citations, merge_citations = TRUE)
  tmp <- tempfile(fileext = ".ris")
  export_ris(dedup_results$unique, tmp)
  unique_citations2 <- reimport_ris(tmp)
}

Description

Running this function will launch the CiteSource shiny app

Usage

runShiny(app = "CiteSource", offer_install = interactive())

Arguments

Value

CiteSource shiny app

Examples

if (interactive()) {
  # To run the CiteSource Shiny app:
  runShiny()
}

Description

Imports common bibliographic reference formats (i.e. .bib, .ris, or .txt).

Usage

synthesisr_read_refs(
  filename,
  tag_naming = "best_guess",
  return_df = TRUE,
  verbose = FALSE,
  select_fields = NULL
)

read_ref(
  filename,
  tag_naming = "best_guess",
  return_df = TRUE,
  verbose = FALSE,
  select_fields = NULL
)

Arguments

Details

The default for argument tag_naming is "best_guess", which estimates what database has been used for ris tag replacement, then fills any gaps with generic tags. Any tags missing from the database (i.e. code_lookup) are passed unchanged. Other options are to use tags from Web of Science ("wos"), Scopus ("scopus"), Ovid ("ovid") or Academic Search Premier ("asp"). If a data.frame is given, then it must contain two columns: "code" listing the original tags in the source document, and "field" listing the replacement column/tag names. The data.frame may optionally include a third column named "order", which specifies the order of columns in the resulting data.frame; otherwise this will be taken as the row order. Finally, passing "none" to replace_tags suppresses tag replacement.

Value

Returns a data.frame or list of assembled search results.

Functions

• read_ref(): Import a single file

Description

This function exports data.frames containing bibliographic information to either a .ris or .bib file.

Usage

write_bib(x)

write_ris(x, tag_naming = "synthesisr")

write_refs(x, format = "ris", tag_naming = "synthesisr", file = FALSE)

Arguments

Value

Returns a character vector containing bibliographic information in the specified format if file is FALSE, or saves output to a file if TRUE.

Functions

• write_bib(): Format a bib file for export

• write_ris(): Format a ris file for export