| 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 |
| 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:
Mohammed Saqr saqr@saqr.me (ORCID) [copyright holder]
Sonsoles López-Pernas (ORCID)
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 |
entity_field |
Character. Name of the entity column. If it is a scalar
column (e.g., |
value_field |
Character. Name of the list-column to aggregate
(e.g., |
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 |
network_type |
Character. |
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 |
type |
Character. Relationship type:
|
counting |
Character. Counting method. Position-independent methods
( |
similarity |
Character. Similarity measure: |
threshold |
Numeric. Minimum edge weight; edges with
|
min_occur |
Integer. Minimum number of papers for an author to be
included. Default 1. Not applied with a position-dependent |
position_weights |
Numeric vector. Custom weights for
|
first_last_weight |
Numeric. Multiplier for |
attention |
Character or NULL. Attention-based weighting independent of
|
top_n |
Integer or NULL. Keep only the |
self_loops |
Logical. If |
deduplicate |
Logical. If |
format |
Character. Output format:
|
authors |
Character. Name of the column containing authors. Default
|
sep |
Character. Separator used to split the entity column (the one
named by the column argument, e.g. |
references_sep |
Character. Separator for the |
strip_quotes |
Logical. If |
id |
Optional. Name of the column to use as the work identifier
(the matrix-row dimension). If |
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
|
first_last_weight |
Numeric. Multiplier for first/last authors
when |
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 |
alpha |
Numeric. Significance threshold in (0, 1). Default |
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 |
field |
Character. Name of the entity column. Default |
counting |
Character. Counting method. |
position_weights |
Numeric vector for |
first_last_weight |
Numeric for |
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 |
field |
Character. Name of the list-column containing entities
(e.g., |
min_freq |
Integer. Minimum number of occurrences for an entity to be included. Default 1 (no filtering). |
sep |
Character. Separator used to split |
strip_quotes |
Logical. Strip surrounding quote characters from
entities. Default |
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 |
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 |
field |
Character. The entity field; its values become the nodes. |
by |
Character or |
sep |
Character or |
counting |
Character. Counting method: |
similarity |
Character. Normalization method. Default |
threshold |
Numeric. Minimum edge weight; edges with
|
min_occur |
Integer. Minimum entity frequency. Default 1. |
top_n |
Integer or NULL. Keep only the |
self_loops |
Logical. If |
deduplicate |
Logical. If |
format |
Character. Output format:
|
strip_quotes |
Logical. If |
id |
Optional. Name of the column to use as the work identifier
(the matrix-row dimension). If |
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 |
type |
Character. |
counting |
Character. Counting method: |
similarity |
Character. Similarity measure. Default |
threshold |
Numeric. Minimum edge weight; edges with
|
min_occur |
Integer. Minimum papers per country. Default 1. |
attention |
Character or NULL. Attention-based weighting independent of
|
top_n |
Integer or NULL. Keep only the |
self_loops |
Logical. If |
deduplicate |
Logical. If |
format |
Character. Output format:
|
countries |
Character. Name of the column containing countries.
Default |
sep |
Character. Separator used to split the entity column (the one
named by the column argument, e.g. |
references_sep |
Character. Separator for the |
strip_quotes |
Logical. If |
id |
Optional. Name of the column to use as the work identifier
(the matrix-row dimension). If |
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 |
type |
Character. Relationship type:
|
counting |
Character. Counting method: |
similarity |
Character. Similarity measure. Default |
threshold |
Numeric. Minimum edge weight; edges with
|
min_occur |
Integer. Minimum reference frequency. Default 1. |
top_n |
Integer or NULL. Keep only the |
self_loops |
Logical. If |
deduplicate |
Logical. If |
format |
Character. Output format:
|
references |
Character. Name of the column containing cited references.
Default |
sep |
Character. Separator used to split the references column when
it is a plain character column. Default |
strip_quotes |
Logical. If |
id |
Optional. Name of the column to use as the work identifier
(the matrix-row dimension). If |
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 |
nodes |
Optional character vector of node names. If |
symmetric |
Logical. If |
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 |
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 |
n |
Integer. Number of top nodes to keep (ties in edge count are
broken by the order of |
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 |
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 |
sep |
Character. Separator used to split the references column when it is a plain
character column. Default |
strip_quotes |
Logical. If |
id |
Optional. Name of the column to use as the work identifier.
If |
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:
nodesOne row per included document (at most
n, each withlcs >= min_lcs), with thelocal_citations()columns (id,lcs,gcswhen available,year, andtitle,journal,doiwhen present), sorted by decreasinglcs.edgesOne row per distinct directed citation that points at an included document, with
from(citing; any document in the data),to(cited),year_fromandyear_to(integer), sorted byyear_fromthenyear_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 |
type |
Character. |
counting |
Character. Counting method: |
similarity |
Character. Similarity measure. Default |
threshold |
Numeric. Minimum edge weight; edges with
|
min_occur |
Integer. Minimum papers per institution. Default 1. |
attention |
Character or NULL. Attention-based weighting independent of
|
top_n |
Integer or NULL. Keep only the |
self_loops |
Logical. If |
deduplicate |
Logical. If |
format |
Character. Output format:
|
affiliations |
Character. Name of the column containing institutions.
Default |
sep |
Character. Separator used to split the entity column (the one
named by the column argument, e.g. |
references_sep |
Character. Separator for the |
strip_quotes |
Logical. If |
id |
Optional. Name of the column to use as the work identifier
(the matrix-row dimension). If |
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 |
keywords |
Character. Name of the keyword column (list-column or
delimited string). Default |
counting |
Character. Counting method: |
similarity |
Character. Similarity measure. Default |
threshold |
Numeric. Minimum edge weight; edges with
|
min_occur |
Integer. Minimum keyword frequency. Default 1. |
attention |
Character or NULL. Attention-based weighting independent of
|
top_n |
Integer or NULL. Keep only the |
self_loops |
Logical. If |
deduplicate |
Logical. If |
format |
Character. Output format:
|
sep |
Character. Separator used to split the keyword column when it
is a plain character column, e.g. |
strip_quotes |
Logical. If |
field |
Deprecated. Use |
id |
Optional. Name of the column to use as the work identifier
(the matrix-row dimension). If |
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
NAif not available.- doi
DOI string without the
https://doi.org/prefix, orNA.- 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 |
references |
Character. Name of the column containing cited references.
Default |
sep |
Character. Separator used to split the references column when it is a plain
character column. Default |
strip_quotes |
Logical. If |
id |
Optional. Name of the column to use as the work identifier.
If |
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:
idDocument identifier (character).
lcsLocal Citation Score (integer): times cited by other documents in the dataset.
gcsGlobal 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 |
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. |
similarity |
Character. Normalization method (see |
threshold |
Numeric. Minimum edge weight to retain. |
top_n |
Integer or |
self_loops |
Logical. Keep diagonal entries as self-loops. Only
honoured with |
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:
|
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.
|
format |
Output style for personal names (group/corporate
authors,
|
surname_first |
How to read comma-less strings (strings with
a comma are always
May also be given as the logical |
Details
Three name conventions are recognised:
-
"Last, First"(a comma): always parsed as surname-then-given. -
"SURNAME Initials"(no comma, e.g."WANG Y","AYALA-ROMERO JA"): the Scopus / bibnets author-label form. -
"First Last"(no comma, e.g."Mohammed Saqr").
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
apply the same call to both endpoint columns or the two ends use different labels;
the mapping is many-to-one, so distinct authors can collapse onto one label (especially with
"last_initials"), and bibnets does not re-aggregate the resulting duplicate edges.
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 |
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 |
threshold |
Numeric or |
top_n |
Integer or |
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:
|
id |
Character. Column name for the document identifier. Only used
when |
authors, keywords, references, countries, affiliations |
Character. For
|
journal |
Character. For |
sep |
Character. Delimiter for splitting the mapped multi-valued
columns. Default |
list_cols |
Character vector. For |
... |
Additional arguments passed to the format-specific reader
(for example |
actors |
Deprecated. Use the entity arguments ( |
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 |
encoding |
Character. File encoding. 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 (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 |
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 |
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 |
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 |
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 |
encoding |
Character. File encoding. 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 (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 |
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. |
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 |
type |
Character. |
counting |
Character. Counting method: |
similarity |
Character. Similarity measure. Default |
threshold |
Numeric. Minimum edge weight; edges with
|
min_occur |
Integer. Minimum times a reference must be cited. Default 1. |
top_n |
Integer or NULL. Keep only the |
self_loops |
Logical. If |
deduplicate |
Logical. If |
format |
Character. Output format:
|
references |
Character. Name of the column containing cited references.
Default |
sep |
Character. Separator used to split the references column when
it is a plain character column. Default |
strip_quotes |
Logical. If |
id |
Optional. Name of the column to use as the work identifier
(the matrix-row dimension). If |
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 |
|
Details
-
id = NULL(default): use the existingidcolumn if one is present, otherwise fall back to row numbers (seq_len(nrow(data))). -
id = "colname": copy the named column toid. The column must exist.
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 |
type |
Character. |
counting |
Character. Counting method: |
similarity |
Character. Similarity measure. Default |
threshold |
Numeric. Minimum edge weight; edges with
|
min_occur |
Integer. Minimum papers per source. Default 1. |
top_n |
Integer or NULL. Keep only the |
self_loops |
Logical. If |
deduplicate |
Logical. If |
format |
Character. Output format:
|
journal |
Character. Name of the column containing the publication
source. Default |
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 |
strip_quotes |
Logical. If |
id |
Optional. Name of the column to use as the work identifier
(the matrix-row dimension). If |
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 |
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 |
... |
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., |
... |
Additional arguments passed to |
window |
Integer. Width of each time window in units of the time column (years, months, quarters, etc.). Default 3. |
step |
Integer or |
strategy |
Character. Time window strategy:
|
time_col |
Character. Name of the column containing the time variable.
Default |
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 |
nodes |
Optional data frame of node attributes with an |
directed |
Logical. Default |
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 |
nodes |
Optional data frame of node attributes. Must contain an |
file |
Optional directory path. If supplied, writes |
directed |
Logical. Sets the |
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 |
nodes |
Optional data frame of node attributes with an |
file |
File path to write. If |
directed |
Logical. Default |
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 |
directed |
Logical. Default |
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 |
symmetric |
Logical. If |
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 |
directed |
Logical. Default |
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.