Package 'birddog'

Description

Tools to detect emergence and trace technological/scientific trajectories in papers and patents. It reads OpenAlex and Web of Science data, builds citation-based networks, identifies groups, and summarizes their dynamics.

Links

• Website: http://roneyfraga.com/birddog/

• GitHub: https://github.com/roneyfraga/birddog

• Issues: https://github.com/roneyfraga/birddog/issues

Pipeline

read_openalex()/read_wos() -> sniff_network() -> sniff_components() -> sniff_groups_cumulative() -> sniff_groups_lineage() -> sniff_trajectory_dag() -> sniff_trajectory_braid() -> analysis (sniff_trajectory_confluence(), ⁠_formation()⁠, ⁠_destination()⁠, ⁠_contribution()⁠, ⁠_self_sufficiency()⁠, ⁠_cct()⁠, ⁠_entropy()⁠, ⁠_hubs()⁠, ⁠_dynamics()⁠), each paired with a ⁠plot_*⁠ function. Focus an analysis with subset(flow, ...). "Flow" names the object kind, not an algorithm (stock vs flow: groups are stock, trajectories are flow): every detector returns a flow, and alternative detectors (⁠sniff_trajectory_<algo>()⁠) return the same contract, checked by validate_flow().

Label grammar

cNgN is a group (component N, group N); ⁠y<YYYY><cNgN>⁠ is a group-year node; ⁠tr::<cNgN>⁠ is a central trajectory (reaches the last year, one per final group); tr1..trN are absorbed trajectories. This grammar is part of the public API and only changes at major versions.

Theoretical background

Trajectories are detected as system-level objects (Dosi, 1982): disjoint chains in the temporal DAG of cumulative clusterings. A trajectory that stops being detected loses its identity, not its papers; tracking its terminal cohort to the last year classifies the outcome as convergence (one destination), divergence (many), or dormancy (none) — with emergence indicators on the living chains (Rotolo et al., 2015; Carley et al., 2017).

Author(s)

Maintainer: Roney Fraga Souza [email protected] (ORCID) [copyright holder]

Other contributors:

• Luis Felipe de Souza Rodrigues [email protected] [contributor]

See Also

Useful links:

• Report bugs at https://github.com/roneyfraga/birddog/issues

Description

Derives a fixed_state_thresholds()-shaped list from an observed sniff_trajectory_dynamics() table, so the cut points adapt to the dataset instead of fixed constants. The growth cuts are placed k robust deviations (median absolute deviation) from the median, which resists outliers such as a single fast-growing young core; the bounded metrics use their median as the neutral split, and dormancy_share keeps the absolute majority rule (its distribution is usually too concentrated at zero to standardize).

Usage

data_state_thresholds(dyn, k = 1)

Arguments

Details

Use it as a drop-in for the thresholds argument; the metrics are threshold-independent, so one pass is enough to derive and re-classify: dyn <- sniff_trajectory_dynamics(flow), th <- data_state_thresholds(dyn), dyn <- sniff_trajectory_dynamics(flow, thresholds = th).

Value

A list shaped like fixed_state_thresholds(): emergence_growth, decline_growth (robust, from the centrals' growth), emergence_novelty (median novelty of the centrals), convergence_entropy (median destination entropy of the absorbed), and dormancy_share (the default majority rule). Any quantity that cannot be derived (too few points, zero spread) falls back to its fixed_state_thresholds() value.

See Also

fixed_state_thresholds(), sniff_trajectory_dynamics(), plot_trajectory_dynamics()

Description

The fixed knobs for sniff_trajectory_dynamics(). These are not the applied default: by default the cut points are derived from the data via data_state_thresholds(), and these constants serve as the explicit fixed-constant option (pass this list as thresholds) and as the fallback for any quantity that cannot be derived. The classification follows two axes (see sniff_trajectory_dynamics()): a life-cycle phase for living (central) trajectories and a terminal fate for declining (absorbed) ones.

Usage

fixed_state_thresholds()

Value

A list: emergence_growth (min annualized growth_rate for a central to count as emergence; default 0.15), emergence_novelty (min novelty for emergence; default 0.30), decline_growth (a central at or below this growth_rate is dormant by stall; default -0.05), convergence_entropy (an absorbed trajectory whose normalized destination entropy is below this converged, else diverged; default 0.5), dormancy_share (an absorbed trajectory whose terminal cohort drops at least this share is dormant by death; default 0.5).

Description

Retrieves specified fields for OpenAlex work IDs using the OpenAlex API. Processes data in batches to avoid API rate limits.

Usage

get_openalex_fields(
  openalex_ids,
  variables = "publication_year",
  batch_size = 50,
  save_dir = NULL
)

Arguments

Details

This function:

1. Accepts either a character vector of IDs or a data frame with a "CR" column

2. Splits semicolon-separated ID strings into individual IDs

3. Validates IDs against the pattern "^W\d+$"

4. Fetches specified variables from OpenAlex API in batches

5. Optionally saves each batch to disk as it's processed

6. Handles API errors gracefully with informative messages

7. Includes delays between batches to respect API rate limits

Value

A tibble with the following columns:

• id: The OpenAlex work ID

• One column for each requested variable (e.g., "publication_year", "doi", "type")

Rows without valid OpenAlex IDs or where API calls fail will have NA values.

Note

The OpenAlex API has rate limits. This function implements:

• Batch processing to reduce number of API calls

• 0.5 second delays between batches

• Error handling for failed API requests

• Progress messages to track execution

• Optional disk saving for data persistence

If you encounter rate limiting errors, consider reducing batch_size or implementing longer delays.

Examples

## Not run: 
# From a character vector
ids <- c("W2261389918", "W1548650423", "W1504492735")
result <- get_openalex_fields(ids)

# Fetch multiple variables
result <- get_openalex_fields(
  ids,
  variables = c("publication_year", "doi", "type")
)

# From a data frame with CR column
oa_data <- data.frame(CR = c("W123;W456", "W789"))
result <- get_openalex_fields(oa_data)

# Save intermediate results while downloading
result <- get_openalex_fields(
  ids,
  variables = c("publication_year", "source_display_name"),
  save_dir = tempdir()
)

## End(Not run)

Description

"Flow" names the object kind, not the algorithm (stock vs flow: groups are stock, trajectories are flow). Every trajectory detector returns a flow – the temporal decomposition of the DAG into trajectories plus the confluence tree – so this predicate accepts the result of sniff_trajectory_braid() and of any future ⁠sniff_trajectory_<algo>()⁠ detector. is_flow() is the cheap predicate; validate_flow() is the contract's authoritative checker.

Usage

is_flow(x)

Arguments

Value

A length-one logical.

See Also

sniff_trajectory_braid(), validate_flow()

Other trajectory detection: sniff_trajectory_braid(), sniff_trajectory_channel(), sniff_trajectory_dag(), subset.birddog_flow(), validate_flow()

Description

Sort character vectors containing embedded numbers in natural numeric order rather than lexicographic order. For example, "c1g2" comes before "c1g10", which standard sort() would not guarantee.

Usage

mixed_sort(x)

Arguments

Details

The function extracts all numeric segments from each string using stringr::str_extract_all() and sorts by them sequentially (first number, then second). Designed for two-segment identifiers such as "c1g1", "c2g10", etc.

Value

A character vector sorted in natural numeric order.

See Also

sort() for standard lexicographic sorting.

Examples

mixed_sort(c("c1g10", "c1g2", "c1g1", "c1g9"))

mixed_sort(c("group12", "group1", "group3"))

Description

Experimental. The directed counterpart of plot_trajectory_confluence_matrix(): a heatmap of the cross-citation channels from a sniff_groups_influence() object. Rows are the citing group ("is influenced by") and columns the cited group ("the influencer"), so a cell and its mirror across the diagonal are the two directions of one pair. Confluence is symmetric; influence is not, and that broken symmetry is the bidirectional relationship.

Usage

plot_groups_influence_matrix(
  influence,
  fill = c("surprise", "raw", "debt", "audience", "salton"),
  diagonal = c("mute", "show", "drop"),
  show_values = TRUE,
  label_size = 4,
  order_by = c("group", "balance"),
  axis_text_size = NULL,
  axis_title_size = NULL,
  x_angle = 0,
  legend_position = "right",
  bg = "white",
  title = NULL
)

Arguments

Value

A ggplot object.

See Also

sniff_groups_influence(), plot_groups_influence_network(), plot_trajectory_confluence_matrix()

Other visualization: plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
infl <- sniff_groups_influence(groups)
plot_groups_influence_matrix(infl)
plot_groups_influence_matrix(infl, fill = "debt", diagonal = "drop")

## End(Not run)

Description

Experimental. Draws the directed influence backbone from a sniff_groups_influence() object as a node-link graph: an arrow runs from the source (the cited, more foundational group) to the recipient (the citing group). By default the edges are the net flow ⁠$net⁠ ($\nu_{ij} = C_{ij} - C_{ji}$), the "who, on balance, leads whom" spine; nodes are coloured by role (source / broker / sink) and sized by citation activity.

Usage

plot_groups_influence_network(
  influence,
  weight = c("net", "gross", "surprise"),
  min_weight = 0,
  node_size = c("equal", "io", "balance"),
  colour_role = TRUE,
  edge_labels = TRUE,
  edge_digits = NULL,
  labels = TRUE,
  label_size = NULL,
  layout = "sugiyama",
  title = NULL
)

Arguments

Value

A ggplot object.

See Also

sniff_groups_influence(), plot_groups_influence_matrix()

Other visualization: plot_groups_influence_matrix(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
infl <- sniff_groups_influence(groups)
plot_groups_influence_network(infl)
plot_groups_influence_network(infl, weight = "gross", min_weight = 50)

## End(Not run)

Description

Creates a 2D visualization of technological trajectories based on group similarity metrics, showing the evolution of research groups over time with node size representing group importance and color representing publication-year deviation.

Usage

plot_groups_lineage_2d(
  groups_lineage,
  group = "c1g1",
  jaccard_similarity = 0.01,
  prop_tracked_intra_group_treshold = 0.2,
  label_type = "size",
  label_vertical_position = 0,
  label_horizontal_position = 0,
  label_angle = 0,
  time_span = NA,
  show_legend = TRUE,
  color_by = c("py_deviation", "final_group_share")
)

Arguments

Details

A descriptive stock view of one group's lineage network. A group's lineage can share year communities with other groups (soft membership), so this view makes no trajectory claims – for detection see sniff_trajectory_braid().

Value

A ggplot2 object visualizing the technological trajectories.

See Also

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
# Compute trajectories first
traj_data <- sniff_groups_lineage(groups_cumulative)

# Visualize a specific group (pass the whole object; the function extracts what it needs internally)
plot_groups_lineage_2d(
  groups_lineage = traj_data,
  group = "c1g5",
  jaccard_similarity = 0.3
)

## End(Not run)

Description

Creates an interactive 3D visualization of technological trajectories showing the evolution of research groups over time with node size representing group importance and color representing publication year deviation.

Usage

plot_groups_lineage_3d(
  groups_lineage,
  group = "component1_g01",
  jaccard_similarity = 0.1,
  prop_tracked_intra_group_treshold = 0.2,
  label_type = "size",
  label_vertical_position = 0,
  label_horizontal_position = 0,
  label_angle = 0,
  time_span = NA,
  show_legend = TRUE,
  last_year_keywords = NULL,
  log_scale = FALSE
)

Arguments

Details

A descriptive stock view of one group's lineage network. A group's lineage can share year communities with other groups (soft membership), so this view makes no trajectory claims – for detection see sniff_trajectory_braid().

Value

A plotly 3D visualization object

See Also

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
# First get trajectory data
traj_data <- sniff_groups_lineage(groups_cumulative)

# Visualize a specific group in 3D
plot_groups_lineage_3d(
  groups_lineage = traj_data,
  group = "component1_g05",
  jaccard_similarity = 0.2
)

## End(Not run)

Description

The birddog stock map: every paper in the cumulative network is a point, laid out by a force-directed layout of the citation network and coloured by its final group, with a text label at each group's centroid. It is the stock snapshot – all final groups, the whole network at once – positioned by citation structure rather than text embeddings.

Usage

plot_groups_map(
  groups_cumulative,
  labels_text = NULL,
  network_until = NULL,
  layout = "drl",
  seed = 888L,
  point_size = 0.9,
  point_alpha = 0.7,
  show_unassigned = TRUE,
  label = TRUE,
  label_size = 3.2,
  title = "Group map",
  title_size = 14,
  normalize = FALSE,
  normalize_q = 0.99
)

Arguments

Value

A ggplot object.

See Also

sniff_groups_cumulative(), plot_trajectory_dag()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Description

One layout of the final network, with every paper revealed at the year it first enters the cumulative network and held at its final position, so the cloud grows without nodes moving. Returns a gganim object; render it to a GIF/MP4 with gganimate::animate() and gganimate::anim_save(). Reveal and colour reuse the static plot_groups_map() engine.

Usage

plot_groups_map_animation(
  groups_cumulative,
  labels_text = NULL,
  layout = "drl",
  seed = 888L,
  show_unassigned = TRUE,
  label = TRUE,
  label_size = 3.2,
  title_size = 14,
  point_size = 0.9
)

Arguments

Details

Rendering: the transition is one frame per year. Render with duration (not fps), which works with either renderer: gganimate::animate(anim, duration = 8) gives nframes/duration fps (with the magick renderer that ratio must divide 100, e.g. 32 years / 8 = 4). Save the rendered object, not the gganim: ⁠a <- gganimate::animate(anim, duration = 8); gganimate::anim_save("x.gif", a)⁠. Installing gifski removes the fps constraint.

Value

A gganim object (render with gganimate::animate()).

See Also

plot_groups_map(), plot_groups_map_interactive()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Description

The interactive twin of plot_groups_map(). Every paper is a scattergl point laid out by a force-directed layout of the citation network and coloured by its final group; hovering a node shows its title, year, authors, keywords, and final group. Returns a plotly htmlwidget – it renders in the RStudio Viewer, embeds in Quarto/Shiny, or saves to a standalone file with htmlwidgets::saveWidget().

Usage

plot_groups_map_interactive(
  groups_cumulative,
  labels_text = NULL,
  network_until = NULL,
  layout = "drl",
  seed = 888L,
  show_unassigned = TRUE,
  label = TRUE,
  label_size = 12,
  title = "Group map",
  title_size = 16,
  normalize = FALSE,
  normalize_q = 0.99,
  marker_size = 5
)

Arguments

Value

A plotly htmlwidget.

See Also

plot_groups_map(), sniff_groups_cumulative()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Description

The stock-side bridge view. One column per year; within a column the cluster-year nodes are ranked by paper count with the largest at the baseline, dot area encodes paper count, and (optionally) the number of groups that year is printed atop the column. No succession edges, no birth rings – it shows the annual + cumulative clustering fan settling onto the final-year groups. It is the stock-side counterpart of the flow-side plot_trajectory_dag(), and reads the sniff_trajectory_dag() object directly.

Usage

plot_groups_per_year(
  dag,
  color_terminal = FALSE,
  point_size = 6,
  show_count = TRUE,
  count_size = 3.2,
  count_colour = "white",
  count_fill = "grey45",
  label_terminal = TRUE,
  label_size = 3,
  axis_text_size = NULL,
  title = "Groups per year"
)

Arguments

Details

The visual encoding:

• One column per year along the x-axis; the y-axis has no intrinsic meaning (nodes are stacked by rank).

• Within a column the cluster-year nodes are ranked by paper count with the largest at the baseline, and dot area encodes the paper count.

• With show_count = TRUE the number of groups that year is printed atop the column on a filled label (count_fill / count_colour).

• There are no succession edges and no births: this is the stock-side view of how many groups exist each year and how large they are, settling onto the final-year groups. For the flow (edges, trajectories) use plot_trajectory_dag().

• With label_terminal = TRUE the final-year nodes are labelled c1gN to the right of the last column.

Value

A ggplot object.

See Also

sniff_trajectory_dag(), plot_trajectory_dag(), plot_trajectory_dag_interactive()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
# docs_per_group comes from sniff_groups_lineage()
dag <- sniff_trajectory_dag(docs_per_group)

plot_groups_per_year(dag)

# colour the dots by destination, bigger count chips and year labels
plot_groups_per_year(dag, color_terminal = TRUE, count_size = 5, axis_text_size = 14)

## End(Not run)

Description

A braided river system over sniff_trajectory_confluence(): every trajectory is a stream flowing left to right along the publication year, merging into its absorber where it hands off, until the central trajectories (tr::cNgN) reach the final year. Each tributary is drawn grey until the first paper it transfers is published, then in its colour; at the merge a band of width equal to the transferred papers (n of the tributary's cohort_size) bends into the river, which widens by that amount. The central spine is centered on its band with tributaries packed above and below. With target = NULL the whole system is drawn (one colour per destination central); with target = "tr::c1g1" only that central's direct feeders are drawn (one colour per tributary).

Usage

plot_trajectory_confluence(
  conf,
  target = "all",
  depth = NULL,
  min_n = 5,
  min_prop = 0.05,
  min_total_size = 0,
  min_duration_years = 0,
  width_range = c(0, 0.42),
  label_terminal = c("id_count", "id"),
  label_intermediary = c("id_count", "id"),
  label_terminal_size = 4.5,
  label_intermediary_size = 4,
  labels_text = NULL,
  legend_ncol = NULL,
  palette = NULL,
  axis_text_size = NULL,
  year_range = NULL,
  show_secondary = TRUE,
  secondary_min_prop = 0.2,
  smooth = TRUE,
  title = NULL
)

Arguments

Details

• x = publication year (never reassigned); the y-axis has no intrinsic meaning, it only packs streams to minimise merge crossings.

• Tributary width follows its community size each year; grey before the first transferred paper, then its colour. Central spine width is the smoothed cumulative inflow of its counted tributaries (papers transferred), on one proportional scale shared with the tributaries (0 papers give 0 width).

• A tributary hands n of its cohort_size papers over; only n enters the river, so the merge band keeps a constant width equal to the transferred papers (the n/cohort label makes the split explicit) and bends over a span that scales with the distance travelled, so its thickness reads the same for near and far feeders.

• min_n / min_prop decide what is counted, not merely hidden: dropped tributaries leave the river narrower and are summarised in the caption.

• An intermediate that delivers 0 documents to the final it flows into (its terminal cohort lands entirely outside that final's community) is always excluded, together with its upstream subtree, regardless of the thresholds: a stream contributing nothing to the destination cannot appear.

Value

A ggplot object.

See Also

sniff_trajectory_confluence(), plot_trajectory_formation(), sniff_trajectory_braid()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
flow <- sniff_trajectory_braid(docs_per_group)
conf <- sniff_trajectory_confluence(flow)

# the whole system: how every central forms
plot_trajectory_confluence(conf, min_n = 20)

# one central's direct feeders, coloured per tributary
plot_trajectory_confluence(conf, target = "tr::c1g1")

# focus on one intermediate trajectory: its feeders + the finals it fed
plot_trajectory_confluence(conf, target = "tr7")

# two selected centrals, a description legend, bigger year labels, bare ids,
#  a visible floor on thin streams, and only sizeable tributaries
descr <- data.frame(id = c("c1g1", "c1g5"), text = c("Topic A", "Topic B"))
plot_trajectory_confluence(conf, target = c("tr::c1g1", "tr::c1g5"),
                              labels_text = descr, axis_text_size = 14,
                              label_intermediary = "id", min_total_size = 30,
                              min_duration_years = 3, width_range = c(0.05, 0.45))

## End(Not run)

Description

The plotly twin of plot_trajectory_confluence(). Every trajectory is a filled stream over the publication year, laid out by the same centered lane packing and coloured by the same rule (per destination central in the whole-forest / multi view, per tributary in a single-central view). There is no legend: hovering a central river shows tr::cNgN (size) (plus its labels_text description), and hovering a tributary shows trN (n/cohort -> tr::cNgN). With label_terminal = TRUE the central (or selected) rivers are also named in a de-overlapped column on the right, joined to their stream by a leader line. Returns a plotly htmlwidget.

Usage

plot_trajectory_confluence_interactive(
  conf,
  target = "all",
  depth = NULL,
  min_n = 5,
  min_prop = 0.05,
  min_total_size = 0,
  min_duration_years = 0,
  width_range = c(0, 0.42),
  palette = NULL,
  labels_text = NULL,
  label_terminal = TRUE,
  label_size = 12,
  smooth = TRUE,
  title = NULL
)

Arguments

Details

Unlike the static function this covers the forest views only ("all", "finals", "intermediary", one or more centrals, and an intermediate shown as its upstream feeders); the single-intermediate focus view and the faint secondary-destination links are not drawn.

Built with plotly, following the same principles as plot_trajectory_dag_interactive():

• The x-axis is the publication year; the y-axis has no intrinsic meaning (it only packs streams to minimise merge crossings).

• Each stream is a filled polygon (fill = "toself", hoverable over its area); a tributary is grey before the first paper it transfers, then in its colour.

• There is no legend: detail is revealed on hover, and only the terminal (central or selected) rivers carry a printed label.

• An intermediate that delivers 0 documents to the final it flows into is always excluded (as in plot_trajectory_confluence()).

The widget renders in the RStudio Viewer, embeds in Quarto/Shiny, or saves to a standalone file with htmlwidgets::saveWidget().

Value

A plotly htmlwidget.

See Also

plot_trajectory_confluence(), plot_trajectory_dag_interactive(), sniff_trajectory_confluence()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
flow <- sniff_trajectory_braid(docs_per_group)
conf <- sniff_trajectory_confluence(flow)

plot_trajectory_confluence_interactive(conf, min_n = 20)

# one central's formation, hover the tributaries for their n/cohort
plot_trajectory_confluence_interactive(conf, target = "tr::c1g1")

## End(Not run)

Description

A heatmap of how each intermediate (absorbed) trajectory's papers spread across the final trajectories. By default rows are the final trajectories tr::cNgN and columns are the intermediate trajectories trN (swap with orientation); the fill is the coupling strength (shared documents) and each intermediate's dominant-final cell is outlined. Which intermediates appear is decided by the same pruning the other flow plots use (plot_trajectory_lines_2d(), plot_trajectory_confluence()), so the column set is consistent across views.

Usage

plot_trajectory_confluence_matrix(
  flow,
  conf = NULL,
  fill = c("n_shared", "prop_of_group", "prop_of_traj"),
  orientation = c("finals-cols", "finals-rows"),
  order_by = c("terminal", "reach", "size", "alpha", "cluster"),
  min_n = 5,
  min_prop = 0.05,
  min_total_size = 0,
  min_duration_years = 0,
  min_target_n = 0,
  mark_terminal = TRUE,
  show_values = FALSE,
  label_size = 2.5,
  axis_text_size = NULL,
  axis_title_size = NULL,
  legend_position = "right",
  legend_text_size = NULL,
  bg = "white",
  title = "Trajectory matrix"
)

Arguments

Value

A ggplot object.

See Also

sniff_trajectory_braid(), plot_trajectory_lines_2d(), plot_trajectory_confluence()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
flow <- sniff_trajectory_braid(docs_per_group)
plot_trajectory_confluence_matrix(flow, min_n = 20, show_values = TRUE)
plot_trajectory_confluence_matrix(flow, order_by = "cluster", bg = "grey20")

## End(Not run)

Description

The braided-river panorama: every cluster-year node laid out by year (x), with succession edges, node colour = terminal_group (or group), node size = paper count, and births ringed. Uses the year-aware Sugiyama layout from sniff_trajectory_dag()'s graph. Nodes from dormant lineages that never reach the final year (a colour value outside the final groups) are drawn grey and kept out of the colour legend.

Usage

plot_trajectory_dag(
  dag,
  color_by = c("terminal_group", "group"),
  edge_alpha = 0.25,
  point_size = 2.5,
  show_legend = FALSE,
  label_terminal = TRUE,
  labels_text = NULL,
  label_size = 3,
  title = "Cumulative network groups",
  legend_text_size = NULL,
  legend_ncol = NULL,
  axis_text_size = NULL
)

Arguments

Details

The visual encoding:

• The x-axis is the publication year (a Sugiyama layered layout); the y-axis has no intrinsic meaning, it only spreads nodes to reduce edge crossings.

• Node colour is the trajectory basin (see color_by), node size is the paper count, and succession edges fade with their Jaccard weight.

• Births (nodes with no strong predecessor) are ringed in black.

• Dormant lineages that never reach the final year are drawn grey and kept out of the colour legend, so the colours stand for the final groups only.

• With label_terminal = TRUE the final-year nodes are labelled c1gN to the right (with a leader line); with labels_text the colour legend moves to the bottom as "c1gN: description" entries.

Value

A ggplot object.

See Also

sniff_trajectory_dag(), plot_groups_per_year(), plot_trajectory_dag_interactive()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
# docs_per_group comes from sniff_groups_lineage()
dag <- sniff_trajectory_dag(docs_per_group)

# the whole braid, coloured by destination group
plot_trajectory_dag(dag)

# human-readable bottom legend, two columns, larger year labels
descr <- data.frame(id = c("c1g1", "c1g2"), text = c("Topic A", "Topic B"))
plot_trajectory_dag(dag, labels_text = descr, legend_ncol = 2, axis_text_size = 14)

## End(Not run)

Description

The plotly twin of plot_trajectory_dag(). Nodes are laid out by the same year-aware Sugiyama layout, sized by paper count, and coloured by the final group their lineage reaches. Dormant lineages that never reach the final year are drawn grey. There is no legend: hovering a final-year node shows its group id and labels_text description (c1gN: description), and hovering any other (intermediate or dormant) node shows its raw id (e.g. y2021c1g2). When label_terminal is TRUE, the final group id (c1gN) is also printed to the right of each final-year node. Returns a plotly htmlwidget.

Usage

plot_trajectory_dag_interactive(
  dag,
  labels_text = NULL,
  marker_range = c(4, 14),
  edge_alpha = 0.3,
  label_terminal = TRUE,
  label_size = 12,
  title = "Cumulative network groups"
)

Arguments

Details

The interactive twin of plot_trajectory_dag(), built with plotly:

• The x-axis is the publication year (Sugiyama layout); the y-axis has no intrinsic meaning.

• Node colour is the trajectory basin (the final group reached); dormant lineages that never reach the final year are grey. Node size scales with paper count over marker_range.

• There is no legend. Hovering a final-year node shows c1gN: description (its group id plus the labels_text description); hovering any other node shows its raw id (yYYYYcXgN).

• Edges are a single faint layer (edge_alpha) and are excluded from hover. With label_terminal = TRUE the final group ids (c1gN) are printed in a de-overlapped column to the right, each joined to its node by a leader line.

The widget renders in the RStudio Viewer, embeds in Quarto/Shiny, or saves to a standalone file with htmlwidgets::saveWidget().

Value

A plotly htmlwidget.

See Also

plot_trajectory_dag(), plot_groups_per_year()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
# docs_per_group comes from sniff_groups_lineage()
dag <- sniff_trajectory_dag(docs_per_group)

plot_trajectory_dag_interactive(dag)

# hover the final nodes for descriptions; fainter edges
descr <- data.frame(id = c("c1g1", "c1g2"), text = c("Topic A", "Topic B"))
p <- plot_trajectory_dag_interactive(dag, labels_text = descr, edge_alpha = 0.2)
# htmlwidgets::saveWidget(p, "trajectory_dag.html", selfcontained = TRUE)

## End(Not run)

Description

Draws the selected intermediate (stagnant) trajectory as a short spine on the left and fans out, from its handoff year, one curved link to every final trajectory its terminal cohort reached (the full destination split), each link's width scaled by the papers that landed there and labelled tr::cNgN (n). It answers, visually, "where did this trajectory go?" – not just the dominant absorber but the complete dispersion. Styling follows the other flow plots (plot_trajectory_lines_2d(), plot_trajectory_confluence()): a Set2/hue palette keyed by final group, a year-aware x-axis, and the shared year_range / axis_text_size / palette controls.

Usage

plot_trajectory_dispersion(
  destination,
  title = NULL,
  label_size = 4.5,
  year_range = NULL,
  axis_text_size = NULL,
  palette = NULL,
  min_n = 0
)

Arguments

Value

A ggplot object.

See Also

sniff_trajectory_destination(), plot_trajectory_confluence(), plot_trajectory_lines_2d()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
flow <- sniff_trajectory_braid(docs_per_group)
d <- sniff_trajectory_destination(flow, "tr1")
plot_trajectory_dispersion(d)

## End(Not run)

Description

A quadrant scatter of sniff_trajectory_dynamics() output, one figure per population, designed to make the dynamic states legible at a glance. Each point is a trajectory, its area the community size, its colour the state; the regions are shaded and named after the state they classify, with the thresholds drawn as reference lines.

Usage

plot_trajectory_dynamics(
  dyn,
  target = c("finals", "intermediary"),
  thresholds = NULL,
  labels_text = NULL,
  label_id = FALSE,
  size_range = c(2, 14),
  label_size = 3.5,
  axis_text_size = NULL,
  palette = NULL,
  show_thresholds = TRUE,
  show_quadrants = TRUE,
  xlim = NULL,
  ylim = NULL,
  legend_position = "right",
  title = NULL
)

Arguments

Details

• "finals" – x = novelty, y = growth_rate; emergence is the novel-and-growing region, dormancy the loss-of-momentum band, maturity the saturated middle.

• "intermediary" – x = dest_entropy, y = dormant_share; convergence is the low-entropy (single destination) side, divergence the high-entropy side, and dormancy the high-dropout band (rare, so this band is usually sparse). Extinct (group NA) lineages have no coordinates and are reported in the caption rather than drawn.

Value

A ggplot object.

See Also

sniff_trajectory_dynamics(), fixed_state_thresholds(), plot_trajectory_confluence()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
flow <- sniff_trajectory_braid(docs_per_group)
dyn  <- sniff_trajectory_dynamics(flow)
descr <- data.frame(id = "c1g1", text = "Anaerobic digestion")

plot_trajectory_dynamics(dyn, target = "finals", labels_text = descr)
plot_trajectory_dynamics(dyn, target = "intermediary")

## End(Not run)

Description

The plotly twin of plot_trajectory_dynamics(). The same quadrant map – shaded and named state regions, classification thresholds as reference lines, points sized by community and coloured by state – rendered as an HTML widget. Hovering a point reveals the full indicator panel (growth, novelty, recruitment, inflow, destination entropy, dormant share, and any CCT / hub-role columns), and the state legend is clickable to isolate one state at a time.

Usage

plot_trajectory_dynamics_interactive(
  dyn,
  target = c("finals", "intermediary"),
  thresholds = NULL,
  labels_text = NULL,
  label_id = FALSE,
  marker_range = c(6, 42),
  show_labels = FALSE,
  label_size = 11,
  palette = NULL,
  show_thresholds = TRUE,
  show_quadrants = TRUE,
  xlim = NULL,
  ylim = NULL,
  title = NULL
)

Arguments

Value

A plotly htmlwidget.

See Also

plot_trajectory_dynamics(), sniff_trajectory_dynamics(), fixed_state_thresholds()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
flow <- sniff_trajectory_braid(docs_per_group)
dyn  <- sniff_trajectory_dynamics(flow)
plot_trajectory_dynamics_interactive(dyn, target = "finals", labels_text = descr)

## End(Not run)

Description

Draws the target trajectory as a central spine and each feeder as a parallel timeline that grows along its length (see feeder_curve) and merges into the spine at its handoff year. The spine is a cumulative river: it widens smoothly as each drawn feeder joins, so by the final year its width reflects the total papers absorbed. Spine and feeder widths share one strictly proportional scale (width 0 at zero papers), so their thickness is directly comparable. It generalises plot_trajectory_dispersion() (one source into one absorber) to many feeders converging on one trajectory, answering visually "which trajectories formed this one?".

Usage

plot_trajectory_formation(
  formation,
  feeder_curve = c("inflow", "size"),
  max_feeders = 8,
  title = NULL,
  label_size = 4.5,
  year_range = NULL,
  axis_text_size = NULL,
  palette = NULL
)

Arguments

Value

A ggplot object.

See Also

sniff_trajectory_formation(), plot_trajectory_lines_2d(), plot_trajectory_dispersion()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_lines_2d(), plot_trajectory_lines_3d()

Examples

## Not run: 
flow <- sniff_trajectory_braid(groups_lineage)
f <- sniff_trajectory_formation(flow, target = "tr::c1g3")
plot_trajectory_formation(f)

## End(Not run)

Description

The line counterpart of plot_trajectory_confluence() over the global flow DAG. Every global trajectory is drawn as a variable-width line through the year-aware Sugiyama layout: the central finals tr::cNgN and the intermediate trN that feed them, each line widening with the documents accumulated along its path. A bottom legend reports, for every intermediate, how many papers of its terminal cohort reached each final group – a single trN can feed more than one final (its terminal cohort splits across groups), which the legend makes explicit.

Usage

plot_trajectory_lines_2d(
  flow,
  target = "all",
  conf = NULL,
  min_n = 5,
  min_prop = 0.05,
  min_total_size = 0,
  min_duration_years = 0,
  min_target_n = 0,
  width_range = c(0.8, 6),
  use_raw_papers = FALSE,
  label_size = 4,
  dest_min_prop = 0.05,
  lowlight_alpha = 0.18,
  lowlight_color = "#9AA5B1",
  legend_ncol = NULL,
  legend_text_size = NULL,
  axis_text_size = NULL,
  year_range = NULL,
  palette = NULL,
  title = NULL
)

Arguments

Details

• x = publication year (Sugiyama layers); the y-axis has no intrinsic meaning (a branching position).

• Line width grows with cumulative tracked documents along the trajectory.

• A single-year feeder has no edge to draw as a line and is dropped (it would otherwise show a label/legend with no visible line); a single-year central (the selected final, e.g. a final-year-only community like tr::c1g17) is kept and drawn as a point.

• Colour is per trajectory. With a single targeted final the legend is summarised to ⁠trN: p% (n)⁠ – n of trN's papers landed in that final, which is ⁠p%⁠ of trN's size (the feeders' counts overlap, so they do not sum to the final's total). With target = "all" it shows the full split ⁠trN -> c1g1:n, c1g2:n⁠. A central is tr::cNgN (final, n), where n is the documents that remained in its final-year community (the last point of its size curve), not the cumulative documents the trajectory ever held.

Value

A ggplot object.

See Also

plot_trajectory_lines_3d(), plot_trajectory_confluence(), sniff_trajectory_braid(), sniff_trajectory_confluence()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_3d()

Examples

## Not run: 
flow <- sniff_trajectory_braid(docs_per_group)
plot_trajectory_lines_2d(flow, min_n = 20)
plot_trajectory_lines_2d(flow, target = "tr::c1g1")

## End(Not run)

Description

The 3D counterpart of plot_trajectory_lines_2d(). Every global trajectory is drawn over the year-aware Sugiyama layout as a growing-thickness line: x = publication year, y = route (the Sugiyama branching coordinate that separates trajectories), and z = cumulative tracked documents along the path. The central finals tr::cNgN and the intermediate trN that feed them share one colour-per-trajectory scheme; the legend reports, for every intermediate, how many papers of its terminal cohort reached each final (a single trN can feed more than one final, which the legend makes explicit). Selection and thresholds are identical to plot_trajectory_lines_2d(); only the rendering adds the document z-axis and interactive hover.

Usage

plot_trajectory_lines_3d(
  flow,
  target = "all",
  conf = NULL,
  min_n = 5,
  min_prop = 0.05,
  min_total_size = 0,
  min_duration_years = 0,
  min_target_n = 0,
  width_range = c(4, 12),
  use_raw_papers = FALSE,
  log_scale = FALSE,
  label_size = 16,
  hover_font_size = 12,
  dest_min_prop = 0.05,
  lowlight_alpha = 0.75,
  lowlight_color = "#9AA5B1",
  lowlight_width = 3,
  show_background = TRUE,
  year_range = NULL,
  palette = NULL,
  title = NULL,
  legend_position = c("bottom", "right", "top", "left", "none"),
  legend_ncol = NULL,
  labels_text = NULL
)

Arguments

Details

• z = cumulative tracked documents along each trajectory (raw or weighted), accumulated node by node; log_scale = TRUE compresses it.

• Line width grows per trajectory with the same cumulative measure, so each line is thinnest at its birth and thickest at its terminal node (the width is rescaled within each trajectory, matching plot_trajectory_lines_2d()).

• A single-year central (e.g. a final-year-only community like tr::c1g17) has no segment to draw and is rendered as a terminal ball; a single-year feeder is dropped (it would show a label with no visible line).

• Colour is per trajectory and the legend carries the feeding split: a central reads tr::cNgN (final, n) (n = documents that remained in its final-year community), an intermediate reads ⁠trN -> c1g1:n, c1g2:n⁠ (its terminal cohort split across finals). In a single-target view it reads ⁠trN: p% (n) -> c1g15:n, c1g1:n, ...⁠ – ⁠p%⁠ and the parenthesised (n) are the share and the document count that reached the target (as in plot_trajectory_lines_2d()); the split then shows the feeder's full destination, so a feeder of c1g1 reveals that more of it may flow elsewhere.

• Hovering a node shows that same feeding-legend text, the trajectory's labels_text description (when supplied), the node's year, and the absolute documents in that cluster-year (quantity_papers, not the running cumulative that sets the height).

Value

A plotly 3D plot object.

See Also

plot_trajectory_lines_2d(), sniff_trajectory_braid(), sniff_trajectory_confluence()

Other visualization: plot_groups_influence_matrix(), plot_groups_influence_network(), plot_groups_lineage_2d(), plot_groups_lineage_3d(), plot_groups_map(), plot_groups_map_animation(), plot_groups_map_interactive(), plot_groups_per_year(), plot_trajectory_confluence(), plot_trajectory_confluence_interactive(), plot_trajectory_confluence_matrix(), plot_trajectory_dag(), plot_trajectory_dag_interactive(), plot_trajectory_dispersion(), plot_trajectory_dynamics(), plot_trajectory_dynamics_interactive(), plot_trajectory_formation(), plot_trajectory_lines_2d()

Examples

## Not run: 
flow <- sniff_trajectory_braid(docs_per_group)
plot_trajectory_lines_3d(flow, min_n = 20)
plot_trajectory_lines_3d(flow, target = "tr::c1g1")

## End(Not run)

Description

Parse datasets exported from OpenAlex in two ways: (1) a CSV file exported in the browser, or (2) a data frame obtained via the {openalexR} API helpers. The function standardizes fields to common bibliographic tags (e.g., AU, SO, CR, PY, DI) and returns a tidy tibble.

Usage

read_openalex(file, format = "csv")

Arguments

Details

CSV mode (format = "csv"):

• If file is a URL, it is downloaded to a temporary file before parsing (a progress message is printed).

• Selected fields are mapped to standardized tags: id_short (short OpenAlex ID), SR (= id_short), PY (= publication_year), TI (= title), DI (= doi), DT (= type), DE (= keywords.display_name), AB (= abstract), AU (= authorships.author.display_name), SO (= locations.source.display_name), C1 (= authorships.countries), TC (= cited_by_count), SC (= primary_topic.field.display_name), CR (= referenced_works, with the ⁠https://openalex.org/⁠ prefix stripped), and DB = "openalex_csv".

• PY is coerced to numeric; a helper column DI2 (uppercase, punctuation-stripped variant of DI) is added; columns with all-caps tags are placed first and DI2 is relocated after DI.

API mode (format = "api"):

• file must be a data frame containing at least column id; typically this is returned by openalexR::oa_request() + openalexR::oa2df() or similar.

• Records are filtered to type %in% c("article","review") and deduplicated by id.

• The function derives:

  • id_short (= id without the ⁠https://openalex.org/⁠ prefix) and SR (= id_short);

  • CR: concatenated short IDs from referenced_works (semicolon-separated);

  • DE: concatenated keyword names (lower case) from keywords;

  • AU: concatenated author names (upper case) from authorships;

  • plus core fields PY (= publication_year), TC (= cited_by_count), TI (= title), AB (= abstract), DI (= doi), and DB = "openalex_api".

• The result keeps one row per id and may include original columns from the input (via a right join), after constructing the standardized fields above.

Value

A tibble with standardized bibliographic columns. Typical output includes: id_short, AU, DI, CR, SO, DT, DE, AB, C1, TC, SC, SR, PY, and DB (source flag: "openalex_csv" or "openalex_api"). See Details.

Supported inputs

• format = "csv" — a local path or an HTTP(S) URL to an OpenAlex CSV export.

• format = "api" — a data frame produced by {openalexR} for the works entity (with the usual OpenAlex columns, including list-columns such as keywords, authorships, and referenced_works).

See Also

OpenAlex R client: oa_request, oa2df. Importers for Web of Science: read_wos.

Examples

## Not run: 
## CSV export (local path)
x <- read_openalex("openalex-works.csv", format = "csv")

## Using the API with openalexR
library(openalexR)
url_api <- "https://api.openalex.org/works?page=1&filter=primary_location.source.id:s121026525"
df_api  <- openalexR::oa_request(query_url = url_api) |>
  openalexR::oa2df(entity = "works")
y <- read_openalex(df_api, format = "api")

## End(Not run)

Description

Parse Web of Science (WoS) export files in multiple formats and return a tidy table. The function automatically dispatches to a specialized parser based on the format argument and can also download from a URL if file points to an ⁠http://⁠ or ⁠https://⁠ resource.

Usage

read_wos(file, format = "bib", normalized_names = TRUE)

Arguments

Details

• file may be a single path/URL or a vector of paths; multiple files will be combined row-wise when applicable.

• When file is a URL, the file is downloaded to a temporary path before parsing (a progress message is printed).

• If normalized_names = TRUE, selected WoS tags are mapped to standardized names (e.g., AU -> author, TI -> title, PY -> year, DI -> doi, DE -> keywords, SR -> unique_id, etc.; the exact mapping depends on the format). Otherwise, original field tags are preserved.

• The output includes:

  • DI2: an uppercase, punctuation-stripped variant of DI (if present),

  • PY: coerced to numeric (when present),

  • DB: a provenance flag indicating the source/format and whether names were normalized.

• Columns with ALL-CAPS tags (e.g., AU, TI, PY) are placed first, followed by other columns, and DI2 is relocated just after DI.

Value

A tibble with the parsed WoS records. See Details for notes on added/coerced columns (DI2, PY, DB) and column ordering.

Supported formats

• "bib" — BibTeX export

• "ris" — RIS export

• "txt-plain-text" — Plain-text export

• "txt-tab-delimited" — Tab-delimited export

See Also

Internal parsers used by this function: read_wos_bib, read_wos_ris, read_wos_plain, read_wos_tab.

Examples

bib_file <- system.file("extdata", "sample_wos.bib", package = "birddog")
M <- read_wos(bib_file, format = "bib", normalized_names = TRUE)
head(M)

## Not run: 
# load data from a URL
M <- read_wos("https://example.com/savedrecs.bib", format = "bib")

## End(Not run)

Description

Calculates the Citation Cycle Time (CCT) to measure the pace of scientific or technological progress in a publication network. Based on Kayal (1999), the indicator measures the median age of cited publications, where lower values indicate faster knowledge replacement cycles.

Usage

sniff_cct(
  network,
  scope = "groups",
  start_year = NULL,
  end_year = NULL,
  tracked_cr_py = NULL,
  batch_size = 50,
  min_papers_per_year = 3,
  rolling_window = NULL,
  normalize = "none",
  dispersion = FALSE,
  citation_scope = "global"
)

Arguments

Details

The Citation Cycle Time (CCT) is calculated following Kayal (1999):

1. Extract citation IDs from the network's CR column

2. Fetch publication years for cited works from OpenAlex API using get_openalex_fields()

3. For each publication, calculate the age of each cited reference (PY - CR_PY)

4. Calculate the median citation age per publication

5. For each year, calculate the median of per-publication medians across all publications in that year (annual mode)

Lower CCT values indicate that publications are citing more recent work, suggesting a faster pace of knowledge replacement. A sudden drop in CCT within a group signals potential scientific emergence.

The function automatically handles:

• Splitting semicolon-separated citation IDs

• Batch processing of OpenAlex API requests

• Filtering invalid citations (where cited work was published after citing work)

• Skipping years with too few papers (min_papers_per_year)

• Optional rolling window smoothing for noisy time series

• Creating temporal plots for each group

Value

A list with the following components:

References

Kayal AA, Waters RC. An empirical evaluation of the technology cycle time indicator as a measure of the pace of technological progress in superconductor technology. IEEE Transactions on Engineering Management. 1999;46(2):127-31. doi:10.1109/17.759138

See Also

sniff_groups(), get_openalex_fields(), indexes_plots()

Examples

## Not run: 
# Group analysis
results <- sniff_cct(network_groups, scope = "groups")

# Network analysis
results_network <- sniff_cct(complete_network, scope = "network")

# With rolling window smoothing
results_smooth <- sniff_cct(
  network_groups,
  scope = "groups",
  rolling_window = 3
)

# Domain-normalized CCT (values around 1; <1 = short-cycle relative to domain)
results_norm <- sniff_cct(
  network_groups,
  scope = "groups",
  normalize = "domain"
)

# With dispersion (adds p25 and p75 columns to detect bimodal distributions)
results_disp <- sniff_cct(
  network_groups,
  scope = "groups",
  dispersion = TRUE
)

# Local citations only (intra-corpus references)
results_local <- sniff_cct(
  network_groups,
  scope = "groups",
  citation_scope = "local"
)

# Accessing results
cct_data <- results$data
plots <- results$plots
plots$c1g1  # View plot for specific group

# Reuse citation data to avoid repeated API calls
saved_citations <- results$tracked_cr_py
results2 <- sniff_cct(
  network_groups,
  tracked_cr_py = saved_citations
)

## End(Not run)

Description

Detects connected components in a citation network and computes summary statistics for each component. Returns both the component information and an updated network with component labels.

Usage

sniff_components(net)

Arguments

Value

A list with two elements:

components

A tibble with component statistics containing:

• component: Component identifier (e.g., "c1")

• quantity_publications: Number of publications in component

• average_age: Mean publication year of component

network

The input network with added component labels

See Also

Other groups (stock): sniff_groups(), sniff_groups_attributes(), sniff_groups_cumulative(), sniff_groups_cumulative_citations(), sniff_groups_hubs(), sniff_groups_influence(), sniff_groups_lineage(), sniff_network()

Examples

## Not run: 
# Create a network first
data <- read_wos("savedrecs.txt")
net <- sniff_network(data)

# Analyze components
result <- sniff_components(net)

# Access component information
result$components

# Get network with component labels
component_net <- result$network

## End(Not run)

Description

Computes the normalized Shannon entropy of keyword distributions from scientific publications over a specified time range. Entropy measures the diversity and evenness of keyword usage within research groups or the entire network.

Usage

sniff_entropy(
  network,
  scope = "groups",
  start_year = NULL,
  end_year = NULL,
  mode = "rolling",
  window_size = 5
)

Arguments

Details

The function calculates the normalized Shannon entropy (Pielou's evenness index) based on Shannon's information theory (Shannon, 1948). The temporal scope of keyword data depends on the mode parameter:

• annual: entropy from keywords published in each specific year. Values tend to be high (near 1) since within-year distributions are typically even.

• cumulative: entropy from all keywords published up to each year. Shows long-term trends in thematic concentration as the keyword pool grows.

• rolling: entropy from a sliding window of recent years. Balances sensitivity to recent shifts with enough data for stable estimates.

The normalized entropy (Pielou's J') is calculated as:

$J' = \frac{H}{H_{max}} = \frac{-\sum_{i=1}^{n} p_i \log_2 p_i}{\log_2 n}$

where $p_i$ is the relative frequency of keyword $i$, $n$ is the number of unique keywords, and $H_{max} = \log_2 n$ is the maximum possible entropy for $n$ categories.

Entropy values range from 0 to 1, where:

• 0 indicates minimal diversity (one dominant keyword)

• 1 indicates maximal diversity (all keywords equally frequent)

A sudden increase in entropy may signal the emergence of new research topics, while a decrease suggests thematic convergence.

Value

A list with three components:

References

Shannon, C. E. (1948). A mathematical theory of communication. Bell System Technical Journal, 27(3), 379-423. doi:10.1002/j.1538-7305.1948.tb01338.x

Pielou, E. C. (1966). The measurement of diversity in different types of biological collections. Journal of Theoretical Biology, 13, 131-144.

See Also

sniff_groups, sniff_network, indexes_plots

Examples

## Not run: 
# Rolling window (default: 5 years)
entropy_results <- sniff_entropy(groups_data, scope = "groups")

# Cumulative mode
entropy_results <- sniff_entropy(groups_data, mode = "cumulative")

# Annual mode
entropy_results <- sniff_entropy(groups_data, mode = "annual")

# Rolling window with custom size
entropy_results <- sniff_entropy(groups_data, mode = "rolling", window_size = 3)

# Access results
entropy_data <- entropy_results$data
entropy_plots <- entropy_results$plots

## End(Not run)

Description

This function identifies and analyzes groups (communities) within scientific networks created from articles and patents data. It can apply different clustering algorithms to detect technological trajectories and emerging scientific fields.

Usage

sniff_groups(
  comps,
  min_group_size = 10,
  keep_component = c("c1"),
  cluster_component = c("c1"),
  algorithm = "fast_greedy",
  seed = 888L
)

Arguments

Details

The function first validates the input network, then applies the specified clustering algorithm to detect communities within the network. It calculates statistics for each detected group and returns the results along with the augmented network. The function can handle multiple network components simultaneously, applying clustering only to specified components.

Value

A list with three elements:

• aggregate: A data frame with group statistics including group name, number of papers, and average publication year

• network: The input network with added group attributes

• pubs_by_year: Publication counts by group and year

See Also

sniff_components() for creating the input network components

Other groups (stock): sniff_components(), sniff_groups_attributes(), sniff_groups_cumulative(), sniff_groups_cumulative_citations(), sniff_groups_hubs(), sniff_groups_influence(), sniff_groups_lineage(), sniff_network()

Examples

## Not run: 
# Assuming 'comps' is output from sniff_components()
groups <- sniff_groups(comps,
  min_group_size = 15,
  algorithm = "leiden",
  seed = 888L
)

# Access group statistics
groups$aggregate
groups$network
groups$pubs_by_year

## End(Not run)

Description

This function analyzes publication growth rates and other attributes for research groups identified in scientific networks. It calculates growth rates using exponential models, creates horizon plots for visualization, and generates summary tables.

Usage

sniff_groups_attributes(
  groups,
  growth_rate_period = 2010:2022,
  horizon_plot = TRUE,
  show_results = TRUE,
  assign_result = NULL
)

Arguments

Details

The function performs the following steps:

1. Calculates growth rates using exponential models for each group

2. Processes publication age and doubling time metrics

3. Optionally creates horizon plots for each group's publication trend

4. Generates a comprehensive summary table

Value

A list with two components:

• attributes_table: A gt table showing group attributes including growth rates

• regression: A list of model summaries for each group's growth rate calculation

See Also

Other groups (stock): sniff_components(), sniff_groups(), sniff_groups_cumulative(), sniff_groups_cumulative_citations(), sniff_groups_hubs(), sniff_groups_influence(), sniff_groups_lineage(), sniff_network()

Examples

## Not run: 
# Assuming groups is output from sniff_groups()
groups_attributes <- sniff_groups_attributes(groups,
  growth_rate_period = 2010:2022,
  horizon_plot = TRUE
)

# View the results table
print(groups_attributes$attributes_table)

# Access model summaries
groups_attributes$regression

## End(Not run)

Description

Performs cumulative community detection on a network over specified time spans, returning group statistics and keyword analysis for each time period.

Usage

sniff_groups_cumulative(
  comps,
  time_span = NULL,
  min_group_size = 10,
  keep_component = c("c1"),
  cluster_component = c("c1"),
  top_n_keywords = 10,
  algorithm = "fast_greedy",
  seed = 888L
)

Arguments

Value

A named list (by year) where each element contains:

groups

A tibble with group statistics and top keywords

documents

A tibble mapping documents to groups

network

The cumulative network up to that year

See Also

Other groups (stock): sniff_components(), sniff_groups(), sniff_groups_attributes(), sniff_groups_cumulative_citations(), sniff_groups_hubs(), sniff_groups_influence(), sniff_groups_lineage(), sniff_network()

Examples

## Not run: 
# Typical pipeline:
data <- read_wos("savedrecs.txt")
net <- sniff_network(data)
comps <- sniff_components(net)

# Cumulative analysis
groups_cumulative <- sniff_groups_cumulative(
  comps,
  time_span = 2010:2020,
  keep_component = c("c1", "c2"),
  cluster_component = c("c1"),
  algorithm = "leiden",
  seed = 888L
)

# Access results for 2015
groups_cumulative[["network_until_2015"]]$groups

## End(Not run)

Description

This function calculates cumulative citations for papers within research groups, tracking how citations accumulate over time for highly cited papers.

Usage

sniff_groups_cumulative_citations(groups, min_citations = 5)

Arguments

Details

For each research group, the function:

• Identifies papers with citations above the threshold

• Tracks citations to these papers year by year

• Calculates cumulative citation patterns

• Computes various growth metrics for citation analysis

Works with both Web of Science (WOS) and OpenAlex data formats.

Value

A named list (by research group) where each element contains a tibble with:

• group: Research group identifier

• SR: Paper identifier

• TC: Total citations

• PY: Publication year

• Ki: Total network citations

• citations_by_year: A tibble with annual citation counts (PY: year, citations: count)

• growth_power: Growth power score (0-100)

• growth_consistency: Percentage of years with citations

• peak_momentum: Highest 3-year rolling average citation count

• early_impact: Citations in first 5 years

• recent_momentum: Citations in last 3 years

• acceleration_factor: Ratio of late to early citations

See Also

Other groups (stock): sniff_components(), sniff_groups(), sniff_groups_attributes(), sniff_groups_cumulative(), sniff_groups_hubs(), sniff_groups_influence(), sniff_groups_lineage(), sniff_network()

Examples

## Not run: 
# Assuming groups is output from sniff_groups()
# Calculate cumulative citations
groups_cumulative_citations <- sniff_groups_cumulative_citations(groups, min_citations = 5)
# View results for first group
head(groups_cumulative_citations[[1]])

## End(Not run)

Description

This function analyzes citation networks to identify hub papers within research groups based on their citation patterns. It calculates several metrics (Zi, Pi) to classify papers into different hub categories.

Usage

sniff_groups_hubs(groups, min_citations = 1)

Arguments

Details

The function classifies papers into hub categories based on:

• R5: Knowledge hubs (Zi >= 2.5 and Pi <= 0.3)

• R6: Bridging hubs (Zi >= 2.5 and 0.3 < Pi <= 0.75)

• R7: Boundary-spanning hubs (Zi >= 2.5 and Pi > 0.75)

Value

A tibble containing:

• group: Research group identifier

• SR: Paper identifier

• TC: Total citations

• Ki: Total citations from all groups

• ki: Citations from within the same group

• Zi: Standardized within-group citation score

• Pi: Citation diversity index

• zone: Hub classification ("noHub", "R5", "R6", "R7")

See Also

Other groups (stock): sniff_components(), sniff_groups(), sniff_groups_attributes(), sniff_groups_cumulative(), sniff_groups_cumulative_citations(), sniff_groups_influence(), sniff_groups_lineage(), sniff_network()

Examples

## Not run: 

# Assuming 'groups' is output from sniff_groups()

# Identify hub papers
hubs <- sniff_groups_hubs(groups, min_citations = 5)

# View results
head(hubs)

## End(Not run)

Description

Experimental. Lifts the internal citations of a sniff_groups() network to the group level and measures how much each group's output flows into every other group's. Influence is directional: if group $B$'s papers cite group $A$'s papers, knowledge flows $A \to B$. The function returns the cross-citation matrix, four size-corrected indices per ordered pair, the net flow between pairs, and a source / broker / sink role per group.

Usage

sniff_groups_influence(groups, self = TRUE, null_reps = 0, seed = NULL)

is_influence(x)

## S3 method for class 'birddog_influence'
print(x, ...)

Arguments

Details

Writing $C_{ij}$ for the number of citations from group $i$ to group $j$ (rows cite columns), out-strength $o_i=\sum_k C_{ik}$, in-strength $\iota_j=\sum_k C_{kj}$, and total $m=\sum_{ij}C_{ij}$, each ordered pair carries four normalizations:

• debt $C_{ij}/o_i$ – the share of $i$'s citations owed to $j$ (how much $i$ leans on $j$);

• audience $C_{ij}/\iota_j$ – the share of $j$'s citations coming from $i$;

• salton $C_{ij}/\sqrt{o_i\,\iota_j}$ – a size-free channel strength, symmetric in the pair;

• surprise $C_{ij}/(o_i\,\iota_j/m)$ – the flow against the configuration-model expectation; $>1$ over-represented, $<1$ under-represented.

The net influence $\nu_{ij}=C_{ij}-C_{ji}$ removes reciprocal flow, and the group balance $\beta_i=\iota_i-o_i$ (received minus made) classifies each group as a source ($\beta>0$, foundational), a sink ($\beta<0$, frontier consumer), or a broker ($\beta\approx 0$). The balances of a closed system sum to zero. The diagonal $C_{ii}$ is intra-group cohesion; self = FALSE drops it before any normalization (the balances and net are unchanged, since the diagonal cancels).

Value

An object of class birddog_influence, a list with:

• matrix: the $G \times G$ cross-citation matrix $C$ (rows cite columns), groups in mixed_sort() order.

• flow: a tibble, one row per observed ordered pair, sorted by descending surprise – influencer (cited group), recipient (citing group), citations, debt, audience, salton, surprise (and p_value when null_reps > 0).

• groups: per-group received, made, balance, role (source / broker / sink), sorted by descending balance.

• net: the net-influence edge list – from (source), to (recipient), net ($\nu_{ij} > 0$).

• params: the call settings.

See Also

sniff_groups(), sniff_groups_hubs(), plot_groups_influence_matrix(), plot_groups_influence_network()

Other groups (stock): sniff_components(), sniff_groups(), sniff_groups_attributes(), sniff_groups_cumulative(), sniff_groups_cumulative_citations(), sniff_groups_hubs(), sniff_groups_lineage(), sniff_network()

Examples

## Not run: 
groups <- sniff_groups(net)
infl <- sniff_groups_influence(groups)
infl
infl$groups          # source / broker / sink per group
infl$net             # who, on balance, leads whom
plot_groups_influence_matrix(infl)

## End(Not run)

Description

This function processes nodes grouped in a network (typically by community detection), and extracts the most frequent and the most distinctive keywords (using TF-IDF) from a descriptor field such as keywords or subject terms.

Usage

sniff_groups_keywords(net_groups, n_terms = 15, min_freq = 1, sep = ";")

Arguments

Value

A tibble with one row per group, containing two columns:

• term_freq: the most frequent terms (with raw frequency).

• term_tfidf: the most distinctive terms (with TF-IDF scores).

Examples

## Not run: 
# Assuming 'groups' is output from sniff_groups()
groups_keywords <- sniff_groups_keywords(groups)

## End(Not run)

Description

This function analyzes the evolution of document groups over time to detect technological trajectories and scientific emergence patterns. It computes similarity measures between groups across time periods and tracks their attributes.

Usage

sniff_groups_lineage(
  groups_cumulative,
  min_group_size = 10,
  top_n_keywords = 3
)

Arguments

Details

Prepares lineage data (docs_per_group, groups_similarity, groups_attributes); detects no trajectories – see sniff_trajectory_braid().

Value

A list with three components:

• groups_attributes: A list of data frames containing attributes for each tracked group

• groups_similarity: A list of data frames containing Jaccard similarity measures between groups across time periods

• docs_per_group: A data frame containing document IDs for all groups across time periods

See Also

Other groups (stock): sniff_components(), sniff_groups(), sniff_groups_attributes(), sniff_groups_cumulative(), sniff_groups_cumulative_citations(), sniff_groups_hubs(), sniff_groups_influence(), sniff_network()

Examples

## Not run: 
# Assuming you have cumulative group data:
trajectories <- sniff_groups_lineage(groups_cumulative, min_group_size = 15)

## End(Not run)

Description

Processes text data for structural topic modeling and performs topic number selection analysis, returning both the processed data and diagnostic plots.

Usage

sniff_groups_stm_prepare(
  groups,
  group_to_stm = "g01",
  search_topics = c(5:40, 45, 50, 55, 60),
  seed = 1234,
  cores = 1
)

Arguments

Value

A list containing:

• result: The searchK results object

• plots: A list containing two ggplot objects (p1: metrics by K, p2: exclusivity vs coherence)

• df_prep: Output from stm::textProcessor

• df_doc: Output from stm::prepDocuments

• df: Original filtered data

Examples

## Not run: 
output <- sniff_groups_stm_prepare(network_data)
output$plots$p1 # View first plot
output$result # Access search results

## End(Not run)

Description

Performs structural topic modeling on prepared text data and returns topic proportions and top documents for each topic.

Usage

sniff_groups_stm_run(groups_stm_prepare, k_topics = 12, n_top_documents = 50)

Arguments

Details

This function:

• Fits an STM model with specified number of topics

• Identifies top terms for each topic

• Calculates topic proportions

• Identifies top documents for each topic

Value

A list containing:

• topic_proportion2: Data frame with topic proportions and top terms

• tab_top_documents: Data frame of top documents for each topic

Examples

## Not run: 
# Prepare data first
stm_data <- sniff_groups_stm_prepare(network_data)

# Run topic modeling
stm_results <- sniff_groups_stm_run(stm_data, k_topics = 15)

# Access results
stm_results$topic_proportion2  # Topic proportions and terms
stm_results$tab_top_documents  # Top documents per topic

## End(Not run)

Description

Identifies and extracts key terms from titles and abstracts of publications within different research groups using natural language processing techniques, and computes term statistics including TF-IDF scores.

Usage

sniff_groups_terms(
  net_groups,
  algorithm = "rake",
  phrase_pattern = "(A|N)*N(P+D*(A|N)*N)*",
  model_dir = tempdir(),
  n_cores = 1,
  show_progress = TRUE,
  n_terms = 15,
  min_freq = 2,
  digits = 4
)

Arguments

Details

This function performs the following steps:

1. Validates input structure and parameters

2. Loads the UDPipe language model from the specified directory

3. Processes text data (titles and abstracts) for each group

4. Applies the selected term extraction algorithm (RAKE, PMI, or phrase patterns)

5. Computes term frequencies and TF-IDF scores

6. Returns ranked terms for each research group with comprehensive statistics

The function uses UDPipe for tokenization, lemmatization and POS tagging before term extraction. For phrase extraction, the default pattern finds noun phrases.

Value

A list with two components:

• terms_by_group: A named list (by group) of data frames containing extracted terms with statistics

• terms_table: A summary tibble with top terms by frequency and TF-IDF for each group

Examples

## Not run: 
# Assuming groups is output from sniff_groups()
terms <- sniff_groups_terms(groups, algorithm = "rake")

# View terms for first group
head(terms$terms_by_group[[1]])

# View summary table
print(terms$terms_table)

# Customized extraction with custom model directory
net_groups_terms <- sniff_groups_terms(net_groups,
  algorithm = "phrase",
  model_dir = tempdir(),
  n_terms = 10,
  min_freq = 3,
  n_cores = 4
)

## End(Not run)

Description

This function identifies and visualizes key citation routes within scientific networks by analyzing the most significant citation paths between publications. The algorithm implements the key-route search from the integrated main path analysis approach described in Liu & Lu (2012).

Usage

sniff_key_route(
  network,
  scope = "network",
  n_routes = 1,
  compact_gaps = FALSE,
  direction = "vertical"
)

Arguments

Details

The function implements the key-route search from Liu & Lu (2012):

1. Computes Search Path Count (SPC) for each citation link using an efficient O(V+E) algorithm based on topological sort. SPC measures how many source-to-sink paths traverse each link.

2. Selects the key-route: the link with the highest SPC value.

3. Searches forward from the end node of the key-route, greedily following the outgoing link with the highest SPC, until a sink is reached.

4. Searches backward from the start node of the key-route, greedily following the incoming link with the highest SPC, until a source is reached.

When n_routes > 1, the procedure is repeated: each iteration selects the edge with the next-highest SPC as a new starting point and extends it forward and backward. Routes can share nodes and edges, producing a divergence-convergence-divergence structure that reveals how knowledge flows through multiple sub-streams.

The SPC is computed as forward[u] * backward[v] for each edge (u, v), where forward[u] counts paths from any source to u and backward[v] counts paths from v to any sink (Batagelj, 2003). This guarantees the most significant link is always included in the key-route path.

Value

A list containing for each group:

• plot - A ggplot2 object visualizing the key citation route(s)

• data - A tibble with publication details (name, TI, AU, PY) of nodes in the key route(s)

References

Liu JS, Lu LYY. An integrated approach for main path analysis: Development of the Hirsch index as an example. Journal of the American Society for Information Science and Technology. 2012;63(3):528-542. doi:10.1002/asi.21692

Batagelj V. Efficient algorithms for citation network analysis. University of Ljubljana, Institute of Mathematics, Physics and Mechanics, Department of Theoretical Computer Science, Preprint Series. 2003;41:897.

Examples

## Not run: 
# Single key-route (default)
result <- sniff_key_route(my_network, scope = "network")

# Multiple key-routes for richer structure
result <- sniff_key_route(my_network, scope = "network", n_routes = 5)

# Group-wise analysis
grouped_network <- sniff_groups(data)
result <- sniff_key_route(grouped_network, scope = "groups", n_routes = 3)

# Access results for a specific group
result$group_name$plot
result$group_name$data

## End(Not run)

Description

Constructs different types of citation networks from bibliographic data imported from Web of Science or OpenAlex using ⁠birddog's⁠ reading functions.

Usage

sniff_network(dataframe, type = "direct citation", external_references = FALSE)