Introduction to andorR
andorR-intro.RmdIntroduction to andorR
andorR (pronounced like the country, Andorra)
is a decision support tool that strategically prioritises evidence
gathering to most efficiently resolve uncertainty in complex logical
trees.
It is designed for problems that are more than simple checklists. It
excels in situations where there are multiple pathways to a conclusion
(OR nodes) and where initial information
is incomplete or uncertain. The core workflow is based on the
progressive gathering of new evidence, with the tool guiding the user on
where to focus their efforts to have the greatest impact on the final
outcome.
What are AND-OR Trees?
An AND-OR tree is a hierarchical model used to break down a complex problem or question (the “root”) into smaller, manageable parts.
- Root: The main goal or final decision you want to reach.
-
Parent Nodes: Intermediate conditions that are
evaluated by logical rules.
- An
ANDnode isTRUEonly if all of its children areTRUE. - An
ORnode isTRUEif at least one of its children isTRUE.
- An
- Leaf Nodes: The basic, answerable questions or pieces of evidence at the bottom of the tree.
Core Features of andorR
The package provides a suite of functions to manage the entire analysis workflow:
-
Flexible Data Loading: Load trees from multiple
formats, including relational data frames (from CSV/Excel), hierarchical
YAML files, and path-string formats. For more details, see the vignette
on data formats:
vignette("data-formats", package = "andorR"). -
Dynamic Prioritization: The tool calculates an
influence_indexfor every unanswered question. Theget_highest_influence()function uses this to suggest the most strategic question to answer next. -
Logical Calculation with Uncertainty: The
calculate_tree()function propagates theTRUE/FALSEanswers up the tree. Crucially, it also aggregates theconfidencescores you provide for each answer, giving you a final confidence score for the overall conclusion. -
Post-Conclusion Guidance: Once a conclusion is
reached, the focus shifts from finding the answer to strengthening it.
The
get_confidence_boosters()function performs a sensitivity analysis to identify which actions will most efficiently increase your confidence in the final result. -
Interactive
tool: Automate the entire workflow with the main wrapper
function,
andorR_interactive(), that provides a user-friendly, text-based interface linking all the other functions together.
A Worked Example
Let’s walk through a typical analysis using the built-in
ethical investment dataset.
Step 1: Load the Tree
First, we load the andorR package and the
ethical dataset, then use load_tree_df() to
build the tree object. We then run update_tree() to
calculate the initial indices.
library(andorR)
# Load the tree from the built-in 'ethical' dataset
dtree <- load_tree_df(ethical)
# Calculate the initial optimisation indices
dtree <- update_tree(dtree)Step 2: Get Initial Guidance
We can now ask the tool for the most important questions to investigate first.
# Get the most important next questions
next_questions_df <- get_highest_influence(dtree, top_n = 3)
knitr::kable(next_questions_df)| name | question | influence_if_true | influence_if_false | influence_index |
|---|---|---|---|---|
| FIN4 | Debt-to-Equity ratio is below the industry average. | 0.0625 | 1 | 1.0625 |
| FIN5 | Company generates strong and positive free cash flow. | 0.0625 | 1 | 1.0625 |
| GOV1 | The board of directors is majority independent and diverse. | 0.0500 | 1 | 1.0500 |
The tool suggests that FIN4, FIN5, and
GOV1 are the most influential starting questions. This is
because they are under AND nodes; a single
FALSE answer to any of them could quickly resolve a major
branch of the tree.
Step 3: Provide Initial Answers
Let’s assume we have some readily available information. We can answer a few questions with varying levels of confidence and see how the tree state changes.
set_answer(dtree, "GOV5", TRUE, 3)
#> Answer for leaf 'GOV5' set to: TRUE with confidence 3/5
set_answer(dtree, "ENV4", TRUE, 3)
#> Answer for leaf 'ENV4' set to: TRUE with confidence 3/5
set_answer(dtree, "SOC1", TRUE, 3)
#> Answer for leaf 'SOC1' set to: TRUE with confidence 3/5
# Update the tree and view the current state
dtree <- update_tree(dtree)
print_tree(dtree)
#> Tree Rule Answer Confidence
#> Invest in Company X AND
#> |-- Financial Viability AND
#> | |-- Profitability and Growth Signals OR
#> | | |-- FIN1
#> | | |-- FIN2
#> | | `-- FIN3
#> | `-- Solvency and Stability AND
#> | |-- FIN4
#> | `-- FIN5
#> |-- Acceptable Environmental Stewardship OR TRUE 80%
#> | |-- Has a Clean Current Record AND
#> | | |-- ENV1
#> | | |-- ENV2
#> | | `-- ENV3
#> | `-- Has a Credible Transition Pathway OR TRUE 80%
#> | |-- ENV4 TRUE 3
#> | |-- ENV5
#> | `-- ENV6
#> |-- Demonstrable Social Responsibility OR TRUE 80%
#> | |-- Shows Excellent Internal Culture OR TRUE 80%
#> | | |-- SOC1 TRUE 3
#> | | |-- SOC2
#> | | |-- SOC3
#> | | `-- SOC4
#> | `-- Has a Positive External Impact AND
#> | |-- SOC5
#> | |-- SOC6
#> | `-- SOC7
#> `-- Strong Corporate Governance AND
#> |-- GOV1
#> |-- GOV2
#> |-- GOV3
#> |-- GOV4
#> `-- GOV5 TRUE 3After these three answers, no conclusion has been reached yet, but
the influence_index values for all other questions have
been dynamically recalculated.
Step 4: Follow the Guidance and Reach a Conclusion
Now, let’s answer a few more questions, including some of the high-influence ones, to push the analysis toward a conclusion.
# Answer some more questions
set_answer(dtree, "FIN4", TRUE, 3)
#> Answer for leaf 'FIN4' set to: TRUE with confidence 3/5
set_answer(dtree, "FIN5", TRUE, 3)
#> Answer for leaf 'FIN5' set to: TRUE with confidence 3/5
set_answer(dtree, "GOV1", TRUE, 3)
#> Answer for leaf 'GOV1' set to: TRUE with confidence 3/5
set_answer(dtree, "GOV2", TRUE, 3)
#> Answer for leaf 'GOV2' set to: TRUE with confidence 3/5
set_answer(dtree, "GOV3", TRUE, 3)
#> Answer for leaf 'GOV3' set to: TRUE with confidence 3/5
set_answer(dtree, "GOV4", TRUE, 3)
#> Answer for leaf 'GOV4' set to: TRUE with confidence 3/5
set_answer(dtree, "FIN1", TRUE, 3)
#> Answer for leaf 'FIN1' set to: TRUE with confidence 3/5
# Update and get the final result
dtree <- update_tree(dtree)
print_tree(dtree)
#> Tree Rule Answer Confidence
#> Invest in Company X AND TRUE 10.7%
#> |-- Financial Viability AND TRUE 51.2%
#> | |-- Profitability and Growth Signals OR TRUE 80%
#> | | |-- FIN1 TRUE 3
#> | | |-- FIN2
#> | | `-- FIN3
#> | `-- Solvency and Stability AND TRUE 64%
#> | |-- FIN4 TRUE 3
#> | `-- FIN5 TRUE 3
#> |-- Acceptable Environmental Stewardship OR TRUE 80%
#> | |-- Has a Clean Current Record AND
#> | | |-- ENV1
#> | | |-- ENV2
#> | | `-- ENV3
#> | `-- Has a Credible Transition Pathway OR TRUE 80%
#> | |-- ENV4 TRUE 3
#> | |-- ENV5
#> | `-- ENV6
#> |-- Demonstrable Social Responsibility OR TRUE 80%
#> | |-- Shows Excellent Internal Culture OR TRUE 80%
#> | | |-- SOC1 TRUE 3
#> | | |-- SOC2
#> | | |-- SOC3
#> | | `-- SOC4
#> | `-- Has a Positive External Impact AND
#> | |-- SOC5
#> | |-- SOC6
#> | `-- SOC7
#> `-- Strong Corporate Governance AND TRUE 32.8%
#> |-- GOV1 TRUE 3
#> |-- GOV2 TRUE 3
#> |-- GOV3 TRUE 3
#> |-- GOV4 TRUE 3
#> `-- GOV5 TRUE 3Success! After providing those answers, the root node “Invest
in Company X” has been resolved to TRUE, with a
calculated confidence of 73.6%. The analysis now automatically moves
into the “Confidence Boosting” phase.
Interactive Analysis with andorR_interactive()
While you can call each function (set_answer,
update_tree, etc.) manually, the package provides a main
wrapper function, andorR_interactive(), that automates the
entire workflow in a user-friendly, text-based interface.
This function links all the stages together: * It displays the
highest-impact questions to guide your analysis. * It prompts you to
select a question and provide an answer and confidence level. * It
automatically calls calculate_tree,
assign_indices, and calculate_influence to
fully update the tree’s state. * It prints the updated tree so you can
see the immediate impact of your answer. * Once a conclusion is reached,
it automatically switches to “Confidence Boosting” mode, showing you the
best ways to improve your result.
To start the interactive session, you simply load a tree and pass it to the function.
# Load the ethical dataset and build the tree
data(ethical)
dtree <- load_tree_df(ethical)
dtree <- update_tree(dtree)
# Start the interactive analysis loop
andorR_interactive(dtree)Included Datasets
The package includes several pre-built decision trees to demonstrate
its features. For a full list and description of these files, please see
the example data files guide:
vignette("example-data-files", package = "andorR") ```