Package {qapproach}

A Q-based workflow to support decision-making processes by identifying shared perspectives

Description

Tools to prepare Q-sort rankings, identify group perspectives, calculate consensus priority scores, validate results, and create figures.

Author(s)

Maintainer: Jonas Geschke hallo@qapproach.app

Authors:

• Jonas Geschke hallo@qapproach.app

References

Zabala, A. (2014). qmethod: A Package to Explore Human Perspectives Using Q Methodology. *The R Journal*, 6(2), 163–173. doi:10.32614/RJ-2014-032

Zabala, A., & Pascual, U. (2016). Bootstrapping Q Methodology to Improve the Understanding of Human Perspectives. *PLOS ONE*, 11(2), e0148087. doi:10.1371/journal.pone.0148087

Geschke, J., Urbach, D., Prescott, G. W., & Fischer, M. (2022). The Q approach to consensus building: integrating diverse perspectives to guide decision-making. *ECOEVORXIV*. doi:10.32942/X2F59S

See Also

Useful links:

• doi:10.5281/zenodo.11518485

• Report bugs at https://github.com/JonasGeschke/qapproach/issues

Trace ranking agreement across successive Q approach levels

Description

**Experimental.** This function traces each original input ranking through an arbitrary number of analytical levels. Original rankings may enter at any supplied level; inputs that match a generated group-perspective identifier are excluded from the set of original rankings. Its interface and interpretation may be refined as additional multi-level applications become available.

Usage

agreement_across_levels(levels, print_table = TRUE)

Arguments

Details

For every supplied level, the returned table reports the analysis in which the current input was found, whether it agreed with, opposed, or was undecided about a perspective, and the relevant perspective identifier. 'Agreement path' joins only positively agreeing perspectives with ' > '. Opposition and undecided status do not propagate agreement through a group perspective. If a raw ranking is explicitly re-added at a later level, it can enter the agreement path there. Rankings that do not agree with a perspective at any level receive 'NA' as their agreement path.

Value

A list containing 'paths', with one row per original input ranking; 'underlying_agreement_counts', with the number of unique original rankings whose positive path reaches each perspective; and 'terminal_path_summary', with counts and shares by terminal perspective. 'rankings_not_agreeing' reports the count, identifiers, and underlying statement-ranking values of original rankings that do not positively agree with any perspective at any level. An internal completeness check warns if the original rankings are not represented exactly once in 'paths'.

Summarize consensus across successive Q approach levels

Description

Experimental. This function is provided for testing and further refinement. Its interface and calculations may change, and it should not yet be used for definitive analytical conclusions.

The transition table reports direct agreement at every level and traces the original individual rankings through successive positive-agreement links.

Usage

consensus_across_levels(levels, print_table = TRUE)

Arguments

Value

A list containing the number of raw input rankings, a transition table, and convenient final-transition values for underlying pool agreement, pool counts, underlying individual agreement, and underlying individual counts by perspective. The transition table stores the pool counts and perspective-level counts as structured list-columns.

Calculate consensus priority scores

Description

Calculates eigenvalue-weighted consensus priority scores from perspective z-scores and eigenvalues on a fixed standard-normal cumulative-probability scale.

Usage

cpscores(statementzscores, factoreigenvalues)

Arguments

Details

The function first calculates the eigenvalue-weighted mean z-score for every statement and then applies the fixed standard-normal cumulative distribution function. A score of 0.5 represents neutral prioritization across the group perspectives; values above or below 0.5 represent relatively higher or lower priority. Comparisons across analyses require the same statements and meanings, ranking distribution, instructions, data preparation, and analytical settings.

Value

A named numeric vector of consensus priority scores between the theoretical boundaries 0 and 1.

Determine the required Q-sort ranking distribution

Description

Returns the fixed ranking distribution used by the Q approach for a given number of statements. This distribution provides the basis for preparing data-collection materials and validating completed rankings.

Usage

distributiondetermination(nstat)

Arguments

Value

A list containing the number of statements per ranking value (distr), the ranking values (values), and the complete ranking gradient (ranking).

Plot a hierarchical network across Q approach levels

Description

Draws a bottom-up network in which the original individual rankings feed into their analyses and the resulting group perspectives feed into analyses at subsequent levels. Each group perspective is retained as a separate edge, including when several perspectives connect the same two analyses. Individual rankings feeding into the same earliest target analysis are positioned next to one another; their order within each target group retains the crossing-minimizing Sugiyama order.

Usage

plot_hierarchical_levels(
  levels,
  file = NULL,
  level_colors = NULL,
  individual_arrow_color = "grey",
  perspective_arrow_color = "black",
  level_node_sizes = NULL,
  analysis_labels = NULL,
  ranking_labelled = FALSE,
  analysis_labelled = TRUE,
  level_gaps = NULL,
  ranking_node_size = 1,
  arrow_size = 0.25,
  width = 12,
  height = 10,
  agreement = FALSE,
  network_object = FALSE
)

Arguments

Details

When 'network_object = TRUE', the returned 'igraph' object contains analytical metadata, but not the graphical settings calculated during plotting.

Attributes included in the returned network

• The standard vertex attribute 'name', plus vertex attributes 'type', 'level', 'label', and 'color'. For analysis vertices, 'name' contains the technical analysis name supplied through 'levels'; the 'color' attribute contains the unmodified level color, before plotting transparency is applied;

• Edge attributes 'input_id', 'input_type', and 'status';

• The graph attribute 'level_names'.

Graphical settings not stored in the returned network

The object does not contain the generated layout, vertex sizes, vertex frame color, label size or other label formatting, edge colors, edge line types or widths, arrow settings, edge curvature, plot limits, or other graphical parameters. These are calculated only when 'network_object = FALSE'.

In the standard plot, individual-ranking nodes use 'ranking_node_size' (default 1). Unless 'level_node_sizes' is supplied, each analysis node is sized as 0.3 times the sum of the underlying individual rankings agreeing through its group perspectives. Analysis-node colors use the stored 'color' attribute with 80 percent opacity; ranking nodes remain opaque. Frames are omitted. Ranking and analysis label sizes are 0.5 and 0.95, respectively; analysis labels are bold, and labels use color '#1F1F1F' and the sans-serif font family.

With 'agreement = FALSE', individual-ranking edges use 'individual_arrow_color' and group-perspective edges use 'perspective_arrow_color'; these defaults are light grey and black, respectively. These are edge colors, not line types, and both use solid lines. With 'agreement = TRUE', the input-type colors are replaced: agreeing edges are grey, opposing edges are firebrick, and undecided edges are dodger blue ('dodgerblue3'). All three statuses use solid lines. Individual-ranking and group-perspective edges both use width 0.5. Arrows use 'arrow_size', and parallel edges are curved with 'igraph::curve_multiple()'.

The 'agreement' argument changes only the drawn styling. The returned network object is the same in either mode: its 'input_type' edge attribute supports the individual-versus-perspective mapping, and its 'status' edge attribute supports the agreeing-versus-opposing-versus-undecided mapping.

Vertical gaps are applied after the deterministic Sugiyama ordering and equal-gap horizontal placement have been calculated. Each value in 'level_gaps' shifts every subsequent analytical level upward without changing node order or horizontal position. Thus, 'level2 = 0.5' adds half a standard level distance only between levels 2 and 3. The special name 'rankings' controls the gap between the individual-ranking foundation and the first analytical level. Multiple named gaps are cumulative.

The retained attributes allow specialists to reproduce these mappings or construct entirely custom layouts and plots directly with 'igraph'.

Value

When 'network_object = TRUE', returns the prepared 'igraph' object. Otherwise, invisibly returns the normalized output path when a file is written and invisibly returns 'NULL' when drawing on the active device.

Plot and save a two-layered multi-dataset synthesis network

Description

Plot and save a two-layered multi-dataset synthesis network

Usage

plot_network_two_layered(
  file = NULL,
  datasets,
  synthesis,
  labels = NULL,
  statement_colors = NULL,
  network_labelled = FALSE,
  perspective_label_cex = 2,
  ranking_label_cex = 1.1,
  dataset_colors = NULL,
  synthesis_color = NULL,
  cps_color = NULL,
  preset = NULL,
  width = 11.2,
  height = 6.4,
  input_network = FALSE,
  arrow_size = 0.56,
  negative_loadings_marked = TRUE,
  layout_seed = NULL
)

Arguments

Value

Invisibly returns the normalized output path.

Plot cp-scores across analyses using SDG icons

Description

Draws one horizontal row per analysis and positions the 17 official United Nations Sustainable Development Goal icons at their respective cp-scores. Icon size increases linearly with the cp-score. The first matrix or data-frame row is displayed at the top. When 'file' is 'NULL', the figure is drawn on the current graphics device; otherwise, a PDF is written to the exact supplied path.

Usage

plot_sdg_cps(
  x,
  analysis_labels = NULL,
  icon_size_range = c(0.18, 0.62),
  style = c("cpscores", "side-by-side"),
  analysis_lines = TRUE,
  file = NULL,
  width = 11.2,
  height = 8.3
)

Arguments

Value

Invisibly returns the normalized PDF path when 'file' is supplied; otherwise invisibly returns 'NULL' after drawing the figure.

Export SDG-priority diamonds for all group perspectives

Description

Creates one TIFF figure per group perspective in a Q approach result. Each figure arranges the 17 Sustainable Development Goal icons in the perspective's required Q-sort distribution, from lower to higher priority. Tied statements retain their order in the perspective table.

Usage

plot_sdg_diamonds(
  results,
  directory,
  filename = NULL,
  width = 30,
  height = 21,
  resolution = 300
)

Arguments

Value

Invisibly returns the normalized paths of the written TIFF files.

Prepare rankings and run a Q approach analysis

Description

'prepare_rankings()' converts participant-by-statement input into the statement-by-ranking orientation used by 'qapproach()'. 'qapproach()' fits perspectives and computes consensus priority scores. The result retains the underlying eigenvalue-weighted mean z-scores as a technical output. The analysis stores recognized Q method conditions, factor-selection details, automatic distribution-repair diagnostics, and opposing rankings silently in 'results$diagnostics'. In particular, the affected ranking identifiers, perspectives, and loadings are available in 'results$diagnostics$negative_flagging'. Unclassified conditions remain visible as warnings so that they can be reported and reviewed. The remaining aliases provide factor selection, unflagged rankings, and manual distribution repair.

Usage

prepare_rankings(dataset, id_column = "ID", statement_columns = NULL,
  add = list(NULL), orientation = c("auto", "participant_rows",
  "statement_rows"))
qapproach(dataset, nfactors = "criteria", rotation = "quartimax",
  load_perc = 0.8, min_load_perc = 0.5, morethan5 = FALSE,
  screeplot_file = NULL,
  repair_distributions = TRUE, distribution_repair_steps = NULL,
  distribution_repair_seed = 42L,
  distribution_repair_max_attempt_multiplier = 10L)
nfactordetermination(dataset, rotation, load_perc, morethan5 = FALSE,
  min_load_perc = 0.5)
not_agreeing(results, status = FALSE)
manually_repair_perspective_distributions(results, bootstrap = NULL,
  perspective = NULL, statement = NULL, value = NULL, interactive = TRUE,
  verbose = interactive)

Arguments

Value

'prepare_rankings()' returns statement-by-ranking data. 'qapproach()' returns the fitted analysis, perspectives, weighted z-scores, consensus priority scores, repair audit, and centralized diagnostics in 'results$diagnostics'. When automatic factor selection is used, its details are available as '<object>$factor_selection', including the captured diagnostic messages and warnings at '<object>$diagnostics$factor_selection'. Other functions return the result described above.

References

Geschke, J., Urbach, D., Prescott, G. W., & Fischer, M.(2022). The Q approach to consensus building: integrating diverse perspectives to guide decision-making. *ECOEVORXIV*. doi:10.32942/X2F59S

Geschke, J. (2024). *Q approach to consensus building*. doi:10.5281/zenodo.11518485

Examples

x <- data.frame(ID = c("A", "B"), stat1 = c(-1, 0),
  stat2 = c(0, 1), stat3 = c(1, -1))
prepare_rankings(x)

Advanced Q approach bootstrap interfaces

Description

Generate Q method bootstrap results or collect a requested number of valid bootstrap iterations of the consensus priority scores. Recognized R messages and warnings emitted by the underlying Q method bootstrap are retained as structured diagnostics without routine console messages; unfamiliar warnings are re-emitted and include the package's bug-report URL. Single-perspective solutions use Procrustes sign alignment. Solutions with two or three perspectives use ‘qindtest', with the package’s orthogonal Procrustes alignment as a documented fallback if 'qindtest' fails; solutions with more than three perspectives use orthogonal Procrustes alignment directly. Flags and z-scores are recalculated after Procrustes alignment.

Usage

qaboots(results, steps = 40, method = "multiplication", seed = NULL,
  max_batch_steps = 500L, max_attempt_multiplier = 10L,
  progress = interactive())
bootstrap_consensus_priority_scores(results, steps = NULL, seed = NULL,
  target_valid_steps = NULL, valid_steps_per_ranking = 40L,
  max_batch_steps = 500L, max_attempt_multiplier = 10L,
  progress = interactive())

Arguments

Value

A list containing bootstrap estimates, iteration accounting, and structured diagnostics.

Plot and export Q approach results

Description

Draw perspective rankings, consensus priority scores, networks, spiderwebs, or consensus priority score bootstrap distributions. 'write_figure_collection()' combines applicable figures and captions in a multi-page PDF.

Usage

plot_barplot(result, labels = NULL, statement_colors = NULL,
  network_labelled = FALSE, preset = NULL,
  show_normalized_weighted_z = FALSE,
  normalized_line_color = "black", normalized_line_width = 1.5,
  file = NULL, width = 11.2, height = 6.4)
plot_heatmap(result, labels = NULL, statement_colors = NULL,
  network_labelled = FALSE, preset = NULL, file = NULL,
  width = 11.2, height = 6.4)
plot_jitterplot(result, labels = NULL, statement_colors = NULL,
  network_labelled = FALSE, preset = NULL, file = NULL,
  width = 11.2, height = 6.4)
plot_network(result, labels = NULL, statement_colors = NULL,
  network_labelled = FALSE, network_perspective_label_cex = 2,
  network_ranking_label_cex = 1.1, network_dataset_colors = NULL,
  network_synthesis_color = NULL, network_cps_color = NULL,
  input_network = FALSE, negative_loadings_marked = TRUE,
  network_arrow_size = 0.56, layout_seed = NULL,
  .mixed_synthesis_inputs = FALSE,
  preset = NULL, file = NULL, width = 11.2, height = 6.4)
plot_spiderweb(result, labels = NULL, statement_colors = NULL,
  network_labelled = FALSE, preset = NULL, file = NULL,
  width = 8.3, height = 8.3)
write_figure_collection(file, result, validation = NULL, labels = NULL,
  statement_colors = NULL, network_labelled = FALSE,
  layout_seed = NULL, figure_assets = NULL, preset = NULL,
  two_layered = FALSE)

Arguments

Value

Plot functions draw on the current device. The writer invisibly returns the normalized output path.

Print a Q approach analysis summary

Description

Prints and returns analysis-summary, group-perspective, and consensus-priority-score tables from an object returned by qapproach(). The analysis summary includes the observed cp-score range in [minimum, maximum] format with two decimal places.

Usage

summary(results, print_table = TRUE, file = NULL)

Arguments

Value

Invisibly returns a named list containing the analysis summary, group perspectives, and consensus priority scores tables. Summary cp-scores are rounded to two decimal places; the source values in results remain unchanged.

See Also

qapproach

Validate group perspectives and consensus priority scores

Description

Runs three complementary procedures: bootstrap stability of the group perspectives, bootstrap stability of the consensus priority scores and ranks, and a sensitivity comparison with input-ranking means transformed onto the same fixed standard-normal cumulative-probability scale. Bootstrap factor alignment uses orthogonal Procrustes sign alignment for one perspective, ‘qindtest' for two or three perspectives, and the package’s orthogonal Procrustes implementation for larger solutions. If 'qindtest' fails, the affected batch is rerun with orthogonal Procrustes alignment and reported with a message referring to this help page. The fallback preserves the intended factor correspondence when 'qindtest' cannot provide a unique alignment; its use and the original error are retained in the diagnostics. Recognized underlying conditions, routine alignment corrections, invalid iterations, and discard reasons are retained silently in 'validation$diagnostics'. Unclassified conditions are emitted as warnings so that they can be reported and reviewed.

Usage

validate(
  results,
  bootstrap = NULL,
  bootstrap_scores = NULL,
  statement_labels = NULL,
  confidence_level = 0.95,
  rank_cutoffs = c(1L, 3L, 5L),
  target_valid_steps = NULL,
  valid_steps_per_ranking = 40L,
  seed = NULL,
  max_batch_steps = 500L,
  max_attempt_multiplier = 10L,
  zscore_instability_threshold = 0.2,
  progress = interactive()
)

Arguments

Value

A list containing three validation-procedure results and centralized diagnostics in 'validation$diagnostics'. These diagnostics contain the alignment methods and fallbacks, recognized bootstrap conditions, invalid iterations and their discard reasons, and the input-mean correlation diagnostic.

Print the consensus-priority-score validation table

Description

Extracts the table already calculated by 'validate()', prints a readable version in the console, and invisibly returns the displayed results for assignment or export. Score and rank confidence intervals are each combined in one column using '[lower, upper]' notation.

Usage

validation_cps(
  validation,
  digits = 2L,
  print_table = TRUE,
  sort_by = "cp-scores",
  decreasing = TRUE,
  include_bottom = FALSE,
  file = NULL
)

Arguments

Details

‘Weighted z-score' is the eigenvalue-weighted mean of the statement’s z-scores across all group perspectives. Positive values indicate relatively higher prioritization, negative values indicate relatively lower prioritization, and zero represents average prioritization across the group perspectives. Differences between weighted z-scores provide a linear measure of the prioritization gap between statements.

Value

Invisibly, the validation data frame with merged interval columns.

Print the sensitivity comparison with input-ranking means

Description

Creates a one-row-per-statement comparison of consensus priority scores with input-ranking means transformed onto the same fixed standard-normal cumulative-probability scale. This is a sensitivity analysis, not a test of whether the consensus priority scores are valid: differences may reflect the intended perspective-based weighting.

Usage

validation_means(
  validation,
  digits = 2L,
  print_table = TRUE,
  sort_by = "cp-scores",
  decreasing = TRUE,
  file = NULL
)

Arguments

Details

The direction of the rank-change measure intentionally differs from the arithmetic order named in its column heading. Because lower rank numbers indicate higher priority, a positive rank change means that the statement moved upward under the cp-score ranking. Positive values in both the score- difference and rank-change columns therefore indicate a higher cp-score priority relative to the input means. When input means are tied, 'Priority comparison' reports 'Tied under input means' instead of assigning a directional interpretation.

The comparison of the cp-scores with the input means is a sensitivity analysis, not a test of whether the consensus priority scores are valid. Differences can reflect the intended perspective-based weighting: input means treat every ranking equally, whereas cp-scores explicitly represent group perspectives. A small difference may indicate that perspective-based weighting has little effect in the dataset, which is itself informative.

Value

Invisibly, the unformatted statement-comparison data frame.

Print the group-perspective stability validation table

Description

Creates a one-row-per-perspective overview from the first validation procedure returned by 'validate()'. The assessment is descriptive: it flags rank-order agreement below 'rank_correlation_threshold' and any statement whose absolute bootstrap z-score bias reaches the threshold supplied to 'validate()'.

Usage

validation_perspectives(
  validation,
  digits = 2L,
  rank_correlation_threshold = 0.9,
  print_table = TRUE,
  sort_by = NULL,
  file = NULL
)

Arguments

Value

Invisibly, the detailed perspective-validation data frame.