theoryforge 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- theoryforge-0.1.0/.gitignore +34 -0
- theoryforge-0.1.0/LICENSE +21 -0
- theoryforge-0.1.0/PKG-INFO +113 -0
- theoryforge-0.1.0/README.md +85 -0
- theoryforge-0.1.0/docs/about.md +58 -0
- theoryforge-0.1.0/docs/api.md +37 -0
- theoryforge-0.1.0/docs/assets/logo.png +0 -0
- theoryforge-0.1.0/docs/assets/logo.svg +35 -0
- theoryforge-0.1.0/docs/changelog.md +45 -0
- theoryforge-0.1.0/docs/getting-started.md +54 -0
- theoryforge-0.1.0/docs/index.md +52 -0
- theoryforge-0.1.0/docs/licence.md +9 -0
- theoryforge-0.1.0/docs/literature.md +298 -0
- theoryforge-0.1.0/docs/methodology.md +120 -0
- theoryforge-0.1.0/docs/stylesheets/brand.css +338 -0
- theoryforge-0.1.0/docs/stylesheets/extra.css +20 -0
- theoryforge-0.1.0/docs/theoryforge.bib +8 -0
- theoryforge-0.1.0/docs/workflow-modes.md +429 -0
- theoryforge-0.1.0/mkdocs.yml +94 -0
- theoryforge-0.1.0/overrides/partials/header.html +82 -0
- theoryforge-0.1.0/pyproject.toml +58 -0
- theoryforge-0.1.0/src/theoryforge/__init__.py +66 -0
- theoryforge-0.1.0/src/theoryforge/_num.py +19 -0
- theoryforge-0.1.0/src/theoryforge/_resources.py +14 -0
- theoryforge-0.1.0/src/theoryforge/core.py +321 -0
- theoryforge-0.1.0/src/theoryforge/develop.py +62 -0
- theoryforge-0.1.0/src/theoryforge/diagram.py +267 -0
- theoryforge-0.1.0/src/theoryforge/dossier.py +59 -0
- theoryforge-0.1.0/src/theoryforge/embedding.py +51 -0
- theoryforge-0.1.0/src/theoryforge/lit.py +261 -0
- theoryforge-0.1.0/src/theoryforge/osf.py +53 -0
- theoryforge-0.1.0/src/theoryforge/prereg.py +61 -0
- theoryforge-0.1.0/src/theoryforge/py.typed +0 -0
- theoryforge-0.1.0/src/theoryforge/redundancy.py +71 -0
- theoryforge-0.1.0/src/theoryforge/report_render.py +31 -0
- theoryforge-0.1.0/src/theoryforge/rigor.py +228 -0
- theoryforge-0.1.0/src/theoryforge/schema/rigor_checklist.yaml +72 -0
- theoryforge-0.1.0/src/theoryforge/schema/theory.schema.json +177 -0
- theoryforge-0.1.0/src/theoryforge/scoring.py +42 -0
- theoryforge-0.1.0/src/theoryforge/sem.py +43 -0
- theoryforge-0.1.0/src/theoryforge/simulate.py +46 -0
- theoryforge-0.1.0/tests/conftest.py +19 -0
- theoryforge-0.1.0/tests/test_diagram_redundancy.py +81 -0
- theoryforge-0.1.0/tests/test_io.py +31 -0
- theoryforge-0.1.0/tests/test_lit.py +88 -0
- theoryforge-0.1.0/tests/test_modes.py +72 -0
- theoryforge-0.1.0/tests/test_p3.py +29 -0
- theoryforge-0.1.0/tests/test_p4.py +52 -0
- theoryforge-0.1.0/tests/test_rigor.py +50 -0
- theoryforge-0.1.0/tests/test_scalar_singleton.py +64 -0
- theoryforge-0.1.0/tests/test_validation_parity.py +94 -0
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# R
|
|
2
|
+
.Rproj.user/
|
|
3
|
+
.Rhistory
|
|
4
|
+
.RData
|
|
5
|
+
.Ruserdata
|
|
6
|
+
*.Rcheck/
|
|
7
|
+
*.tar.gz
|
|
8
|
+
r/theoryforge/man/*.Rd.bak
|
|
9
|
+
|
|
10
|
+
# Python
|
|
11
|
+
__pycache__/
|
|
12
|
+
*.py[cod]
|
|
13
|
+
*.egg-info/
|
|
14
|
+
.eggs/
|
|
15
|
+
build/
|
|
16
|
+
dist/
|
|
17
|
+
.venv/
|
|
18
|
+
venv/
|
|
19
|
+
.pytest_cache/
|
|
20
|
+
.mypy_cache/
|
|
21
|
+
.ruff_cache/
|
|
22
|
+
|
|
23
|
+
# Quarto / docs build
|
|
24
|
+
/_site/
|
|
25
|
+
*.html.bak
|
|
26
|
+
.quarto/
|
|
27
|
+
/python/site/
|
|
28
|
+
/r/theoryforge/docs/
|
|
29
|
+
# Manuscript kept out of the public repo pending journal submission
|
|
30
|
+
/manuscript/
|
|
31
|
+
|
|
32
|
+
# OS
|
|
33
|
+
.DS_Store
|
|
34
|
+
Thumbs.db
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pablo Bernabeu
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: theoryforge
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Systematic theory development.
|
|
5
|
+
Project-URL: Homepage, https://github.com/pablobernabeu/theoryforge
|
|
6
|
+
Project-URL: Repository, https://github.com/pablobernabeu/theoryforge
|
|
7
|
+
Project-URL: Issues, https://github.com/pablobernabeu/theoryforge/issues
|
|
8
|
+
Author-email: Pablo Bernabeu <pcbernabeu@gmail.com>
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: falsifiability,metascience,psychology,reproducibility,theory
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Requires-Dist: pyyaml>=6.0
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: mypy; extra == 'dev'
|
|
25
|
+
Requires-Dist: pytest>=7.0; extra == 'dev'
|
|
26
|
+
Requires-Dist: ruff; extra == 'dev'
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# theoryforge (Python) <img src="docs/assets/logo.png" align="right" height="138" alt="theoryforge hex logo" />
|
|
30
|
+
|
|
31
|
+
Systematic theory development: a rigorous, reproducible workflow for building, developing and
|
|
32
|
+
testing scientific theories. This is the Python twin of [the R package](https://pablobernabeu.github.io/theoryforge/r/) of the same name,
|
|
33
|
+
and the two return identical results.
|
|
34
|
+
|
|
35
|
+
The rendered documentation site, with the API reference and worked guides, is at
|
|
36
|
+
<https://pablobernabeu.github.io/theoryforge/python/>.
|
|
37
|
+
|
|
38
|
+
Prefer to click rather than install? The
|
|
39
|
+
[interactive web app](https://pablobernabeu.github.io/theoryforge/apps/py/) runs this package in
|
|
40
|
+
your browser via [Pyodide](https://pyodide.org/): load a theory, run any operation, and export the
|
|
41
|
+
visualisation (SVG/PNG) and the Python code to reproduce it.
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
import theoryforge as tf
|
|
45
|
+
|
|
46
|
+
# read + check an existing theory
|
|
47
|
+
t = tf.read("../fixtures/panic-network.theory.yaml")
|
|
48
|
+
t.validate() # structural validation against the shared schema
|
|
49
|
+
print(t.report("json")) # 12-item rigour checklist + gate
|
|
50
|
+
print(t.diagram("nomological_net"))# Graphviz DOT
|
|
51
|
+
t.redundancy_check() # lexical jingle-jangle screen
|
|
52
|
+
|
|
53
|
+
# BUILD a theory programmatically (provenance auto-logged)
|
|
54
|
+
b = (tf.new_theory("demo", "Demo theory")
|
|
55
|
+
.add_construct("a", "Alpha", "the first thing", measurement=["m1"], boundary_conditions=["adults"])
|
|
56
|
+
.add_proposition("p1", "a", "b", "increases", mechanism="a drives b")
|
|
57
|
+
.add_prediction("pred1", "a point claim", "point", derives_from=["p1"]))
|
|
58
|
+
|
|
59
|
+
# DEVELOP: progressive vs degenerating appraisal of an amendment
|
|
60
|
+
v1 = tf.read("../fixtures/panic-network.theory.yaml")
|
|
61
|
+
v2 = tf.read("../fixtures/panic-network-2026-v2.theory.yaml")
|
|
62
|
+
print(v2.appraise_amendment(v1)) # -> {'verdict': 'progressive', ...}
|
|
63
|
+
|
|
64
|
+
# TEST: operationalised severity + a preregistration document
|
|
65
|
+
t.severity() # per-prediction risk + computed severity
|
|
66
|
+
print(t.preregister()) # markdown prereg
|
|
67
|
+
|
|
68
|
+
# LITERATURE: map the field, then position the theory against it
|
|
69
|
+
corpus = tf.read_corpus("../fixtures/panic-corpus.yaml")
|
|
70
|
+
tf.litmap(corpus) # keyword co-occurrence, themes, co-citation
|
|
71
|
+
t.landscape(corpus) # -> themes flagged 'under_theorised' / 'crowded' (redundancy risk)
|
|
72
|
+
# tf.fetch_corpus("panic disorder theory") # optional OpenAlex fetch (network call)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The `../fixtures/*.yaml` files referenced above are sample theories that live in the
|
|
76
|
+
[project repository](https://github.com/pablobernabeu/theoryforge); adjust the paths to
|
|
77
|
+
your own theory files when running the examples.
|
|
78
|
+
|
|
79
|
+
## Install
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
pip install theoryforge
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
To work on the package itself, install an editable checkout with the development extras:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
pip install -e ".[dev]"
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Test
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
pytest
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## What the package provides
|
|
98
|
+
|
|
99
|
+
The deterministic core covers theory-object I/O and validation, the 12-item rigour checklist
|
|
100
|
+
with its weighted aggregate score and blocker gate, ten diagram exporters and a lexical
|
|
101
|
+
redundancy screen. The three workflow modes sit on the same object: a BUILDING builder API with
|
|
102
|
+
auto-logged provenance, the Lakatosian amendment appraisal (DEVELOPMENT), and the
|
|
103
|
+
operationalised severity rubric with preregistration export (TESTING). The literature layer
|
|
104
|
+
comprises `read_corpus`, `litmap` (keyword co-occurrence, deterministic connected-component
|
|
105
|
+
themes and co-citation), `landscape` (which maps a theory and its alternatives onto the themes,
|
|
106
|
+
flagging under-theorised fronts and redundancy risk), `lit_diagram`, the network-dependent
|
|
107
|
+
`fetch_corpus` OpenAlex adapter, and `new_evidence_dois` (a deterministic check for candidate
|
|
108
|
+
DOIs, from any search tool, not yet cited by a theory). `compile_sem` translates constructs and
|
|
109
|
+
propositions to lavaan model syntax, and `dossier` assembles a reviewer-facing audit bundle.
|
|
110
|
+
Simulation and adapters round the package out: `simulate` (a deterministic dynamical-system
|
|
111
|
+
runner over the construct network), `render_report` (a Quarto report wrapping the dossier),
|
|
112
|
+
`embedding_redundancy` (an opt-in, embedder-dependent screen) and `osf_push` (an OSF
|
|
113
|
+
deposit adapter, dry-run by default).
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# theoryforge (Python) <img src="docs/assets/logo.png" align="right" height="138" alt="theoryforge hex logo" />
|
|
2
|
+
|
|
3
|
+
Systematic theory development: a rigorous, reproducible workflow for building, developing and
|
|
4
|
+
testing scientific theories. This is the Python twin of [the R package](https://pablobernabeu.github.io/theoryforge/r/) of the same name,
|
|
5
|
+
and the two return identical results.
|
|
6
|
+
|
|
7
|
+
The rendered documentation site, with the API reference and worked guides, is at
|
|
8
|
+
<https://pablobernabeu.github.io/theoryforge/python/>.
|
|
9
|
+
|
|
10
|
+
Prefer to click rather than install? The
|
|
11
|
+
[interactive web app](https://pablobernabeu.github.io/theoryforge/apps/py/) runs this package in
|
|
12
|
+
your browser via [Pyodide](https://pyodide.org/): load a theory, run any operation, and export the
|
|
13
|
+
visualisation (SVG/PNG) and the Python code to reproduce it.
|
|
14
|
+
|
|
15
|
+
```python
|
|
16
|
+
import theoryforge as tf
|
|
17
|
+
|
|
18
|
+
# read + check an existing theory
|
|
19
|
+
t = tf.read("../fixtures/panic-network.theory.yaml")
|
|
20
|
+
t.validate() # structural validation against the shared schema
|
|
21
|
+
print(t.report("json")) # 12-item rigour checklist + gate
|
|
22
|
+
print(t.diagram("nomological_net"))# Graphviz DOT
|
|
23
|
+
t.redundancy_check() # lexical jingle-jangle screen
|
|
24
|
+
|
|
25
|
+
# BUILD a theory programmatically (provenance auto-logged)
|
|
26
|
+
b = (tf.new_theory("demo", "Demo theory")
|
|
27
|
+
.add_construct("a", "Alpha", "the first thing", measurement=["m1"], boundary_conditions=["adults"])
|
|
28
|
+
.add_proposition("p1", "a", "b", "increases", mechanism="a drives b")
|
|
29
|
+
.add_prediction("pred1", "a point claim", "point", derives_from=["p1"]))
|
|
30
|
+
|
|
31
|
+
# DEVELOP: progressive vs degenerating appraisal of an amendment
|
|
32
|
+
v1 = tf.read("../fixtures/panic-network.theory.yaml")
|
|
33
|
+
v2 = tf.read("../fixtures/panic-network-2026-v2.theory.yaml")
|
|
34
|
+
print(v2.appraise_amendment(v1)) # -> {'verdict': 'progressive', ...}
|
|
35
|
+
|
|
36
|
+
# TEST: operationalised severity + a preregistration document
|
|
37
|
+
t.severity() # per-prediction risk + computed severity
|
|
38
|
+
print(t.preregister()) # markdown prereg
|
|
39
|
+
|
|
40
|
+
# LITERATURE: map the field, then position the theory against it
|
|
41
|
+
corpus = tf.read_corpus("../fixtures/panic-corpus.yaml")
|
|
42
|
+
tf.litmap(corpus) # keyword co-occurrence, themes, co-citation
|
|
43
|
+
t.landscape(corpus) # -> themes flagged 'under_theorised' / 'crowded' (redundancy risk)
|
|
44
|
+
# tf.fetch_corpus("panic disorder theory") # optional OpenAlex fetch (network call)
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The `../fixtures/*.yaml` files referenced above are sample theories that live in the
|
|
48
|
+
[project repository](https://github.com/pablobernabeu/theoryforge); adjust the paths to
|
|
49
|
+
your own theory files when running the examples.
|
|
50
|
+
|
|
51
|
+
## Install
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pip install theoryforge
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
To work on the package itself, install an editable checkout with the development extras:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pip install -e ".[dev]"
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Test
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pytest
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## What the package provides
|
|
70
|
+
|
|
71
|
+
The deterministic core covers theory-object I/O and validation, the 12-item rigour checklist
|
|
72
|
+
with its weighted aggregate score and blocker gate, ten diagram exporters and a lexical
|
|
73
|
+
redundancy screen. The three workflow modes sit on the same object: a BUILDING builder API with
|
|
74
|
+
auto-logged provenance, the Lakatosian amendment appraisal (DEVELOPMENT), and the
|
|
75
|
+
operationalised severity rubric with preregistration export (TESTING). The literature layer
|
|
76
|
+
comprises `read_corpus`, `litmap` (keyword co-occurrence, deterministic connected-component
|
|
77
|
+
themes and co-citation), `landscape` (which maps a theory and its alternatives onto the themes,
|
|
78
|
+
flagging under-theorised fronts and redundancy risk), `lit_diagram`, the network-dependent
|
|
79
|
+
`fetch_corpus` OpenAlex adapter, and `new_evidence_dois` (a deterministic check for candidate
|
|
80
|
+
DOIs, from any search tool, not yet cited by a theory). `compile_sem` translates constructs and
|
|
81
|
+
propositions to lavaan model syntax, and `dossier` assembles a reviewer-facing audit bundle.
|
|
82
|
+
Simulation and adapters round the package out: `simulate` (a deterministic dynamical-system
|
|
83
|
+
runner over the construct network), `render_report` (a Quarto report wrapping the dossier),
|
|
84
|
+
`embedding_redundancy` (an opt-in, embedder-dependent screen) and `osf_push` (an OSF
|
|
85
|
+
deposit adapter, dry-run by default).
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# About
|
|
2
|
+
|
|
3
|
+
## Citing theoryforge
|
|
4
|
+
|
|
5
|
+
If you use the Python package in your work, please cite it:
|
|
6
|
+
|
|
7
|
+
<p style="margin: 0 0 0.6em 0; padding-left: 1.8em; text-indent: -1.8em;">Bernabeu, P. (2026). <em>theoryforge: Systematic theory development</em> (Python package version 0.1.0). <a href="https://doi.org/10.5281/zenodo.21229964">https://doi.org/10.5281/zenodo.21229964</a></p>
|
|
8
|
+
|
|
9
|
+
```bibtex
|
|
10
|
+
@Manual{theoryforge,
|
|
11
|
+
title = {theoryforge: Systematic theory development},
|
|
12
|
+
author = {Pablo Bernabeu},
|
|
13
|
+
year = {2026},
|
|
14
|
+
note = {Python package version 0.1.0},
|
|
15
|
+
doi = {10.5281/zenodo.21229964},
|
|
16
|
+
url = {https://doi.org/10.5281/zenodo.21229964},
|
|
17
|
+
}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
You can <a href="../theoryforge.bib" download>download the BibTeX entry</a>. The package
|
|
21
|
+
installs with `pip install theoryforge`.
|
|
22
|
+
|
|
23
|
+
## The developer
|
|
24
|
+
|
|
25
|
+
theoryforge is developed and maintained by
|
|
26
|
+
[Pablo Bernabeu](https://pablobernabeu.github.io), a researcher in the
|
|
27
|
+
Department of Education at the University of Oxford. His work spans cognitive psychology and
|
|
28
|
+
neuroscience, linguistics, education and digital technologies, and research methods and open
|
|
29
|
+
science, with hands-on experience in behavioural and EEG experiments, corpus analysis,
|
|
30
|
+
computational modelling and statistics. He develops open, reproducible research software in R
|
|
31
|
+
and Python, and is a Fellow of the Software Sustainability Institute. His
|
|
32
|
+
[ORCID record](https://orcid.org/0000-0003-1083-2460) lists his other work.
|
|
33
|
+
|
|
34
|
+
This Python package has a feature-parity twin written in R. Its documentation lives at the
|
|
35
|
+
[theoryforge (R) site](https://pablobernabeu.github.io/theoryforge/r/), keeping a theory
|
|
36
|
+
development workflow legible across both languages.
|
|
37
|
+
|
|
38
|
+
## Licence
|
|
39
|
+
|
|
40
|
+
theoryforge is released under the MIT licence, a permissive licence that allows use,
|
|
41
|
+
modification and redistribution provided the copyright and licence notices are kept. The full
|
|
42
|
+
text is reproduced on this site's [licence page](licence.md).
|
|
43
|
+
|
|
44
|
+
## Versioning and archival
|
|
45
|
+
|
|
46
|
+
Releases are tagged on [GitHub](https://github.com/pablobernabeu/theoryforge/releases) and
|
|
47
|
+
archived on [Zenodo](https://doi.org/10.5281/zenodo.21229964). The concept DOI,
|
|
48
|
+
10.5281/zenodo.21229964, always resolves to the latest version, so a citation stays current
|
|
49
|
+
without naming a version. The [changelog](changelog.md) records what changed in each release.
|
|
50
|
+
|
|
51
|
+
## Contributing and support
|
|
52
|
+
|
|
53
|
+
Bugs and feature requests are best reported on the
|
|
54
|
+
[GitHub issues page](https://github.com/pablobernabeu/theoryforge/issues), and the
|
|
55
|
+
[contributing guide](https://github.com/pablobernabeu/theoryforge/blob/main/.github/CONTRIBUTING.md)
|
|
56
|
+
explains how to set up a development environment and propose a change. Because the OSF deposit
|
|
57
|
+
adapter takes a personal access token, never paste that token, or any other secret, into an
|
|
58
|
+
issue; replace it with a placeholder.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# API reference
|
|
2
|
+
|
|
3
|
+
Every public function and the `Theory` class. The three functions whose name
|
|
4
|
+
matches their module (`diagram`, `dossier`, `simulate`) are documented by their
|
|
5
|
+
canonical path so the function, rather than the module, is shown.
|
|
6
|
+
|
|
7
|
+
::: theoryforge
|
|
8
|
+
options:
|
|
9
|
+
members:
|
|
10
|
+
- Theory
|
|
11
|
+
- read
|
|
12
|
+
- write
|
|
13
|
+
- new_theory
|
|
14
|
+
- check
|
|
15
|
+
- report
|
|
16
|
+
- redundancy_check
|
|
17
|
+
- tokens
|
|
18
|
+
- jaccard
|
|
19
|
+
- severity
|
|
20
|
+
- appraise_amendment
|
|
21
|
+
- preregister
|
|
22
|
+
- read_corpus
|
|
23
|
+
- litmap
|
|
24
|
+
- landscape
|
|
25
|
+
- lit_diagram
|
|
26
|
+
- fetch_corpus
|
|
27
|
+
- new_evidence_dois
|
|
28
|
+
- compile_sem
|
|
29
|
+
- embedding_redundancy
|
|
30
|
+
- render_report
|
|
31
|
+
- osf_push
|
|
32
|
+
|
|
33
|
+
::: theoryforge.diagram.diagram
|
|
34
|
+
|
|
35
|
+
::: theoryforge.dossier.dossier
|
|
36
|
+
|
|
37
|
+
::: theoryforge.simulate.simulate
|
|
Binary file
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
<svg viewBox="0 0 174 200" xmlns="http://www.w3.org/2000/svg">
|
|
2
|
+
<defs>
|
|
3
|
+
<linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
|
|
4
|
+
<stop offset="0" stop-color="#22384f"/>
|
|
5
|
+
<stop offset="1" stop-color="#101b27"/>
|
|
6
|
+
</linearGradient>
|
|
7
|
+
<radialGradient id="ember" cx="0.5" cy="0.38" r="0.72">
|
|
8
|
+
<stop offset="0" stop-color="#ffce72"/>
|
|
9
|
+
<stop offset="1" stop-color="#ef9d2c"/>
|
|
10
|
+
</radialGradient>
|
|
11
|
+
<marker id="ah" markerWidth="5" markerHeight="5" refX="4.2" refY="2.3" orient="auto">
|
|
12
|
+
<path d="M0,0 L4.6,2.3 L0,4.6 Z" fill="#7ad0c1"/>
|
|
13
|
+
</marker>
|
|
14
|
+
</defs>
|
|
15
|
+
|
|
16
|
+
<path d="M87,7 L167,53.5 L167,146.5 L87,193 L7,146.5 L7,53.5 Z"
|
|
17
|
+
fill="url(#bg)" stroke="#4cc2b0" stroke-width="7" stroke-linejoin="round"/>
|
|
18
|
+
<path d="M87,15.4 L159.8,57.7 L159.8,142.3 L87,184.6 L14.2,142.3 L14.2,57.7 Z"
|
|
19
|
+
fill="none" stroke="#ffffff" stroke-opacity="0.06" stroke-width="1.4" stroke-linejoin="round"/>
|
|
20
|
+
|
|
21
|
+
<!-- construct network (shifted down to centre the content) -->
|
|
22
|
+
<g stroke="#7ad0c1" stroke-width="2.2" fill="none">
|
|
23
|
+
<line x1="70" y1="65" x2="104" y2="65" marker-end="url(#ah)"/>
|
|
24
|
+
<line x1="67" y1="74" x2="80" y2="88" marker-end="url(#ah)"/>
|
|
25
|
+
<line x1="107" y1="74" x2="94" y2="88" marker-end="url(#ah)"/>
|
|
26
|
+
</g>
|
|
27
|
+
<circle cx="61" cy="65" r="9" fill="#4cc2b0" stroke="#101b27" stroke-width="2.2"/>
|
|
28
|
+
<circle cx="113" cy="65" r="9" fill="#4cc2b0" stroke="#101b27" stroke-width="2.2"/>
|
|
29
|
+
<circle cx="87" cy="97" r="10" fill="url(#ember)" stroke="#101b27" stroke-width="2.2"/>
|
|
30
|
+
|
|
31
|
+
<!-- wordmark -->
|
|
32
|
+
<text x="87" y="139" text-anchor="middle"
|
|
33
|
+
font-family="Segoe UI, Helvetica, Arial, sans-serif"
|
|
34
|
+
font-size="24" font-weight="700" letter-spacing="-0.4"><tspan fill="#f3f6f7">theory</tspan><tspan fill="#f6b24a">forge</tspan></text>
|
|
35
|
+
</svg>
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Source: [NEWS.md](https://github.com/pablobernabeu/theoryforge/blob/main/r/theoryforge/NEWS.md)
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## theoryforge 0.1.0
|
|
8
|
+
|
|
9
|
+
First public release. The package provides a reproducible workflow for building,
|
|
10
|
+
developing and testing scientific theories, with behaviour pinned by a shared
|
|
11
|
+
specification
|
|
12
|
+
([`API_SPEC.md`](https://github.com/pablobernabeu/theoryforge/blob/main/API_SPEC.md)) so the R
|
|
13
|
+
and Python twins return identical verdicts and byte-identical diagram intermediate
|
|
14
|
+
representations.
|
|
15
|
+
|
|
16
|
+
* Core: theory-object input, output and structural validation; a 12-item
|
|
17
|
+
rigour checklist with a weighted aggregate score and a blocker gate; diagram
|
|
18
|
+
intermediate representations (nomological net, provenance, causal DAG); and a
|
|
19
|
+
deterministic lexical construct-redundancy screen. Where the schema expects an
|
|
20
|
+
array of strings, a nonempty scalar string is read as a singleton list
|
|
21
|
+
(API_SPEC.md section 4), so natural YAML such as `derives_from: p1` yields the
|
|
22
|
+
same rigour verdict and gate in both twins; an empty or whitespace-only scalar
|
|
23
|
+
counts as absent.
|
|
24
|
+
* Workflow modes: a builder API with auto-logged provenance (BUILDING); an
|
|
25
|
+
operationalised severity rubric and preregistration export (TESTING); and a
|
|
26
|
+
Lakatosian progressive-versus-degenerating amendment appraisal (DEVELOPMENT).
|
|
27
|
+
* Literature layer: a deterministic bibliometric mapping (`litmap`,
|
|
28
|
+
`landscape`, `lit_diagram`), a parity-exempt OpenAlex corpus adapter, and a
|
|
29
|
+
deterministic, dependency-free check for DOIs not yet cited by a theory
|
|
30
|
+
(`new_evidence_dois`), for use with a search from any source, including the
|
|
31
|
+
companion `scopusflow` package. `lit_diagram` lists the valid types in its
|
|
32
|
+
unknown-type error, matching `diagram`.
|
|
33
|
+
* Testing and review: lavaan model-syntax compilation (`compile_sem`) and a
|
|
34
|
+
reviewer-facing audit dossier (`dossier`).
|
|
35
|
+
* Simulation, reporting and deposit: a deterministic dynamical-system runner
|
|
36
|
+
(`simulate`), a Quarto report wrapper (`render_report`), an opt-in
|
|
37
|
+
embedding redundancy screen (`embedding_redundancy`), and an OSF deposit
|
|
38
|
+
adapter (`osf_push`, dry-run by default). `osf_push` percent-encodes the
|
|
39
|
+
filename component of the upload URL, keeping the dry-run request identical
|
|
40
|
+
across the twins.
|
|
41
|
+
* Cross-language determinism: the literature layer and the amendment appraisal
|
|
42
|
+
sort keywords and ids by codepoint regardless of locale, so mixed-case inputs
|
|
43
|
+
order identically in both twins.
|
|
44
|
+
* Metadata: `theoryforge.__version__` is read from the installed distribution's
|
|
45
|
+
metadata rather than duplicated in source.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Getting started
|
|
2
|
+
|
|
3
|
+
This guide walks through installing the Python package and running a first session against an existing theory file.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
Install from PyPI with pip:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pip install theoryforge
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Sample theories
|
|
14
|
+
|
|
15
|
+
The examples below read a sample theory bundled with the project repository. The fixture files live under `fixtures/` in the repository at [github.com/pablobernabeu/theoryforge](https://github.com/pablobernabeu/theoryforge), for example [`fixtures/panic-network.theory.yaml`](https://github.com/pablobernabeu/theoryforge/blob/main/fixtures/panic-network.theory.yaml). Download a fixture, or point the path at one of your own theory files.
|
|
16
|
+
|
|
17
|
+
## A first session
|
|
18
|
+
|
|
19
|
+
Import the package and read a theory from a YAML file. Adjust the path to the file on your own machine.
|
|
20
|
+
|
|
21
|
+
```python
|
|
22
|
+
import theoryforge as tf
|
|
23
|
+
|
|
24
|
+
t = tf.read("panic-network.theory.yaml")
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Validate the theory. With no arguments this checks the required fields and enum membership, returning `True` on success and raising `ValueError` with a list of problems otherwise. Pass `full=True` to additionally check referential integrity: that ids are unique within each collection, that every cross-reference between constructs, propositions, predictions and alternatives points to a declared id, and that assumption, test-outcome and evidence entries reference declared predictions.
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
t.validate()
|
|
31
|
+
t.validate(full=True) # also checks referential integrity
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Produce the rigour report. The `"json"` format returns the 12-item rigour checklist together with the overall gate. `t.check()` returns the same information as a plain Python dictionary; `t.report(format=...)` renders it as a string, in `"json"` or `"html"`.
|
|
35
|
+
|
|
36
|
+
```python
|
|
37
|
+
print(t.report("json"))
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Export a diagram. The `nomological_net` type returns Graphviz DOT, which you can render with Graphviz or inspect directly.
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
print(t.diagram("nomological_net"))
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Run the lexical redundancy screen. This returns every construct pair with a lexical similarity of their definitions and an `ok`/`review` flag, marking `review` the pairs whose definitions overlap enough to suggest jingle-jangle redundancy.
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
t.redundancy_check()
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Next steps
|
|
53
|
+
|
|
54
|
+
The same `Theory` object supports the building, development and testing modes (`severity()`, `appraise_amendment()`, `preregister()`) and the literature layer (`read_corpus`, `litmap`, `landscape`). See the [API reference](api.md) for the full function list.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# theoryforge <span class="mrd-lang">(Python)</span>
|
|
2
|
+
|
|
3
|
+
theoryforge treats a scientific theory as a versioned, machine-checkable object, so that
|
|
4
|
+
building, developing and testing it becomes systematic and reproducible. It targets the
|
|
5
|
+
familiar weaknesses of soft-science theorising: vague constructs, unfalsifiable claims,
|
|
6
|
+
redundant 'jingle-jangle' constructs and amendments that quietly weaken a theory rather than
|
|
7
|
+
strengthen it. Each weakness becomes something the package can surface and check.
|
|
8
|
+
|
|
9
|
+
The package scaffolds the three workflow modes (building, development and testing), scores a
|
|
10
|
+
theory against a 12-item structural rigour checklist drawn from the methodology literature, generates
|
|
11
|
+
diagrams and positions the theory within the bibliometric literature. This is the Python twin
|
|
12
|
+
of [the R package](https://pablobernabeu.github.io/theoryforge/r/) of the same name, and the
|
|
13
|
+
two return identical results (see the [API reference](api.md) for the shared specification
|
|
14
|
+
behind that guarantee).
|
|
15
|
+
|
|
16
|
+
For the fuller rationale, what each rigour check establishes, and exactly how every reported
|
|
17
|
+
value is computed, see [Methodological foundations](methodology.md). For a step-by-step
|
|
18
|
+
walkthrough, see [Getting started](getting-started.md). The repository
|
|
19
|
+
[README](https://github.com/pablobernabeu/theoryforge) gives an overview and the
|
|
20
|
+
[API reference](api.md) lists every function.
|
|
21
|
+
|
|
22
|
+
!!! tip "Try it in your browser (no install)"
|
|
23
|
+
The [**interactive web app**](https://pablobernabeu.github.io/theoryforge/apps/py/) runs this
|
|
24
|
+
package entirely client-side via [Pyodide](https://pyodide.org/). Load a theory, run any
|
|
25
|
+
operation, and export both the visualisation (SVG/PNG) and the Python code to reproduce it.
|
|
26
|
+
|
|
27
|
+
## Install
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
pip install theoryforge
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## At a glance
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
import theoryforge as tf
|
|
37
|
+
|
|
38
|
+
t = tf.read("panic-network.theory.yaml")
|
|
39
|
+
t.check() # 12-item rigour checklist + gate
|
|
40
|
+
t.severity() # operationalised severity rubric
|
|
41
|
+
t.preregister() # preregistration document
|
|
42
|
+
corpus = tf.read_corpus("panic-corpus.yaml")
|
|
43
|
+
t.landscape(corpus) # under-theorised fronts + redundancy risk
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Author
|
|
47
|
+
|
|
48
|
+
theoryforge is written and maintained by
|
|
49
|
+
[Pablo Bernabeu](https://pablobernabeu.github.io). The R and
|
|
50
|
+
Python packages share one specification and are released under the MIT licence.
|
|
51
|
+
|
|
52
|
+
Archived on Zenodo: [](https://doi.org/10.5281/zenodo.21229964)
|