ProbabilityPewter 0.5.0__py3-none-any.whl

ProbabilityPewter/__init__.py

@@ -0,0 +1,30 @@
+"""
+Docstring for ProbabilityPewter package
+========================================
+
+This package provides tools for simulating and visualising probability, primarily aimed at RPGs but also useful for other applications.
+It includes functions for rolling dice, generating random statistics, and visualizing probability distributions.
+
+"""
+
+__version__ = "0.5.0"
+
+
+#Reminder: list functions here that are main features of the package, for easier access. 
+# For more niche functions or helper functions, users can do a full import from the submodules.
+from .calculator import combined_prob
+from .roll_stats import rpg_dice, prob_table, combat_odds
+from .visualiser import plot_dice, plot_normal, plot_combat
+
+#Finally, we can define __all__ to list the public API of the package.
+# This is optional, but it can help with tools like autocomplete in IDEs, and it also serves as documentation for users about what the main features of the package are.
+__all__ = [
+	"__version__",
+	"combined_prob",
+	"rpg_dice",
+	"prob_table",
+	"combat_odds",
+	"plot_dice",
+	"plot_normal",
+	"plot_combat",
+]

ProbabilityPewter/calculator/__init__.py

@@ -0,0 +1,5 @@
+"""Probability calculation tools for ProbabilityPewter."""
+
+from .combiner import combined_prob
+
+__all__ = ["combined_prob"]

ProbabilityPewter/calculator/bayes.py

@@ -0,0 +1,46 @@
+"""
+Docstring for the bayes module
+
+This module provides functionality to update probabilities using Bayes' theorem.
+
+"""
+
+
+def bayes_updater(prior_A, likelihood_B_given_A, likelihood_B_given_not_A):
+    """Calculate the posterior probability of A given B, P(A|B), using Bayes' theorem.
+    
+    Parameters:
+    -----------
+    prior_A : float
+        Prior probability P(A) - between 0 and 1.
+    likelihood_B_given_A : float
+        Probability of B given A, P(B|A) - between 0 and 1.
+    likelihood_B_given_not_A : float
+        Probability of B given not A, P(B|not A) - between 0 and 1.
+
+    Returns:
+    --------
+    float
+        Posterior probability P(A|B) - between 0 and 1.
+    """
+    values = {
+        "prior_A": prior_A,
+        "likelihood_B_given_A": likelihood_B_given_A,
+        "likelihood_B_given_not_A": likelihood_B_given_not_A,
+    }
+
+    for name, value in values.items():
+        if not isinstance(value, (int, float)):
+            raise TypeError(f"{name} must be numeric, got {type(value).__name__}.")
+        if value < 0 or value > 1:
+            raise ValueError(f"{name} must be between 0 and 1.")
+
+    prior_not_A = 1 - prior_A
+    numerator = likelihood_B_given_A * prior_A
+    denominator = numerator + (likelihood_B_given_not_A * prior_not_A)
+
+    if denominator == 0:
+        raise ValueError("Denominator is zero, check input probabilities.")
+
+    posterior_A_given_B = numerator / denominator
+    return posterior_A_given_B

ProbabilityPewter/calculator/combiner.py

@@ -0,0 +1,143 @@
+"""
+Docstring for the combiner module
+
+This module provides functionality to calculate combined probabilities and outcomes.
+
+"""
+import math
+from fractions import Fraction
+
+
+def _round_sig(val, sig=10):
+    """Round val to sig significant figures, preserving very small values."""
+    if val == 0:
+        return 0.0
+    magnitude = math.floor(math.log10(abs(val)))
+    return round(val, sig - 1 - magnitude)
+
+
+def _to_decimal_str(val):
+    """Format a float as a plain decimal string without scientific notation."""
+    if val == 0:
+        return "0"
+    magnitude = math.floor(math.log10(abs(val)))
+    decimal_places = max(0, 10 - 1 - magnitude)
+    formatted = f"{val:.{decimal_places}f}"
+    if "." in formatted:
+        formatted = formatted.rstrip("0").rstrip(".")
+    return formatted
+
+
+def combined_prob(A=0.5, B=0.33, event="A&B", output_scale="prob"):
+    """
+    Calculate the combined probability of independent events, like A and B.
+    The syntax for the event parameter specifies the relationship between events. For example: "A&B" means the probability that both A and B occur, while "A/B" means that either A or B occurs.
+    
+    
+    Parameters:
+    -----------
+    A : float or str
+        Probability of event A, either as a decimal (0-1), percentage (0-100), or odds ("X:Y")
+    B : float or str
+        Probability of event B, either as a decimal (0-1), percentage (0-100), or odds ("X:Y")
+    event : str
+        Syntax for the event combination:
+        - "A&B" or "A∩B": AND/intersection P(A∩B) = P(A) * P(B)     # both A and B occur, assuming independence
+        - "A/B" or "A∪B": OR/union P(A∪B) = P(A) + P(B) - P(A∩B)    # either A or B or both occur
+        - "!A" or "¬A": NOT/complement P(¬A) = 1 - P(A)             # A does not occur
+        - "A^B" or "A⊕B": XOR P(A⊕B) = P(A) + P(B) - 2*P(A∩B)     # either A or B occurs, but not both
+        - "A-B" or "A∖B": Difference P(A∖B) = P(A) - P(A∩B)         # A occurs but not B (instead of just: B not occuring)
+        - "none(A, B)": P(none) = ∏(1-P(i))                      # neither A nor B occur
+        - "atleast1(A, B)": P(at least one) = 1 - P(none)        # at least one of A or B occurs
+    output_scale : str
+        Output format: 
+         "prob" (0-1), "percent" (0-100%), or "odds" (X:Y)
+    
+    Returns:
+    --------
+    float or str
+        Combined probability in requested scale
+    """
+    
+    # Convert inputs to probability scale (0-1) by auto-detecting format:
+    # "X:Y" string -> odds, value > 1 -> percent (0-100), otherwise -> prob (0-1)
+    def to_prob(val):
+        if isinstance(val, str) and ":" in val:
+            x, y = map(float, val.split(':'))
+            return x / (x + y)
+        if isinstance(val, str) and "%" in val:
+            return float(val.strip('%')) / 100
+        elif val > 1:
+            return val / 100
+        return val
+    
+    def from_prob(val, out_scale=output_scale):
+        val = _round_sig(val)  # remove floating point noise without destroying very small values
+        if out_scale == "percent" or out_scale == "%" or out_scale == "perc" or out_scale == "percentage":
+            return _to_decimal_str(_round_sig(val * 100)) + "%"
+        elif out_scale == "odds":
+            if val == 0:
+                return "0:1"
+            elif val == 1:
+                return "1:0"
+            if val < 0.001:
+                # Very small probability: Fraction.limit_denominator(1000) would round to 0, so compute directly
+                denom = int(_round_sig(1 / val, sig=3))
+                return f"1:{denom}"
+            # Convert to simplified integer odds A:B (e.g. 0.25 -> "1:3") expressing the ratio of favorable outcomes to unfavorable outcomes
+            frac = Fraction(val).limit_denominator(1000)
+            a, b = frac.numerator, frac.denominator - frac.numerator
+            return f"{a}:{b}"
+        return val
+    
+    p_a = to_prob(A)
+    p_b = to_prob(B)
+    
+    event = event.strip()
+    
+    # AND / Intersection
+    if "&" in event or "∩" in event:
+        result = p_a * p_b
+    
+    # OR / Union
+    elif "/" in event or "∪" in event:
+        result = p_a + p_b - (p_a * p_b)
+    
+    # NOT / Complement
+    elif event.startswith("!") or event.startswith("¬"):
+        result = 1 - p_a
+    
+    # XOR
+    elif "^" in event or "⊕" in event:
+        result = p_a + p_b - 2 * (p_a * p_b)
+    
+    # Difference
+    elif "-" in event or "∖" in event:
+        result = p_a - (p_a * p_b)
+    
+    # None (all fail)
+    elif event.startswith("none"):
+        # Extract all probability arguments
+        probs = [p_a, p_b]
+        result = 1
+        for p in probs:
+            result *= (1 - p)
+    
+    # At least one
+    elif event.startswith("atleast1"):
+        probs = [p_a, p_b]
+        p_none = 1
+        for p in probs:
+            p_none *= (1 - p)
+        result = 1 - p_none
+    
+    else:
+        raise ValueError(f"Unknown event syntax: {event}")
+    
+    return from_prob(result)
+    
+    #To do:
+    # - Improve code to handle very low probabilities 
+    # - Add support for more than 2 events (e.g. A, B, C, ...)
+    # - Add a function for Bayesian updating P(A|B) = P(B|A)*P(A)/P(B)
+    # - Multi-event combinations like: exactly k of n events occur (independent Bernoulli), or at least k of n occur

ProbabilityPewter/calculator/series.py

@@ -0,0 +1,63 @@
+"""
+Docstring for the series module
+
+This module provides functionality to calculate series probabilities and outcomes.
+
+"""
+import math
+
+def at_least_k_of_n(k, n, p, output='result'):
+    """Calculate the probability of getting at least k successes in n independent Bernoulli trials with success probability p.
+    
+    Parameters:
+    -----------
+    k : int
+        Minimum number of successes
+    n : int
+        Total number of trials
+    p : float
+        Probability of success on each trial (0-1). Input can also be a fraction (e.g. 1/3)
+    output : str, optional
+        Output format: 'result' (default, numeric) or 'verbose' (string)
+    
+    """
+    if k > n:
+        return 0.0
+    if k <= 0:
+        return 1.0
+    # Calculate the cumulative probability of getting fewer than k successes
+    cumulative_prob = sum(math.comb(n, i) * (p ** i) * ((1 - p) ** (n - i)) for i in range(k))
+    if output == 'verbose':
+        print(f"The probability of getting {k} or more successes after {n} attempts/trials (each having a {p*100:.2f}% probability of success) is:")
+        return f"{(1 - cumulative_prob)*100:.2f}%"
+    else:
+        return 1 - cumulative_prob
+    
+    
+def gambler_ruin(i, n, p=0.5):
+    """Calculate the probability of ending up with n after starting at i, derived from the 
+    gambler's ruin Markov chain, also used for the random walk problem.
+    
+    Parameters:
+    -----------
+    i : int
+        Starting amount
+    n : int
+        Target amount
+    p : float, optional
+        Probability of winning each bet or getting closer to the target (default is 0.5)
+    Returns:
+    --------
+    float
+        Probability of reaching n without first going broke (reaching 0)
+    """
+    if i <= 0:
+        return 0.0
+    if i >= n:
+        return 1.0
+    if p == 0.5:
+        return i / n
+    else:
+        q = 1 - p
+        return (1 - (q / p) ** i) / (1 - (q / p) ** n)
+    #Validated using https://zcalculators.com/calculator/gamblers-ruin

ProbabilityPewter/roll_stats/__init__.py

@@ -0,0 +1,7 @@
+"""Dice rolling tools for ProbabilityPewter."""
+
+from .dice import rpg_dice
+from .compare import prob_table
+from .combat import combat_odds, risk_odds, ti_odds, aa_odds
+
+__all__ = ["rpg_dice", "prob_table", "combat_odds"]