Package {bibnets}


Title: Importing, Constructing, and Exporting Bibliometric Networks
Version: 0.7.0
Description: Imports, constructs, and exports bibliometric networks from scholarly metadata. Reads 'Scopus', 'Web of Science', 'BibTeX', 'RIS', 'OpenAlex', 'Lens.org', 'Dimensions', and 'Crossref' exports. Goes beyond standard co-networks with attention-weighted networks (lead, last, proximity, circular position weights), position-aware counting (harmonic, arithmetic, geometric, golden-ratio), similarity and dissimilarity normalisations, temporal networks with fixed, sliding, and cumulative windows, disparity-filter backbone extraction, historiograph construction, and local citation scoring. Methods described in López-Pernas, Saqr & Apiola (2023) <doi:10.1007/978-3-031-25336-2_5>.
License: MIT + file LICENSE
URL: https://github.com/mohsaqr/bibnets
BugReports: https://github.com/mohsaqr/bibnets/issues
Depends: R (≥ 4.1.0)
Imports: Matrix, stats, utils
Suggests: cograph, igraph, knitr, openalexR, rcrossref, rmarkdown, testthat (≥ 3.0.0), tidygraph
VignetteBuilder: knitr
Config/testthat/edition: 3
Encoding: UTF-8
LazyData: true
LazyDataCompression: xz
RoxygenNote: 7.3.3
NeedsCompilation: no
Packaged: 2026-11-17 14:15:14 UTC; mohammedsaqr
Author: Mohammed Saqr ORCID iD [aut, cre, cph], Sonsoles López-Pernas ORCID iD [aut]
Maintainer: Mohammed Saqr <saqr@saqr.me>
Repository: CRAN
Date/Publication: 2026-11-17 17:40:15 UTC

bibnets: Importing, Constructing, and Exporting Bibliometric Networks

Description

bibnets builds bibliometric networks from the exports of scholarly databases. A bibliometric network links authors, documents, references, keywords, journals, institutions or countries through the records they share: co-authorship links authors who write together, co-citation links references cited together (Small, 1973), and bibliographic coupling links documents that cite the same work (Kessler, 1963). These networks show how a research field is organized: its collaborating groups, its intellectual base and its topics. The weight of a link can be normalized for how active each entity is (normalize()), and authorship credit can be counted in full, fractionally or by author position (the counting argument of the builders). Networks can be built for time windows (temporal_network()), reduced to their backbone with the disparity filter (backbone(); Serrano et al., 2009), and traced over time with a historiograph of the most locally cited documents (historiograph(); Garfield, 2004).

Records are read with read_biblio() from Scopus, Web of Science, OpenAlex, BibTeX, RIS, Lens.org, Dimensions and Crossref exports, or taken from any data frame with its own column names and separators. The builders (author_network(), document_network(), reference_network(), keyword_network(), source_network(), institution_network(), country_network() and the generic conetwork()) return an edge list with from, to, weight and count columns, which to_igraph(), to_tbl_graph(), to_cograph(), to_gephi(), to_graphml() and to_matrix() export.

Author(s)

Maintainer: Mohammed Saqr saqr@saqr.me (ORCID) [copyright holder]

Authors:

References

Garfield, E. (2004). Historiographic mapping of knowledge domains literature. Journal of Information Science, 30(2), 119–145. doi:10.1177/0165551504042802

Kessler, M. M. (1963). Bibliographic coupling between scientific papers. American Documentation, 14(1), 10–25. doi:10.1002/asi.5090140103

Serrano, M. A., Boguna, M., & Vespignani, A. (2009). Extracting the multiscale backbone of complex weighted networks. Proceedings of the National Academy of Sciences, 106(16), 6483–6488.

Small, H. (1973). Co-citation in the scientific literature: A new measure of the relationship between two documents. Journal of the American Society for Information Science, 24(4), 265–269.

See Also

Useful links:


Aggregate multi-valued fields by an entity

Description

aggregate_by_entity() groups documents by a single-valued or list-column entity (e.g., author, journal) and pools all values from another list-column (e.g., references, keywords) across documents belonging to that entity.

Usage

aggregate_by_entity(data, entity_field, value_field, min_freq = 1L)

Arguments

data

A data frame with id and the specified columns.

entity_field

Character. Name of the entity column. If it is a scalar column (e.g., "journal"), each document belongs to one entity. If it is a list-column (e.g., "authors"), each document may belong to multiple entities.

value_field

Character. Name of the list-column to aggregate (e.g., "references").

min_freq

Integer. Minimum number of papers per entity. Default 1.

Value

A data frame with columns id (entity name) and value_field (list-column of pooled values, with duplicates preserved).


Align columns before row-binding bibliographic files

Description

align_biblio_columns() gives every data frame in a list the same columns in the same order, so that they can be row-bound. A missing list-column is filled with empty character vectors and any other missing column with NA. It returns the list of aligned data frames.

Usage

align_biblio_columns(dfs)

Apply counting weights to a generic bipartite matrix

Description

apply_counting() weights a binary works x entities matrix by a position-independent counting method ("fractional", "paper" or "strength"; "full" leaves it unchanged). It is used for non-author fields (references, keywords, etc.). "fractional" and "paper" modify the bipartite matrix row weights; "strength" weights the columns by inverse document frequency and leaves the row normalization to multiply_bipartite(). For position-dependent counting use build_author_bipartite().

Usage

apply_counting(B, counting = "full", network_type = "symmetric")

Arguments

B

A sparse binary bipartite matrix (works x entities).

counting

Character. One of "full", "fractional", "paper", "strength".

network_type

Character. "symmetric" or "coupling".

Value

A weighted sparse matrix.


Build an author network

Description

author_network() builds a network between authors using one of four relationship types: co-authorship ("collaboration"), bibliographic coupling ("coupling"), author co-citation ("co_citation") or profile similarity ("equivalence"). Edges are weighted by any of 13 counting methods, including 9 position-dependent methods that respect author byline order, such as harmonic counting (Hagen, 2008); full and fractional counting are described by Perianes-Rodriguez et al. (2016).

Usage

author_network(
  data,
  type = "collaboration",
  counting = "full",
  similarity = "none",
  threshold = 0,
  min_occur = 1L,
  position_weights = c(1, 0.8, 0.6, 0.4),
  first_last_weight = 2,
  attention = NULL,
  top_n = NULL,
  self_loops = FALSE,
  deduplicate = TRUE,
  format = "edgelist",
  authors = "authors",
  sep = ";",
  references_sep = ";",
  strip_quotes = TRUE,
  id = NULL
)

Arguments

data

A data frame with one row per work and an author column (list-column or delimited string, byline order preserved). An id column is optional (see id). type = "coupling" also needs a references column; type = "co_citation" needs a cited_first_authors list-column.

type

Character. Relationship type:

"collaboration"

Co-authorship: authors linked when they co-author a publication.

"coupling"

Bibliographic coupling aggregated at author level: authors linked when they cite the same references.

"co_citation"

Author co-citation: authors linked when they are cited together by the same paper. Requires a cited_first_authors list-column.

"equivalence"

Profile similarity: cosine similarity of the authors' paper-incidence vectors. counting and similarity are ignored (always cosine).

counting

Character. Counting method. Position-independent methods ("full", "fractional", "paper", "strength") work for all types. Position-dependent methods ("harmonic", "arithmetic", "geometric", "adaptive_geometric", "golden", "first", "last", "first_last", "position_weighted") apply to type = "collaboration"; for the other types they fall back to "full".

similarity

Character. Similarity measure: "none", "association", "cosine", "jaccard", "inclusion", "equivalence".

threshold

Numeric. Minimum edge weight; edges with weight < threshold are dropped. Default 0 (keep all).

min_occur

Integer. Minimum number of papers for an author to be included. Default 1. Not applied with a position-dependent counting method or with attention.

position_weights

Numeric vector. Custom weights for counting = "position_weighted". Default c(1, 0.8, 0.6, 0.4).

first_last_weight

Numeric. Multiplier for counting = "first_last". Default 2.

attention

Character or NULL. Attention-based weighting independent of type and counting. One of "proximity" (center authors weighted most), "lead" (first author dominates, quadratic drop), "last" (last author dominates, quadratic rise), "circular" (first and last both prominent). The weights of one paper sum to 1 and an edge receives the product of its two endpoints' weights. When attention is set, type and counting are ignored. Default NULL (disabled).

top_n

Integer or NULL. Keep only the top_n most frequent nodes (largest diagonal of the projected matrix, i.e. the number of papers under full counting) and return the edges among them. Default NULL (all nodes).

self_loops

Logical. If TRUE, include self-loops (an entity linked to itself). Default FALSE. Only takes effect with similarity = "none"; every similarity measure zeroes the diagonal.

deduplicate

Logical. If TRUE (default), each ⁠(paper, entity)⁠ pair is counted at most once – duplicate entries in the source data (e.g., the same author listed twice on a paper) are treated as one occurrence. Set to FALSE to count every raw occurrence.

format

Character. Output format:

"edgelist"

Default. A bibnets_network data frame with columns from, to, weight, count.

"gephi"

Gephi-ready data frame: Source, Target, Weight, Count, Type.

"igraph"

An igraph graph object (requires igraph).

"cograph"

A cograph_network object (requires cograph).

"matrix"

A sparse adjacency matrix.

authors

Character. Name of the column containing authors. Default "authors". Use this to point at any column of a custom data set, e.g. authors = "Author Names".

sep

Character. Separator used to split the entity column (the one named by the column argument, e.g. authors) when it is a plain character column rather than a list-column, e.g. sep = "," or sep = " and ". Default ";". Ignored for list-columns. In coupling networks the references column is split with references_sep instead.

references_sep

Character. Separator for the references column in type = "coupling". Default ";" (reference strings usually contain internal commas, so this is kept independent of sep). Set it when your references are delimited differently.

strip_quotes

Logical. If TRUE (default), surrounding quote characters are removed from each entity, so a quoted CSV value such as "Alice" or ⁠""Alice""⁠ is treated as Alice. Set FALSE to keep quotes as part of the label.

id

Optional. Name of the column to use as the work identifier (the matrix-row dimension). If NULL (default), an existing id column is used when present, otherwise row numbers are used.

Details

The authors and the works form a two-mode matrix that is projected onto the authors; similarity normalizes the projected counts, threshold, min_occur and top_n prune the result, and attention replaces the counting method with an attention weighting of the byline. It returns a bibnets_network edge list by default, or the network in another format. For networks of other entities use keyword_network(), reference_network(), document_network(), source_network(), country_network(), institution_network() or, for any column, conetwork().

Value

Depends on format. The default "edgelist" returns a bibnets_network: a data frame with one row per undirected edge and columns from, to (character), weight (numeric) and count (integer raw co-occurrence), sorted by decreasing weight, with attributes network_type, counting and similarity. "gephi" returns a plain data frame with columns Source, Target, Weight, Count, Type; "igraph" an igraph graph; "cograph" a cograph_network; "matrix" a symmetric sparse dgCMatrix.

References

Perianes-Rodriguez, A., Waltman, L., & van Eck, N. J. (2016). Constructing bibliometric networks: A comparison between full and fractional counting. Journal of Informetrics, 10(4), 1178–1195. doi:10.1016/j.joi.2016.10.006

Hagen, N. T. (2008). Harmonic allocation of authorship credit: Source-level correction of bibliometric bias assures accurate publication and citation analysis. PLoS ONE, 3(12), e4021. doi:10.1371/journal.pone.0004021

Examples

data(biblio_data)
author_network(biblio_data, "collaboration")
author_network(biblio_data, "collaboration", counting = "harmonic")
author_network(biblio_data, "collaboration", counting = "geometric",
               similarity = "association")

# Custom CSV: any column name, any separator
d <- data.frame(id = 1:3,
                Researchers = c("Smith J, Doe A", "Smith J, Lee K",
                                "Doe A, Lee K"))
author_network(d, authors = "Researchers", sep = ",")

Compute positional author weights for a single paper

Description

author_weights() computes the weight of each byline position on a paper with n authors under a positional counting method, such as harmonic counting, where the author in position i receives 1/i, rescaled. All methods normalize weights to sum to 1 per paper. Position-independent methods (fractional, paper, strength) are handled by apply_counting() instead.

Usage

author_weights(
  n,
  counting = "fractional",
  position_weights = c(1, 0.8, 0.6, 0.4),
  first_last_weight = 2
)

Arguments

n

Integer. Number of authors.

counting

Character. Counting method.

position_weights

Numeric vector. Custom weights for counting = "position_weighted". Default c(1, 0.8, 0.6, 0.4).

first_last_weight

Numeric. Multiplier for first/last authors when counting = "first_last". Default 2.

Value

Numeric vector of length n, summing to 1.


Extract network backbone using the disparity filter

Description

backbone() extracts the backbone of a weighted edge list with the disparity filter (Serrano et al., 2009). For each edge, it computes an alpha (p-value) from both endpoints and keeps the edge if it is statistically significant from at least one endpoint.

Usage

backbone(edges, alpha = 0.05)

Arguments

edges

A data frame with at least columns from, to, and weight. Must be an undirected edge list (each pair appears once).

alpha

Numeric. Significance threshold in (0, 1). Default 0.05.

Details

Under the null model, the total strength s_i of node i is distributed uniformly across its k_i edges; the probability that a single edge weight is as large as w_{ij} is then

\alpha_{ij} = \left(1 - \frac{w_{ij}}{s_i}\right)^{k_i - 1}

An edge is retained if \min(\alpha_{ij}, \alpha_{ji}) < \alpha. Nodes with only one edge always have \alpha = 0 and are always kept. It returns the retained edges with their alpha. To prune by a fixed weight cut-off or a per-node edge count instead, use prune(); to keep the edges among the most connected nodes, use filter_top().

Value

The input edge data frame (same class and columns) restricted to the retained edges, with an added numeric alpha column (the smaller of the two endpoint alphas), one row per retained edge, sorted by decreasing weight.

References

Serrano, M. A., Boguna, M., & Vespignani, A. (2009). Extracting the multiscale backbone of complex weighted networks. Proceedings of the National Academy of Sciences, 106(16), 6483–6488. doi:10.1073/pnas.0808904106

Examples

edges <- data.frame(
  from   = c("A", "A", "A", "B", "C"),
  to     = c("B", "C", "D", "C", "D"),
  weight = c(10,   1,   1,   8,   1)
)
backbone(edges, alpha = 0.05)

Example bibliometric dataset

Description

biblio_data is a small synthetic dataset of 10 scholarly papers with overlapping authors, references, and keywords, used in the examples of the network construction functions.

Usage

biblio_data

Format

A data frame with 10 rows and 9 columns:

id

Unique document identifier (W1–W10).

title

Document title.

year

Publication year (2018–2022).

journal

Source journal (Scientometrics, Journal of Informetrics, JASIST, Quantitative Science Studies).

doi

DOI string.

cited_by_count

Times cited.

authors

List-column of author name strings (6 unique authors).

references

List-column of cited reference IDs (13 unique values): external references R1–R10 (R8 unused) and the in-corpus document IDs W1, W2, W3 and W5, which give the direct-citation, local-citation and historiograph examples something to find. Each paper cites exactly 4 references.

keywords

List-column of keyword strings (23 unique keywords). Each paper has 3 keywords.

Examples

data(biblio_data)
reference_network(biblio_data)
document_network(biblio_data, "coupling")
author_network(biblio_data, "collaboration")

Build a weighted bipartite matrix using positional counting

Description

build_author_bipartite() builds the works x authors two-mode matrix for position-dependent counting methods. It replaces the binary bipartite matrix entries with positional weights derived from author order (see author_weights()); authors with weight zero on a paper are dropped.

Usage

build_author_bipartite(
  data,
  field = "authors",
  counting = "full",
  position_weights = c(1, 0.8, 0.6, 0.4),
  first_last_weight = 2,
  deduplicate = TRUE,
  sep = ";",
  strip_quotes = TRUE
)

Arguments

data

A data frame with id and an ordered entity column (list-column or delimited string).

field

Character. Name of the entity column. Default "authors".

counting

Character. Counting method.

position_weights

Numeric vector for counting = "position_weighted".

first_last_weight

Numeric for counting = "first_last".

deduplicate

Logical. Keep only the first position of an entity repeated within one paper.

sep

Character. Separator for a plain character column.

strip_quotes

Logical. Strip surrounding quotes from each entity.

Value

A sparse weighted bipartite matrix (works x authors).


Build a bipartite incidence matrix from bibliometric data

Description

build_bipartite() builds a sparse works x entities two-mode matrix from a data frame with a list-column. This is the core engine behind all network construction functions: each network is a projection of this matrix (see multiply_bipartite()).

Usage

build_bipartite(
  data,
  field,
  min_freq = 1L,
  deduplicate = TRUE,
  sep = ";",
  strip_quotes = TRUE
)

Arguments

data

A data frame with at least columns id and the field specified.

field

Character. Name of the list-column containing entities (e.g., "authors", "references", "keywords").

min_freq

Integer. Minimum number of occurrences for an entity to be included. Default 1 (no filtering).

sep

Character. Separator used to split field when it is a plain character column. Default ";".

strip_quotes

Logical. Strip surrounding quote characters from entities. Default TRUE.

Details

It returns a dgCMatrix with one row per work and one column per unique entity. When the data are already in long form, use build_bipartite_long().

Value

A sparse dgCMatrix with rows = works (named by id) and columns = unique entities.


Build bipartite matrix from a long-format edge table

Description

build_bipartite_long() builds a sparse two-mode matrix from data that is already in long form (e.g., a two-column data frame of document-reference pairs). It is the long-form alternative to build_bipartite(), which takes a list-column.

Usage

build_bipartite_long(edges, min_freq = 1L)

Arguments

edges

A data frame with columns source (work id) and target (entity id).

min_freq

Integer. Minimum entity frequency. Default 1.

Value

A sparse dgCMatrix.


Build a network where entities share values from another field

Description

build_by_network() builds the network behind conetwork(by = ...): two entities of field are linked when they share values of the by field across documents. It pools each entity's by values, builds an entities x values two-mode matrix and projects it onto the entities, returning an edge data frame with columns from, to, weight and count.

Usage

build_by_network(
  data,
  field,
  by,
  counting,
  similarity,
  threshold,
  min_occur,
  top_n = NULL,
  self_loops = FALSE,
  deduplicate = TRUE,
  strip_quotes = TRUE
)

Build time window definitions

Description

build_windows() computes the time windows used by temporal_network() for the fixed, sliding or cumulative strategy. It returns a data frame with one row per window and columns start, end and label ("start-end").

Usage

build_windows(min_time, max_time, window, step, strategy)

Build a co-occurrence network from any field

Description

conetwork() builds a network between the values of any column. With one field, entities are linked when they co-occur in the same document. With by, entities are linked when they share values of the by field across documents; for example, journals linked by shared references form a journal coupling network.

Usage

conetwork(
  data,
  field,
  by = NULL,
  sep = ";",
  counting = "full",
  similarity = "none",
  threshold = 0,
  min_occur = 1L,
  top_n = NULL,
  self_loops = FALSE,
  deduplicate = TRUE,
  format = "edgelist",
  strip_quotes = TRUE,
  id = NULL
)

Arguments

data

A data frame with one row per work and the specified field(s). An id column is optional (see id).

field

Character. The entity field; its values become the nodes.

by

Character or NULL. What links the nodes. If NULL (default), entities are linked by co-occurring in the same document. If specified, entities are linked when they share values from the by field.

sep

Character or NULL. Delimiter for splitting character columns (applied to both field and by). Default ";". List-columns are never split. NULL keeps each character value as a single entity.

counting

Character. Counting method: "full" (default), "fractional", "paper" or "strength".

similarity

Character. Normalization method. Default "none".

threshold

Numeric. Minimum edge weight; edges with weight < threshold are dropped. Default 0 (keep all).

min_occur

Integer. Minimum entity frequency. Default 1.

top_n

Integer or NULL. Keep only the top_n most frequent nodes and return the edges among them. Default NULL (all nodes).

self_loops

Logical. If TRUE, include self-loops (an entity linked to itself). Default FALSE. Only takes effect with similarity = "none"; every similarity measure zeroes the diagonal.

deduplicate

Logical. If TRUE (default), each ⁠(paper, entity)⁠ pair is counted at most once – duplicate entries in the source data (e.g., the same author listed twice on a paper) are treated as one occurrence. Set to FALSE to count every raw occurrence.

format

Character. Output format:

"edgelist"

Default. A bibnets_network data frame with columns from, to, weight, count.

"gephi"

Gephi-ready data frame: Source, Target, Weight, Count, Type.

"igraph"

An igraph graph object (requires igraph).

"cograph"

A cograph_network object (requires cograph).

"matrix"

A sparse adjacency matrix.

strip_quotes

Logical. If TRUE (default), surrounding quote characters are removed from each entity, so a quoted CSV value such as "Alice" or ⁠""Alice""⁠ is treated as Alice. Set FALSE to keep quotes as part of the label.

id

Optional. Name of the column to use as the work identifier (the matrix-row dimension). If NULL (default), an existing id column is used when present, otherwise row numbers are used.

Details

Fields can be list-columns (already split) or character columns with delimiters (auto-split via sep). Edges are weighted by one of four position-independent counting methods and optionally normalized with similarity. It returns a bibnets_network edge list by default. The dedicated builders, such as author_network() (which adds position-dependent counting) and keyword_network(), cover the standard bibliometric networks.

Value

Depends on format. The default "edgelist" returns a bibnets_network data frame with one row per undirected edge, columns from, to, weight and count, sorted by decreasing weight, and attributes network_type, counting and similarity. See author_network() for the other formats.

Examples

data(biblio_data)

# Co-occurrence: keywords appearing in the same document
conetwork(biblio_data, "keywords")

# Authors linked by shared keywords
conetwork(biblio_data, "authors", by = "keywords")

# Keywords linked by shared authors
conetwork(biblio_data, "keywords", by = "authors")

# Journals linked by shared references (= journal coupling)
conetwork(biblio_data, "journal", by = "references", similarity = "cosine")

# Auto-splits semicolon-delimited string columns
d <- data.frame(id = 1:3, tags = c("ml; dl; nlp", "ml; cv", "dl; cv"))
conetwork(d, "tags")

Build a country network

Description

country_network() builds a network between countries based on collaboration or coupling. In a collaboration network two countries are linked when they appear on the same paper; in a coupling network they are linked when their papers cite the same references; the equivalence type uses the cosine similarity of the countries' paper-incidence vectors.

Usage

country_network(
  data,
  type = "collaboration",
  counting = "full",
  similarity = "none",
  threshold = 0,
  min_occur = 1L,
  attention = NULL,
  top_n = NULL,
  self_loops = FALSE,
  deduplicate = TRUE,
  format = "edgelist",
  countries = "countries",
  sep = ";",
  references_sep = ";",
  strip_quotes = TRUE,
  id = NULL
)

Arguments

data

A data frame with one row per work and a country column (list-column or delimited string). An id column is optional (see id). For coupling, also needs references.

type

Character. "collaboration" (default), "coupling", or "equivalence" (cosine similarity of paper-incidence vectors; counting and similarity are ignored). Ignored when attention is set.

counting

Character. Counting method: "full" (default), "fractional", "paper" or "strength". Ignored when attention is set.

similarity

Character. Similarity measure. Default "none".

threshold

Numeric. Minimum edge weight; edges with weight < threshold are dropped. Default 0 (keep all).

min_occur

Integer. Minimum papers per country. Default 1.

attention

Character or NULL. Attention-based weighting independent of type and counting. One of "proximity" (center authors weighted most), "lead" (first author dominates, quadratic drop), "last" (last author dominates, quadratic rise), "circular" (first and last both prominent). The weights of one paper sum to 1 and an edge receives the product of its two endpoints' weights. When attention is set, type and counting are ignored. Default NULL (disabled).

top_n

Integer or NULL. Keep only the top_n most frequent nodes and return the edges among them. Default NULL (all nodes).

self_loops

Logical. If TRUE, include self-loops (an entity linked to itself). Default FALSE. Only takes effect with similarity = "none"; every similarity measure zeroes the diagonal.

deduplicate

Logical. If TRUE (default), each ⁠(paper, entity)⁠ pair is counted at most once – duplicate entries in the source data (e.g., the same author listed twice on a paper) are treated as one occurrence. Set to FALSE to count every raw occurrence.

format

Character. Output format:

"edgelist"

Default. A bibnets_network data frame with columns from, to, weight, count.

"gephi"

Gephi-ready data frame: Source, Target, Weight, Count, Type.

"igraph"

An igraph graph object (requires igraph).

"cograph"

A cograph_network object (requires cograph).

"matrix"

A sparse adjacency matrix.

countries

Character. Name of the column containing countries. Default "countries".

sep

Character. Separator used to split the entity column (the one named by the column argument, e.g. authors) when it is a plain character column rather than a list-column, e.g. sep = "," or sep = " and ". Default ";". Ignored for list-columns. In coupling networks the references column is split with references_sep instead.

references_sep

Character. Separator for the references column in type = "coupling". Default ";".

strip_quotes

Logical. If TRUE (default), surrounding quote characters are removed from each entity.

id

Optional. Name of the column to use as the work identifier (the matrix-row dimension). If NULL (default), an existing id column is used when present, otherwise row numbers are used.

Details

counting and similarity weight the edges, threshold, min_occur and top_n prune them, and attention replaces the type and counting method with an attention weighting of the country order. It returns a bibnets_network edge list by default. For institutions see institution_network(); for authors see author_network().

Value

Depends on format. The default "edgelist" returns a bibnets_network data frame with one row per undirected edge, columns from, to, weight and count, sorted by decreasing weight, and attributes network_type, counting and similarity. See author_network() for the other formats.

Examples

data(learning_analytics)
country_network(learning_analytics, "collaboration")

Detect bibliometric file format

Description

detect_format() detects the format of a bibliometric export from its first non-empty lines: BibTeX (@), RIS (⁠TY -⁠), Web of Science plaintext (FN or PT), or, from the CSV header, Scopus, Dimensions (whose header follows an ⁠About the data⁠ line), Lens.org or the flat OpenAlex CSV.

Usage

detect_format(file)

Arguments

file

Path to file.

Value

Character: format name or "unknown".


Build a document network

Description

document_network() builds a network between documents (papers) in the dataset. By default two documents are linked by bibliographic coupling, when they share cited references (Kessler, 1963); the other types are direct citation, co-citation of the cited items (Small, 1973) and the cosine similarity of the documents' reference vectors.

Usage

document_network(
  data,
  type = "coupling",
  counting = "full",
  similarity = "none",
  threshold = 0,
  min_occur = 1L,
  top_n = NULL,
  self_loops = FALSE,
  deduplicate = TRUE,
  format = "edgelist",
  references = "references",
  sep = ";",
  strip_quotes = TRUE,
  id = NULL
)

Arguments

data

A data frame with one row per work and a references column (list-column or delimited string). An id column is optional (see id); direct citation needs the references to use the same identifiers.

type

Character. Relationship type:

"coupling"

Bibliographic coupling: documents linked when they share cited references.

"citation"

Direct citation: directed edges from citing to cited documents (internal citations only). counting, similarity, threshold and min_occur are not applied; top_n keeps the documents with the most citation edges.

"co_citation"

Co-citation of the cited items: the nodes are the values of the references column (as in reference_network()), linked when the same document cites both. They are documents of the dataset only when the references are document identifiers.

"equivalence"

Cosine similarity of the documents' reference vectors; counting and similarity are ignored.

counting

Character. Counting method: "full" (default), "fractional", "paper" or "strength". Position-dependent methods are not applicable to document networks.

similarity

Character. Similarity measure. Default "none".

threshold

Numeric. Minimum edge weight; edges with weight < threshold are dropped. Default 0 (keep all).

min_occur

Integer. Minimum reference frequency. Default 1.

top_n

Integer or NULL. Keep only the top_n most frequent nodes and return the edges among them. Default NULL (all nodes).

self_loops

Logical. If TRUE, include self-loops (an entity linked to itself). Default FALSE. Only takes effect with similarity = "none"; every similarity measure zeroes the diagonal.

deduplicate

Logical. If TRUE (default), each ⁠(paper, entity)⁠ pair is counted at most once – duplicate entries in the source data (e.g., the same author listed twice on a paper) are treated as one occurrence. Set to FALSE to count every raw occurrence.

format

Character. Output format:

"edgelist"

Default. A bibnets_network data frame with columns from, to, weight, count.

"gephi"

Gephi-ready data frame: Source, Target, Weight, Count, Type.

"igraph"

An igraph graph object (requires igraph).

"cograph"

A cograph_network object (requires cograph).

"matrix"

A sparse adjacency matrix.

references

Character. Name of the column containing cited references. Default "references".

sep

Character. Separator used to split the references column when it is a plain character column. Default ";". Ignored for list-columns.

strip_quotes

Logical. If TRUE (default), surrounding quote characters are removed from each reference.

id

Optional. Name of the column to use as the work identifier (the matrix-row dimension). If NULL (default), an existing id column is used when present, otherwise row numbers are used.

Details

The documents and their references form a two-mode matrix, projected onto the documents for coupling and onto the cited items for co-citation; counting and similarity weight the edges and threshold, min_occur and top_n prune them. It returns a bibnets_network edge list by default, directed for type = "citation". For a co-citation network of the references themselves see reference_network(); for local citation counts and a chronological citation network see local_citations() and historiograph().

Value

Depends on format. The default "edgelist" returns a bibnets_network data frame with one row per edge, columns from, to, weight and count, and attributes network_type, counting and similarity; see author_network() for the other formats. For type = "citation" the edges are directed (from = citing, to = cited) with weight and count both 1, in data order; the other types are undirected and sorted by decreasing weight.

References

Kessler, M. M. (1963). Bibliographic coupling between scientific papers. American Documentation, 14(1), 10–25. doi:10.1002/asi.5090140103

Small, H. (1973). Co-citation in the scientific literature: A new measure of the relationship between two documents. Journal of the American Society for Information Science, 24(4), 265–269. doi:10.1002/asi.4630240406

Examples

data(biblio_data)
document_network(biblio_data, "coupling")
document_network(biblio_data, "coupling", counting = "strength")

Convert edge list to a square sparse matrix

Description

edgelist_to_mat() converts an edge list to a square sparse matrix of edge weights, one row and column per node. With symmetric = TRUE each edge is entered in both directions. It is the inverse of mat_to_edgelist() and the engine behind to_matrix().

Usage

edgelist_to_mat(edges, nodes = NULL, symmetric = TRUE)

Arguments

edges

A data frame with columns from, to, weight.

nodes

Optional character vector of node names. If NULL, derived from the edge list.

symmetric

Logical. If TRUE (default), the matrix is made symmetric.

Value

A sparse dgCMatrix.


Ensure a column is a list-column, splitting if needed

Description

ensure_list_column() turns a column into a list-column. A character column is split on sep with split_field() (with a warning from warn_if_sep_mismatch() when the separator looks wrong); with sep = NULL each value becomes a single entity. A list-column is kept as it is. It returns data with the column replaced.

Usage

ensure_list_column(data, field, sep = ";", strip_quotes = TRUE)

Arguments

strip_quotes

Logical. If TRUE (default), surrounding quote characters and whitespace are removed from every entity (e.g. a quoted CSV value "Alice" becomes Alice). See strip_surrounding_quotes().


Filter edges to top-n nodes

Description

filter_top() keeps only the edges between the n most frequent nodes. Node frequency is determined by how many edges each node participates in. It returns the edges whose two endpoints are both among the top nodes. To prune by edge weight or keep each node's strongest edges, use prune(); for a statistical backbone, use backbone().

Usage

filter_top(edges, n)

Arguments

edges

A data frame with at least from, to, weight columns.

n

Integer. Number of top nodes to keep (ties in edge count are broken by the order of table(), i.e. alphabetically).

Value

The edge data frame restricted to edges whose two endpoints are both among the top n nodes, with the same class and columns as the input, sorted by decreasing weight.

Examples

data(biblio_data)
edges <- author_network(biblio_data, "collaboration")

# Keep only edges among the top 3 most connected authors
filter_top(edges, 3)

Build a historiograph (chronological citation network)

Description

historiograph() builds a Garfield-style historiograph (Garfield, 2004): the n most locally cited documents and the within-corpus citations they receive, each edge carrying the publication years of both ends so the network can be laid out chronologically. The citing document of an edge may be any document in the data, not only one of the n selected.

Usage

historiograph(
  data,
  n = 30,
  min_lcs = 1,
  references = "references",
  sep = ";",
  strip_quotes = TRUE,
  id = NULL
)

Arguments

data

A data frame with one row per work, a references column (list-column or delimited string) whose values use the same identifiers as the works, and year. An id column is optional (see id). Optionally title, journal, doi, cited_by_count.

n

Integer. Number of top locally cited documents to include. Default 30.

min_lcs

Integer. Minimum local citation score for inclusion. Default 1.

references

Character. Name of the column containing cited references. Default "references".

sep

Character. Separator used to split the references column when it is a plain character column. Default ";".

strip_quotes

Logical. If TRUE (default), surrounding quote characters are removed from each reference.

id

Optional. Name of the column to use as the work identifier. If NULL (default), an existing id column is used when present, otherwise row numbers are used.

Details

The documents are ranked by local_citations(); n and min_lcs set how many are kept. It returns a list with a nodes and an edges data frame.

Value

A list of two data frames:

nodes

One row per included document (at most n, each with lcs >= min_lcs), with the local_citations() columns (id, lcs, gcs when available, year, and title, journal, doi when present), sorted by decreasing lcs.

edges

One row per distinct directed citation that points at an included document, with from (citing; any document in the data), to (cited), year_from and year_to (integer), sorted by year_from then year_to.

Both are empty (zero rows) when no document reaches min_lcs.

References

Garfield, E. (2004). Historiographic mapping of knowledge domains literature. Journal of Information Science, 30(2), 119–145. doi:10.1177/0165551504042802

Examples

data(biblio_data)
historiograph(biblio_data, n = 5)

Build an institution network

Description

institution_network() builds a network between institutions (affiliations). In a collaboration network two institutions are linked when they appear on the same paper; in a coupling network they are linked when their papers cite the same references; the equivalence type uses the cosine similarity of the institutions' paper-incidence vectors.

Usage

institution_network(
  data,
  type = "collaboration",
  counting = "full",
  similarity = "none",
  threshold = 0,
  min_occur = 1L,
  attention = NULL,
  top_n = NULL,
  self_loops = FALSE,
  deduplicate = TRUE,
  format = "edgelist",
  affiliations = "affiliations",
  sep = ";",
  references_sep = ";",
  strip_quotes = TRUE,
  id = NULL
)

Arguments

data

A data frame with one row per work and an affiliation column (list-column or delimited string). An id column is optional (see id). For coupling, also needs references.

type

Character. "collaboration" (default), "coupling", or "equivalence" (cosine similarity of paper-incidence vectors; counting and similarity are ignored). Ignored when attention is set.

counting

Character. Counting method: "full" (default), "fractional", "paper" or "strength". Ignored when attention is set.

similarity

Character. Similarity measure. Default "none".

threshold

Numeric. Minimum edge weight; edges with weight < threshold are dropped. Default 0 (keep all).

min_occur

Integer. Minimum papers per institution. Default 1.

attention

Character or NULL. Attention-based weighting independent of type and counting. One of "proximity" (center authors weighted most), "lead" (first author dominates, quadratic drop), "last" (last author dominates, quadratic rise), "circular" (first and last both prominent). The weights of one paper sum to 1 and an edge receives the product of its two endpoints' weights. When attention is set, type and counting are ignored. Default NULL (disabled).

top_n

Integer or NULL. Keep only the top_n most frequent nodes and return the edges among them. Default NULL (all nodes).

self_loops

Logical. If TRUE, include self-loops (an entity linked to itself). Default FALSE. Only takes effect with similarity = "none"; every similarity measure zeroes the diagonal.

deduplicate

Logical. If TRUE (default), each ⁠(paper, entity)⁠ pair is counted at most once – duplicate entries in the source data (e.g., the same author listed twice on a paper) are treated as one occurrence. Set to FALSE to count every raw occurrence.

format

Character. Output format:

"edgelist"

Default. A bibnets_network data frame with columns from, to, weight, count.

"gephi"

Gephi-ready data frame: Source, Target, Weight, Count, Type.

"igraph"

An igraph graph object (requires igraph).

"cograph"

A cograph_network object (requires cograph).

"matrix"

A sparse adjacency matrix.

affiliations

Character. Name of the column containing institutions. Default "affiliations".

sep

Character. Separator used to split the entity column (the one named by the column argument, e.g. authors) when it is a plain character column rather than a list-column, e.g. sep = "," or sep = " and ". Default ";". Ignored for list-columns. In coupling networks the references column is split with references_sep instead.

references_sep

Character. Separator for the references column in type = "coupling". Default ";".

strip_quotes

Logical. If TRUE (default), surrounding quote characters are removed from each entity.

id

Optional. Name of the column to use as the work identifier (the matrix-row dimension). If NULL (default), an existing id column is used when present, otherwise row numbers are used.

Details

counting and similarity weight the edges, threshold, min_occur and top_n prune them, and attention replaces the type and counting method with an attention weighting of the affiliation order. It returns a bibnets_network edge list by default. For countries see country_network(); for authors see author_network().

Value

Depends on format. The default "edgelist" returns a bibnets_network data frame with one row per undirected edge, columns from, to, weight and count, sorted by decreasing weight, and attributes network_type, counting and similarity. See author_network() for the other formats.

Examples

data(learning_analytics)
institution_network(learning_analytics, "collaboration")

Build a keyword co-occurrence network

Description

keyword_network() builds a keyword co-occurrence network, in which two keywords are linked when they appear together in the same document.

Usage

keyword_network(
  data,
  keywords = "keywords",
  counting = "full",
  similarity = "none",
  threshold = 0,
  min_occur = 1L,
  attention = NULL,
  top_n = NULL,
  self_loops = FALSE,
  deduplicate = TRUE,
  format = "edgelist",
  sep = ";",
  strip_quotes = TRUE,
  field = NULL,
  id = NULL
)

Arguments

data

A data frame with one row per work and a keyword column (list-column or delimited string). An id column is optional (see id).

keywords

Character. Name of the keyword column (list-column or delimited string). Default "keywords". Any column of a custom data set works, e.g. keywords = "Tags".

counting

Character. Counting method: "full" (default), "fractional", "paper" or "strength". Position-dependent methods are not available; use attention for order-based weights.

similarity

Character. Similarity measure. Default "none".

threshold

Numeric. Minimum edge weight; edges with weight < threshold are dropped. Default 0 (keep all).

min_occur

Integer. Minimum keyword frequency. Default 1.

attention

Character or NULL. Attention-based weighting independent of type and counting. One of "proximity" (center authors weighted most), "lead" (first author dominates, quadratic drop), "last" (last author dominates, quadratic rise), "circular" (first and last both prominent). The weights of one paper sum to 1 and an edge receives the product of its two endpoints' weights. When attention is set, type and counting are ignored. Default NULL (disabled).

top_n

Integer or NULL. Keep only the top_n most frequent nodes and return the edges among them. Default NULL (all nodes).

self_loops

Logical. If TRUE, include self-loops (an entity linked to itself). Default FALSE. Only takes effect with similarity = "none"; every similarity measure zeroes the diagonal.

deduplicate

Logical. If TRUE (default), each ⁠(paper, entity)⁠ pair is counted at most once – duplicate entries in the source data (e.g., the same author listed twice on a paper) are treated as one occurrence. Set to FALSE to count every raw occurrence.

format

Character. Output format:

"edgelist"

Default. A bibnets_network data frame with columns from, to, weight, count.

"gephi"

Gephi-ready data frame: Source, Target, Weight, Count, Type.

"igraph"

An igraph graph object (requires igraph).

"cograph"

A cograph_network object (requires cograph).

"matrix"

A sparse adjacency matrix.

sep

Character. Separator used to split the keyword column when it is a plain character column, e.g. sep = ",". Default ";". Ignored for list-columns.

strip_quotes

Logical. If TRUE (default), surrounding quote characters are removed from each keyword.

field

Deprecated. Use keywords instead.

id

Optional. Name of the column to use as the work identifier (the matrix-row dimension). If NULL (default), an existing id column is used when present, otherwise row numbers are used.

Details

The documents and their keywords form a two-mode matrix that is projected onto the keywords; counting and similarity weight the edges, threshold, min_occur and top_n prune them, and attention replaces the counting method with an attention weighting of the keyword order. It returns a bibnets_network edge list by default. To link keywords by another field (for example shared authors) use conetwork(data, "keywords", by = ...) (see conetwork()).

Value

Depends on format. The default "edgelist" returns a bibnets_network data frame with one row per undirected edge, columns from, to, weight and count, sorted by decreasing weight, and attributes network_type, counting and similarity. See author_network() for the other formats.

Examples

data(biblio_data)
keyword_network(biblio_data)
keyword_network(biblio_data, similarity = "association")

# Custom CSV: any column name, any separator
d <- data.frame(id = 1:3, Tags = c("ml, ai", "ml, nlp", "ai, nlp"))
keyword_network(d, keywords = "Tags", sep = ",")

Learning analytics dataset (OpenAlex)

Description

learning_analytics is a corpus of 1,508 gold open-access scholarly works on learning analytics, retrieved from OpenAlex (CC0 licence). All records have a verified title, publication year, and at least one author. Journal names are present for works published in a named source; preprints and book chapters may have NA in journal.

Usage

learning_analytics

Format

A data frame with 1,508 rows and 11 columns:

id

OpenAlex work ID (e.g. "W2769342982").

title

Work title.

year

Publication year (integer).

journal

Source name, or NA if not available.

doi

DOI string without the https://doi.org/ prefix, or NA.

cited_by_count

Number of citing works as recorded in OpenAlex.

type

Work type ("article", "review", "preprint", "book-chapter", etc.).

authors

List-column of author display names (pipe-split from the OpenAlex flat export; one name per authorship slot).

keywords

List-column with one element: the primary OpenAlex topic for the work (e.g. "Online Learning and Analytics").

affiliations

List-column of institution display names (one entry per authorship-institution pair).

countries

List-column of two-letter ISO country codes (one entry per authorship-institution pair).

Source

OpenAlex https://openalex.org, CC0 licence.

Examples

data(learning_analytics)
author_network(learning_analytics, "collaboration")
country_network(learning_analytics, "collaboration")

Compute local citation scores

Description

local_citations() computes the local citation score (LCS) of each document: how many times it is cited by other documents within the dataset. When the data carry cited_by_count, the global citation score (GCS) is reported beside it.

Usage

local_citations(
  data,
  references = "references",
  sep = ";",
  strip_quotes = TRUE,
  id = NULL
)

Arguments

data

A data frame with one row per work and a references column (list-column or delimited string) whose values use the same identifiers as the works. An id column is optional (see id). Optionally year, title, journal, doi, cited_by_count.

references

Character. Name of the column containing cited references. Default "references".

sep

Character. Separator used to split the references column when it is a plain character column. Default ";".

strip_quotes

Logical. If TRUE (default), surrounding quote characters are removed from each reference.

id

Optional. Name of the column to use as the work identifier. If NULL (default), an existing id column is used when present, otherwise row numbers are used.

Details

It returns one row per document, sorted by decreasing lcs. To lay the most locally cited documents out as a chronological citation network, use historiograph(); for the full citation network, use document_network(type = "citation") (see document_network()).

Value

A data frame with one row per document, sorted by decreasing lcs, with columns:

id

Document identifier (character).

lcs

Local Citation Score (integer): times cited by other documents in the dataset.

gcs

Global Citation Score (integer): cited_by_count; only when that column is present.

followed by year (integer), title, journal and doi when present in the input.

Examples

data(biblio_data)
local_citations(biblio_data)

Convert a sparse square matrix to a tidy edge list

Description

mat_to_edgelist() converts a square matrix to an edge list with columns from, to and weight. It extracts non-zero entries directly from the sparse representation, without a dense matrix allocation. For undirected networks, only the upper triangle is returned.

Usage

mat_to_edgelist(A, directed = FALSE)

Arguments

A

A square sparse or dense matrix.

directed

Logical. If FALSE (default), returns only upper-triangle entries. If TRUE, returns all non-zero off-diagonal entries.

Value

A data frame with columns from, to, weight, sorted by descending weight.


Construct a co-occurrence network via two-mode multiplication

Description

multiply_bipartite() projects a weighted works x entities matrix onto a one-mode co-occurrence network and returns its edges. With mode = "columns" it links the entities (columns) that occur in the same rows (crossprod(B), e.g. co-citation); with mode = "rows" it links the rows that share entities (tcrossprod(B), e.g. coupling).

Usage

multiply_bipartite(
  B,
  mode = "columns",
  similarity = "none",
  threshold = 0,
  top_n = NULL,
  self_loops = FALSE
)

Arguments

B

A sparse bipartite matrix (works x entities), already weighted by the counting method.

mode

Character. "columns" for column-mode co-occurrence (e.g., co-citation), "rows" for row-mode (e.g., coupling).

similarity

Character. Normalization method (see normalize()).

threshold

Numeric. Minimum edge weight to retain.

top_n

Integer or NULL. If specified, keep only the top n most frequent nodes and return all edges among them.

self_loops

Logical. Keep diagonal entries as self-loops. Only honoured with similarity = "none".

Details

It is the unified engine for all bibliometric networks. It operates entirely in sparse representation and never allocates a dense n x n matrix; top_n keeps the most frequent nodes, similarity normalizes the projection with normalize(), and threshold drops weak edges.

Value

A data frame with columns from, to, weight, count.


Normalize a co-occurrence matrix

Description

normalize() normalizes a square co-occurrence matrix by a similarity measure: association strength, cosine, Jaccard, inclusion or equivalence (van Eck & Waltman, 2009). The diagonal of the input matrix is used as the total occurrence count w_i of each item (a zero diagonal entry is treated as 1). Matrices with 500 or more rows are processed in sparse triplet form, so no dense outer product is allocated. Every network builder calls this through its similarity argument; call it directly to normalize a matrix you built yourself.

Usage

normalize(A, method = "none")

Arguments

A

A square symmetric matrix (dense or sparse) representing co-occurrence counts.

method

Character. Normalization method:

"none"

No normalization. Returns raw co-occurrence counts.

"association"

Association strength (probabilistic affinity index). s_{ij} = c_{ij} / (w_i \cdot w_j). Often recommended as the best normalization for co-occurrence data.

"cosine"

Salton's cosine. s_{ij} = c_{ij} / \sqrt{w_i \cdot w_j}.

"jaccard"

Jaccard index. s_{ij} = c_{ij} / (w_i + w_j - c_{ij}).

"inclusion"

Inclusion index (Simpson coefficient). s_{ij} = c_{ij} / \min(w_i, w_j).

"equivalence"

Equivalence index (Salton's cosine squared). s_{ij} = c_{ij}^2 / (w_i \cdot w_j).

Value

For method = "none", A unchanged. Otherwise a sparse Matrix of the same dimensions and dimnames holding s_{ij}, with a zero diagonal.

References

van Eck, N. J., & Waltman, L. (2009). How to normalize cooccurrence data? An analysis of some well-known similarity measures. Journal of the American Society for Information Science and Technology, 60(8), 1635–1651. doi:10.1002/asi.21075

Examples

# Create a small co-occurrence matrix
A <- matrix(c(10, 3, 1, 3, 8, 2, 1, 2, 5), nrow = 3,
            dimnames = list(c("a", "b", "c"), c("a", "b", "c")))
normalize(A, "association")
normalize(A, "cosine")
normalize(A, "jaccard")

Reorder and parse author names

Description

parse_names() converts author names to "First Last" order (or another format) and breaks each name into its components. The parser is aware of nobiliary particles (van, von, de, del, da, der, ...) and generational suffixes (Jr, Sr, II, III, IV), and is case-insensitive so it handles bibnets' uppercased entity labels.

Usage

parse_names(
  x,
  format = c("first_last", "last_initials", "last"),
  surname_first = c("auto", "yes", "no")
)

Arguments

x

Character vector of author names, one name per element. NA and empty strings are preserved.

format

Output style for personal names (group/corporate authors, NA, and empty strings are returned unchanged in every style). One of:

"first_last"

(default) "Saqr, Mohammed" -> "Mohammed Saqr".

"last_initials"

"Saqr, Mohammed" -> "Saqr M."; multiple given names become concatenated initials ("Garcia Marquez G.J."); any suffix is appended ("Smith J. Jr").

"last"

surname only, including any particle ("van der Berg", "de la Cruz").

surname_first

How to read comma-less strings (strings with a comma are always "Last, First"). One of:

"auto"

(default) surname-first when the trailing token looks like initials (an all-uppercase token of 1-3 letters), the Scopus / bibnets signature: "WANG Y" is read as surname WANG, given Y. Otherwise treated as "First Last". This is the "bibnets takes precedence" bias: native bibnets/Scopus labels parse correctly with no extra arguments, while ordinary mixed-case "First Last" input is never misread.

"yes"

force surname-first ("Wang Yong" -> surname Wang, given Yong).

"no"

force given-first ("First Last"); comma-less input is returned unchanged.

May also be given as the logical TRUE / FALSE. Inherently ambiguous input (e.g. uppercase "MOHAMMED LI") follows the auto bias toward the bibnets/Scopus convention; pass "no" to override.

Details

Three name conventions are recognised:

Comma-less strings that look like group or corporate authors (e.g. "WHO Collaborating Group") are detected and left untouched, as are NA and empty strings.

This is an optional, standalone utility. No reader or network builder in bibnets calls it; entity labels are matched verbatim unless you choose to apply this function yourself first.

Value

A character vector the same length as x, formatted per format. The parsed components are attached as the attribute "parts" (independent of format): a data frame with columns original, first, last, particle, suffix, and type (one of "person", "organization", "empty", "missing"). Casing of the input is preserved; periods are stripped from parsed initials.

Input shape

parse_names() takes a flat character vector (one name per element), not a data frame and not a list. bibnets readers store authors as a list-column (each element is a character vector, because a paper has a variable number of authors), so map the function over it rather than passing the column directly:

df$authors <- lapply(df$authors, parse_names, format = "last_initials")

For an ordinary flat character column (or the from / to columns of a bibnets_network), call it directly: parse_names(df$col).

Recommended workflow

Normalise names before building a network, on the reader's authors list-column. Node identity in bibnets is fixed when the bipartite matrix is built (labels are upper-cased and matched verbatim), so two spellings of one author ("Saqr, Mohammed" and "SAQR M") only merge into a single node if they are normalised before author_network() is called:

d <- read_biblio("scopus.csv")
d$authors <- lapply(d$authors, parse_names, format = "last_initials")
net <- author_network(d, type = "collaboration")

Applying to an existing edgelist

You can call parse_names() on the from / to (or source / target) columns of a built network, but it is a per-column, graph-blind relabelling: edges, pairing, weight and count are preserved, but

Prefer the pre-build workflow above.

Limitations

Comma-less names are inherently ambiguous; the auto heuristic is biased toward the bibnets/Scopus surname-first convention and may misread uppercase "GIVEN SURNAME" where the surname is 1-3 letters (e.g. "MOHAMMED LI"). Suffix-first garbage ("Jr., Sammy Davis") is not specially handled. Use surname_first to force interpretation when you know the source convention.

See Also

author_network() and read_biblio() for the upstream stage where normalisation is best applied.

Examples

parse_names(c("Saqr, Mohammed", "Lopez-Pernas, Sonsoles"))

# Alternative output styles
parse_names("Saqr, Mohammed", format = "last_initials")  # "Saqr M."
parse_names("Saqr, Mohammed", format = "last")            # "Saqr"
parse_names("van der Berg, Jan", format = "last_initials") # "van der Berg J."

# The parsed components travel in the "parts" attribute
str(parse_names("Saqr, M."))

# Particles and suffixes
parse_names(c("van der Berg, Jan", "Smith, John, Jr.", "de la Cruz, Ana"))

# Scopus / bibnets surname-first labels are detected automatically
parse_names(c("WANG Y", "AYALA-ROMERO JA", "VAN DER BERG J"))
parse_names("WANG Y", format = "last_initials")          # "WANG Y."

# Override the auto heuristic when you know the convention
parse_names("Wang Yong", surname_first = "yes")          # "Yong Wang"

# Group authors are detected and left unchanged
parse_names("WHO Collaborating Group")

# Recommended workflow: normalise the authors list-column, then build
papers <- data.frame(
  id = c("P1", "P2", "P3"),
  authors = I(list(
    c("Saqr, Mohammed", "Lopez, Ana"),
    c("SAQR M",         "Lopez, Ana"),
    c("Saqr, Mohammed", "Chen, Wei")
  ))
)
papers$authors <- lapply(papers$authors, parse_names,
                         format = "last_initials")
author_network(papers, type = "collaboration")

List the position-independent counting methods

Description

position_independent_counts() returns the names of the four position-independent counting methods: "full", "fractional", "paper" and "strength". Every network builder accepts these; the position-dependent methods apply only to co-authorship networks (see author_network()).

Usage

position_independent_counts()

Value

Character vector of method names.


Print a bibnets network edge list

Description

print() displays a bibnets_network edge list: a one-line header (network type, number of nodes and edges, counting method and, when used, the similarity measure) followed by the first n edges, so a printed edge list always states how it was built. For network-level statistics use summary.bibnets_network().

Usage

## S3 method for class 'bibnets_network'
print(x, n = 10L, ...)

Arguments

x

A bibnets_network data frame.

n

Integer. Number of rows to show. Default 10.

...

Ignored.

Value

x, unchanged and invisibly (a bibnets_network data frame with columns from, to, weight, count). Called for its printed output.

Examples

data(biblio_data)
edges <- author_network(biblio_data, "collaboration")
print(edges)

Prune a weighted edge list

Description

prune() reduces a weighted edge list by removing weak or excess edges. Supply exactly one of threshold (a global cut-off) or top_n (a local, per-node cut-off); supplying both or neither is an error.

Usage

prune(edges, threshold = NULL, top_n = NULL)

Arguments

edges

A data frame with at least columns from, to, and weight.

threshold

Numeric or NULL. Keep only edges with weight >= threshold. Default NULL.

top_n

Integer or NULL. For each node, keep only its top_n strongest edges. An edge is kept if it is in the top top_n for either endpoint (ties at the cut-off are kept). Default NULL.

Details

It returns the retained edges. To keep the edges among the most connected nodes, use filter_top(); for a statistical backbone, use backbone().

Value

The edge data frame restricted to the retained edges, with the same class and columns as the input, one row per edge, sorted by decreasing weight.

Examples

edges <- data.frame(
  from   = c("A","A","A","B","B","C"),
  to     = c("B","C","D","C","D","D"),
  weight = c(5,  1,  2,  4,  1,  3)
)

# Keep only edges with weight >= 3
prune(edges, threshold = 3)

# Keep the 2 strongest edges per node
prune(edges, top_n = 2)

Read bibliometric data

Description

read_biblio() reads bibliometric exports into a standardized data frame. It is the universal reader: it handles files, folders, format detection, and generic CSV input, and accepts a single file, multiple files, or a directory.

Usage

read_biblio(
  path,
  format = "auto",
  id = NULL,
  authors = NULL,
  keywords = NULL,
  references = NULL,
  countries = NULL,
  affiliations = NULL,
  journal = NULL,
  sep = ";",
  list_cols = NULL,
  ...,
  actors = NULL
)

Arguments

path

Character. Path to a file, a vector of file paths, or a directory containing export files.

format

Character. File format:

"auto"

Default. Auto-detect from file content.

"scopus"

Scopus CSV.

"wos"

Web of Science plaintext.

"wos_tab"

Web of Science tab-delimited.

"bibtex"

BibTeX .bib file.

"ris"

RIS file.

"dimensions"

Dimensions CSV.

"lens"

Lens.org CSV.

"openalex_csv"

Flat OpenAlex CSV export (pipe-delimited fields).

"generic"

Any CSV. Map its columns with id, authors, keywords, references, countries, affiliations, journal. Inferred automatically when any of those arguments is supplied, so format = "generic" is optional in that case.

id

Character. Column name for the document identifier. Only used when format = "generic". Default NULL: an existing id column is kept, otherwise row numbers are used.

authors, keywords, references, countries, affiliations

Character. For format = "generic", the name of the source column to map onto that standard field. Its cells are split on sep into a list-column. For example authors = "Author Names" reads the ⁠Author Names⁠ column into the standard authors list-column.

journal

Character. For format = "generic", the name of the source column to use as the (scalar) journal field. Not split.

sep

Character. Delimiter for splitting the mapped multi-valued columns. Default ";".

list_cols

Character vector. For format = "generic", additional columns to split into list-columns in place (keeping their original names), for fields without a dedicated argument above.

...

Additional arguments passed to the format-specific reader (for example encoding for read_scopus()). Not used by the generic reader.

actors

Deprecated. Use the entity arguments (authors, keywords, ...) or list_cols instead.

Details

With format = "auto" the format of each file is detected from its content and the matching reader is called (read_scopus(), read_wos(), read_bibtex(), read_ris(), read_dimensions(), read_lens() or read_openalex_csv()); naming source columns with authors, keywords and the other mapping arguments reads any CSV instead. It returns one row per record, with the files' rows bound together. Data already loaded in R from openalexR or rcrossref are converted with read_openalex() and read_crossref().

Value

A data frame with one row per record. The format-specific readers return the standard bibnets columns id, title, year, journal, doi, cited_by_count, abstract, type and the list-columns authors, references, keywords, followed by any source-specific extras. When several files are read, their columns are aligned (missing scalar columns filled with NA, missing list-columns with empty vectors), the rows are bound, and a message reports the number of files and rows. The generic reader keeps every source column and adds id plus the mapped standard fields.

Examples

# Auto-detect format from file content (here: a bundled OpenAlex CSV)
f <- system.file("extdata", "openalex_works.csv", package = "bibnets")
data <- read_biblio(f)
head(subset(data, select = c(id, title, year, journal)))

# Read multiple files at once; auto-detects each format
f_scopus <- system.file("extdata", "scopus_sample.csv", package = "bibnets")
f_wos    <- system.file("extdata", "wos_sample.txt",  package = "bibnets")
combined <- read_biblio(c(f_scopus, f_wos))
head(subset(combined, select = c(id, title, year, journal)))

# Read every supported export in a directory (here: the bundled extdata)
folder <- system.file("extdata", package = "bibnets")
all_data <- read_biblio(folder)
nrow(all_data)

# Custom CSV: map each source column onto a standard field by name.
# Naming columns implies format = "generic" (no need to pass it).
tmp <- tempfile(fileext = ".csv")
write.csv(data.frame(
  doc_id  = c("a", "b"),
  Authors = c("Smith J; Jones A", "Davis M"),
  Keywords = c("networks; bibliometrics", "analytics")
), tmp, row.names = FALSE)
generic <- read_biblio(tmp,
                       id = "doc_id",
                       authors = "Authors",
                       keywords = "Keywords",
                       sep = ";")
generic
unlink(tmp)

Read a BibTeX file

Description

read_bibtex() parses a .bib file into a standardized bibliometric data frame. Note: standard BibTeX does not contain cited references, so the references column will be empty unless the file includes a non-standard cited-references or note field with reference data. read_biblio() reads several files at once and detects the format.

Usage

read_bibtex(file, encoding = "UTF-8")

Arguments

file

Path to a .bib file.

encoding

Character. File encoding. Default "UTF-8".

Value

A data frame in the standard bibnets format: id, title, year, journal, doi, cited_by_count, abstract, type, plus list-columns authors, references (typically empty for BibTeX), and keywords.

Examples

# Write a minimal BibTeX entry to a temp file, then read it
bib <- '@article{smith2020,
  title  = {Bibliometric networks},
  author = {Smith, J. and Jones, K.},
  journal = {Test Journal},
  year   = {2020},
  doi    = {10.1000/test}
}'
f <- tempfile(fileext = ".bib")
writeLines(bib, f)
data <- read_bibtex(f)
subset(data, select = c(id, title, year, journal, doi, authors))
unlink(f)

Convert Crossref API data to bibnets format

Description

read_crossref() converts the output of rcrossref::cr_works() (the ⁠$data⁠ tibble/data frame) to the standardized bibnets format. For exported files rather than data in R, use read_biblio().

Usage

read_crossref(data)

Arguments

data

A data frame from cr_works(...)$data.

Value

A data frame in the standard bibnets format: id, title, year, journal, doi, cited_by_count, abstract, type, plus list-columns authors, references, and keywords.

Examples

# Construct a minimal data frame matching the structure of
# rcrossref::cr_works(...)$data. In practice, pass that data frame directly.
raw <- data.frame(
  doi = c("10.1/a", "10.2/b"),
  title = c("First paper", "Second paper"),
  issued = c("2022-01-01", "2021-06-15"),
  container.title = c("Journal A", "Journal B"),
  is.referenced.by.count = c("3", "9"),
  type = c("journal-article", "journal-article"),
  author = I(list(
    data.frame(given = c("Jane", "Anne"), family = c("Smith", "Jones")),
    data.frame(given = "Mark", family = "Davis")
  ))
)
data <- read_crossref(raw)
subset(data, select = c(id, title, year, journal, authors))

Read Dimensions CSV export

Description

read_dimensions() parses a CSV file exported from Dimensions into a standardized bibliometric data frame. read_biblio() reads several files at once and detects the format.

Usage

read_dimensions(file, encoding = "UTF-8")

Arguments

file

Path to a Dimensions CSV export file.

encoding

Character. File encoding. Default "UTF-8".

Value

A data frame in the standard bibnets format: id, title, year, journal, doi, cited_by_count, abstract, type, plus list-columns authors, references, and keywords. Dimensions-specific extras: affiliations (list-column), countries (list-column).

Examples

f <- system.file("extdata", "dimensions_sample.csv", package = "bibnets")
data <- read_dimensions(f)
subset(data, select = c(id, title, year, journal, authors))

Read a generic CSV with user-specified columns

Description

read_generic() reads any CSV and maps its columns onto the standard bibnets fields by name. The authors, keywords, references, countries and affiliations columns, and any list_cols, are split on sep into list-columns; journal is copied as a single value; id is set from the named column or from row numbers. Named columns missing from the file are skipped with a warning. It returns every source column plus the mapped fields.

Usage

read_generic(
  file,
  id = NULL,
  sep = ";",
  authors = NULL,
  keywords = NULL,
  references = NULL,
  countries = NULL,
  affiliations = NULL,
  journal = NULL,
  list_cols = NULL
)

Read Lens.org CSV export

Description

read_lens() parses a CSV file exported from Lens.org into a standardized bibliometric data frame. read_biblio() reads several files at once and detects the format.

Usage

read_lens(file, encoding = "UTF-8")

Arguments

file

Path to a Lens.org CSV export file.

encoding

Character. File encoding. Default "UTF-8".

Value

A data frame in the standard bibnets format: id, title, year, journal, doi, cited_by_count, abstract, type, plus list-columns authors, references, and keywords.

Examples

f <- system.file("extdata", "lens_sample.csv", package = "bibnets")
data <- read_lens(f)
subset(data, select = c(id, title, year, journal, authors))

Convert OpenAlex data to bibnets format

Description

read_openalex() converts the output of openalexR::oa_fetch() (a tibble/data frame of works) to the standardized bibnets format with list-columns. For a flat CSV downloaded from the OpenAlex website, use read_openalex_csv().

Usage

read_openalex(data)

Arguments

data

A data frame from oa_fetch(entity = "works", ...). Must contain at least an id column. Common columns include display_name, publication_year, so, doi, cited_by_count, referenced_works, ab, and author (nested).

Value

A data frame in the standard bibnets format: id, title, year, journal, doi, cited_by_count, abstract, type, plus list-columns authors, references, and keywords.

Examples

# Construct a minimal data frame matching the structure returned by
# openalexR::oa_fetch(entity = "works", ...). In practice, pass the
# result of oa_fetch() directly.
raw <- data.frame(
  id = c("W123", "W456"),
  display_name = c("First paper", "Second paper"),
  publication_year = c(2022L, 2021L),
  so = c("Journal A", "Journal B"),
  doi = c("https://doi.org/10.1/a", "https://doi.org/10.2/b"),
  cited_by_count = c(5L, 12L),
  author = I(list(
    data.frame(au_display_name = c("Smith J", "Jones A")),
    data.frame(au_display_name = "Davis M")
  )),
  referenced_works = I(list(c("W100", "W200"), "W123"))
)
data <- read_openalex(raw)
subset(data, select = c(id, title, year, doi, authors, references))

Read a flat OpenAlex CSV export

Description

read_openalex_csv() reads the flat CSV format downloaded directly from the OpenAlex website (openalex.org/works exports). Multi-value fields are pipe-delimited (|). This is distinct from the nested tibble produced by openalexR::oa_fetch(), which is handled by read_openalex().

Usage

read_openalex_csv(file, sep = "|")

Arguments

file

Path to the CSV file.

sep

Character. Delimiter for multi-value fields. Default "|".

Value

A data frame in the standard bibnets format: id, title, year, journal, doi, cited_by_count, abstract, type, plus list-columns authors, references, keywords, affiliations, countries, one row per work. abstract is always NA and every references element is empty, because the flat export carries neither.

Examples

f <- system.file("extdata", "openalex_works.csv", package = "bibnets")
data <- read_openalex_csv(f)
head(subset(data, select = c(id, year, authors, countries)))

Read an RIS file

Description

read_ris() parses a .ris file into a standardized bibliometric data frame. Like BibTeX, standard RIS does not include cited references. read_biblio() reads several files at once and detects the format.

Usage

read_ris(file, encoding = "UTF-8")

Arguments

file

Path to a .ris file.

encoding

Character. File encoding. Default "UTF-8".

Value

A data frame in the standard bibnets format: id, title, year, journal, doi, cited_by_count, abstract, type, plus list-columns authors, references (typically empty for RIS), and keywords.

Examples

# Write a minimal RIS record to a temp file, then read it
ris <- "TY  - JOUR
AU  - Smith, J.
AU  - Jones, K.
TI  - Bibliometric networks
JO  - Test Journal
PY  - 2020
DO  - 10.1000/test
ER  - "
f <- tempfile(fileext = ".ris")
writeLines(ris, f)
data <- read_ris(f)
subset(data, select = c(id, title, year, journal, doi, authors))
unlink(f)

Read Scopus CSV export

Description

read_scopus() parses a CSV file exported from Scopus into a standardized bibliometric data frame with list-columns for multi-valued fields. read_biblio() reads several files at once and detects the format.

Usage

read_scopus(file, encoding = "UTF-8")

Arguments

file

Path to a Scopus CSV export file.

encoding

Character. File encoding. Default "UTF-8".

Value

A data frame in the standard bibnets format: id, title, year, journal, doi, cited_by_count, abstract, type, plus list-columns authors, references, and keywords. Scopus-specific extras: index_keywords (list-column), affiliations (character), language (character).

Examples

f <- system.file("extdata", "scopus_sample.csv", package = "bibnets")
data <- read_scopus(f)
subset(data, select = c(id, title, year, journal, authors))

Read a single bibliometric file

Description

read_single_biblio() reads one file for read_biblio(). It calls read_generic() for format = "generic"; otherwise it detects the format with detect_format() when format = "auto" and dispatches to the matching format-specific reader, with an error that lists the supported formats when none matches.

Usage

read_single_biblio(
  file,
  format,
  id,
  sep,
  authors = NULL,
  keywords = NULL,
  references = NULL,
  countries = NULL,
  affiliations = NULL,
  journal = NULL,
  list_cols = NULL,
  ...
)

Read Web of Science plaintext or tab-delimited export

Description

read_wos() parses a Web of Science export file (plaintext or tab-delimited) into a standardized bibliometric data frame. read_biblio() reads several files at once and detects plaintext exports automatically; pass it format = "wos_tab" for tab-delimited files.

Usage

read_wos(file, format = "plaintext")

Arguments

file

Path to a WoS export file (.txt).

format

Character. "plaintext" (default) for WoS tagged format, or "tab" for tab-delimited export.

Value

A data frame in the standard bibnets format: id, title, year, journal, doi, cited_by_count, abstract, type, plus list-columns authors, references, and keywords. WoS-specific extra: keywords_plus (list-column).

Examples

f <- system.file("extdata", "wos_sample.txt", package = "bibnets")
data <- read_wos(f)
subset(data, select = c(id, title, year, journal, authors))

Build a reference network

Description

reference_network() builds a co-citation or equivalence network among cited references. In a co-citation network two references are linked when they are cited together by the same paper; the equivalence network instead uses the cosine similarity of the references' citing-paper vectors.

Usage

reference_network(
  data,
  type = "co_citation",
  counting = "full",
  similarity = "none",
  threshold = 0,
  min_occur = 1L,
  top_n = NULL,
  self_loops = FALSE,
  deduplicate = TRUE,
  format = "edgelist",
  references = "references",
  sep = ";",
  strip_quotes = TRUE,
  id = NULL
)

Arguments

data

A data frame with one row per work and a references column (list-column or delimited string). An id column is optional (see id).

type

Character. "co_citation" (default) or "equivalence" (cosine similarity of the references' citing-paper vectors; counting and similarity are ignored).

counting

Character. Counting method: "full" (default), "fractional", "paper" or "strength".

similarity

Character. Similarity measure. Default "none".

threshold

Numeric. Minimum edge weight; edges with weight < threshold are dropped. Default 0 (keep all).

min_occur

Integer. Minimum times a reference must be cited. Default 1.

top_n

Integer or NULL. Keep only the top_n most frequent nodes and return the edges among them. Default NULL (all nodes).

self_loops

Logical. If TRUE, include self-loops (an entity linked to itself). Default FALSE. Only takes effect with similarity = "none"; every similarity measure zeroes the diagonal.

deduplicate

Logical. If TRUE (default), each ⁠(paper, entity)⁠ pair is counted at most once – duplicate entries in the source data (e.g., the same author listed twice on a paper) are treated as one occurrence. Set to FALSE to count every raw occurrence.

format

Character. Output format:

"edgelist"

Default. A bibnets_network data frame with columns from, to, weight, count.

"gephi"

Gephi-ready data frame: Source, Target, Weight, Count, Type.

"igraph"

An igraph graph object (requires igraph).

"cograph"

A cograph_network object (requires cograph).

"matrix"

A sparse adjacency matrix.

references

Character. Name of the column containing cited references. Default "references".

sep

Character. Separator used to split the references column when it is a plain character column. Default ";". Ignored for list-columns.

strip_quotes

Logical. If TRUE (default), surrounding quote characters are removed from each reference.

id

Optional. Name of the column to use as the work identifier (the matrix-row dimension). If NULL (default), an existing id column is used when present, otherwise row numbers are used.

Details

The citing papers and their references form a two-mode matrix that is projected onto the references; counting and similarity weight the edges and threshold, min_occur and top_n prune them. It returns a bibnets_network edge list by default. To link the citing documents instead (bibliographic coupling or direct citation), use document_network().

Value

Depends on format. The default "edgelist" returns a bibnets_network data frame with one row per undirected edge, columns from, to, weight and count, sorted by decreasing weight, and attributes network_type, counting and similarity. See author_network() for the other formats.

Examples

data(biblio_data)
reference_network(biblio_data)
reference_network(biblio_data, similarity = "association")

Resolve the work-identifier column

Description

resolve_id() materializes a top-level id column that the network pipeline uses to index works (matrix rows). Resolution rules:

Usage

resolve_id(data, id = NULL)

Arguments

data

A data frame.

id

NULL or a single column name (character scalar).

Details

When id names a column other than "id" and the data already has a distinct "id" column, the request is ambiguous (the existing "id" column might itself be an entity field). Rather than silently overwriting it, this errors and asks the caller to resolve the conflict.

Value

data with a guaranteed character id column.


Resolve file paths from a file, vector of files, or directory

Description

resolve_paths() expands path into a character vector of files: a directory contributes its .csv, .txt, .bib, .ris, .xls and .xlsx files, an existing file is kept, and a path that does not exist is dropped.

Usage

resolve_paths(path)

Scopus dataset: green cloud computing and quantization (2020–2025)

Description

scopus_quantum_cloud is a 499-record subset of a Scopus bibliometric export on the intersection of green cloud computing and quantization, covering 2020–2025. Includes full reference strings, author keywords, and affiliations. The references are formatted citation strings, not Scopus EIDs, so they do not match the id column: use this dataset for co-citation, coupling, keyword and collaboration networks, not for local citations or historiographs.

Usage

scopus_quantum_cloud

Format

A data frame with 499 rows and 12 columns:

id

Scopus EID.

title

Work title.

year

Publication year (integer).

journal

Source title.

doi

DOI string without the https://doi.org/ prefix.

cited_by_count

Times cited in Scopus.

abstract

Abstract text.

type

Document type ("Article", "Review", etc.).

authors

List-column of author name strings.

references

List-column of cited reference strings.

keywords

List-column of author keywords.

affiliations

List-column of affiliation strings.

Source

Scopus bibliometric export. Dataset archived at doi:10.5281/zenodo.17142636 (CC BY 4.0).

Examples

data(scopus_quantum_cloud)
author_network(scopus_quantum_cloud, "collaboration")
keyword_network(scopus_quantum_cloud)
document_network(scopus_quantum_cloud, "coupling", similarity = "cosine")

Build a source (journal) network

Description

source_network() builds a network between publication sources (journals, book series). By default two sources are linked by bibliographic coupling, when their papers share cited references; the other types are source co-citation (sources cited together, from a cited_journals column) and the cosine similarity of the sources' pooled reference vectors.

Usage

source_network(
  data,
  type = "coupling",
  counting = "full",
  similarity = "none",
  threshold = 0,
  min_occur = 1L,
  top_n = NULL,
  self_loops = FALSE,
  deduplicate = TRUE,
  format = "edgelist",
  journal = "journal",
  sep = ";",
  references_sep = ";",
  strip_quotes = TRUE,
  id = NULL
)

Arguments

data

A data frame with one row per work and a journal column (one value per work). An id column is optional (see id). Coupling and equivalence also need references; co-citation needs a cited_journals list-column.

type

Character. "coupling" (default; sources linked by the references their papers share), "co_citation" (sources cited together, from cited_journals), or "equivalence" (cosine similarity of the sources' pooled reference vectors; counting and similarity are ignored).

counting

Character. Counting method: "full" (default), "fractional", "paper" or "strength".

similarity

Character. Similarity measure. Default "none".

threshold

Numeric. Minimum edge weight; edges with weight < threshold are dropped. Default 0 (keep all).

min_occur

Integer. Minimum papers per source. Default 1.

top_n

Integer or NULL. Keep only the top_n most frequent nodes and return the edges among them. Default NULL (all nodes).

self_loops

Logical. If TRUE, include self-loops (an entity linked to itself). Default FALSE. Only takes effect with similarity = "none"; every similarity measure zeroes the diagonal.

deduplicate

Logical. If TRUE (default), each ⁠(paper, entity)⁠ pair is counted at most once – duplicate entries in the source data (e.g., the same author listed twice on a paper) are treated as one occurrence. Set to FALSE to count every raw occurrence.

format

Character. Output format:

"edgelist"

Default. A bibnets_network data frame with columns from, to, weight, count.

"gephi"

Gephi-ready data frame: Source, Target, Weight, Count, Type.

"igraph"

An igraph graph object (requires igraph).

"cograph"

A cograph_network object (requires cograph).

"matrix"

A sparse adjacency matrix.

journal

Character. Name of the column containing the publication source. Default "journal". Use this to point at any column of a custom data set, e.g. journal = "Source title".

sep

Character. Not used: the journal column holds one value per work and is never split. Kept for a signature consistent with the other builders.

references_sep

Character. Separator for the references column in type = "coupling" and "equivalence". Default ";".

strip_quotes

Logical. If TRUE (default), surrounding quote characters are removed from each entity.

id

Optional. Name of the column to use as the work identifier (the matrix-row dimension). If NULL (default), an existing id column is used when present, otherwise row numbers are used.

Details

counting and similarity weight the edges and threshold, min_occur and top_n prune them. It returns a bibnets_network edge list by default. To link sources by any other field, use conetwork(data, "journal", by = ...) (see conetwork()).

Value

Depends on format. The default "edgelist" returns a bibnets_network data frame with one row per undirected edge, columns from, to, weight and count, sorted by decreasing weight, and attributes network_type, counting and similarity. See author_network() for the other formats.

Examples

data(biblio_data)
source_network(biblio_data, "coupling")

Split delimited strings into a list-column

Description

split_field() splits delimited strings (semicolons are common in Scopus/WoS exports) into character vectors, trimming whitespace around each piece and dropping empty pieces. This is the operation every reader and builder applies to a multi-valued character column; use it to prepare a list-column yourself.

Usage

split_field(x, sep = ";")

Arguments

x

A character vector (a factor is coerced to character) of delimited strings.

sep

Character. Literal delimiter (not a regular expression). Default ";".

Value

A list the same length as x; element i is the character vector of pieces of x[i]. NA and empty strings give character(0).

Examples

split_field(c("Alice; Bob; Carol", "Dave; Eve"))
split_field(c("a|b|c", "d||e", NA), sep = "|")

Standardize author names

Description

standardize_authors() cleans author names by uppercasing, whitespace normalisation, and dot removal from initials (F.J. -> FJ). Name order and format are preserved, consistent with how bibliometrix handles multi-source data. To reorder and parse names, use parse_names().

Usage

standardize_authors(x, flip_names = FALSE)

Arguments

x

Character vector of author names.

flip_names

Logical. If TRUE, names in ⁠Last, First⁠ format are reordered to ⁠First Last⁠. Off by default; enable only when all names in x reliably follow the ⁠Last, First⁠ convention.

Value

Character vector, uppercased and cleaned.


Strip surrounding quote characters from entity labels

Description

strip_surrounding_quotes() removes leading/trailing double-quote characters (straight ⁠"⁠, the CSV doubled "", and curly quotes) plus surrounding whitespace, so quoted values such as "Alice" or ⁠""Bob""⁠ become Alice / Bob. Quotes inside a label (e.g. an apostrophe in ⁠O'Brien⁠) are left untouched.

Usage

strip_surrounding_quotes(x)

Arguments

x

Character vector.

Value

Character vector with surrounding quotes/whitespace removed.


Summarise a bibnets network

Description

summary() describes a bibnets_network edge list. It prints the network type, counting and similarity methods, the number of nodes and edges, the density (edges over the n (n - 1) / 2 possible undirected pairs), the minimum, median and maximum weight, and the five nodes with the most edges.

Usage

## S3 method for class 'bibnets_network'
summary(object, ...)

Arguments

object

A bibnets_network data frame.

...

Ignored.

Value

object, unchanged and invisibly (a bibnets_network data frame). Called for its printed output.

Examples

data(biblio_data)
edges <- author_network(biblio_data, "collaboration")
summary(edges)

Build time-windowed networks

Description

temporal_network() splits data by time windows and builds a separate network for each window using any network function, so the same construction can be compared across periods.

Usage

temporal_network(
  data,
  network_fun,
  ...,
  window = 3,
  step = NULL,
  strategy = "fixed",
  time_col = "year"
)

Arguments

data

A data frame with a numeric time column.

network_fun

Function or character string naming a network function (e.g., author_network, "reference_network", conetwork).

...

Additional arguments passed to network_fun (e.g., type, counting, similarity, threshold, top_n).

window

Integer. Width of each time window in units of the time column (years, months, quarters, etc.). Default 3.

step

Integer or NULL. Step size between windows. Default NULL (equals window for fixed, 1 for sliding).

strategy

Character. Time window strategy:

"fixed"

Disjoint non-overlapping windows (default).

"sliding"

Overlapping windows advancing by step units.

"cumulative"

Each window starts at the earliest value and extends further.

time_col

Character. Name of the column containing the time variable. Default "year". Works with any numeric time unit: years, months, quarters, semesters, weeks, etc. (e.g., "month", "quarter", "time").

Details

The time column is coerced to integer before windows are formed. Windows are fixed (disjoint), sliding (overlapping, advancing by step) or cumulative (each starting at the earliest value), of width window. It returns a named list with one edge list per non-empty window.

network_fun must return a data frame, so keep the builder's default format = "edgelist".

Value

A named list with one element per non-empty window, named by the window label ("start-end", e.g. "2018-2020"). Each element is the edge list returned by network_fun (a bibnets_network for the package builders with the default format) with an extra character column window. Windows with fewer than two records or no edges are omitted; if network_fun fails in a window, a warning naming the window is raised and that window is omitted. An empty list is returned when the time column has no non-missing values.

Examples

data(biblio_data)

# Fixed 3-year windows
temporal_network(biblio_data, author_network, "collaboration")

# Sliding window
temporal_network(biblio_data, author_network, "collaboration",
                 window = 2, strategy = "sliding")

# Cumulative
temporal_network(biblio_data, reference_network,
                 threshold = 0, strategy = "cumulative", window = 2)

# With string name
temporal_network(biblio_data, "keyword_network", window = 3)

Prepare network for cograph::splot()

Description

to_cograph() converts a bibnets edge list to a cograph_network object by calling cograph::as_cograph(). Optionally merges node metadata (e.g., from local_citations()) into the network's node table so attributes like lcs or year can be used directly in splot() aesthetic parameters (e.g., node_size = "lcs").

Usage

to_cograph(edges, nodes = NULL, directed = FALSE)

Arguments

edges

A data frame with at least from, to, weight columns.

nodes

Optional data frame of node attributes with an id column (e.g., output of local_citations()). All other columns are merged into the node table of the cograph_network and become available as aesthetic mappings.

directed

Logical. Default FALSE.

Details

Note: bibnets edge lists (from, to, weight) are accepted directly by cograph::splot() without conversion. This function is only needed when you want to attach node-level metadata.

Value

A cograph_network (a list whose nodes and edges components are data frames); with nodes supplied, its node table gains every non-id column of nodes, matched by node label (NA where a node has no metadata row).

Examples


data(biblio_data)

# Without metadata
to_cograph(author_network(biblio_data, "collaboration"))

# With metadata: local citation scores attached to a document network
to_cograph(document_network(biblio_data, type = "coupling"),
           nodes = local_citations(biblio_data))


Export to Gephi node and edge tables

Description

to_gephi() converts a bibnets edge list (and optional node table) to the CSV format expected by Gephi's Data Laboratory. Column names are remapped to Gephi conventions (Source, Target, Weight, Id, Label).

Usage

to_gephi(edges, nodes = NULL, file = NULL, directed = FALSE)

Arguments

edges

A data frame with at least from, to, weight columns.

nodes

Optional data frame of node attributes. Must contain an id column. All other columns are included as Gephi node attributes.

file

Optional directory path. If supplied, writes nodes.csv and edges.csv into that directory. If NULL (default), returns a list.

directed

Logical. Sets the Type column. Default FALSE.

Value

If file = NULL, a list of two plain data frames: nodes (one row per node, columns Id, Label, then any extra node attributes) and edges (one row per edge, columns Source, Target, Weight, Type, then the remaining edge columns such as count). If file is an existing directory, writes nodes.csv and edges.csv there, reports the paths with a message, and returns the two paths invisibly.

Examples

data(biblio_data)
edges <- author_network(biblio_data, "collaboration")
to_gephi(head(edges, 3))

# Write nodes.csv and edges.csv into a directory
out_dir <- tempfile("gephi")
dir.create(out_dir)
to_gephi(edges, file = out_dir)
unlink(out_dir, recursive = TRUE)

Export to GraphML

Description

to_graphml() writes a bibnets edge list (and optional node attributes) to a GraphML file, or returns the document as a string, using base R only, without an XML package.

Usage

to_graphml(edges, nodes = NULL, file = NULL, directed = FALSE)

Arguments

edges

A data frame with at least from, to, weight columns.

nodes

Optional data frame of node attributes with an id column.

file

File path to write. If NULL (default), returns the GraphML as a character string.

directed

Logical. Default FALSE.

Value

If file = NULL, the GraphML document as a single character string. Otherwise writes the file, reports the path with a message, and returns the path invisibly.

Examples

data(biblio_data)
edges <- keyword_network(biblio_data)
xml <- to_graphml(edges)
cat(substr(xml, 1, 300))

Convert edge data frame to igraph

Description

to_igraph() converts a bibnets edge list to an igraph graph with igraph::graph_from_data_frame(). It requires the suggested package igraph. For a tbl_graph use to_tbl_graph(); for a cograph network use to_cograph().

Usage

to_igraph(edges, directed = FALSE)

Arguments

edges

A data frame with at least from, to, weight columns, as returned by any network function in bibnets.

directed

Logical. Default FALSE.

Value

An igraph graph with one vertex per node label and one edge per row of edges; the remaining columns (weight, count, ...) become edge attributes.

Examples


data(biblio_data)
edges <- author_network(biblio_data, "collaboration")
to_igraph(edges)


Convert edge data frame to adjacency matrix

Description

to_matrix() converts a bibnets edge list to a square sparse adjacency matrix of edge weights, one row and column per node. By default each edge is entered in both directions, so the matrix is symmetric.

Usage

to_matrix(edges, symmetric = TRUE)

Arguments

edges

A data frame with from, to, weight columns.

symmetric

Logical. If TRUE (default), produces a symmetric matrix (each edge is entered in both directions).

Value

A square sparse dgCMatrix of edge weights with one row and column per node label (dimnames are the node labels).

Examples

data(biblio_data)
edges <- reference_network(biblio_data, min_occur = 2)
to_matrix(edges)

Convert edge data frame to tbl_graph

Description

to_tbl_graph() converts a bibnets edge list to a tidygraph tbl_graph, through to_igraph(). It requires the suggested packages tidygraph and igraph.

Usage

to_tbl_graph(edges, directed = FALSE)

Arguments

edges

A data frame with at least from, to, weight columns.

directed

Logical. Default FALSE.

Value

A tbl_graph (tidygraph) with the edge columns as edge data and one node row per node label.

Examples


data(biblio_data)
edges <- keyword_network(biblio_data)
to_tbl_graph(edges)


Warn when a separator likely failed to split a multi-entity column

Description

warn_if_sep_mismatch() warns when a separator likely failed to split a multi-entity column. Splitting with the wrong separator silently yields one "entity" per row (e.g., a whole author byline as a single node). Heuristic: no row split into more than one entity, yet most non-empty strings contain a common structural delimiter.

Usage

warn_if_sep_mismatch(col, parts, field, sep)

Details

Only structural delimiters (";", "|", tab) are considered, because they essentially never occur inside a single legitimate label. Commas and " and " are deliberately excluded: they appear inside valid single values (e.g. "Last, First" author names, one-reference-per-row citation strings, or organisations like "Smith and Sons"), so warning on them would mislead users with correct data.