Title: Tournament Generator
Version: 0.1.1
Description: Create and manage tournament brackets for various competition formats including single elimination, double elimination, round robin, Swiss system, and group-stage-to-knockout tournaments. Provides tools for seeding, scheduling, recording results, and tracking standings.
URL: https://github.com/bbtheo/bracketeer, https://bbtheo.github.io/bracketeer/
BugReports: https://github.com/bbtheo/bracketeer/issues
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.3
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown
VignetteBuilder: knitr
Config/testthat/edition: 3
Config/Needs/website: pkgdown
NeedsCompilation: no
Packaged: 2026-02-21 10:44:47 UTC; theo
Author: Theo Blauberg ORCID iD [aut, cre, cph]
Maintainer: Theo Blauberg <theo.blauberg@outlook.com>
Depends: R (≥ 4.1.0)
Repository: CRAN
Date/Publication: 2026-02-25 19:20:07 UTC

bracketeer: Tournament Generator

Description

logo

Create and manage tournament brackets for various competition formats including single elimination, double elimination, round robin, Swiss system, and group-stage-to-knockout tournaments. Provides tools for seeding, scheduling, recording results, and tracking standings.

Author(s)

Maintainer: Theo Blauberg theo.blauberg@outlook.com (ORCID) [copyright holder]

See Also

Useful links:

Add a stage to a tournament specification

Description

Add a stage to a tournament specification

Usage

add_stage(spec, stage_id, stage)

Arguments

spec

A tournament_spec object.

stage_id

Unique stage identifier.

stage

Stage definition object.

Value

Updated tournament_spec.

Add a transition between stages

Description

Add a transition between stages

Usage

add_transition(
  spec,
  from,
  to,
  rule = NULL,
  seeding = "by_source_rank",
  take = NULL,
  priority = 1L,
  consume = TRUE,
  allow_overlap = FALSE,
  transition_id = NULL
)

Arguments

spec

A tournament_spec object.

from

Source stage ID, or from_previous().

to

Destination stage ID.

rule

Transition rule object (optional for MVP graph wiring).

seeding

Seeding policy label.

take

Selector object for transition participant selection.

priority

Transition resolution priority.

consume

Whether selected participants are consumed.

allow_overlap

Whether overlap is allowed across transitions.

transition_id

Transition ID. If NULL, deterministic auto-ID is used.

Value

Updated tournament_spec.

Advance tournament to next round

Description

Check if current round is complete and update bracket state.

Usage

advance(x, stage = NULL, ...)

## S3 method for class 'bracket'
advance(x, stage = NULL, ...)

## S3 method for class 'double_elim_bracket'
advance(x, stage = NULL, ...)

## S3 method for class 'group_stage_knockout'
advance(x, stage = NULL, ...)

## S3 method for class 'single_elim_bracket'
advance(x, stage = NULL, ...)

## S3 method for class 'swiss_bracket'
advance(x, stage = NULL, ...)

## S3 method for class 'tournament'
advance(x, stage = NULL, ...)

Arguments

x

A bracket object.

stage

Optional stage identifier for tournament methods.

...

Additional method-specific arguments.

Value

Updated bracket object

Advance winner to next match

Description

Advance winner to next match

Usage

advance_winner(bracket, match_id)

## S3 method for class 'bracket'
advance_winner(bracket, match_id)

## S3 method for class 'double_elim_bracket'
advance_winner(bracket, match_id)

## S3 method for class 'single_elim_bracket'
advance_winner(bracket, match_id)

Arguments

bracket

A bracket object

match_id

The ID of the completed match

Value

Updated bracket object

Apply seed ordering to participants

Description

Apply seed ordering to participants

Usage

apply_seed_method(participants_df, seed_method = "standard")

Arguments

participants_df

data.frame from normalize_participants()

seed_method

Character seed method

Value

data.frame reordered with a seed_rank column

Apply tiebreaker ordering

Description

Apply tiebreaker ordering

Usage

apply_tiebreakers(df, matches, tiebreakers, allow_ties = TRUE)

Arguments

df

Standings data frame with participant column

matches

List of matches

tiebreakers

Character vector of tiebreakers

allow_ties

Logical

Value

Ordered data frame with rank column

Assign participants to groups using snake distribution

Description

Assign participants to groups using snake distribution

Usage

assign_groups(participants_df, groups)

Arguments

participants_df

data.frame with participants

groups

Number of groups

Value

data.frame with added group column

Select bottom ranked participants from source standings

Description

Select bottom ranked participants from source standings

Usage

bottom_n(n)

Arguments

n

Positive integer count.

Value

A bracketeer_selector object.

Select bottom ranked participants per group

Description

Select bottom ranked participants per group

Usage

bottom_per_group(n)

Arguments

n

Positive integer count per group.

Value

A bracketeer_selector object.

Create a tournament bracket

Description

Generic constructor for tournament brackets. Dispatches to specific tournament type constructors.

Usage

bracket(participants, type = "single_elim", ...)

Arguments

participants

Character vector of participant names, or a data.frame with a 'name' column and optional 'seed' or 'rating' columns.

type

Tournament type: "single_elim", "double_elim", "round_robin", "swiss", "group_stage_knockout", or "two_leg_knockout"

...

Additional arguments passed to type-specific constructor

Value

A bracket object

Build a live tournament runtime from a specification

Description

Build a live tournament runtime from a specification

Usage

build(x, participants)

Arguments

x

A bracketeer_spec or tournament_spec object.

participants

Character vector of participant names, or a data.frame with a name column.

Value

A tournament runtime object.

Examples

my_spec <- spec() |>
  swiss("open", rounds = 3) |>
  single_elim("playoffs", take = top_n(4))

# Materialize with participants
trn <- build(my_spec, paste("Team", LETTERS[1:8]))

Build a tournament runtime from a tournament specification

Description

Build a tournament runtime from a tournament specification

Usage

build_tournament(spec, participants)

Arguments

spec

A tournament_spec object.

participants

Character vector of participant names, or a data.frame with a name column.

Value

A tournament runtime object.

Calculate number of byes needed

Description

Calculate number of byes needed

Usage

calc_byes(n)

Arguments

n

Number of participants

Value

Number of byes needed to reach next power of 2

Calculate number of rounds for single elimination

Description

Calculate number of rounds for single elimination

Usage

calc_rounds_single_elim(n)

Arguments

n

Number of participants

Value

Number of rounds

Compute tournament rankings

Description

Compute tournament rankings

Usage

compute_tournament_rankings(tournament)

Arguments

tournament

A tournament object.

Value

Data frame with rank and participant, or NULL when unavailable.

Create a match object

Description

Create a match object

Usage

create_match(
  id,
  round,
  position,
  participant1 = NA_character_,
  participant2 = NA_character_,
  next_match = NA_integer_,
  next_slot = NA_integer_,
  bracket_type = "main",
  loser_next_match = NA_integer_,
  loser_next_slot = NA_integer_
)

Arguments

id

Match ID

round

Round number

position

Position within round

participant1

First participant (or NA for TBD)

participant2

Second participant (or NA for TBD)

next_match

ID of match winner advances to (or NA for final)

next_slot

Which slot (1 or 2) in next match

bracket_type

For double elim: "winners", "losers", or "grand_final"

Value

A bracket_match object

Default tiebreakers per format

Description

Default tiebreakers per format

Usage

default_tiebreakers(format)

Arguments

format

Tournament format

Value

Character vector of tiebreakers

Create a double elimination bracket

Description

Double elimination tournament with winners and losers brackets.

Usage

double_elim(participants, ...)

Arguments

participants

Character vector of participant names, or a data.frame with a 'name' column and optional 'seed' column.

...

Additional arguments passed to bracket constructors or tournament stage-verb dispatch methods.

Value

A double_elim_bracket object

Examples

# Double elimination bracket (two losses to be eliminated)
trn <- tournament(paste("Team", LETTERS[1:8])) |>
  double_elim("bracket")

# After Swiss rounds
trn <- tournament(paste("Team", LETTERS[1:16])) |>
  swiss("open", rounds = 4) |>
  double_elim("playoffs", take = top_n(8))

Export tournament matches across materialized stages

Description

Export tournament matches across materialized stages

Usage

export_matches(tournament)

Arguments

tournament

A tournament object.

Value

Data frame with stage-tagged matches and compound match IDs.

Export tournament standings across materialized stages

Description

Export tournament standings across materialized stages

Usage

export_standings(tournament)

Arguments

tournament

A tournament object.

Value

Data frame with stage-tagged standings.

Export tournament routing log entries

Description

Export tournament routing log entries

Usage

export_tournament_log(tournament)

Arguments

tournament

A tournament object.

Value

Data frame with one row per routing log entry.

Select participants using a custom predicate function

Description

Select participants using a custom predicate function

Usage

filter_by(fn)

Arguments

fn

A transition predicate function.

Value

A bracketeer_selector object.

Format tournament type for display

Description

Format tournament type for display

Usage

format_type(type)

Resolve source stage from most recently defined stage order

Description

Resolve source stage from most recently defined stage order

Usage

from_previous()

Value

Sentinel object to be resolved by add_transition().

Generate standard seeding order for bracket

Description

Creates seeding positions so that seed 1 vs seed N is in the final if both win all matches. Uses standard bracket seeding algorithm.

Usage

generate_seed_order(n)

Arguments

n

Number of slots (must be power of 2)

Value

Vector of seed positions

Get matches from a bracket

Description

Get matches from a bracket

Usage

get_matches(bracket, round = NULL, status = "all")

## S3 method for class 'bracket'
get_matches(bracket, round = NULL, status = "all")

## S3 method for class 'group_stage_knockout'
get_matches(bracket, round = NULL, status = "all")

Arguments

bracket

A bracket object

round

Optional round number to filter by

status

Filter by status: "pending", "complete", or "all"

Value

Data frame of matches

Get stage IDs currently ready to advance

Description

Get stage IDs currently ready to advance

Usage

get_ready_stages(tournament)

Arguments

tournament

A tournament object.

Value

Character vector of stage IDs in deterministic order.

Get transition routing log entries

Description

Get transition routing log entries

Usage

get_routing_log(tournament)

Arguments

tournament

A tournament object.

Value

List of routing log entries in append order.

Get tournament standings

Description

Get tournament standings

Usage

get_standings(bracket)

## S3 method for class 'double_elim_bracket'
get_standings(bracket)

## S3 method for class 'group_stage_knockout'
get_standings(bracket)

## S3 method for class 'round_robin_bracket'
get_standings(bracket)

## S3 method for class 'single_elim_bracket'
get_standings(bracket)

## S3 method for class 'swiss_bracket'
get_standings(bracket)

Arguments

bracket

A bracket object

Details

Standings are ordered using bracket-specific tiebreakers where applicable (e.g., round robin and Swiss).

Value

Data frame with standings

Get tournament winner

Description

Get tournament winner

Usage

get_winner(bracket)

## S3 method for class 'bracket'
get_winner(bracket)

## S3 method for class 'double_elim_bracket'
get_winner(bracket)

## S3 method for class 'group_stage_knockout'
get_winner(bracket)

## S3 method for class 'round_robin_bracket'
get_winner(bracket)

## S3 method for class 'single_elim_bracket'
get_winner(bracket)

## S3 method for class 'swiss_bracket'
get_winner(bracket)

## S3 method for class 'tournament'
get_winner(bracket)

Arguments

bracket

A bracket object

Value

Name of winner, or NA if tournament not complete

Create a group stage followed by knockout bracket

Description

Create a group stage followed by knockout bracket

Usage

group_stage_knockout(participants, ...)

Arguments

participants

Character vector of participant names, or a data.frame with a 'name' column and optional 'seed' column.

...

Additional arguments passed to bracket constructors or tournament stage-verb dispatch methods.

Value

A group_stage_knockout object

Compute head-to-head points within a subset

Description

Compute head-to-head points within a subset

Usage

head_to_head_points(matches, participants, allow_ties = TRUE)

Arguments

matches

List of matches

participants

Character vector of participants

allow_ties

Logical

Value

Named numeric vector of points

Check if a match is a bye (one participant is NA)

Description

Check if a match is a bye (one participant is NA)

Usage

is_bye_match(match)

Arguments

match

A bracket_match object

Value

Logical

Check if tournament is complete

Description

Check if tournament is complete

Usage

is_complete(bracket)

## S3 method for class 'bracket'
is_complete(bracket)

## S3 method for class 'double_elim_bracket'
is_complete(bracket)

## S3 method for class 'group_stage_knockout'
is_complete(bracket)

## S3 method for class 'swiss_bracket'
is_complete(bracket)

Arguments

bracket

A bracket object

Value

Logical

Check if n is a power of 2

Description

Check if n is a power of 2

Usage

is_power_of_2(n)

Arguments

n

A positive integer

Value

Logical

Check whether a stage is complete

Description

Check whether a stage is complete

Usage

is_stage_complete(x, ...)

Arguments

x

A stage bracket object or tournament.

...

Additional method-specific arguments.

Value

Logical scalar.

Select losers from a source stage by elimination round

Description

Select losers from a source stage by elimination round

Usage

losers(round = "all", stage = NULL, ordering = "elimination_round")

Arguments

round

One of "all", "latest", or an integer vector of rounds.

stage

Optional stage selector (reserved for future use).

ordering

Ordering mode: "elimination_round", "source_seed", or "as_recorded".

Value

A bracketeer_selector object.

Inspect tournament matches

Description

Inspect tournament matches

Usage

matches(x, stage = NULL, status = "pending")

## S3 method for class 'tournament'
matches(x, stage = NULL, status = "pending")

Arguments

x

A tournament object.

stage

Optional stage identifier.

status

One of "pending", "complete", or "all".

Value

Data frame of matches.

Examples

trn <- tournament(c("A", "B", "C", "D")) |>
  round_robin("groups")

# Get pending matches
matches(trn, "groups")

# Get all matches across stages
matches(trn, status = "all")

Internal generic bracket constructor

Description

Internal generic bracket constructor

Usage

new_bracket(participants, type = "single_elim", ...)

Arguments

participants

Character vector of participant names, or a data.frame with a 'name' column and optional 'seed' or 'rating' columns.

type

Tournament type: "single_elim", "double_elim", "round_robin", "swiss", "group_stage_knockout", or "two_leg_knockout"

...

Additional arguments passed to type-specific constructor

Value

A bracket object.

Internal double-elimination bracket constructor

Description

Internal double-elimination bracket constructor

Usage

new_double_elim_bracket(
  participants,
  seed = TRUE,
  grand_final_reset = TRUE,
  best_of = NULL,
  reseed = FALSE
)

Arguments

participants

Character vector of participant names, or a data.frame with a name column and optional seed column.

seed

Seeding policy forwarded to internal seeding helpers.

grand_final_reset

Whether to schedule a potential reset grand final.

best_of

Optional odd-integer series length specification.

reseed

Whether to reseed winners-bracket participants between rounds.

Value

A double_elim_bracket object.

Internal group-stage-knockout bracket constructor

Description

Internal group-stage-knockout bracket constructor

Usage

new_group_stage_knockout_bracket(
  participants,
  groups = 2,
  advance_per_group = 2,
  seed = TRUE,
  group_home_away = FALSE,
  group_best_of = NULL,
  group_tiebreakers = NULL,
  knockout_type = "single_elim",
  knockout_seed = TRUE,
  third_place = FALSE,
  grand_final_reset = TRUE,
  knockout_best_of = NULL
)

Arguments

participants

Character vector of participant names, or a data.frame with a name column and optional seed column.

groups

Number of groups to create.

advance_per_group

Number of participants advancing from each group.

seed

Seeding policy for initial participant allocation.

group_home_away

Whether group matches are home/away double round robin.

group_best_of

Optional odd-integer series length for group matches.

group_tiebreakers

Optional ordered tiebreaker vector for groups.

knockout_type

Knockout format: "single_elim" or "double_elim".

knockout_seed

Seeding policy for knockout-stage placement.

third_place

Whether to include a third-place match in single elimination.

grand_final_reset

Whether double-elim knockout can trigger a reset final.

knockout_best_of

Optional odd-integer series length for knockout matches.

Value

A group_stage_knockout object.

Internal round-robin bracket constructor

Description

Internal round-robin bracket constructor

Usage

new_round_robin_bracket(
  participants,
  home_away = FALSE,
  n_rounds = NULL,
  best_of = NULL,
  tiebreakers = NULL,
  groups = NULL
)

Arguments

participants

Character vector of participant names, or a data.frame with a name column and optional seed column.

home_away

Whether to schedule home/away mirrored pairings.

n_rounds

Optional positive integer number of round-robin cycles.

best_of

Optional odd-integer series length specification.

tiebreakers

Optional ordered tiebreaker vector.

groups

Optional positive integer number of groups.

Value

A round_robin_bracket object.

Construct a selector object for transition ⁠take =⁠ routing

Description

Construct a selector object for transition ⁠take =⁠ routing

Usage

new_selector(kind, params = list(), evaluator)

Arguments

kind

Selector kind label.

params

Selector parameters list.

evaluator

Function implementing selection logic.

Value

A bracketeer_selector object.

Internal single-elimination bracket constructor

Description

Internal single-elimination bracket constructor

Usage

new_single_elim_bracket(
  participants,
  seed = TRUE,
  third_place = FALSE,
  best_of = NULL,
  reseed = FALSE
)

Arguments

participants

Character vector of participant names, or a data.frame with a name column and optional seed column.

seed

Seeding policy forwarded to internal seeding helpers.

third_place

Whether to include a third-place match.

best_of

Optional odd-integer series length specification.

reseed

Whether to reseed participants between rounds.

Value

A single_elim_bracket object.

Internal swiss bracket constructor

Description

Internal swiss bracket constructor

Usage

new_swiss_bracket(
  participants,
  rounds = NULL,
  seed = TRUE,
  allow_ties = TRUE,
  bye_points = 1,
  best_of = NULL,
  tiebreakers = NULL
)

Arguments

participants

Character vector of participant names, or a data.frame with a name column and optional seed column.

rounds

Optional positive integer number of Swiss rounds.

seed

Seeding policy for initial ordering.

allow_ties

Whether drawn results are allowed.

bye_points

Points awarded for a bye.

best_of

Optional odd-integer series length specification.

tiebreakers

Optional ordered tiebreaker vector.

Value

A swiss_bracket object.

Internal two-leg bracket constructor

Description

Internal two-leg bracket constructor

Usage

new_two_leg_bracket(
  participants,
  seed = TRUE,
  third_place = FALSE,
  away_goals = TRUE,
  reseed = FALSE
)

Arguments

participants

Character vector of participant names, or a data.frame with a name column and optional seed column.

seed

Seeding policy forwarded to internal seeding helpers.

third_place

Whether to include a third-place match.

away_goals

Whether away goals break aggregate-score ties.

reseed

Whether to reseed participants between rounds.

Value

A two_leg_knockout object.

Calculate the next power of 2

Description

Calculate the next power of 2

Usage

next_power_of_2(n)

Arguments

n

A positive integer

Value

The smallest power of 2 >= n

Normalize match scores (supports series)

Description

Normalize match scores (supports series)

Usage

normalize_match_scores(
  score1,
  score2,
  best_of = NULL,
  allow_ties = FALSE,
  participant1 = NA_character_,
  participant2 = NA_character_
)

Arguments

score1

Numeric score or vector of game scores for participant1

score2

Numeric score or vector of game scores for participant2

best_of

Optional best-of value

allow_ties

Logical, whether ties are allowed

Value

List with score1, score2, winner, loser, games

Normalize participants input

Description

Normalize participants input

Usage

normalize_participants(participants)

Arguments

participants

Character vector or data.frame with a 'name' column. Optional 'seed' and 'rating' columns are preserved.

Value

List with names and data (data.frame).

Normalize seed method

Description

Normalize seed method

Usage

normalize_seed_method(seed)

Arguments

seed

Logical or character

Value

Character seed method

Normalize tiebreaker configuration

Description

Normalize tiebreaker configuration

Usage

normalize_tiebreakers(tiebreakers, format)

Arguments

tiebreakers

Character vector or NULL

format

Tournament format

Value

Normalized character vector

Resolve source stage from the immediately preceding stage

Description

Alias for from_previous() used by the rewritten stage-verb API.

Usage

previous_stage()

Value

Sentinel object to be resolved by transition wiring.

Examples

teams <- paste("Team", LETTERS[1:8])

# Implicit: defaults to previous_stage()
trn <- tournament(teams) |>
  swiss("open", rounds = 3) |>
  single_elim("playoffs", take = top_n(4))

# Explicit: useful for branching
trn <- tournament(teams) |>
  round_robin("groups") |>
  single_elim("finals", from = previous_stage(), take = top_n(2))

Print bracketeer objects

Description

Print bracketeer objects

Usage

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

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

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

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

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

Arguments

x

A bracket or match object.

...

Additional arguments (unused).

Value

The object, invisibly.

Process bye matches automatically (round 1 only)

Description

Process bye matches automatically (round 1 only)

Usage

process_byes(bracket, round = 1L, bracket_type = NULL)

Arguments

bracket

A bracket object

round

Round number to process byes for

bracket_type

Optional bracket type filter

Value

Updated bracket object with byes resolved

Select losers from a source stage by elimination round

Description

Returns a transition rule function intended for use with add_transition().

Usage

qualify_losers(round = "all", stage = NULL, ordering = "elimination_round")

Arguments

round

One of "all", "latest", or an integer vector of elimination rounds to include.

stage

Optional stage selector (reserved for future use).

ordering

Ordering mode: "elimination_round", "source_seed", or "as_recorded".

Value

A transition rule function.

Select all entrants remaining in the transition source pool

Description

Returns a transition rule function intended for use with add_transition(). During advance(), this selects all participants still available from the source stage after higher-priority consuming transitions have resolved.

Usage

qualify_remaining()

Value

A transition rule function.

Get tournament rankings

Description

Get tournament rankings

Usage

rankings(tournament)

Arguments

tournament

A tournament object.

Value

Data frame of rankings.

Select entrants remaining in the current transition source pool

Description

Select entrants remaining in the current transition source pool

Usage

remaining()

Value

A bracketeer_selector object.

Fluent tournament result entry helper

Description

Convenience wrapper around set_result() for tournament workflows.

Usage

result(tournament, stage, match, score, overwrite = FALSE, auto_advance = NULL)

Arguments

tournament

A tournament object.

stage

Stage identifier containing the match.

match

Match identifier inside stage.

score

Numeric vector score payload. For a single match, pass c(score1, score2).

overwrite

Logical; forwards to set_result(..., overwrite = ...).

auto_advance

Optional logical override. If NULL, defaults to the tournament's auto_advance setting when present.

Value

Updated tournament object.

Examples

teams <- c("A", "B", "C", "D")
trn <- tournament(teams) |>
  round_robin("groups")

# Enter a single result
trn <- result(trn, "groups", match = 1, score = c(2, 1))

Fluent tournament batch result entry helper

Description

Convenience wrapper for entering multiple match results for one stage.

Usage

results(tournament, stage, df, overwrite = FALSE, auto_advance = NULL)

Arguments

tournament

A tournament object.

stage

Stage identifier containing the matches.

df

Data frame with required columns: match, score1, score2.

overwrite

Logical; forwards to result(..., overwrite = ...).

auto_advance

Optional logical override for the final row. If NULL, defaults to the tournament's auto_advance setting when present.

Value

Updated tournament object.

Examples

teams <- c("A", "B", "C", "D")
trn <- tournament(teams) |>
  round_robin("groups")

m <- matches(trn, "groups")
trn <- results(trn, "groups", data.frame(
  match  = m$match_id,
  score1 = c(2, 1, 3),
  score2 = c(1, 2, 0)
))

Create a round robin tournament

Description

Round robin tournament where each participant plays every other participant.

Usage

round_robin(participants, ...)

Arguments

participants

Character vector of participant names, or a data.frame with a 'name' column and optional 'seed' column.

...

Additional arguments passed to bracket constructors or tournament stage-verb dispatch methods.

Value

A round_robin_bracket object

Examples

# Simple round robin
trn <- tournament(c("A", "B", "C", "D")) |>
  round_robin("groups")

# Multiple groups (World Cup style)
teams <- paste("Team", sprintf("%02d", 1:32))
trn <- tournament(teams) |>
  round_robin("groups", groups = 8)

Get transition routing log

Description

Get transition routing log

Usage

routing_log(tournament)

Arguments

tournament

A tournament object.

Value

Data frame audit trail.

Assign participants to bracket positions with seeding

Description

Assign participants to bracket positions with seeding

Usage

seed_participants(participants, seed = TRUE)

Arguments

participants

Character vector of participant names

seed

Logical, whether to apply seeding

Value

List with slot assignments and bye information

Configure tournament outcome depth

Description

Configure tournament outcome depth

Usage

set_outcome(spec, track_placements = 1L)

Arguments

spec

A tournament_spec object.

track_placements

Number of placements to track.

Value

Updated tournament_spec.

Set match result by scores

Description

Record the score for a match. The winner is determined by the higher score.

Usage

set_result(
  bracket,
  match_id,
  score1,
  score2,
  stage_id = NULL,
  overwrite = FALSE,
  auto_advance = FALSE
)

## S3 method for class 'bracket'
set_result(
  bracket,
  match_id,
  score1,
  score2,
  stage_id = NULL,
  overwrite = FALSE,
  auto_advance = FALSE
)

## S3 method for class 'group_stage_knockout'
set_result(
  bracket,
  match_id,
  score1,
  score2,
  stage_id = NULL,
  overwrite = FALSE,
  auto_advance = FALSE
)

## S3 method for class 'round_robin_bracket'
set_result(
  bracket,
  match_id,
  score1,
  score2,
  stage_id = NULL,
  overwrite = FALSE,
  auto_advance = FALSE
)

## S3 method for class 'swiss_bracket'
set_result(
  bracket,
  match_id,
  score1,
  score2,
  stage_id = NULL,
  overwrite = FALSE,
  auto_advance = FALSE
)

## S3 method for class 'tournament'
set_result(
  bracket,
  match_id,
  score1,
  score2,
  stage_id = NULL,
  overwrite = FALSE,
  auto_advance = TRUE
)

Arguments

bracket

A bracket object

match_id

The ID of the match to update

score1

Score for participant 1, or a numeric vector of game scores.

score2

Score for participant 2, or a numeric vector of game scores.

stage_id

Optional stage identifier used by multi-stage tournament runtimes.

overwrite

Logical; when TRUE, requests explicit result overwrite handling where supported.

auto_advance

Logical; when TRUE and supported by the bracket type, automatically advances completed stages.

Value

Updated bracket object

Set match winner directly

Description

Record the winner of a match without specifying scores.

Usage

set_winner(bracket, match_id, winner)

## S3 method for class 'bracket'
set_winner(bracket, match_id, winner)

## S3 method for class 'group_stage_knockout'
set_winner(bracket, match_id, winner)

Arguments

bracket

A bracket object

match_id

The ID of the match to update

winner

Name of the winning participant

Value

Updated bracket object

Create a single elimination bracket

Description

Single elimination (knockout) tournament where losing a match eliminates the participant from the tournament.

Usage

single_elim(participants, ...)

Arguments

participants

Character vector of participant names, or a data.frame with a 'name' column and optional 'seed' column.

...

Additional arguments passed to bracket constructors or tournament stage-verb dispatch methods.

Value

A single_elim_bracket object

Examples

# Simple knockout bracket
trn <- tournament(paste("Team", LETTERS[1:8])) |>
  single_elim("bracket")

# Chain after group stage
trn <- tournament(c("A", "B", "C", "D")) |>
  round_robin("groups") |>
  single_elim("finals", take = top_n(2))

Create a stage specification

Description

Stage specifications describe how to materialize a stage bracket from a participant set inside a tournament_spec graph.

Usage

single_elim_stage(
  seed = TRUE,
  third_place = FALSE,
  best_of = NULL,
  reseed = FALSE
)

double_elim_stage(
  seed = TRUE,
  grand_final_reset = TRUE,
  best_of = NULL,
  reseed = FALSE
)

round_robin_stage(
  home_away = FALSE,
  n_rounds = NULL,
  best_of = NULL,
  tiebreakers = NULL,
  groups = NULL
)

swiss_stage(
  rounds = NULL,
  seed = TRUE,
  allow_ties = TRUE,
  bye_points = 1,
  best_of = NULL,
  tiebreakers = NULL
)

group_stage_knockout_stage(
  groups = 2,
  advance_per_group = 2,
  seed = TRUE,
  group_home_away = FALSE,
  group_best_of = NULL,
  group_tiebreakers = NULL,
  knockout_type = "single_elim",
  knockout_seed = TRUE,
  third_place = FALSE,
  grand_final_reset = TRUE,
  knockout_best_of = NULL
)

two_leg_stage(
  seed = TRUE,
  third_place = FALSE,
  away_goals = TRUE,
  reseed = FALSE
)

Arguments

seed

Logical or character seed method.

third_place

Logical; include third-place match.

best_of

Optional best-of value (must be odd).

reseed

Logical; reseed between rounds for supported formats.

grand_final_reset

Logical; allow grand-final reset.

home_away

Logical; whether repeated pairings alternate home/away.

n_rounds

Number of round-robin cycles.

tiebreakers

Ordered tiebreakers.

groups

Number of groups.

rounds

Number of Swiss rounds.

allow_ties

Logical; whether ties are allowed.

bye_points

Points awarded for a bye.

advance_per_group

Number of qualifiers per group.

group_home_away

Logical; home/away behavior in groups.

group_best_of

Optional best-of in groups.

group_tiebreakers

Ordered group-stage tiebreakers.

knockout_type

Knockout format: "single_elim" or "double_elim".

knockout_seed

Logical or character seed method for knockout.

knockout_best_of

Optional knockout best-of value.

away_goals

Logical; enable away-goals tiebreaker.

Value

A stage_spec object.

Select an inclusive standings slice per group

Description

Select an inclusive standings slice per group

Usage

slice_per_group(from, to)

Arguments

from

Positive integer starting position.

to

Positive integer ending position (must be ⁠>= from⁠).

Value

A bracketeer_selector object.

Select an inclusive standings slice

Description

Select an inclusive standings slice

Usage

slice_range(from, to)

Arguments

from

Positive integer starting position.

to

Positive integer ending position (must be ⁠>= from⁠).

Value

A bracketeer_selector object.

Generate a simple snake order

Description

Generate a simple snake order

Usage

snake_order(n, block_size = 2L)

Arguments

n

Number of items

block_size

Block size to reverse in alternating fashion

Value

Integer vector of indices

Create a bracketeer tournament specification

Description

Create a bracketeer tournament specification

Usage

spec()

Value

A bracketeer_spec object.

Examples

# Create a reusable tournament blueprint
my_spec <- spec() |>
  round_robin("groups") |>
  single_elim("finals", take = top_n(2))

# Build with different participant lists
trn1 <- build(my_spec, c("A", "B", "C", "D"))
trn2 <- build(my_spec, c("W", "X", "Y", "Z"))

Add multiple transitions from one source stage

Description

Convenience sugar for branching stage fan-out. Compiles into deterministic add_transition() calls.

Usage

split_stage(
  spec,
  from,
  into,
  priority_start = 1L,
  consume = TRUE,
  allow_overlap = FALSE,
  seeding = "by_source_rank"
)

Arguments

spec

A tournament_spec object.

from

Source stage ID, or from_previous().

into

Named list mapping destination stage IDs to transition rules, or branch configs with a required rule field.

priority_start

Starting priority for branch transitions when a branch does not explicitly provide priority.

consume

Default consume value for branches.

allow_overlap

Default allow_overlap value for branches.

seeding

Default seeding policy for branches.

Value

Updated tournament_spec.

Inspect tournament stage status

Description

Inspect tournament stage status

Usage

stage_status(tournament)

Arguments

tournament

A tournament object.

Value

Data frame with one row per stage.

Inspect tournament standings

Description

Inspect tournament standings

Usage

standings(x, stage = NULL)

## S3 method for class 'tournament'
standings(x, stage = NULL)

Arguments

x

A tournament object.

stage

Optional stage identifier.

Value

Data frame of standings.

Examples

trn <- tournament(c("A", "B", "C", "D")) |>
  round_robin("groups")

# Enter some results
m <- matches(trn, "groups")
trn <- result(trn, "groups", m$match_id[1], score = c(2, 1))

# View current standings
standings(trn, "groups")

Summarize bracketeer objects

Description

Summarize bracketeer objects

Usage

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

Arguments

object

A bracket object.

...

Additional arguments (unused).

Value

The object, invisibly.

Create a Swiss-system tournament

Description

Swiss system pairs participants by similar records each round.

Usage

swiss(participants, ...)

Arguments

participants

Character vector of participant names, or a data.frame with a 'name' column and optional 'seed' column.

...

Additional arguments passed to bracket constructors or tournament stage-verb dispatch methods.

Value

A swiss_bracket object

Examples

# Swiss system followed by top-cut playoffs
teams <- paste("Team", LETTERS[1:16])
trn <- tournament(teams) |>
  swiss("open", rounds = 5) |>
  single_elim("playoffs", take = top_n(8))

Teardown tournament state

Description

For tournament runtimes, this un-materializes a stage and its downstream dependents so upstream results can be corrected and replayed.

Usage

teardown(x, stage = NULL, ...)

## S3 method for class 'bracket'
teardown(x, stage = NULL, ...)

## S3 method for class 'tournament'
teardown(x, stage = NULL, ...)

Arguments

x

A bracket or tournament object.

stage

Stage identifier to teardown (tournament method).

...

Additional method-specific arguments.

Value

Updated object.

Build an ordered tiebreaker chain

Description

Build an ordered tiebreaker chain

Usage

tiebreaker_chain(...)

Arguments

...

Tiebreaker names. Accepts one or more strings or character vectors.

Value

Character vector of unique tiebreakers in input order.

Determine tiebreaker direction

Description

Determine tiebreaker direction

Usage

tiebreaker_direction(tiebreaker)

Arguments

tiebreaker

Name

Value

"asc" or "desc"

Select top ranked participants from source standings

Description

Select top ranked participants from source standings

Usage

top_n(n)

Arguments

n

Positive integer count.

Value

A bracketeer_selector object.

Examples

# Route top 4 to playoffs
trn <- tournament(paste("Team", LETTERS[1:8])) |>
  swiss("open", rounds = 3) |>
  single_elim("playoffs", take = top_n(4))

Select top ranked participants per group

Description

Select top ranked participants per group

Usage

top_per_group(n)

Arguments

n

Positive integer count per group.

Value

A bracketeer_selector object.

Examples

# World Cup style: 8 groups, top 2 per group advance
teams <- paste("Team", sprintf("%02d", 1:32))
trn <- tournament(teams) |>
  round_robin("groups", groups = 8) |>
  single_elim("knockout", take = top_per_group(2))

Create an empty live tournament pipeline

Description

Create an empty live tournament pipeline

Usage

tournament(participants, auto_advance = TRUE)

Arguments

participants

Character vector of participant names, or a data.frame with a name column.

auto_advance

Logical scalar. Stored as the runtime default for future result-entry helpers.

Value

A tournament runtime object with no stages materialized yet.

Examples

# Simple tournament with auto-advance
teams <- c("Lions", "Bears", "Eagles", "Wolves")
trn <- tournament(teams) |>
  round_robin("groups") |>
  single_elim("finals", take = top_n(2))

# Manual advance mode
trn_manual <- tournament(teams, auto_advance = FALSE) |>
  swiss("open", rounds = 3)

Create a tournament specification graph

Description

Construct a multi-stage tournament specification object.

Usage

tournament_spec()

Value

A tournament_spec object.

Create a two-leg stage or bracket

Description

Alias for two_leg_knockout() used by the tournament stage-verb API.

Usage

two_leg(participants, ...)

Arguments

participants

Participants, a spec object, or a tournament object.

...

Additional arguments forwarded to two_leg_knockout().

Value

A bracket, spec, or tournament depending on participants.

Examples

# Two-leg knockout (Champions League style)
teams <- paste("Club", sprintf("%02d", 1:16))
trn <- tournament(teams) |>
  round_robin("groups", groups = 4) |>
  two_leg("knockouts", take = top_per_group(2))

Create a two-leg knockout bracket

Description

Two-leg knockout tournament with home/away legs and aggregate scoring. Pass per-leg scores as length-2 vectors to set_result().

Usage

two_leg_knockout(participants, ...)

Arguments

participants

Character vector of participant names, or a data.frame with a 'name' column and optional 'seed' column.

...

Additional arguments passed to bracket constructors or tournament stage-verb dispatch methods.

Value

A two_leg_knockout object

Utility functions for bracketeer

Description

Utility functions for bracketeer

Validate a tournament spec preflight

Description

Validate a tournament spec preflight

Usage

validate(x, n)

Arguments

x

A bracketeer_spec or tournament_spec object.

n

Participant count for feasibility checks.

Value

A preflight validation summary.

Examples

my_spec <- spec() |>
  round_robin("groups", groups = 4) |>
  single_elim("knockout", take = top_per_group(2))

# Check if 16 participants can work
validate(my_spec, n = 16)

Validate best-of parameter

Description

Validate best-of parameter

Usage

validate_best_of(best_of)

Arguments

best_of

Integer or NULL

Value

Normalized integer or NULL

Dry-run preflight validation for tournament flow feasibility

Description

Validates a tournament_spec against a participant count without running a live tournament. This preflight catches infeasible routing paths and stage size mismatches early.

Usage

validate_tournament(spec, n_participants)

Arguments

spec

A tournament_spec object.

n_participants

Positive integer participant count.

Value

A tournament_validation summary list.

Validate a tournament specification

Description

Validate a tournament specification

Usage

validate_tournament_spec(spec)

Arguments

spec

A tournament_spec object.

Value

The validated tournament_spec.

Get tournament winner

Description

Get tournament winner

Usage

winner(tournament)

Arguments

tournament

A tournament object.

Value

Winner name or NA_character_.

Examples

teams <- c("A", "B", "C", "D")
trn <- tournament(teams) |>
  round_robin("groups") |>
  single_elim("finals", take = top_n(2))

# ... enter all results ...

# Get the champion
winner(trn)