rtisanepy 0.1.0__tar.gz

rtisanepy-0.1.0/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:github.com)",
+      "WebSearch",
+      "WebFetch(domain:tisane-stats.org)",
+      "WebFetch(domain:dl.acm.org)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:api.github.com)",
+      "Bash(python:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(gh pr:*)",
+      "Bash(git:*)"
+    ]
+  }
+}

rtisanepy-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+*.pyc

rtisanepy-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12.0

rtisanepy-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: rtisanepy
+Version: 0.1.0
+Summary: Authoring generalized linear mixed effects models from conceptual models
+Project-URL: Homepage, https://github.com/emjun/rTisanePy
+Project-URL: Repository, https://github.com/emjun/rTisanePy
+Author: Eunice Jun
+License-Expression: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: networkx>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# rTisanePy
+
+Authoring generalized linear mixed effects models from conceptual models. Based on [rTisane](https://github.com/emjun/rTisane).
+
+rTisanePy lets you:
+
+- Declare variables and specify causal and relational assumptions
+- Query for a statistical model from a conceptual model
+- Automatically identify confounders (following [Cinelli, Forney & Pearl, 2022](https://doi.org/10.1177/00491241221099552))
+- Infer random effects from nesting and repeated measures
+- Select candidate family/link functions based on DV type
+
+## Installation
+
+```bash
+pip install rtisanepy
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Requires Python 3.10+ and `networkx`.
+
+## Quick Start
+
+```python
+from rtisanepy import (
+    Unit, continuous, categories,
+    causes, equals, increases,
+    ConceptualModel,
+)
+
+# Declare variables
+student = Unit("student", cardinality=100)
+classroom = Unit("classroom", cardinality=10)
+student = Unit("student", cardinality=100, nests_within=classroom)
+
+tutoring = categories(unit=student, name="Tutoring", cardinality=2)
+ses = categories(unit=student, name="SES", order=["lower", "middle", "upper"])
+test_score = continuous(unit=student, name="TestScore")
+
+# Build a conceptual model
+cm = (
+    ConceptualModel()
+    .assume(causes(ses, test_score))
+    .assume(causes(ses, tutoring))
+    .hypothesize(causes(tutoring, test_score,
+                        when=equals(tutoring, "in-person"),
+                        then=increases(test_score)))
+)
+
+# Query for a statistical model
+model = cm.query(iv=tutoring, dv=test_score)
+
+print(model.formula())       # TestScore ~ Tutoring + SES + (1 | classroom)
+print(model.family)           # Inverse Gaussian
+print(model.main_effects)     # ['Tutoring', 'SES']
+print(model.random_effects)   # [RandomIntercept(group=classroom)]
+
+# Override family/link
+model2 = model.with_family("Gaussian", link="identity")
+```
+
+## API Overview
+
+### Variables
+
+| Constructor | Description |
+|---|---|
+| `Unit(name, cardinality, nests_within=None)` | Entity (participant, subject) |
+| `Participant(name, cardinality, nests_within=None)` | Alias for Unit |
+| `Time(name, order=None, cardinality=0)` | Time variable |
+| `continuous(unit, name, number_of_instances=1)` | Continuous measure |
+| `counts(unit, name, number_of_instances=1)` | Count measure |
+| `categories(unit, name, *, cardinality=None, order=None)` | Categorical measure (ordered if `order` given) |
+
+### Relationships
+
+| Function | Description |
+|---|---|
+| `causes(cause, effect, *, when=None, then=None)` | Directed causal relationship |
+| `relates(lhs, rhs, *, when=None, then=None)` | Undirected (ambiguous) relationship |
+| `nests(base, group)` | Nesting relationship between units |
+
+### Comparisons (for `when`/`then` annotations)
+
+| Function | Description |
+|---|---|
+| `equals(variable, value)` | Variable equals a value |
+| `not_equals(variable, value)` | Variable does not equal a value |
+| `increases(variable)` | Variable increases |
+| `decreases(variable)` | Variable decreases |
+
+### ConceptualModel
+
+```python
+cm = ConceptualModel()
+cm.assume(relationship)        # Add assumed relationship (returns self)
+cm.hypothesize(relationship)   # Add hypothesized relationship (returns self)
+cm.interacts(*vars, dv=dv)     # Add interaction annotation (returns self)
+cm.query(iv=iv, dv=dv)         # Infer a StatisticalModel
+```
+
+At least one hypothesized relationship connecting `iv` and `dv` is required to query.
+
+### StatisticalModel
+
+| Attribute / Method | Description |
+|---|---|
+| `.formula()` | R-style formula string |
+| `.main_effects` | List of main effect variable names |
+| `.interaction_effects` | List of interaction terms |
+| `.random_effects` | List of `RandomIntercept` / `RandomSlope` |
+| `.family` | Selected family function |
+| `.link` | Selected link function |
+| `.family_candidates` | All candidate family/link pairs |
+| `.summary()` | Machine-readable dict |
+| `.with_family(family, link=None)` | Copy with overridden family/link |
+
+## Running Tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+## Citation
+
+If you use rTisanePy in your research, please cite:
+
+```bibtex
+@software{rtisanepy,
+  author = {Eunice Jun},
+  title = {rTisanePy: A Python Tool for Authoring Statistical Models from Conceptual Models},
+  url = {https://github.com/emjun/rTisanePy},
+  year = {2026}
+}
+```
+
+## References
+
+- Eunice Jun, Audrey Seo, Jeffrey Heer, and René Just. 2024. [Tisane: Authoring Statistical Models via Formal Reasoning from Conceptual and Data Relationships.](https://doi.org/10.1145/3613904.3642347) *CHI 2024*.
+- Carlos Cinelli, Andrew Forney, and Judea Pearl. 2022. [A Crash Course in Good and Bad Controls.](https://doi.org/10.1177/00491241221099552) *Sociological Methods & Research*.

rtisanepy-0.1.0/README.md

@@ -0,0 +1,145 @@
+# rTisanePy
+
+Authoring generalized linear mixed effects models from conceptual models. Based on [rTisane](https://github.com/emjun/rTisane).
+
+rTisanePy lets you:
+
+- Declare variables and specify causal and relational assumptions
+- Query for a statistical model from a conceptual model
+- Automatically identify confounders (following [Cinelli, Forney & Pearl, 2022](https://doi.org/10.1177/00491241221099552))
+- Infer random effects from nesting and repeated measures
+- Select candidate family/link functions based on DV type
+
+## Installation
+
+```bash
+pip install rtisanepy
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Requires Python 3.10+ and `networkx`.
+
+## Quick Start
+
+```python
+from rtisanepy import (
+    Unit, continuous, categories,
+    causes, equals, increases,
+    ConceptualModel,
+)
+
+# Declare variables
+student = Unit("student", cardinality=100)
+classroom = Unit("classroom", cardinality=10)
+student = Unit("student", cardinality=100, nests_within=classroom)
+
+tutoring = categories(unit=student, name="Tutoring", cardinality=2)
+ses = categories(unit=student, name="SES", order=["lower", "middle", "upper"])
+test_score = continuous(unit=student, name="TestScore")
+
+# Build a conceptual model
+cm = (
+    ConceptualModel()
+    .assume(causes(ses, test_score))
+    .assume(causes(ses, tutoring))
+    .hypothesize(causes(tutoring, test_score,
+                        when=equals(tutoring, "in-person"),
+                        then=increases(test_score)))
+)
+
+# Query for a statistical model
+model = cm.query(iv=tutoring, dv=test_score)
+
+print(model.formula())       # TestScore ~ Tutoring + SES + (1 | classroom)
+print(model.family)           # Inverse Gaussian
+print(model.main_effects)     # ['Tutoring', 'SES']
+print(model.random_effects)   # [RandomIntercept(group=classroom)]
+
+# Override family/link
+model2 = model.with_family("Gaussian", link="identity")
+```
+
+## API Overview
+
+### Variables
+
+| Constructor | Description |
+|---|---|
+| `Unit(name, cardinality, nests_within=None)` | Entity (participant, subject) |
+| `Participant(name, cardinality, nests_within=None)` | Alias for Unit |
+| `Time(name, order=None, cardinality=0)` | Time variable |
+| `continuous(unit, name, number_of_instances=1)` | Continuous measure |
+| `counts(unit, name, number_of_instances=1)` | Count measure |
+| `categories(unit, name, *, cardinality=None, order=None)` | Categorical measure (ordered if `order` given) |
+
+### Relationships
+
+| Function | Description |
+|---|---|
+| `causes(cause, effect, *, when=None, then=None)` | Directed causal relationship |
+| `relates(lhs, rhs, *, when=None, then=None)` | Undirected (ambiguous) relationship |
+| `nests(base, group)` | Nesting relationship between units |
+
+### Comparisons (for `when`/`then` annotations)
+
+| Function | Description |
+|---|---|
+| `equals(variable, value)` | Variable equals a value |
+| `not_equals(variable, value)` | Variable does not equal a value |
+| `increases(variable)` | Variable increases |
+| `decreases(variable)` | Variable decreases |
+
+### ConceptualModel
+
+```python
+cm = ConceptualModel()
+cm.assume(relationship)        # Add assumed relationship (returns self)
+cm.hypothesize(relationship)   # Add hypothesized relationship (returns self)
+cm.interacts(*vars, dv=dv)     # Add interaction annotation (returns self)
+cm.query(iv=iv, dv=dv)         # Infer a StatisticalModel
+```
+
+At least one hypothesized relationship connecting `iv` and `dv` is required to query.
+
+### StatisticalModel
+
+| Attribute / Method | Description |
+|---|---|
+| `.formula()` | R-style formula string |
+| `.main_effects` | List of main effect variable names |
+| `.interaction_effects` | List of interaction terms |
+| `.random_effects` | List of `RandomIntercept` / `RandomSlope` |
+| `.family` | Selected family function |
+| `.link` | Selected link function |
+| `.family_candidates` | All candidate family/link pairs |
+| `.summary()` | Machine-readable dict |
+| `.with_family(family, link=None)` | Copy with overridden family/link |
+
+## Running Tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+## Citation
+
+If you use rTisanePy in your research, please cite:
+
+```bibtex
+@software{rtisanepy,
+  author = {Eunice Jun},
+  title = {rTisanePy: A Python Tool for Authoring Statistical Models from Conceptual Models},
+  url = {https://github.com/emjun/rTisanePy},
+  year = {2026}
+}
+```
+
+## References
+
+- Eunice Jun, Audrey Seo, Jeffrey Heer, and René Just. 2024. [Tisane: Authoring Statistical Models via Formal Reasoning from Conceptual and Data Relationships.](https://doi.org/10.1145/3613904.3642347) *CHI 2024*.
+- Carlos Cinelli, Andrew Forney, and Judea Pearl. 2022. [A Crash Course in Good and Bad Controls.](https://doi.org/10.1177/00491241221099552) *Sociological Methods & Research*.

rtisanepy-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rtisanepy"
+version = "0.1.0"
+description = "Authoring generalized linear mixed effects models from conceptual models"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["networkx>=3.0"]
+authors = [
+    { name = "Eunice Jun" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/emjun/rTisanePy"
+Repository = "https://github.com/emjun/rTisanePy"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]

rtisanepy-0.1.0/src/rtisanepy/__init__.py

@@ -0,0 +1,48 @@
+"""rTisanePy — Python port of rTisane for authoring statistical models."""
+
+from .variables import (
+    Unit,
+    Participant,
+    Time,
+    Continuous,
+    Counts,
+    UnorderedCategories,
+    OrderedCategories,
+    Measure,
+    Exactly,
+    AtMost,
+    Per,
+    continuous,
+    counts,
+    categories,
+)
+from .relationships import causes, relates, nests
+from .comparisons import equals, not_equals, increases, decreases
+from .conceptual_model import ConceptualModel
+from .statistical_model import StatisticalModel
+
+__all__ = [
+    "Unit",
+    "Participant",
+    "Time",
+    "Continuous",
+    "Counts",
+    "UnorderedCategories",
+    "OrderedCategories",
+    "Measure",
+    "Exactly",
+    "AtMost",
+    "Per",
+    "continuous",
+    "counts",
+    "categories",
+    "causes",
+    "relates",
+    "nests",
+    "equals",
+    "not_equals",
+    "increases",
+    "decreases",
+    "ConceptualModel",
+    "StatisticalModel",
+]

rtisanepy-0.1.0/src/rtisanepy/comparisons.py

@@ -0,0 +1,37 @@
+"""Comparison predicates for when/then annotations.
+
+Ports equals.R, increases.R, decreases.R, notEquals.R.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .variables import AbstractVariable
+
+
+@dataclass(frozen=True)
+class Compares:
+    """Holds a variable reference and a condition string."""
+    variable: AbstractVariable
+    condition: str
+
+
+def equals(variable: AbstractVariable, value) -> Compares:
+    """Condition: variable == value."""
+    return Compares(variable=variable, condition=f"=={value}")
+
+
+def not_equals(variable: AbstractVariable, value) -> Compares:
+    """Condition: variable != value."""
+    return Compares(variable=variable, condition=f"!={value}")
+
+
+def increases(variable: AbstractVariable) -> Compares:
+    """Condition: variable increases."""
+    return Compares(variable=variable, condition="increases")
+
+
+def decreases(variable: AbstractVariable) -> Compares:
+    """Condition: variable decreases."""
+    return Compares(variable=variable, condition="decreases")

rtisanepy-0.1.0/src/rtisanepy/conceptual_model.py

@@ -0,0 +1,171 @@
+"""ConceptualModel: the central object for declaring domain knowledge.
+
+Ports ConceptualModel, assume(), hypothesize() from rTisane.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import networkx as nx
+
+from .variables import AbstractVariable, Measure, Unit, Time
+from .relationships import Causes, Relates, Nests, Interacts
+from .graph import build_graph
+
+if TYPE_CHECKING:
+    from .statistical_model import StatisticalModel
+
+
+# ---------------------------------------------------------------------------
+# Wrappers that label a relationship as assumed vs hypothesized
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Assumption:
+    """A relationship the analyst assumes (prior work / strong belief)."""
+    relationship: Causes | Relates | Interacts
+
+
+@dataclass
+class Hypothesis:
+    """A relationship the analyst hypothesises (focus of analysis)."""
+    relationship: Causes | Relates | Interacts
+
+
+# ---------------------------------------------------------------------------
+# ConceptualModel
+# ---------------------------------------------------------------------------
+
+class ConceptualModel:
+    """Graph-backed collection of variables and labeled relationships."""
+
+    def __init__(self):
+        self.variables: dict[str, AbstractVariable] = {}
+        self.relationships: list[Assumption | Hypothesis] = []
+        self.graph: nx.DiGraph = nx.DiGraph()
+        self.interactions: list[Interacts] = []
+
+    # -- helpers ----------------------------------------------------------
+
+    def _track_variables(self, rel: Causes | Relates | Nests | Interacts):
+        """Register variables mentioned in a relationship."""
+        if isinstance(rel, Causes):
+            self._add_var(rel.cause)
+            self._add_var(rel.effect)
+        elif isinstance(rel, Relates):
+            self._add_var(rel.lhs)
+            self._add_var(rel.rhs)
+        elif isinstance(rel, Nests):
+            self._add_var(rel.base)
+            self._add_var(rel.group)
+        elif isinstance(rel, Interacts):
+            for v in rel.variables:
+                self._add_var(v)
+            if rel.dv is not None:
+                self._add_var(rel.dv)
+
+    def _add_var(self, var: AbstractVariable):
+        if var.name not in self.variables:
+            self.variables[var.name] = var
+
+    def _rebuild_graph(self):
+        self.graph = build_graph(self.relationships)
+
+    # -- public API -------------------------------------------------------
+
+    def assume(self, relationship: Causes | Relates) -> "ConceptualModel":
+        """Add an assumed relationship. Returns *self* for chaining."""
+        a = Assumption(relationship)
+        self.relationships.append(a)
+        self._track_variables(relationship)
+        self._rebuild_graph()
+        return self
+
+    def hypothesize(self, relationship: Causes | Relates) -> "ConceptualModel":
+        """Add a hypothesised relationship. Returns *self* for chaining."""
+        h = Hypothesis(relationship)
+        self.relationships.append(h)
+        self._track_variables(relationship)
+        self._rebuild_graph()
+        return self
+
+    def interacts(self, *variables: AbstractVariable, dv: AbstractVariable) -> "ConceptualModel":
+        """Annotate an interaction among *variables* w.r.t. *dv*."""
+        interaction = Interacts(variables=list(variables), dv=dv)
+        self.interactions.append(interaction)
+        self._track_variables(interaction)
+        return self
+
+    # -- query ------------------------------------------------------------
+
+    def query(self, *, iv: AbstractVariable, dv: AbstractVariable, data=None) -> "StatisticalModel":
+        """Infer a statistical model for the effect of *iv* on *dv*.
+
+        Requires at least one hypothesised relationship involving *iv* and *dv*.
+        """
+        from .inference.confounders import infer_confounders
+        from .inference.random_effects import infer_random_effects
+        from .inference.family_link import infer_family_link_functions
+        from .statistical_model import StatisticalModel
+
+        # Validate: must have at least one hypothesis
+        hypotheses = [r for r in self.relationships if isinstance(r, Hypothesis)]
+        if not hypotheses:
+            raise ValueError("ConceptualModel must contain at least one hypothesized relationship to query.")
+
+        # Validate: hypothesis must connect iv and dv
+        has_iv_dv = False
+        for h in hypotheses:
+            rel = h.relationship
+            if isinstance(rel, Causes):
+                if rel.cause.name == iv.name and rel.effect.name == dv.name:
+                    has_iv_dv = True
+            elif isinstance(rel, Relates):
+                names = {rel.lhs.name, rel.rhs.name}
+                if iv.name in names and dv.name in names:
+                    has_iv_dv = True
+        if not has_iv_dv:
+            raise ValueError(
+                f"No hypothesis connects iv={iv.name!r} and dv={dv.name!r}."
+            )
+
+        # 1. Confounders
+        confounders = infer_confounders(self, iv, dv)
+
+        # 2. Random effects
+        relevant_interactions = [
+            ix for ix in self.interactions if ix.dv is not None and ix.dv.name == dv.name
+        ]
+        random_effects = infer_random_effects(
+            confounders=confounders,
+            interactions=relevant_interactions,
+            conceptual_model=self,
+            iv=iv,
+            dv=dv,
+        )
+
+        # 3. Family / link
+        family_candidates = infer_family_link_functions(dv)
+
+        # 4. Interaction effects
+        interaction_effects: list[str] = []
+        for ix in relevant_interactions:
+            var_names = [v.name for v in ix.variables]
+            interaction_effects.append(":".join(var_names))
+
+        # 5. Build StatisticalModel
+        first_family = next(iter(family_candidates))
+        first_link = family_candidates[first_family][0] if family_candidates[first_family] else None
+
+        return StatisticalModel(
+            dv=dv.name,
+            iv=iv.name,
+            main_effects=[iv.name] + confounders,
+            interaction_effects=interaction_effects,
+            random_effects=random_effects,
+            family_candidates=family_candidates,
+            family=first_family,
+            link=first_link,
+        )

rtisanepy-0.1.0/src/rtisanepy/graph.py

@@ -0,0 +1,62 @@
+"""DAG construction and traversal using networkx.
+
+Replaces rTisane's dagitty-based graph operations.
+"""
+
+from __future__ import annotations
+
+import networkx as nx
+
+from .relationships import Causes, Relates
+
+
+def build_graph(relationships) -> nx.DiGraph:
+    """Build a directed graph from a list of Assumption/Hypothesis wrappers.
+
+    - Causes  → single directed edge (cause → effect)
+    - Relates → two directed edges tagged ``ambiguous=True``
+    """
+    g = nx.DiGraph()
+    for entry in relationships:
+        rel = entry.relationship
+        if isinstance(rel, Causes):
+            g.add_edge(rel.cause.name, rel.effect.name, ambiguous=False)
+        elif isinstance(rel, Relates):
+            g.add_edge(rel.lhs.name, rel.rhs.name, ambiguous=True)
+            g.add_edge(rel.rhs.name, rel.lhs.name, ambiguous=True)
+    return g
+
+
+def parents(graph: nx.DiGraph, node: str) -> list[str]:
+    """Direct predecessors of *node*."""
+    if node not in graph:
+        return []
+    return list(graph.predecessors(node))
+
+
+def children(graph: nx.DiGraph, node: str) -> list[str]:
+    """Direct successors of *node*."""
+    if node not in graph:
+        return []
+    return list(graph.successors(node))
+
+
+def ancestors(graph: nx.DiGraph, node: str) -> set[str]:
+    """All ancestors of *node* (including *node* itself, matching dagitty)."""
+    if node not in graph:
+        return {node}
+    return nx.ancestors(graph, node) | {node}
+
+
+def descendants(graph: nx.DiGraph, node: str) -> set[str]:
+    """All descendants of *node* (including *node* itself)."""
+    if node not in graph:
+        return {node}
+    return nx.descendants(graph, node) | {node}
+
+
+def find_paths(graph: nx.DiGraph, source: str, target: str) -> list[list[str]]:
+    """All simple paths from *source* to *target*."""
+    if source not in graph or target not in graph:
+        return []
+    return list(nx.all_simple_paths(graph, source, target))