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

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 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.

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 remaining aliases provide factor selection, unflagged rankings, and manual distribution repair.

Usage

prepare_rankings(dataset, idcolumn = "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 = NULL,
  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 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; unfamiliar warnings are re-emitted (feel free to report them). 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 transparently reported as 'qindtest with orthogonal Procrustes fallback'.

Usage

validate(
  results,
  bootstrap = NULL,
  bootstrap_scores = NULL,
  statement_labels = NULL,
  confidence_level = 0.95,
  rank_cutoffs = c(1L, 3L, 5L),
  include_bottom = FALSE,
  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.

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,
  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

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.