prspace 0.1.0__tar.gz

prspace-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/
+uv.lock
+.Rhistory
+.RData
+.Rproj.user/
+*.Rcheck/
+prspace_*.tar.gz

prspace-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Gutierrez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prspace-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: prspace
+Version: 0.1.0
+Summary: Probability spaces with the same syntax in Python and R: Pr[X == 0] = 0.25
+Project-URL: Homepage, https://github.com/ivanharvard/prspace
+Project-URL: Issues, https://github.com/ivanharvard/prspace/issues
+Author-email: Ivan Gutierrez <gutierrezi0222@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: education,probability,statistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# prspace
+
+Probability spaces with the same syntax in Python and R: `Pr[X == 0] = 0.25`.
+
+> **Alpha.** The API may change between 0.x releases.
+
+```python
+import math
+from prspace import PrSpace, Event
+
+n_samples = math.comb(19, 10)
+Pr = PrSpace()
+S_B = Event()
+
+for B in (100, 1000):
+    Pr[S_B == 0] = math.prod(1 - k / n_samples for k in range(B))
+    Pr[S_B >= 1] = 1 - Pr[S_B == 0]
+    print("Pr[S_B >= 1] =", Pr[S_B >= 1])
+
+print(Pr)
+# PrSpace with 2 probabilities:
+#   Pr[S_B == 0] = 0.004397413
+#   Pr[S_B >= 1] = 0.9956026
+```
+
+- Complements are derived: after `Pr[X == 0] = 0.25`, `Pr[X != 0]` and `Pr[~(X == 0)]` are `0.75`.
+- Reading a condition that was never assigned raises `UndefinedProbabilityError` (a `KeyError`).
+- Event names are inferred from the variable they're bound to, or pass `Event("name")`.
+
+The R package has the same syntax. See the [repository](https://github.com/ivanharvard/prspace)
+for both.

prspace-0.1.0/README.md

@@ -0,0 +1,31 @@
+# prspace
+
+Probability spaces with the same syntax in Python and R: `Pr[X == 0] = 0.25`.
+
+> **Alpha.** The API may change between 0.x releases.
+
+```python
+import math
+from prspace import PrSpace, Event
+
+n_samples = math.comb(19, 10)
+Pr = PrSpace()
+S_B = Event()
+
+for B in (100, 1000):
+    Pr[S_B == 0] = math.prod(1 - k / n_samples for k in range(B))
+    Pr[S_B >= 1] = 1 - Pr[S_B == 0]
+    print("Pr[S_B >= 1] =", Pr[S_B >= 1])
+
+print(Pr)
+# PrSpace with 2 probabilities:
+#   Pr[S_B == 0] = 0.004397413
+#   Pr[S_B >= 1] = 0.9956026
+```
+
+- Complements are derived: after `Pr[X == 0] = 0.25`, `Pr[X != 0]` and `Pr[~(X == 0)]` are `0.75`.
+- Reading a condition that was never assigned raises `UndefinedProbabilityError` (a `KeyError`).
+- Event names are inferred from the variable they're bound to, or pass `Event("name")`.
+
+The R package has the same syntax. See the [repository](https://github.com/ivanharvard/prspace)
+for both.

prspace-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "prspace"
+version = "0.1.0"
+description = "Probability spaces with the same syntax in Python and R: Pr[X == 0] = 0.25"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ivan Gutierrez", email = "gutierrezi0222@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["probability", "statistics", "education"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Education",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+
+[project.urls]
+Homepage = "https://github.com/ivanharvard/prspace"
+Issues = "https://github.com/ivanharvard/prspace/issues"
+
+[dependency-groups]
+dev = ["pytest>=8"]

prspace-0.1.0/src/prspace/__init__.py

@@ -0,0 +1,6 @@
+"""prspace: probability spaces with the same syntax in Python and R."""
+
+from ._core import Condition, Event, PrSpace, UndefinedProbabilityError
+
+__all__ = ["PrSpace", "Event", "Condition", "UndefinedProbabilityError"]
+__version__ = "0.1.0"

prspace-0.1.0/src/prspace/_core.py

@@ -0,0 +1,195 @@
+"""Core objects: PrSpace, Event, and the Condition you get by comparing an Event."""
+
+from __future__ import annotations
+
+import itertools
+import math
+import numbers
+import sys
+from types import FrameType
+from typing import Any
+
+_ids = itertools.count(1)
+
+# The complement of each comparison, e.g. not (X == 0) is (X != 0).
+_NEGATE = {"==": "!=", "!=": "==", "<": ">=", ">=": "<", ">": "<=", "<=": ">"}
+
+
+class UndefinedProbabilityError(KeyError):
+    """Raised when reading ``Pr[cond]`` that was never assigned (directly or via its complement)."""
+
+    def __init__(self, condition: Condition):
+        super().__init__(condition)
+        self.condition = condition
+
+    def __str__(self) -> str:
+        return (
+            f"Pr[{self.condition}] has not been assigned "
+            f"(nor has its complement Pr[{~self.condition}])"
+        )
+
+
+class Event:
+    """A quantity you can make probability statements about.
+
+    Comparing an Event with a value (``S_B == 0``, ``S_B >= 1``) gives a
+    :class:`Condition`, which is what you index a :class:`PrSpace` with.
+
+    If ``name`` is omitted, it is taken from the variable the Event is bound to
+    the first time it is compared, so ``S_B = Event()`` prints as ``S_B``.
+    """
+
+    def __init__(self, name: str | None = None):
+        if name is not None and not isinstance(name, str):
+            raise TypeError("`name` must be a string")
+        self._id = next(_ids)
+        self.name = name
+
+    @property
+    def label(self) -> str:
+        return self.name if self.name is not None else f"E{self._id}"
+
+    def _compare(self, op: str, value: Any, frame: FrameType | None) -> Condition:
+        if isinstance(value, Event):
+            raise TypeError("comparing two Events is not supported yet")
+        try:
+            hash(value)
+        except TypeError:
+            raise TypeError(
+                f"an Event can only be compared with a single value, not {type(value).__name__}"
+            ) from None
+        if self.name is None and frame is not None:
+            self.name = _infer_name(self, frame)
+        return Condition(self, op, value)
+
+    # Python reflects `0 == S_B` to `S_B == 0` (and `1 <= S_B` to `S_B >= 1`) on its own.
+    def __eq__(self, value: Any) -> Condition:  # type: ignore[override]
+        return self._compare("==", value, sys._getframe(1))
+
+    def __ne__(self, value: Any) -> Condition:  # type: ignore[override]
+        return self._compare("!=", value, sys._getframe(1))
+
+    def __lt__(self, value: Any) -> Condition:
+        return self._compare("<", value, sys._getframe(1))
+
+    def __le__(self, value: Any) -> Condition:
+        return self._compare("<=", value, sys._getframe(1))
+
+    def __gt__(self, value: Any) -> Condition:
+        return self._compare(">", value, sys._getframe(1))
+
+    def __ge__(self, value: Any) -> Condition:
+        return self._compare(">=", value, sys._getframe(1))
+
+    def __hash__(self) -> int:
+        return hash(("prspace.Event", self._id))
+
+    def __repr__(self) -> str:
+        return f"<Event {self.label}>"
+
+
+class Condition:
+    """An event such as ``S_B == 0``. Use it as a key: ``Pr[S_B == 0]``.
+
+    ``~cond`` is the complement (``~(S_B == 0)`` is ``S_B != 0``).
+    """
+
+    __slots__ = ("event", "op", "value")
+
+    def __init__(self, event: Event, op: str, value: Any):
+        self.event = event
+        self.op = op
+        self.value = value
+
+    @property
+    def _key(self) -> tuple:
+        return (self.event._id, self.op, self.value)
+
+    def __invert__(self) -> Condition:
+        return Condition(self.event, _NEGATE[self.op], self.value)
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Condition) and self._key == other._key
+
+    def __hash__(self) -> int:
+        return hash(self._key)
+
+    def __bool__(self) -> bool:
+        raise TypeError(
+            f"`{self}` is an event, not True/False; use it as a key, e.g. Pr[{self}]"
+        )
+
+    def __str__(self) -> str:
+        return f"{self.event.label} {self.op} {self.value!r}"
+
+    def __repr__(self) -> str:
+        return f"<Condition {self}>"
+
+
+class PrSpace:
+    """A probability space: assign ``Pr[cond] = p`` and read back ``Pr[cond]``.
+
+    Complements are derived: after ``Pr[X == 0] = 0.3``, ``Pr[X != 0]`` is 0.7.
+    Assigning a condition replaces any stored value for its complement.
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[tuple, tuple[Condition, float]] = {}
+
+    def __setitem__(self, condition: Condition, p: Any) -> None:
+        condition = _as_condition(condition)
+        p = _as_probability(p, condition)
+        self._store.pop((~condition)._key, None)
+        self._store[condition._key] = (condition, p)
+
+    def __getitem__(self, condition: Condition) -> float:
+        condition = _as_condition(condition)
+        if condition._key in self._store:
+            return self._store[condition._key][1]
+        complement = (~condition)._key
+        if complement in self._store:
+            return 1.0 - self._store[complement][1]
+        raise UndefinedProbabilityError(condition)
+
+    def __delitem__(self, condition: Condition) -> None:
+        condition = _as_condition(condition)
+        for key in (condition._key, (~condition)._key):
+            if key in self._store:
+                del self._store[key]
+                return
+        raise UndefinedProbabilityError(condition)
+
+    def __len__(self) -> int:
+        return len(self._store)
+
+    def __repr__(self) -> str:
+        if not self._store:
+            return "PrSpace with no probabilities assigned"
+        lines = [f"PrSpace with {len(self._store)} probabilit{'y' if len(self._store) == 1 else 'ies'}:"]
+        lines += [f"  Pr[{c}] = {p:.7g}" for c, p in self._store.values()]
+        return "\n".join(lines)
+
+
+def _as_condition(x: Any) -> Condition:
+    if isinstance(x, Condition):
+        return x
+    if isinstance(x, Event):
+        raise TypeError(f"index a PrSpace with a condition such as Pr[{x.label} == 0], not a bare Event")
+    raise TypeError(f"index a PrSpace with a condition such as Pr[X == 0], not {type(x).__name__}")
+
+
+def _as_probability(p: Any, condition: Condition) -> float:
+    if isinstance(p, bool) or not isinstance(p, numbers.Real):
+        raise TypeError(f"Pr[{condition}] must be a number, not {type(p).__name__}")
+    p = float(p)
+    if math.isnan(p) or not 0.0 <= p <= 1.0:
+        raise ValueError(f"Pr[{condition}] must be between 0 and 1, got {p}")
+    return p
+
+
+def _infer_name(event: Event, frame: FrameType) -> str | None:
+    for scope in (frame.f_locals, frame.f_globals):
+        for name, value in list(scope.items()):
+            if value is event:
+                return name
+    return None

prspace-0.1.0/tests/test_prspace.py

@@ -0,0 +1,131 @@
+# Keep these cases in sync with r/tests/testthat/test-prspace.R.
+import math
+
+import pytest
+
+from prspace import Event, PrSpace, UndefinedProbabilityError
+
+
+def test_readme_example():
+    n_samples = math.comb(2 * 10 - 1, 10)
+    Pr = PrSpace()
+    S_B = Event()
+    for B in (100, 1000):
+        Pr[S_B == 0] = math.prod(1 - k / n_samples for k in range(B))
+        Pr[S_B >= 1] = 1 - Pr[S_B == 0]
+        assert Pr[S_B == 0] + Pr[S_B >= 1] == pytest.approx(1)
+    assert Pr[S_B == 0] == pytest.approx(math.prod(1 - k / n_samples for k in range(1000)))
+
+
+def test_assign_and_read():
+    Pr = PrSpace()
+    X = Event()
+    Pr[X == 0] = 0.25
+    assert Pr[X == 0] == 0.25
+    assert len(Pr) == 1
+
+
+def test_complements_are_derived():
+    Pr = PrSpace()
+    X = Event()
+    Pr[X == 0] = 0.25
+    assert Pr[X != 0] == 0.75
+    assert Pr[~(X == 0)] == 0.75
+    Pr[X < 3] = 0.4
+    assert Pr[X >= 3] == pytest.approx(0.6)
+
+
+def test_assigning_replaces_stored_complement():
+    Pr = PrSpace()
+    X = Event()
+    Pr[X != 0] = 0.9
+    Pr[X == 0] = 0.3
+    assert len(Pr) == 1
+    assert Pr[X != 0] == pytest.approx(0.7)
+
+
+def test_reversed_comparisons():
+    Pr = PrSpace()
+    X = Event()
+    Pr[1 <= X] = 0.4
+    assert Pr[X >= 1] == 0.4
+    Pr[0 == X] = 0.1
+    assert Pr[X == 0] == 0.1
+
+
+def test_values_are_part_of_the_key():
+    Pr = PrSpace()
+    X = Event()
+    Pr[X == 0] = 0.1
+    Pr[X == 1] = 0.2
+    Pr[X == "heads"] = 0.5
+    assert (Pr[X == 0], Pr[X == 1], Pr[X == "heads"]) == (0.1, 0.2, 0.5)
+
+
+def test_events_are_distinct():
+    Pr = PrSpace()
+    X, Y = Event(), Event()
+    Pr[X == 0] = 0.1
+    with pytest.raises(UndefinedProbabilityError):
+        Pr[Y == 0]
+
+
+def test_undefined_probability_message():
+    Pr = PrSpace()
+    X = Event()
+    with pytest.raises(UndefinedProbabilityError, match=r"Pr\[X >= 1\] has not been assigned"):
+        Pr[X >= 1]
+
+
+def test_names_are_inferred_or_given():
+    X = Event()
+    Z = Event("Z_total")
+    assert str(X == 0) == "X == 0"
+    assert str(Z > 2) == "Z_total > 2"
+
+
+def test_rejects_bad_probabilities():
+    Pr = PrSpace()
+    X = Event()
+    for bad in (-0.1, 1.5, float("nan")):
+        with pytest.raises(ValueError):
+            Pr[X == 0] = bad
+    for bad in ("0.5", None, True):
+        with pytest.raises(TypeError):
+            Pr[X == 0] = bad
+
+
+def test_rejects_bad_keys():
+    Pr = PrSpace()
+    X = Event()
+    with pytest.raises(TypeError):
+        Pr[X] = 0.5
+    with pytest.raises(TypeError):
+        Pr["X == 0"] = 0.5
+    with pytest.raises(TypeError):
+        X == [1, 2]
+
+
+def test_condition_is_not_a_bool():
+    X = Event()
+    with pytest.raises(TypeError):
+        if X == 0:
+            pass
+
+
+def test_delete():
+    Pr = PrSpace()
+    X = Event()
+    Pr[X == 0] = 0.25
+    del Pr[X != 0]  # deleting via the complement removes the stored value
+    assert len(Pr) == 0
+    with pytest.raises(UndefinedProbabilityError):
+        del Pr[X == 0]
+
+
+def test_print():
+    Pr = PrSpace()
+    S_B = Event()
+    assert repr(Pr) == "PrSpace with no probabilities assigned"
+    Pr[S_B == 0] = 0.25
+    assert repr(Pr) == "PrSpace with 1 probability:\n  Pr[S_B == 0] = 0.25"