| Title: | Systematic Theory Development |
| Version: | 0.7.0 |
| Description: | Provides a reproducible workflow for building, developing and testing scientific theories represented as versioned, machine-checkable objects. Functions read and validate theory objects, score them against a versioned rigour checklist, screen constructs for redundancy, derive the conditional independencies a causal theory implies, appraise amendments as progressive, degenerating or neutral, write preregistration and audit documents, compile 'lavaan' model syntax, simulate the construct network, map a theory onto the themes of a literature corpus and write diagram intermediate representations. A 'Python' package of the same name offers the same functions. Both follow one specification, so they produce the same verdicts and the same diagram intermediate representations. |
| License: | MIT + file LICENSE |
| URL: | https://github.com/pablobernabeu/theoryforge, https://pablobernabeu.github.io/theoryforge/r/ |
| BugReports: | https://github.com/pablobernabeu/theoryforge/issues |
| Encoding: | UTF-8 |
| Language: | en-GB |
| Depends: | R (≥ 4.1.0) |
| Imports: | jsonlite, stats, tools, utils, yaml (≥ 2.3.8) |
| Suggests: | testthat (≥ 3.1.7), knitr, rmarkdown, curl, dagitty, ggm, DiagrammeR, DiagrammeRsvg, htmltools, lavaan, Matrix, spelling |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| RoxygenNote: | 8.0.0 |
| NeedsCompilation: | no |
| Packaged: | 2026-11-21 19:40:42 UTC; runner |
| Author: | Pablo Bernabeu |
| Maintainer: | Pablo Bernabeu <pcbernabeu@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-11-22 00:20:02 UTC |
theoryforge: systematic theory development
Description
A Python package of
the same name offers a counterpart of every exported function. Both follow
one public specification
(API_SPEC.md),
so they produce the same verdicts and the same diagram intermediate
representations. The helpers that depend on a network service or a
user-supplied embedder (tf_fetch_corpus(), tf_osf_push() and
tf_embedding_redundancy()) and the diagram renderer
(tf_render_diagram()) have counterparts there too, but their results can
differ between the two packages. Their pages describe what each depends on.
Details
The main functions are tf_read(), tf_validate(), tf_write(),
tf_check(), tf_report(), tf_redundancy_check() and tf_diagram().
Author(s)
Pablo Bernabeu, author and maintainer (pcbernabeu@gmail.com, ORCID).
See Also
Useful links:
Report bugs at https://github.com/pablobernabeu/theoryforge/issues
Read, validate and write theory objects.
Description
Read, validate and write theory objects.
Development mode: amendment appraisal.
Description
Operationalises the Lakatosian distinction between progressive and degenerating amendments (Lakatos, 1970; Meehl, 1990a).
Diagram intermediate representations.
Description
Deterministic string renderers for every diagram type.
Assemble a reviewer-facing audit bundle as a single Markdown document.
Description
Composes the rigour report, severity table, test record, evidence, provenance and preregistration document into one deterministic bundle.
Opt-in embedding-based construct-redundancy screen.
Description
Results depend on a user-supplied embedding function whose outputs are not
deterministic across model versions or SDKs. This screen is the assistive
counterpart to the deterministic lexical screen in
tf_redundancy_check.
Access to the example theories shipped inside the package.
Description
Functions that find the example files installed with the package, through
system.file(). The Python package offers the same files through
example_path() and example_names().
Testable implications derived from the graph a theory's propositions state.
Description
Every proposition is read through the relation table: the directed relations
are edges and associates is a bidirected edge. Each pair of constructs that
no edge joins is independent given some set of other constructs whenever a
set m-separates the pair. A graph with feedback loops is refused by default,
or read by sigma-separation on request.
Bibliometric literature layer.
Description
The analysis (the literature map, the landscape and their diagrams) is
deterministic for a given corpus. Only the OpenAlex fetch,
tf_fetch_corpus(), depends on a live network service.
Open Science Framework deposit adapter (assistive).
Description
Builds the request to upload a theory's audit dossier to OSF. Defaults to
dry_run = TRUE, which constructs the request without sending it. A live
push requires the user's OSF token and network access and is never performed
automatically.
Preregistration document export.
Description
Deterministic Markdown output.
Deterministic lexical redundancy screen.
Description
Tokenisation and Jaccard similarity over construct definitions.
Render a theory's audit dossier as a standalone Quarto report.
Description
Writes a .qmd (a YAML header plus the deterministic dossier body) and
can optionally invoke Quarto to render it. The report content is the
deterministic tf_dossier output, and only the rendering step depends
on the environment.
The theory-rigour checklist engine.
Description
Scores a theory against the 12-item checklist installed with the package.
Claim-form riskiness rubric (deterministic, pre-data)
Description
A pre-data ranking of the form of each prediction's claim. It reads a
prediction's declared type and its diagnostic_vs ids, and
neither the statement nor any test, outcome or data.
Compile a theory to lavaan model syntax.
Description
Deterministic output.
Deterministic dynamical-system runner derived from a theory network.
Description
Each construct is a state variable, and each proposition whose relation is
increases, decreases, causes or mediates
contributes a signed linear coupling term. The system is propagated either
with fixed-step (Euler) updates or exactly, with the matrix exponential of
the coupling matrix, so the trajectory is deterministic.
Add an alternative theory (BUILDING mode)
Description
Add an alternative theory (BUILDING mode)
Usage
tf_add_alternative(theory, id, label, key_constructs = NULL)
Arguments
theory |
A theory object (named list). |
id, label |
Alternative fields. |
key_constructs |
Optional character vector. |
Value
The (mutated) theory object.
Examples
tf_theory("demo-1", "A demonstration theory") |>
tf_add_alternative("alt1", "Cognitive appraisal account",
key_constructs = c("c_threat"))
Add an auxiliary assumption (BUILDING mode)
Description
Add an auxiliary assumption (BUILDING mode)
Usage
tf_add_assumption(theory, id, statement, added_for = NULL, protects = NULL)
Arguments
theory |
A theory object (named list). |
id, statement |
Assumption fields. |
added_for |
Optional id of the prediction whose anomaly the assumption
was added to answer. Leave it |
protects |
Optional character vector of the ids of the predictions the assumption shields from refutation. |
Value
The (mutated) theory object.
Examples
tf_theory("demo-1", "A demonstration theory") |>
tf_add_assumption("a1", "Measurement error is negligible.")
Add a construct to a theory (BUILDING mode)
Description
Appends a construct and a provenance entry, returning the mutated theory.
Usage
tf_add_construct(
theory,
id,
label,
definition,
measurement = NULL,
boundary_conditions = NULL
)
Arguments
theory |
A theory object (named list). |
id, label, definition |
Construct fields. |
measurement, boundary_conditions |
Optional character vectors. |
Value
The (mutated) theory object.
Examples
tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Physiological arousal",
"Bodily activation in response to a stressor.")
Add a prediction to a theory (BUILDING mode)
Description
Appends a prediction and a provenance entry, returning the mutated theory.
Usage
tf_add_prediction(
theory,
id,
statement,
type,
derives_from = NULL,
diagnostic_vs = NULL,
severity = NULL,
test = NULL
)
Arguments
theory |
A theory object (named list). |
id |
The prediction's identifier. |
statement |
The claim in words. |
type |
The form of the claim, one of four. |
derives_from, diagnostic_vs |
Optional character vectors. |
severity |
Optional declared pre-data severity from 0 to 1, stored only
when given. The checklist's risk_severity item reads it, and reads the
claim-form rubric's value ( |
test |
Optional sampling plan for testing the prediction, a named list
of any of |
Value
The (mutated) theory object.
Examples
tf_theory("demo-1", "A demonstration theory") |>
tf_add_prediction("h1", "Arousal precedes threat appraisal.", "directional")
# A prediction with the sampling plan of its test.
tf_theory("demo-1", "A demonstration theory") |>
tf_add_prediction("h1", "The switch cost lies between 20 and 60 ms.", "interval",
test = list(n_planned = 48, unit = "participants", alpha = 0.05,
sided = "two", power = 0.9))
Add a proposition to a theory (BUILDING mode)
Description
Add a proposition to a theory (BUILDING mode)
Usage
tf_add_proposition(theory, id, from, to, relation, mechanism = NULL)
Arguments
theory |
A theory object (named list). |
id, from, to, relation |
Proposition fields. |
mechanism |
Optional mechanism string. |
Value
The (mutated) theory object.
Examples
tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.") |>
tf_add_construct("c_threat", "Perceived threat", "Appraised danger.") |>
tf_add_proposition("p1", "c_arousal", "c_threat", "increases")
Appraise an amendment as progressive, degenerating or neutral
Description
Compares an amended theory new with its prior version by
content, not by prediction ids, and returns a Lakatosian verdict with the
evidence behind it.
Usage
tf_appraise_amendment(new, prior)
Arguments
new |
The amended theory object (named list). |
prior |
The prior theory object (named list). |
Details
A new prediction whose statement and type match a prediction the amendment
dropped is that prediction renamed. A new prediction derived only from
propositions the prior already held, and needing no new assumption,
articulates old content. A prediction is corroborated when at least one test
outcome passes it and none fails it. An assumption added for an anomaly (its
added_for names the prediction it answers) is ad hoc unless a
prediction it protects that is new in this version, other than the anomaly,
is corroborated.
The verdict is "progressive" when a corroborated new prediction is
neither an articulation nor underived, no assumption is ad hoc and no
corroborated prediction is dropped. It is "degenerating" when an
assumption is ad hoc and no such prediction exists, and "neutral"
otherwise. Lakatos has only the first two. "neutral" is
theoryforge's label for an amendment that meets neither rule, and the
vectors returned tell its cases apart. Only
corroborated_new_registered reads a test outcome's
registered, and no date or version field is read, so which
version is the prior is the caller's responsibility.
A test outcome whose passed is present and not TRUE or
FALSE, in new (checked first) or in prior, is
refused. Read as not passed, a quoted "true" could turn a progressive
amendment into a degenerating one.
Value
A named list whose first element, verdict, is one of
"progressive", "degenerating" and "neutral".
new_predictions, corroborated_new, ad_hoc_assumptions,
articulated, underived, corroborated_new_registered,
dropped, dropped_corroborated, content_lost and
new_anomalies are ascending-sorted character vectors.
renamed is a list of list(prior, new) pairs sorted by
new, and assumptions holds one
list(id, added_for, class, independent) per new assumption added
for an anomaly, in file order. independent lists, each as
list(id, status) and in the order of protects, the distinct
predictions the assumption protects that are new in this version and
differ from added_for, with their status in new
("corroborated", "refuted", "mixed" or
"untested"). class is "ad_hoc1" when there are none,
"ad_hoc2" when none is corroborated and
"independently_corroborated" otherwise, and
ad_hoc_assumptions holds the ids of the first two classes. The
elements come in the order verdict, new_predictions,
corroborated_new, ad_hoc_assumptions, articulated,
underived, corroborated_new_registered, renamed,
dropped, dropped_corroborated, content_lost,
new_anomalies and assumptions.
References
Lakatos, I. (1970). Falsification and the methodology of scientific research programmes. In I. Lakatos & A. Musgrave (Eds.), Criticism and the growth of knowledge (pp. 91-196). Cambridge University Press. doi:10.1017/cbo9781139171434.009
Meehl, P. E. (1990a). Appraising and amending theories: The strategy of Lakatosian defense and two principles that warrant it. Psychological Inquiry, 1(2), 108-141. doi:10.1207/s15327965pli0102_1
Examples
prior <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.") |>
tf_add_construct("c_threat", "Perceived threat", "Appraised danger.") |>
tf_add_proposition("p1", "c_arousal", "c_threat", "increases") |>
tf_add_prediction("h1", "Threat rises with arousal.", "directional",
derives_from = "p1")
new <- prior |>
tf_add_construct("c_avoid", "Avoidance", "Withdrawal from feared situations.") |>
tf_add_proposition("p2", "c_threat", "c_avoid", "increases") |>
tf_add_prediction("h2", "Avoidance rises 0.3 SD per SD of threat.", "point",
derives_from = "p2")
new$test_outcomes <- list(list(prediction_id = "h2", passed = TRUE))
tf_appraise_amendment(new, prior)$verdict
Compute the rigour checklist report
Description
Runs the full rigour checklist (12 items) over a theory object and returns a report, with the items in checklist order.
Usage
tf_check(theory)
Arguments
theory |
A theory object (named list), such as one from |
Details
Each item has a status ("pass", "warn" or "fail") and
a score from 0 to 1. An item with nothing to assess has the status
"n/a" and a NULL score: the redundancy screen with fewer than
two constructs, the derivation chain with no prediction and parsimony when
no auxiliary assumption was added in response to an anomaly. The aggregate
score is the weighted mean of the applicable items' scores, times 100, and
coverage is the share of the checklist's weight that was applicable.
Two values are refused before anything is scored, since no score built on
them would be defensible. One is a test outcome whose passed is
present and not TRUE or FALSE, such as the quoted string
"true". The other is a prediction severity that is present and
not a finite number from 0 to 1. Both stop with an error, and
tf_validate() with full = TRUE reports both.
Value
A named list with elements theory_id, schema_version
(the theory's), checklist_version (the rigour checklist's, which is
what the weights and thresholds came from), maturity,
aggregate_score (0 to 100, to one decimal), coverage,
gate, n_blockers_failed and items. gate is
"advisory" at draft maturity, and otherwise "blocked"
when an item whose severity_if_fail is "blocker"
(falsifiability or derivation_chain) fails and "pass" when none
does. items holds one list per checklist item, in checklist order,
with id, status, score, weight,
severity_if_fail ("blocker" or "warning") and
citation. An error is raised for a prediction severity that is not
a finite number or is below 0 or above 1.
Examples
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.") |>
tf_add_construct("c_threat", "Perceived threat", "Appraised danger.") |>
tf_add_proposition("p1", "c_arousal", "c_threat", "causes",
mechanism = "Activation raises salience of threat cues.") |>
tf_add_prediction("h1", "Arousal precedes threat appraisal.", "point")
report <- tf_check(theory)
report$aggregate_score
report$gate
Compile a theory to lavaan model syntax
Description
Compiles a theory's constructs and propositions into lavaan model
syntax written for lavaan::sem(). Constructs with measurement
indicators become a latent measurement model (=~), propositions
become structural paths (~) and covariances (~~), and the
covariances the theory rules out are fixed at zero. Comments say what to
check before a fit. The output is deterministic.
Usage
tf_compile_sem(theory)
Arguments
theory |
A theory object (named list), such as one from |
Value
The lavaan model syntax as a single string (LF line endings, single trailing newline).
The structural model
Each proposition becomes a line in file order: a regression
(to ~ from) for causes, increases, decreases and
mediates, and a covariance (from ~~ to) for
associates. A moderates proposition gives the moderator's
main effect, to ~ from, unless a path relation already writes that
line. A comment follows on the product term, which has to be added by hand:
to ~ x:from for an observed predictor x, and
lavaan::sam() or the modsem package when the variables are latent.
The propositions form the graph that tf_implications() reads. Two of its
constructs that are both exogenous, with no proposition pointing into
either, or both terminal, with neither pointing to another construct, are
unrelated by the theory's account unless an association joins them. By
default, lavaan::sem() frees the covariance of two exogenous latent
variables and of two terminal variables, and takes that of two exogenous
observed variables from the data. A fit with those defaults could not refute
the claim. In the modality-switching example, two of the six independencies
tf_implications() derives would go untested. The syntax therefore ends
with a block that fixes each such covariance at zero (a ~~ 0*b), and
deleting the block restores lavaan's defaults. A pair with a moderator keeps
those defaults, because the product term changes the moderator's role.
lavaan takes the covariances of observed exogenous variables from the data
only until a covariance line names one of them. It then treats that variable
as random and fixes at zero each of its covariances that the syntax does not
write. Where a zero line names such a variable, the block therefore ends by
freeing each covariance between two observed exogenous variables that no
association names, when either is a moderator (x ~~ m). The moderator
then keeps lavaan's defaults.
Before fitting
The syntax is a starting point for a fit. Indicator names are the sanitised
measurement entries and must match columns of the data, so entries written
as column names, such as heart_rate, give syntax that fits as it
stands. A comment lists each construct with a single indicator, whose
residual variance lavaan::sem() fixes at zero, so the construct is
treated as measured without error. A comment flags each feedback loop. A
non-recursive model may not be identified (Bollen, 1989), and the
panic-network example is not, so check identification before fitting. Some
constructs have to be re-specified by hand. A manipulation is better entered
as a coded observed variable and a categorical predictor with more than two
levels as dummy variables. A covariate that a measurement entry only
describes needs a variable of its own. Once the block names an observed
predictor, a product term added by hand needs a free covariance with each
observed exogenous variable that a covariance line names. lavaan fixes each
one left unwritten at zero, and each takes a line of its own
(x:m ~~ x).
Names
Every name is one lavaan reads as written. Construct ids that lavaan would
refuse or misread, such as self-efficacy, 1arousal, NA
or its own keyword efa, are renamed. A comment after the header
records each renaming
(# renamed for lavaan: 'self-efficacy' -> self_efficacy). An
indicator is its measurement entry folded and lower-cased, with each run of
other characters made one underscore. i_ goes in front when the
result would still be refused, so 7-point Likert rating gives
i_7_point_likert_rating. A comment writes each control character of
an id, and each character outside the Basic Multilingual Plane, as
<U+XXXX>, so that it stays one line that lavaan reads as a comment.
The function stops when two different ids would share a name, since lavaan would merge them. Such a pair is two constructs, two indicators of one construct or a construct and an indicator. A construct and an indicator collide when the construct is measured by its own name or named like an indicator of another construct. An indicator shared by two constructs, a cross-loading, is allowed.
References
Bollen, K. A. (1989). Structural equations with latent variables. Wiley. doi:10.1002/9781118619179
See Also
tf_implications() for the independencies the zero block encodes.
Examples
# Measurement entries written as column names give syntax that fits as it
# stands. Threat and avoidance both follow from arousal alone, so the
# syntax fixes the covariance of their disturbances at zero.
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.",
measurement = c("heart_rate", "arousal_rating")) |>
tf_add_construct("c_threat", "Perceived threat", "Appraised danger.",
measurement = "threat_rating") |>
tf_add_construct("c_avoidance", "Avoidance", "Withdrawal from the trigger.",
measurement = c("avoidance_task", "avoidance_diary")) |>
tf_add_proposition("p1", "c_arousal", "c_threat", "increases") |>
tf_add_proposition("p2", "c_arousal", "c_avoidance", "increases")
cat(tf_compile_sem(theory))
Render a diagram intermediate representation
Description
Produces a deterministic diagram IR string for the requested type. The
engine argument is accepted but has no effect, because the IR is
engine independent (Graphviz DOT for the six digraph views, dagitty syntax
for the causal DAG and SVG for the venn, rigour and
severity views).
Usage
tf_diagram(theory, type = "nomological_net", engine = "graphviz")
Arguments
theory |
A theory object (named list). |
type |
One of |
engine |
Rendering engine label, accepted but unused (default
|
Details
The causal DAG is read by dagitty and drawn by the apps with Graphviz.
It writes a construct id bare only when the id is made of ASCII letters,
digits and underscores, does not begin with a digit and is not a DOT keyword.
The keywords are node, edge, graph, digraph,
subgraph and strict, in any case. Any other id is
double-quoted, with a double quote inside it escaped by a backslash, so
self-efficacy stays one node, which dagitty would otherwise read as
two. The view stops when it would write the id node or graph,
which dagitty refuses even quoted.
The pipeline and workflow views give every test outcome a node of its own.
The first outcome of a prediction is result_<id> (outcome_<id> in the
workflow) and each later one result_<id>#<k> (outcome_<id>#<k>), where
<k> counts the prediction's outcomes in file order, so a failed
replication is not merged into an earlier pass. When a prediction has
several outcomes, each label also carries the outcome's date.
The development_roadmap and rigour views score the checklist,
so they stop, as tf_check() does, when a test outcome's passed is
present and not TRUE or FALSE, or when a prediction's
severity is not a finite number from 0 to 1.
Value
A single string ending in a newline: Graphviz DOT for the digraphs,
dagitty syntax for the causal DAG and SVG for the venn,
rigour and severity views.
Examples
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.") |>
tf_add_construct("c_threat", "Perceived threat", "Appraised danger.") |>
tf_add_proposition("p1", "c_arousal", "c_threat", "causes")
cat(tf_diagram(theory, "nomological_net"))
cat(tf_diagram(theory, "causal_dag"))
Render a theory audit dossier (Markdown)
Description
Assembles a reviewer-facing audit bundle: the header, the rigour-checklist table, the severity list, the test record, the evidence, the provenance list and the appended preregistration document. The output is deterministic, so the same theory always yields the same dossier.
Usage
tf_dossier(theory)
Arguments
theory |
A theory object (named list), such as one from |
Details
The header gives the checklist version, the aggregate score, the checklist
coverage, the gate and the blockers that failed. The rigour table prints
n/a for an item with nothing to assess. The severity list gives each
prediction's claim-form rubric values and, when the prediction declares a
severity, that value too, with a note when it exceeds the rubric by more
than 0.2. The test record lists every test outcome in file order, with what
it found and the observation, date and registration it records, and with
the post-data severity of tf_post_data_severity() where it can be
computed, an open bound written as -inf or inf. The
evidence lists the prediction each entry supports, its direction and its
DOI. The implied independencies appear once, in the preregistration.
It stops, as tf_check() does, when a test outcome's passed is
present and not TRUE or FALSE, or when a prediction's
severity is not a finite number from 0 to 1.
Value
The dossier Markdown as a single string (LF line endings, single trailing newline).
Examples
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.") |>
tf_add_construct("c_threat", "Perceived threat", "Appraised danger.") |>
tf_add_proposition("p1", "c_arousal", "c_threat", "causes",
mechanism = "Activation raises salience of threat cues.") |>
tf_add_prediction("h1", "Effect is exactly 0.30.", "point")
cat(tf_dossier(theory))
Embedding-based pairwise construct-redundancy screen
Description
For every unordered pair of constructs, embeds each definition with the
supplied embedder and computes the cosine similarity (rounded to 6
decimals). The vectors of every compared pair must be of equal, nonzero
length, or the pair is refused. Returns a data frame sorted by descending
cosine then (a, b), flagging pairs at or above threshold for
review. This assistive screen complements the deterministic lexical
tf_redundancy_check(), and its results are only as reproducible as the
supplied embedder.
Usage
tf_embedding_redundancy(theory, embedder, threshold = NULL)
Arguments
theory |
A theory object (named list), such as one from |
embedder |
A function mapping a definition string to a numeric vector. |
threshold |
Cosine threshold for the |
Value
A data frame with columns a, b, cosine and
flag.
Examples
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal", "bodily activation") |>
tf_add_construct("c_threat", "Threat", "appraised danger")
# A toy deterministic embedder: bag-of-words counts over a fixed vocabulary.
vocab <- c("bodily", "activation", "appraised", "danger")
embedder <- function(def) {
words <- strsplit(tolower(def), "\\s+")[[1]]
vapply(vocab, function(w) sum(words == w), numeric(1))
}
tf_embedding_redundancy(theory, embedder)
Names of the packaged example files
Description
The bundled set is four example theories and two literature corpora, which
tf_read_corpus() reads. panic-corpus.yaml is a small corpus designed
to fall into four themes, and openalex-panic-2026.corpus.yaml holds
150 works fetched from OpenAlex and saved.
Usage
tf_example_names()
Value
A sorted character vector of the .yaml file names. The Python
package's example_names() lists the same files.
Examples
tf_example_names()
Path to a packaged example file
Description
Path to a packaged example file
Usage
tf_example_path(name)
Arguments
name |
File name, for example |
Value
The path to the installed file. A name that matches no
installed file stops with an error that lists the names
tf_example_names() returns.
Examples
tf_read(tf_example_path("panic-network.theory.yaml"))$id
Build a corpus from the OpenAlex API (network call)
Description
Assistive helper that builds a corpus by querying the OpenAlex works API
(https://api.openalex.org/works?search=...). This is a network call
to a live service whose results change over time, so it is not part of the
package's deterministic core. Each work is mapped to
{id, doi, title, year, keywords, references}, with the DOI as OpenAlex
gives it (keywords falls back to the first five concepts when no keywords
are present).
Usage
tf_fetch_corpus(
query,
per_page = 25,
mailto = NULL,
api_key = Sys.getenv("OPENALEX_API_KEY", ""),
max_records = NULL
)
Arguments
query |
Free-text search query. |
per_page |
Number of works to request in each page (default |
mailto |
Optional contact email. It is still sent, but OpenAlex now ignores it, since API keys replaced the polite pool it once selected. |
api_key |
An OpenAlex API key, by default the |
max_records |
Number of works to collect, paging as needed.
|
Details
OpenAlex returns the works that match a search in pages of per_page,
ranked by relevance, and a search usually matches far more works than one
page holds. A max_records above per_page pages on through
OpenAlex's cursor until that many works are collected or the results run
out. Paging needs an API key: without one, OpenAlex serves the first page
and refuses the next with HTTP 401, so the function stops and keeps none of
the works already fetched. By default, max_records equals
per_page, so one request is made, which works without a key. Each
page is one request and costs USD 0.001. OpenAlex allows USD 0.10 a day
without a key, about 100 one-page searches, and USD 1 with a free key. When
OpenAlex refuses a request, as it does with HTTP 429 once the budget is
spent and with HTTP 401 when a later page is asked for without a key, the
function stops with the status and, when the suggested curl package
is installed, OpenAlex's own message. The request is not retried. Every
request is abandoned after 30 seconds.
The arguments are checked before any request. per_page must be a
whole number from 1 to 200 and max_records a positive whole number,
and api_key, unless NULL, must be a single string that holds
only visible ASCII characters once the spaces, tabs and line breaks around it
are trimmed.
The corpus records where, when and how it was fetched in source. It
gives the service, endpoint and query and the UTC time of retrieval
(retrieved), then the number of works that matched
(total_count), the number kept (n_records), the page size and
the order (sort). The date matters because the keywords change.
Since late September 2026, OpenAlex has written each work's keywords with a
language model that reads its title, abstract and venue. It merges and
splits that vocabulary over time. Works without keywords fall back to their
concepts, a deprecated vocabulary with capitalised names that do not match
the lower-case keywords in tf_litmap(). Save a fetched corpus and work
from the saved file.
Value
A corpus object (named list) with schema_version, id,
source and records.
Examples
## Not run:
# With OPENALEX_API_KEY set, for example in .Renviron, the key is sent in a
# request header.
corpus <- tf_fetch_corpus("panic disorder interoception",
per_page = 100, max_records = 400)
corpus$source
# null = "null" writes a missing DOI or count as null, where jsonlite would
# write an empty object.
path <- tempfile(fileext = ".json")
jsonlite::write_json(corpus, path, auto_unbox = TRUE, null = "null")
corpus <- tf_read_corpus(path)
## End(Not run)
Derive a theory's implied conditional independencies
Description
Reads every proposition through the package's relation table. A directed
relation ("increases", "decreases",
"causes", "mediates" or "moderates") is an edge from
from to to, and "associates" is a bidirected edge,
covariance the theory leaves unexplained, as a latent common cause of the two
constructs would. The constructs that a directed relation names are the
vertices, and an association is an edge only between two of them. The
function then takes every pair of vertices that no edge joins. The pair is
stated independent given the parents of both when those m-separate it
(Richardson, 2003), and otherwise given all the other ancestors of the two
when those do. A pair that neither set separates is separated by no set of
constructs (Richardson & Spirtes, 2002, Theorem 4.2), so the theory implies
no independence for it, and it is listed under inseparable. These are
the conditional independencies the causal graph implies, each one a claim
that data could refute. When every relation is directed and the graph is
acyclic, they are the basis set of Pearl (1988) and Shipley (2000), from
which every other independence the graph implies follows.
Usage
tf_implications(theory, cycles = "refuse")
Arguments
theory |
A theory object (named list), such as one from |
cycles |
What to do with a graph whose directed edges form a cycle:
|
Details
Constructs that no directed relation names are left out, because silence about a construct is not a claim that it is independent of anything, and so are constructs without an id, which no proposition can name. A construct named only by associations would be a collider on every path through it, so leaving it out loses no statement about the others. A theory with no directed relations therefore comes back with no vertices and no error.
Value
A named list
list(theory_id, criterion, acyclic, constructs, n_edges,
n_bidirected, feedback, implications, n_implications, inseparable).
criterion names the separation criterion, "m" under
cycles = "refuse" and "sigma" under cycles = "sigma".
constructs holds the vertices in file order. n_edges counts
the directed edges the theory states and n_bidirected the
bidirected ones, a pair stated twice counting once, before any
acyclification. feedback lists the feedback loops, each a list of
the ids of its members in file order and the loops in the order of their
first members. A loop has two or more members, or one construct with an
edge to itself. acyclic is TRUE when feedback is
empty, which is always the case under cycles = "refuse", and both
are carried so that a serialised record states the verdict. Each entry of
implications is a list
list(a, b, given, statement), where statement renders the
claim as a _||_ b | z1, z2, and each entry of inseparable is
list(a, b). Pairs come in construct file order, as do the members of
given.
Measurement
The statements concern constructs, and a study measures them with error.
Error in a conditioning construct leaves part of the dependence that holding
it fixed should remove. A conditional statement tested on observed scores is
therefore rejected too often, and more often the larger the sample (Westfall
& Yarkoni, 2016). Take a chain whose two paths have standardised
coefficients of .5, with the middle construct measured at a reliability of
.8. A partial-correlation test at the 5 per cent level then rejects the true
statement in about 14, 29 and 51 per cent of studies of 200, 500 and 1,000
observations. Conditional statements are better tested with latent-variable
models, which take the measurement error into account (Westfall & Yarkoni,
2016). The measurement model that tf_compile_sem() writes is one starting
point, and each statement can be tested in it separately (Thoemmes et al.,
2018).
Feedback loops
With cycles = "sigma", a graph whose directed edges form a cycle is
read by sigma-separation (Bongers et al., 2021), the criterion that holds
when each feedback loop, a strongly connected component of the directed
edges, has a unique equilibrium. The graph is replaced by its
acyclification (Definition A.13): every member of a loop takes the parents
of the whole loop from outside it, and the members of a loop are joined to
each other by bidirected edges. Each pair the theory leaves unjoined is then
tested in that graph as above, where m-separation equals sigma-separation in
the theory's own graph (Proposition A.19). There, two members of one loop
are always joined. So is a construct outside a loop to every member, when it
enters one of them or when it or a member of its own loop is associated with
one of them. No set separates such a pair, and when the theory itself leaves
the pair unjoined, it is listed under inseparable. A theory that
posits alternative stable states, such as a bistable network, has more than
one equilibrium and violates the assumption, and its sigma statements are
not guaranteed. On an acyclic graph, the two options give the same
statements. Applying d-separation to a cyclic graph, as dagitty does with
the causal_dag export, is valid only in special cases such as a linear
model.
Refusals
The function stops in four cases. A value of cycles other than
"refuse" or "sigma" is refused before the theory is read. Two
constructs sharing an id would give one node two sets of parents, and a
directed relation naming an undeclared construct would shrink the graph and
so imply independencies the theory never claimed. With
cycles = "refuse", the default, a cycle among the directed edges is
refused too, and the message names a cycle that was found and the
"sigma" option.
References
Bongers, S., Forré, P., Peters, J., & Mooij, J. M. (2021). Foundations of structural causal models with cycles and latent variables. The Annals of Statistics, 49(5), 2885-2915. doi:10.1214/21-AOS2064
Pearl, J. (1988). Probabilistic reasoning in intelligent systems: Networks of plausible inference. Morgan Kaufmann.
Richardson, T. (2003). Markov properties for acyclic directed mixed graphs. Scandinavian Journal of Statistics, 30(1), 145-157. doi:10.1111/1467-9469.00323
Richardson, T., & Spirtes, P. (2002). Ancestral graph Markov models. The Annals of Statistics, 30(4), 962-1030. doi:10.1214/aos/1031689015
Shipley, B. (2000). A new inferential test for path models based on directed acyclic graphs. Structural Equation Modeling: A Multidisciplinary Journal, 7(2), 206-218. doi:10.1207/S15328007SEM0702_4
Thoemmes, F., Rosseel, Y., & Textor, J. (2018). Local fit evaluation of structural equation models using graphical criteria. Psychological Methods, 23(1), 27-41. doi:10.1037/met0000147
Westfall, J., & Yarkoni, T. (2016). Statistically controlling for confounding constructs is harder than you think. PLOS ONE, 11(3), e0152719. doi:10.1371/journal.pone.0152719
See Also
tf_diagram() with type = "causal_dag", which exports the
same graph as dagitty syntax without reading it, and the methodological
foundations article for the literature behind the causal-testability
criterion.
Examples
# A mediated chain commits the theory to one thing it does not state
# directly: arousal and avoidance are independent once threat is held fixed.
theory <- tf_theory("mediation", "A mediated chain") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.") |>
tf_add_construct("c_threat", "Perceived threat", "Appraised danger.") |>
tf_add_construct("c_avoidance", "Avoidance", "Withdrawal from the trigger.") |>
tf_add_proposition("p1", "c_arousal", "c_threat", "increases") |>
tf_add_proposition("p2", "c_threat", "c_avoidance", "increases")
implied <- tf_implications(theory)
implied$n_implications
implied$implications[[1]]$statement
# Stating that arousal and avoidance also covary for reasons the theory
# leaves open withdraws that claim: the pair is joined by an edge.
covary <- tf_add_proposition(theory, "p3", "c_arousal", "c_avoidance", "associates")
tf_implications(covary)$n_implications
# Closing a feedback loop from threat back to arousal makes the graph cyclic.
# The default refuses it, and sigma-separation keeps the claim, since holding
# threat fixed still cuts the one way out of the loop towards avoidance.
loop <- tf_add_proposition(theory, "p3", "c_threat", "c_arousal", "causes")
try(tf_implications(loop))
implied <- tf_implications(loop, cycles = "sigma")
lapply(implied$feedback, unlist)
implied$implications[[1]]$statement
Jaccard similarity of two token sets
Description
Returns 0.0 if both sets are empty and otherwise the size of the intersection divided by the size of the union, rounded to 3 decimals.
Usage
tf_jaccard(a, b)
Arguments
a, b |
Character vectors of tokens (treated as sets). |
Value
A numeric similarity in [0, 1].
Examples
tf_jaccard(tf_tokens("arousal threat response"),
tf_tokens("threat appraisal response"))
Map a theory and its alternatives onto a literature landscape (deterministic)
Description
Maps a theory's focal constructs and its registered alternatives onto the
thematic structure of a corpus (computed by tf_litmap()). Each theme is
tagged "under_theorised", "covered" or "crowded".
Usage
tf_landscape(
theory,
corpus,
min_link = 2,
max_token_share = 0.5,
method = "components"
)
Arguments
theory |
A theory object (named list), such as one from |
corpus |
A corpus object (named list), such as one from
|
min_link |
Minimum co-occurrence count passed to |
max_token_share |
A number from 0 to 1 (default |
method |
How |
Details
A theme is matched by the words its keywords share with the focal theory's
construct labels, or with an alternative's label and key constructs, and
every match reports those words (focal_terms and
alternative_terms). Three kinds of word never match. Field tokens,
the words most of the corpus shares, are those in the keywords of more than
max_token_share of the records. Phenomenon tokens are the words of
the theory's title, which names the phenomenon that the focal theory and its
rivals all explain. A construct word that also appears in the title does not
match either. The third kind is a fixed list of words that name a kind of
account: theory, model, account, hypothesis, framework and approach, with
their plurals. One shared word is enough for a match.
The statuses count the registered accounts, the focal theory and its
registered alternatives, that address a theme. A theme is
"under_theorised" when none of them addresses it, which says nothing
of accounts the theory does not register, "covered" when one does and
"crowded" when two or more do. A crowded theme calls for predictions
that discriminate between the accounts, and is not a finding of redundancy.
under_theorised_fronts lists the ids of the under-theorised themes,
and redundancy_risk, despite its name, the ids of the crowded ones.
The arguments are checked in the order min_link,
max_token_share, method, then the corpus. The themes are
those of tf_litmap(), built by method with its other defaults. With "components",
tf_landscape() gives the warning of tf_litmap() when one theme
holds most of the linked keywords. With "simple_centres", the result
gains method after theory_id, and each theme its
centrality, density and quadrant.
Value
A named list with elements theory_id,
max_token_share, field_tokens, phenomenon_tokens,
themes, under_theorised_fronts and redundancy_risk.
Each theme holds id, keywords, alternatives,
focal, status, focal_terms and
alternative_terms, the last a list of {id, terms} in the
order of alternatives.
Examples
theory <- tf_theory("demo-1", "A theory of panic") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.")
corpus <- list(
schema_version = "1.0", id = "demo-corpus",
records = list(
list(id = "w1", keywords = list("arousal", "threat")),
list(id = "w2", keywords = list("arousal", "threat")),
list(id = "w3", keywords = list("avoidance", "exposure")),
list(id = "w4", keywords = list("avoidance", "exposure"))
)
)
tf_landscape(theory, corpus)
Render a literature-layer diagram intermediate representation
Description
Produces a deterministic DOT string for the literature layer.
Usage
tf_lit_diagram(obj, type = "keyword_cooccurrence", max_edges = NULL)
Arguments
obj |
A |
type |
One of |
max_edges |
A positive integer that caps a
|
Value
A single string ending in a newline.
Examples
corpus <- list(
schema_version = "1.0", id = "demo-corpus",
records = list(
list(id = "w1", keywords = list("arousal", "threat")),
list(id = "w2", keywords = list("arousal", "threat")),
list(id = "w3", keywords = list("avoidance", "exposure")),
list(id = "w4", keywords = list("avoidance", "exposure"))
)
)
cat(tf_lit_diagram(tf_litmap(corpus), "keyword_cooccurrence"))
# On a large map, draw only the strongest edges.
fixture <- tf_read_corpus(system.file("fixtures", "panic-corpus.yaml",
package = "theoryforge"))
cat(tf_lit_diagram(tf_litmap(fixture), "co_citation", max_edges = 1))
Bibliometric map of a literature corpus (deterministic)
Description
Computes keyword co-occurrence, thematic components and reference co-citation for a corpus. Records are read in file order.
Usage
tf_litmap(
corpus,
min_link = 2,
method = "components",
min_cocitation = NULL,
min_theme_size = 2,
max_theme_size = 10,
max_df = 1
)
Arguments
corpus |
A corpus object (named list), such as one from
|
min_link |
Minimum co-occurrence count for a keyword pair to be kept
(default |
method |
|
min_cocitation |
Minimum count for a reference pair to be kept in
|
min_theme_size, max_theme_size |
The smallest theme kept (default
|
max_df |
A number from 0 to 1 (default |
Details
The corpus is checked before anything is counted. It must hold a
records list of mappings (an empty list is an empty corpus). A
keyword or reference that is an integer becomes its decimal string, so an
unquoted PubMed or Scopus id keys the same work in R and in Python. One of
2^{53} or more is refused, since R cannot hold every such integer
exactly. A logical, a fraction or a nested value is
refused: an unquoted NO (nitric oxide) or on in YAML is read
as a logical, so quote it.
A reference that holds a DOI is keyed by the DOI, lower-cased and without
its resolver prefix, as tf_new_evidence_dois() compares DOIs. One work
cited as 10.1016/J.BRAT.2015.10.002 in one record and as
https://doi.org/10.1016/j.brat.2015.10.002 in another is therefore
one node, labelled 10.1016/j.brat.2015.10.002. Any other reference,
such as a Scopus or OpenAlex identifier, is compared exactly as written, and
so is every keyword.
Co-citation maps of real corpora are large. 200 OpenAlex records give about
11,000 reference pairs that share two or more citing records, so
min_cocitation can be set above min_link, and
tf_lit_diagram() can draw only the strongest edges.
method chooses how keywords are grouped into themes. With
"components", the default, a theme is a connected component of the
keyword map, and on a real corpus one or a few keywords shared by most
records join nearly every keyword into one. When the largest theme holds more
than half the linked keywords, a warning says so: such themes, and any
landscape built on them, do not describe the field. The result is returned
unchanged.
"simple_centres" is the co-word clustering of Coulter et al. (1998)
and Cobo et al. (2011). Each link is weighted by the equivalence index
c^2 / (df_a df_b), where c counts the records holding both
keywords and df the records holding each. The strongest link between
two unassigned keywords seeds a theme, which takes its strongest unassigned
neighbour until it holds max_theme_size keywords, ties going to the
keyword first in code-point order. A keyword whose links all reach keywords
already in themes joins none. Themes smaller than min_theme_size are
dropped. Each theme gains its centrality (ten times the summed index of its
links to the keywords of other themes) and its density (100 times the
summed index of its internal links, over its size), the measures
of Callon et al. (1991) as Cobo et al. (2011) scale them. It also gains its
quadrant in the strategic diagram, split here at the median of each:
"motor" (both high), "basic" (central but not dense),
"niche" (dense but not central) or "emerging_or_declining"
(both low). On real corpora, this gives bounded themes where components give
one. Components remain the default for this release.
Value
A named list with elements n_records, keywords (the
distinct keywords, sorted), keyword_cooccurrence (one
list(a, b, count) per kept pair, a sorting before b,
in (a, b) order), themes (one list(id, keywords, size)
per theme, numbered theme_1, theme_2, ... in the order of
their first keyword) and co_citation (as
keyword_cooccurrence, over the reference keys). With
"simple_centres", each theme also holds centrality,
density and quadrant, and the list ends with
method, parameters (the five settings used) and
field_terms.
References
Callon, M., Courtial, J. P., & Laville, F. (1991). Co-word analysis as a tool for describing the network of interactions between basic and technological research: The case of polymer chemistry. Scientometrics, 22(1), 155-205. doi:10.1007/BF02019280
Coulter, N., Monarch, I., & Konda, S. (1998). Software engineering as seen through its research literature: A study in co-word analysis. Journal of the American Society for Information Science, 49(13), 1206-1223. doi:10.1002/(SICI)1097-4571(1998)49:13<1206::AID-ASI7>3.0.CO;2-F
Cobo, M. J., López-Herrera, A. G., Herrera-Viedma, E., & Herrera, F. (2011). An approach for detecting, quantifying, and visualizing the evolution of a research field: A practical application to the Fuzzy Sets Theory field. Journal of Informetrics, 5(1), 146-166. doi:10.1016/j.joi.2010.10.002
Examples
corpus <- list(
schema_version = "1.0", id = "demo-corpus",
records = list(
list(id = "w1", keywords = list("arousal", "threat")),
list(id = "w2", keywords = list("arousal", "threat")),
list(id = "w3", keywords = list("avoidance", "exposure")),
list(id = "w4", keywords = list("avoidance", "exposure"))
)
)
tf_litmap(corpus)
# Simple centres on the frozen OpenAlex corpus, where components give one
# theme.
openalex <- tf_read_corpus(tf_example_path("openalex-panic-2026.corpus.yaml"))
lm <- tf_litmap(openalex, method = "simple_centres")
table(vapply(lm$themes, function(th) th$quadrant, character(1)))
DOIs not already cited by a theory (deterministic)
Description
Compares each DOI in candidate_dois against the theory's
evidence[].source_doi and alternatives[].source_doi fields, by
normalised form, so a fresh literature search, for example via OpenAlex,
Scopus or any other source, can be checked against what the theory already
engages with. The normalised form is the DOI itself, trimmed, lower-cased
(ASCII letters only) and percent-decoded, wherever it sits in the text, so
doi: 10..., DOI 10..., doi.org/10...,
https://www.doi.org/10... and a URL with %2F all match the
bare DOI, and trailing full stops, commas and semicolons are dropped.
Returns the qualifying DOIs in their original form, deduplicated and sorted
by normalised form. The function is deterministic and makes no network
call. The search itself is left to whichever literature tool the caller
prefers.
Usage
tf_new_evidence_dois(theory, candidate_dois)
Arguments
theory |
A theory object (named list), such as one from |
candidate_dois |
Character vector of DOIs to check. |
Value
A character vector of the candidate DOIs not already cited, deduplicated and sorted.
Examples
# The bundled panic theory cites one DOI as evidence and one for each of its
# two registered alternatives. All three count as already cited.
theory <- tf_read(system.file("fixtures", "panic-network.theory.yaml",
package = "theoryforge"))
tf_new_evidence_dois(theory, c(
"10.1016/j.brat.2015.10.002", # cited as evidence
"https://doi.org/10.1016/0005-7967(86)90011-2", # an alternative, in URL form
"https://doi.org/10.1037/0033-2909.99.1.20" # not yet cited
))
Deposit a theory's audit dossier to OSF storage
Description
Builds (and optionally sends) a request to upload tf_dossier(theory) to
OSF storage. With dry_run = TRUE (the default), the planned request
is returned and nothing is sent. A live upload (dry_run = FALSE) requires
both token and node (the OSF project id) and performs an
authenticated PUT through the suggested curl package, which must
be installed. Each request is abandoned after 30 seconds. The dossier is
built first, so the
function stops when tf_check() refuses the theory, with
dry_run = TRUE as well.
Usage
tf_osf_push(
theory,
token = NULL,
node = NULL,
filename = NULL,
dry_run = TRUE,
base_url = .tf_OSF_BASE,
overwrite = FALSE
)
Arguments
theory |
A theory object (named list), such as one from |
token |
OSF personal access token (required when |
node |
OSF project (node) id, used to build the upload URL and required
when |
filename |
Destination filename. It defaults to |
dry_run |
When |
base_url |
OSF storage base URL, by default
|
overwrite |
When |
Details
OSF storage refuses to create a file whose name already exists in the
project folder (HTTP 409), so depositing the same theory twice under the
default filename fails. Pass a version-specific filename, or
overwrite = TRUE to add a new version of the existing file: the
folder is listed first and the dossier is sent to that file's upload link,
the WaterButler route that records a new OSF version. When the folder holds
no file of that name, overwrite = TRUE creates it as usual.
Value
When dry_run = TRUE, a list list(dry_run = TRUE,
request = list(method, url, filename, content_bytes), note), with a
lookup = list(method = "GET", url) entry before note when
overwrite = TRUE. When dry_run = FALSE, list(dry_run =
FALSE, status, filename) for the completed upload. A status outside 2xx
stops with OSF upload failed with HTTP <status>, so a refused upload
is never returned as a completed one.
Examples
theory <- tf_theory("demo-1", "A demonstration theory")
tf_osf_push(theory)
tf_osf_push(theory, node = "abc12")$request$url
tf_osf_push(theory, node = "abc12", overwrite = TRUE)$lookup
Post-data severity of each bounded prediction
Description
How severely each bounded claim passed its test, from the test outcome's estimate and standard error.
Usage
tf_post_data_severity(theory)
Arguments
theory |
A theory object (named list), such as one from |
Details
A prediction states the region its claim allows in bounds, a mapping
of lower and upper, either of which may be null (or infinite)
for an open side. A test outcome records the estimate it observed and
its standard error se. For an outcome with both, whose prediction
declares bounds, the severity with which the claim passed is the smallest of
\Phi((estimate - lower) / se) and
\Phi((upper - estimate) / se) over the
finite bounds, rounded to three decimals (Mayo & Spanos, 2006, 2011). It is
the probability that the test would have given a result less in accord with
the claim, had the claim been false at the bound. A one-sided claim, such as
an effect above a smallest effect of interest, is a lower bound with the
upper one open.
The computation is a normal approximation to the sampling distribution of
the estimate. With two finite bounds, the value equals 1 minus the p value of
the two one-sided tests (TOST) of equivalence. A point claim with lower equal
to upper can pass with a severity of at most 0.5, so it needs a tolerance
around its value. Unlike tf_severity(), which grades the form of a claim
before any data, this value depends on the design and the data. The rigour
checklist does not read it. tf_dossier() gives each value in its test
record.
The function stops at the first outcome, in file order, that cannot be
read, with one of these messages:
post_data_severity requires both estimate and se; test_outcome[<i>],
... requires a finite se greater than 0; ... and
... requires a finite estimate; ..., and for its prediction's bounds
... requires bounds with numeric or null lower and upper; prediction '<id>',
... requires at least one finite bound; ... and
... requires lower <= upper; .... tf_validate() with full = TRUE
reports each of these.
Value
A data.frame with one row per test outcome, in file order,
that carries both an estimate and a standard error and whose prediction
declares bounds. Its columns are prediction_id, outcome (the
outcome's 0-based index among the test outcomes), lower and
upper (NA for an open bound), estimate, se and
severity.
References
Mayo, D. G., & Spanos, A. (2006). Severe testing as a basic concept in a Neyman-Pearson philosophy of induction. The British Journal for the Philosophy of Science, 57(2), 323-357. doi:10.1093/bjps/axl003
Mayo, D. G., & Spanos, A. (2011). Error statistics. In P. S. Bandyopadhyay & M. R. Forster (Eds.), Philosophy of statistics (pp. 153-198). Elsevier. doi:10.1016/B978-0-444-51862-0.50005-8
Examples
theory <- tf_read(tf_example_path("modality-switching.theory.yaml"))
tf_post_data_severity(theory)
# A claim that |r| <= .10, tested with an estimate of 0 and a standard error
# of .10, passes with a severity of .841.
theory$predictions[[4]]$bounds <- list(lower = -0.10, upper = 0.10)
theory$test_outcomes <- list(list(prediction_id = "pred4", passed = TRUE,
estimate = 0, se = 0.10))
tf_post_data_severity(theory)
Render the hypotheses section of a preregistration
Description
Produces a deterministic preregistration Markdown string for a theory and,
if path is given, writes it (LF, single trailing newline).
Usage
tf_preregister(theory, path = NULL)
Arguments
theory |
A theory object (named list), such as one from |
path |
Optional destination path. When it is given, the Markdown is written with LF line endings. |
Details
The header gives the theory id, the version when it has an id (with its
parent, when one is named), the schema version, the maturity and whether
every prediction's derivation references resolve: yes, no or
not applicable (no predictions). The derivation line reports the
checklist's reference check, which does not show that a prediction follows
from the propositions it cites.
Each hypothesis is listed in file order with its claim type, statement and
derivation, followed by the auxiliary assumptions that protect it
(core or added for <id>), the registered rivals it discriminates and its
test record. A hypothesis that a recorded outcome has already tested reads
already tested: passed (<date>, registered <where>), one entry per
outcome, and any other reads untested.
When at least one prediction states a sampling plan in its test
block, a section headed Sampling plan (author-recorded; not scored)
follows, with one line per prediction in file order. A line gives what is
recorded of the planned sample, alpha and sidedness, smallest effect of
interest, power or decision probability, design analysis and justification.
A prediction without a plan reads no sampling plan stated. Nothing scores
the plan: power does not raise a claim's severity (Meehl, 1967), though it
decides how informative a failed test is (Lakens, 2022). A theory without a
plan has no such section.
A section then lists the conditional independencies that
tf_implications() derives from the causal graph with its default
settings, which are claims the theory makes without stating them, or says
why there are none. The claim-form severity rubric closes the document.
The document is the part of a preregistration that the theory file holds. It is to be completed with the study design, the analysis plan, the inference criteria and whatever the sampling plan leaves out, the sections that a template such as PRP-QUANT asks for (Bosnjak et al., 2022).
It stops, as tf_check() does, when a test outcome's passed is
present and not TRUE or FALSE, or when a prediction's
severity is not a finite number from 0 to 1, and then writes nothing.
Value
The preregistration Markdown as a single string.
References
Bosnjak, M., Fiebach, C. J., Mellor, D., Mueller, S., O'Connor, D. B., Oswald, F. L., & Sokol, R. I. (2022). A template for preregistration of quantitative research in psychology: Report of the joint psychological societies preregistration task force. American Psychologist, 77(4), 602-615. doi:10.1037/amp0000879
Lakens, D. (2022). Sample size justification. Collabra: Psychology, 8(1), Article 33267. doi:10.1525/collabra.33267
Meehl, P. E. (1967). Theory-testing in psychology and physics: A methodological paradox. Philosophy of Science, 34(2), 103-115. doi:10.1086/288135
Examples
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_prediction("h1", "Effect is exactly 0.30.", "point")
cat(tf_preregister(theory))
Read a theory object from a YAML or JSON file
Description
Reads a theory object authored as YAML (or JSON, chosen by file extension) into a named list.
Usage
tf_read(path)
Arguments
path |
Path to a |
Details
The file is read as the Python package's theoryforge.read() reads
it. The text is UTF-8, and a byte-order mark is ignored. A YAML or JSON
sequence is always a list, even with one element, so tf_validate() refuses
maturity: [draft].
Unquoted y, Y, n and N stay strings, as do
dates, while yes, no, true, false, on and
off are logicals. Integers are decimal, octal or hexadecimal only, so
1:30 and 1_000 are strings, and so is a number written with a
comma (1,000). An integer too large for an R integer is read as a
double. A merge key (<<) lets the mapping's own keys win. A key
repeated in any mapping, in YAML or JSON, stops with
(<path>) Duplicate map key: '<key>'. A document that is not a
mapping, such as a sequence or an empty YAML file, stops with
Theory data must be a mapping.
Value
A named list holding the parsed theory object.
Examples
# Round-trip a theory through a temporary file.
theory <- tf_theory("demo-1", "A demonstration theory")
path <- tempfile(fileext = ".yaml")
tf_write(theory, path)
tf_read(path)
Read a literature corpus from a YAML or JSON file
Description
Reads a corpus object ({schema_version, id, records}) into a named
list. The file extension sets the format: JSON for .json and YAML
otherwise. The file is read by the rules that tf_read() follows, so an
unquoted keyword such as y or n stays a string and a repeated
key is refused. A document that is not a
mapping stops with Corpus data must be a mapping. The records
themselves are checked by tf_litmap() and tf_landscape().
Usage
tf_read_corpus(path)
Arguments
path |
Path to a |
Value
A named list holding the parsed corpus object.
Examples
corpus <- list(
schema_version = "1.0", id = "demo-corpus",
records = list(
list(id = "w1", keywords = list("arousal", "threat")),
list(id = "w2", keywords = list("arousal", "threat"))
)
)
path <- tempfile(fileext = ".json")
jsonlite::write_json(corpus, path, auto_unbox = TRUE)
tf_read_corpus(path)
Pairwise lexical similarity of construct definitions
Description
Compares the definitions of every unordered pair of constructs and returns
a data frame with one row per pair, sorted by descending similarity then
(a, b) ascending. similarity is the Jaccard index of the two
definitions' token sets and overlap their overlap coefficient, the
shared tokens over the tokens of the shorter definition. flag is
"review" for a near-duplicate, a similarity at or above the
checklist's redundancy_similarity_max, and for a definition contained
in the other, an overlap at or above redundancy_overlap_max when both
definitions hold at least three tokens. It is "ok" otherwise.
Usage
tf_redundancy_check(theory)
Arguments
theory |
A theory object (named list). |
Details
The screen compares words, so it cannot detect empirical redundancy, two differently defined constructs that correlate almost perfectly once measurement error is corrected for (Le et al., 2010). Sibling constructs (Lawson & Robins, 2021) may share vocabulary without being redundant.
Value
A data frame with columns a, b, similarity,
overlap and flag.
References
Le, H., Schmidt, F. L., Harter, J. K., & Lauver, K. J. (2010). The problem of empirical redundancy of constructs in organizational research: An empirical investigation. Organizational Behavior and Human Decision Processes, 112(2), 112-125. doi:10.1016/j.obhdp.2010.02.003
Lawson, K. M., & Robins, R. W. (2021). Sibling constructs: What are they, why do they matter, and how should you handle them? Personality and Social Psychology Review, 25(4), 344-366. doi:10.1177/10888683211047101
Examples
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal",
"Bodily activation in response to a stressor.") |>
tf_add_construct("c_threat", "Perceived threat",
"Appraised danger in response to a stressor.")
tf_redundancy_check(theory)
Render a diagram in the viewer or as SVG
Description
Renders a digraph view of a theory without leaving R. Where tf_diagram()
returns the deterministic Graphviz DOT string, tf_render_diagram() passes
that string to the DiagrammeR engine and returns either an interactive
widget, which displays in the RStudio viewer and in R Markdown documents, or
a standalone SVG string, ready to embed in a page or save to a file.
Usage
tf_render_diagram(x, type = "nomological_net", as = c("widget", "svg"))
Arguments
x |
A theory object (named list), or a diagram IR string from
|
type |
The diagram type, as in |
as |
Either |
Details
The three chart views (venn, rigour and severity) are already SVG, so
they are returned as-is under as = "svg" and wrapped for display under
as = "widget". The causal_dag view emits dagitty syntax rather than DOT,
so it is not rendered here. Paste it into a dagitty tool or the dagitty R
package instead.
The DOT views need the suggested DiagrammeR package, and as = "svg"
also needs DiagrammeRsvg. The chart views need neither, but showing one
under as = "widget" needs htmltools. A missing package stops with a
message naming it.
Value
With as = "widget", an htmlwidget for a DOT view, or a browsable
htmltools HTML object for the venn, rigour and severity views. With
as = "svg", a single SVG string.
See Also
tf_diagram() for the intermediate representation itself, which
needs no optional packages and is identical in R and in Python.
Examples
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.") |>
tf_add_construct("c_threat", "Perceived threat", "Appraised danger.") |>
tf_add_proposition("p1", "c_arousal", "c_threat", "causes")
tf_render_diagram(theory, "nomological_net")
Write a Quarto report for a theory
Description
Writes a standalone Quarto report to path (forced to a .qmd
suffix): a YAML header (title, format) followed by the
deterministic tf_dossier(theory) body. Returns the written path. When
render = TRUE, invokes quarto render, which requires a Quarto
installation, and stops if that render fails. It stops before writing
anything when tf_check() refuses the theory.
Usage
tf_render_report(theory, path, title = NULL, render = FALSE, to = "html")
Arguments
theory |
A theory object (named list), such as one from |
path |
Destination path. Any extension is replaced with |
title |
Optional report title. It defaults to
|
render |
When |
to |
Quarto output format (default |
Value
The path of the written .qmd file.
Examples
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.")
path <- tempfile(fileext = ".qmd")
tf_render_report(theory, path)
Render the rigour report as a string
Description
Renders the result of tf_check() as a string. format = "json"
returns valid, pretty-printed JSON. format = "html" returns an HTML
fragment in which every interpolated value is escaped. Any other
format stops, and so does a theory that tf_check() refuses.
Usage
tf_report(theory, format = "json")
Arguments
theory |
A theory object (named list). |
format |
One of |
Value
A single string.
Examples
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.") |>
tf_add_prediction("h1", "Arousal precedes threat appraisal.", "point")
cat(tf_report(theory, format = "json"))
Set the formal model (BUILDING mode)
Description
Set the formal model (BUILDING mode)
Usage
tf_set_formal_model(theory, type, spec_ref = NULL)
Arguments
theory |
A theory object (named list). |
type |
Formal-model type, one of |
spec_ref |
Optional reference to the model specification. |
Value
The (mutated) theory object.
Examples
tf_theory("demo-1", "A demonstration theory") |>
tf_set_formal_model("ode", spec_ref = "models/panic.ode")
Per-prediction claim-form riskiness
Description
A pre-data rubric of the form of each prediction's claim. risk_score
is the base riskiness of the declared type: existence 0.1, directional 0.4,
interval 0.7 and point 0.9. computed_severity discounts a directional
prediction by 25 per cent, adds 0.1 when diagnostic_vs names a
registered alternative and is capped at 1. The order of the types follows
Popper (1959, sections 31-33) for nested claims about one quantity, and the
directional penalty follows Meehl's (1967, 1990b) argument that a sign alone
risks little. The base values, the discount and the bonus are the package's
conventions, and neither source gives them.
Usage
tf_severity(theory)
Arguments
theory |
A theory object (named list), such as one from |
Details
How severely a claim is tested depends on the design and the data, which the rubric does not read. A prediction scores the same however it is tested, and a failed test leaves the value where it was.
Value
A data.frame with columns prediction_id, type,
risk_score and computed_severity, with one row per
prediction in file order.
References
Meehl, P. E. (1967). Theory-testing in psychology and physics: A methodological paradox. Philosophy of Science, 34(2), 103-115. doi:10.1086/288135
Meehl, P. E. (1990b). Why summaries of research on psychological theories are often uninterpretable. Psychological Reports, 66(1), 195-244. doi:10.2466/pr0.1990.66.1.195
Popper, K. R. (1959). The logic of scientific discovery. Hutchinson.
Examples
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_prediction("h1", "Effect is exactly 0.30.", "point") |>
tf_add_prediction("h2", "Effect is positive.", "directional")
tf_severity(theory)
Simulate a theory's construct network as a linear dynamical system
Description
Treats each construct (in file order) as a state variable and each
proposition whose relation is increases, decreases,
causes or mediates as a signed linear coupling term. It then
propagates dX/dt = A X - damping * X either with fixed-step (Euler)
updates or exactly, with the matrix exponential of
(A - damping * I) * dt. The result is deterministic. Construct ids
must be unique, and duplicates are refused rather than assigned to an
arbitrary state. A construct without an id is a state with no couplings, and
two of them do not count as duplicates.
Usage
tf_simulate(
theory,
steps = 10,
dt = 0.1,
k = 1,
damping = 0.5,
init = 1,
method = "euler"
)
Arguments
theory |
A theory object (named list), such as one from |
steps |
Number of steps, a whole number of at least 0 (default
|
dt |
Time between rows, a finite number greater than 0 (default
|
k |
Coupling gain applied to each signed edge, a finite number (default
|
damping |
Per-state linear decay, a finite number (default
|
init |
Initial value for every state, a single finite number (default
|
method |
|
Details
With method = "exact", each step multiplies the state by the matrix
exponential, computed by scaling and squaring a degree-18 Taylor polynomial
(Moler and Van Loan, 2003, method 3), so the trajectory is the solution of
the linear system at times 0, dt, 2 * dt, ... whatever dt is.
With method = "euler", the default for this release, the explicit
step is stable only when |1 + dt \lambda| < 1 for every eigenvalue
\lambda of A - damping * I. A theory that decays at rate
damping therefore grows without bound, alternating in sign, once
dt * damping exceeds 2, and the steps turn a sustained oscillation
into growth. Raising damping can cause a divergence as well as fail
to stop one. The function warns when the Euler trajectory departs from the
exact one by more than 5 per cent of max(1, |exact|) at any step. The
default will change to "exact" in the next minor release.
When a state grows so large that a million times it is not a finite number,
the function stops with a message naming the step and the state. The initial
state is tested as step 0, so an init beyond about 1.8e302 in absolute
value stops there.
The model is deliberately simple: one gain k for every coupling,
causes and mediates taken as positive, moderates and
associates coupling nothing, functional_form not read and a
common initial value for every state. A linear system has one equilibrium,
or a continuum of them when its matrix is singular, and never two separate
ones, so it cannot show bistability.
Value
A named list
list(states, dt, steps, k, damping, init, method, ignored, opposed,
trajectory), where states are the construct ids in file order and
trajectory is a list of steps + 1 numeric vectors (row 0 is
the initial state), every value rounded to 6 decimals. The settings and
the method are returned as given, because the trajectory cannot be
reproduced without them. ignored lists the ids of the propositions
that couple nothing (moderates, associates, a relation outside the schema's
set or an endpoint that is not a declared construct), and opposed
the c(from, to) pairs that carry couplings of both signs, which
offset each other. An invalid setting is refused with an error.
References
Moler, C., & Van Loan, C. (2003). Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later. SIAM Review, 45(1), 3-49. doi:10.1137/S00361445024180
Examples
theory <- tf_theory("demo-1", "A demonstration theory") |>
tf_add_construct("c_arousal", "Arousal", "Bodily activation.") |>
tf_add_construct("c_threat", "Perceived threat", "Appraised danger.") |>
tf_add_proposition("p1", "c_arousal", "c_threat", "increases")
sim <- tf_simulate(theory, steps = 5, method = "exact")
sim$states
sim$trajectory[[1]] # the common initial state
sim$trajectory[[length(sim$trajectory)]] # at time 5 * dt
Start a new, empty theory object (BUILDING mode entry point)
Description
Seeds schema_version = "1.0" and a first provenance entry
{step:"1", action:"tf_theory", detail:<id>}.
Usage
tf_theory(id, title, maturity = "building", theory_form = "network")
Arguments
id |
Theory id. |
title |
Human-readable title. |
maturity |
Maturity stage, one of |
theory_form |
Theory form, one of |
Details
The builders do not check field values. tf_validate() reports a value
outside its enum, except that it checks the formal-model type, an evidence
entry's direction and a test block's sided only with
full = TRUE.
Value
A theory object (named list).
Examples
tf_theory("demo-1", "A demonstration theory")
Tokenise a string into a set of content tokens
Description
Folds the text through the package's fold table (accented Latin letters to ASCII, Greek and Cyrillic letters to small unaccented ones) and lower-cases ASCII letters, then takes every maximal run of letters, marks and digits in any script (Unicode general categories L, M and N) as a token. Tokens shorter than 3 code points and the canonical English stopwords are dropped, and the unique set is returned. Scripts other than Latin, Greek and Cyrillic are compared as written, and text written without spaces, such as Chinese, gives one token per run.
Usage
tf_tokens(s)
Arguments
s |
A single string (or |
Value
A character vector of unique tokens (possibly empty).
Examples
tf_tokens("The physiological arousal response to a threat")
# Accents and case are folded, so these give the same tokens.
tf_tokens("Na\u00efve \u00c9motion")
tf_tokens("naive emotion")
Validate a theory object
Description
Checks a theory against the package's schema, theory.schema.json,
without a JSON Schema engine, so that it runs wherever R does, webR
included.
Usage
tf_validate(theory, full = FALSE)
Arguments
theory |
A theory object (named list), such as one from |
full |
When |
Details
The default (full = FALSE) checks structure. It covers the required
top-level fields, the maturity and theory_form enums, the
top-level field names and the required fields and enums of each construct,
proposition and prediction. It also checks that every collection is a list.
A field that is absent, NULL or blank is reported as missing, and one
that holds another type as such (id must be a string).
With full = TRUE, it also checks that every id is unique within its
collection and that every cross-reference points to a declared id. The
cross-references are the endpoints of a proposition, the derivations and
diagnostics of a prediction and the target of an assumption, an evidence
entry or a test outcome. It then checks the rest of the schema. That covers
the required fields of assumptions, alternatives, evidence and test
outcomes, a logical passed, the evidence direction and formal-model
type enums, the version block and the schema_version pattern. It also covers numbers within [0, 1] where
the schema asks for them, a prediction's bounds and test
block and a test outcome's estimate and se. Last, it checks
the type of every other field and of every entry of a string array.
Besides the ids and references, which the schema cannot express, the full
check is stricter than a JSON Schema 2020-12 validator in three ways. A
blank required string counts as missing. An entry of a string array must be
a nonempty string. A prediction's bounds must hold a finite bound
with lower not above upper, a test outcome's estimate
and se and a test block's sesoi must be finite, that
block's n_planned must lie within the range of a double and its
power_lo must not be above power_hi. The full check is more
lenient in three ways. A NULL optional field other than
theory_form is absent, as is a single NA, which tf_write()
writes as null. A single string stands for a one-element array of strings.
An empty list() stands for an empty mapping as well as an empty
sequence.
Both checks are deterministic, and the Python package's
Theory.validate() reports the same problems in the same order with
the same text.
Value
TRUE (invisibly) on success. Otherwise, it stops with
"invalid theory object: " followed by every problem found, joined
by "; ".
Examples
theory <- tf_read(system.file("fixtures", "panic-network.theory.yaml",
package = "theoryforge"))
isTRUE(tf_validate(theory)) # required fields and enums
isTRUE(tf_validate(theory, full = TRUE)) # also ids, cross-references and the rest of the schema
# The failure path is the more informative one. Point a prediction at a
# proposition that was never declared.
broken <- theory
broken$predictions[[1]]$derives_from <- "p_missing"
tryCatch(tf_validate(broken, full = TRUE), error = conditionMessage)
Write a theory object to YAML or JSON
Description
Serialises a theory object to disk. The file extension sets the format:
JSON for .json and YAML otherwise. Files are UTF-8 with LF line
endings.
Usage
tf_write(theory, path)
Arguments
theory |
A theory object (named list). |
path |
Destination path. |
Details
Numbers keep 15 significant digits in both formats, logicals are written as
true and false, and a missing value (NA) is written as
null, which reads back as NULL in R and None in Python. Every
field the schema types as an array of strings (derives_from,
diagnostic_vs, protects, measurement,
boundary_conditions, key_constructs) is written as an array,
even when the theory holds it as a single string. A theory that validates
against the package's own schema therefore still validates once written, and
it reads back the same in R and in Python.
Value
The path (invisibly).
Examples
theory <- tf_theory("demo-1", "A demonstration theory")
tf_write(theory, tempfile(fileext = ".yaml"))