densitty 0.8.2__py3-none-any.whl → 0.9.0__py3-none-any.whl

densitty/util.py

@@ -1,26 +1,28 @@
 """Utility functions."""
 
-from bisect import bisect_left
-from collections import namedtuple
-from decimal import Decimal
+from __future__ import annotations  # for pre-Python 3.12 compatibility
+
 import math
-from typing import Any, Protocol, Sequence, SupportsFloat
+import typing
 
+from bisect import bisect_left
+from decimal import Decimal, BasicContext
+from fractions import Fraction
+from typing import Any, Callable, NamedTuple, Sequence
 
-class FloatLike[T](SupportsFloat, Protocol):
-    """A Protocol that supports the arithmetic ops we require, and can convert to float"""
 
-    def __lt__(self, __other: T) -> bool: ...
-    def __add__(self, __other: Any) -> T: ...
-    def __sub__(self, __other: Any) -> T: ...
-    def __mul__(self, __other: Any) -> T: ...
-    def __truediv__(self, __other: Any) -> T: ...
-    def __abs__(self) -> T: ...
+# FloatLike and Vec are defined in the stubs file util.pyi for type checking
+# At runtime, define as Any so older Python versions don't choke:
+if not typing.TYPE_CHECKING:
+    FloatLike = Any
+    Vec = Any
 
 
-ValueRange = namedtuple("ValueRange", ["min", "max"])
+class ValueRange(NamedTuple):
+    """Encapsulates a range from min..max"""
 
-type Vec = Sequence[FloatLike]
+    min: Decimal
+    max: Decimal
 
 
 def clamp(x, min_x, max_x):
@@ -76,44 +78,73 @@ def nearest(stepwise: Sequence, x: float):
     return stepwise[clamped_idx]
 
 
-def decimal_value_range(v: ValueRange | Sequence):
-    """Produce a ValueRange containing Decimal values"""
-    return ValueRange(Decimal(v[0]), Decimal(v[1]))
+def make_decimal(x: FloatLike) -> Decimal:
+    """Turn a float into a decimal with reasonable precision,
+    avoiding things like 1.0000000000000002220446049250313080847263336181640625"""
+    if isinstance(x, Decimal):
+        return x
+    return BasicContext.create_decimal_from_float(float(x))
+
+
+def make_value_range(v: ValueRange | Sequence[FloatLike]) -> ValueRange:
+    """Produce a ValueRange from from something that may be a sequence of FloatLikes"""
+    return ValueRange(make_decimal(v[0]), make_decimal(v[1]))
+
+
+def partial_first(f: Callable[[FloatLike, FloatLike], FloatLike]) -> Callable:
+    """Equivalent to functools.partial, but works with Python 3.10"""
+
+    def out(x: FloatLike):
+        return f(x, 0)
+
+    return out
+
+
+def partial_second(f: Callable[[FloatLike, FloatLike], FloatLike]) -> Callable:
+    """Equivalent to functools.partial, but works with Python 3.10"""
+
+    def out(x: FloatLike):
+        return f(0, x)
+
+    return out
 
 
 def sfrexp10(value):
     """Returns sign, base-10 fraction (mantissa), and exponent.
-    i.e. (s, f, e) such that value = s * f * 10 ** e with 0 <= f < 1.0
+    i.e. (s, f, e) such that value = s * f * 10 ** e.
+    if f == 0 => value == 0, else 0.1 < f <= 1.0
     """
     if value == 0:
-        return 1, 0, -100
+        return 1, Fraction(0), -100
 
-    sign = -1 if value < 0 else 1
-
-    v = Decimal(abs(value))
-    exponent = v.adjusted() + 1
-    frac = v.scaleb(-exponent)  # scale frac's exponent to be 0
+    if value < 0:
+        sign = -1
+        value = -value
+    else:
+        sign = 1
 
-    return sign, frac, exponent
+    exp = math.ceil(math.log10(float(value)))
+    frac = (Fraction(value) / Fraction(10) ** exp).limit_denominator()
+    return sign, frac, exp
 
 
 round_fractions = (
-    Decimal(1) / Decimal(10),
-    Decimal(1) / Decimal(8),
-    Decimal(1) / Decimal(6),
-    Decimal(1) / Decimal(5),
-    Decimal(1) / Decimal(4),
-    Decimal(1) / Decimal(3),
-    Decimal(2) / Decimal(5),
-    Decimal(1) / Decimal(2),
-    Decimal(2) / Decimal(3),
-    Decimal(4) / Decimal(5),
-    Decimal(1),
+    Fraction(1, 10),
+    Fraction(1, 8),
+    Fraction(1, 6),
+    Fraction(1, 5),
+    Fraction(1, 4),
+    Fraction(1, 3),
+    Fraction(2, 5),
+    Fraction(1, 2),
+    Fraction(2, 3),
+    Fraction(4, 5),
+    Fraction(1, 1),
 )
 
 
 def round_up_ish(value, round_fracs=round_fractions):
-    """'Round' the value up to the next highest value in 'round_vals' times a multiple of 10
+    """'Round' the value up to the next highest value in 'round_fracs' times a multiple of 10
 
     Parameters
     ----------
@@ -121,114 +152,85 @@ def round_up_ish(value, round_fracs=round_fractions):
     round_vals: the allowable values (mantissa in base 10)
     return: the closest round_vals[i] * 10**N equal to or larger than 'value'
     """
-    sign, frac, exp = sfrexp10(value)
+    sign, frac_float, exp = sfrexp10(value)
 
     # if we're passed in a float that can't be represented in binary (say 0.1 or 0.2), it will be
-    # rounded up to the next representable float. Subtract the smallest possible value (ulp) to
-    # so that when we round up, it can match an exact Decimal("0.1") or such:
-    frac -= Decimal(math.ulp(frac))
+    # rounded up to the next representable float. Adjust to closest sensible fraction:
+    frac = Fraction(frac_float).limit_denominator()
 
     idx = bisect_left(round_fracs, frac)  # find index that this would be inserted before (>= frac)
     round_frac = round_fracs[idx]
 
-    return sign * round_frac.scaleb(exp)
+    return sign * round_frac * 10**exp
 
 
 def roundness(value):
     """Metric for how 'round' a value is. 10 is rounder than 1, is rounder than 1.1."""
 
-    # if value is a sequence, combine the roundness of all elements, prioritizing in order:
     if isinstance(value, Sequence):
-        out, weight = 0, 1
-        for v in value:
-            out += roundness(v) * weight
-            weight *= 0.99
-        return out
-
+        # return the average roundness of all elements, with a bonus for the size of the range
+        num = len(value)
+
+        if num > 1:
+            roundnesses = (roundness(v) for v in value)
+            mean = sum(roundnesses) / num
+            # give a bonus to sets that cover a longer interval
+            log_value_range = math.log(value[-1] - value[0])
+        else:
+            mean = roundness(value[0])
+            log_value_range = -1000  # as if we're covering a range of 10^-1000
+
+        # we want a small bonus to "roundness" if the range is bigger.
+        # Keep it small enough that 1..2 won't get expanded to 0.5..2, say
+        # log_value_range increases by ~0.3 for every doubling of range
+        # which is ~ the penalty for using 1/2 vs 1
+        return mean + log_value_range
+
+    # Just a single value, not a sequence:
     if value == 0:
         # 0 is the roundest value
         return 1000  # equivalent to roundness of 1e1000
-    _, frac, exp = sfrexp10(value)
 
-    round_frac = round(frac, 5)  # round to specific # of digits so we can interpret as fraction
+    if value < 0:
+        value = -value
+
+    exp = math.ceil(math.log10(float(value)))
+    frac = (Fraction(value) / Fraction(10) ** exp).limit_denominator()
+    # so frac is 1 for a multiple of 10, and <1 for non-multiples of 10
+
+    # penalties based on the denominator of 'frac' when expressed as a ratio:
     penalties = {
-        1.00000: 0.0,  # no penalty for multiples of 10
-        0.50000: 0.5,  # penalty for multiple of 5 vs multiple of 10
-        0.25000: 0.6,  # penalty for multiple of 4 vs multiple of 10
-        0.75000: 0.6,  #
-        Decimal("0.33333"): 0.7,  # penalty for multiple of 3 vs multiple of 10
-        Decimal("0.66667"): 0.7,  #
-        0.12500: 0.8,  # penalty for multiple of 8 vs multiple of 10
-        0.37500: 0.8,
-        0.62500: 0.8,
-        0.87500: 0.8,
+        1: 0,  # value is power of 10 (1eX)
+        2: 0.3,  # value is 5.0eX
+        5: 0.5,  # value is 2/4/6/8.0 eX
+        10: 1,  # x.1, x.3, x.7, x.9 eX
+        4: 1,  # x.25, x.75 eX
+        3: 1.2,  # x.333, x.666  TODO: figure out how these are being printed and limit digits
+        20: 1.2,  # x.05, x.15, x.35...
+        25: 1.8,  # x.04, x.08, ...
+        50: 1.8,  # x.02, x.06, ...
+        100: 2,  # x.01, ...
     }
 
-    if round_frac in penalties:
-        return exp - penalties[round_frac]
+    if frac.denominator in penalties:
+        return exp - penalties[frac.denominator]
 
-    # Ouch: our fractional part is just not nice, so maximally un-round:
-    return -1000  # equivalent to roundness of 1e-1000
+    # In case we have ticks like 1.001, 1.002, 1.003, try to account for number of digits required:
+    max_digits = 10
+    for digits in range(2, max_digits):
+        if 10**digits % frac.denominator == 0:
+            return exp - digits
 
+    return exp - max_digits
 
-def most_round(values):
-    """Pick the most round of the input values. Ties go to the earliest."""
-    best_r = -1e100
-    best_v = 0
-    for v in values:
-        r = roundness(v)
-        if r > best_r:
-            best_r, best_v = r, v
-    return best_v
 
+def roundness_ordered(values):
+    """Returns values in order of decreasing roundness"""
+    d = {roundness(v): v for v in values}
+    for r in reversed(sorted(d)):
+        yield d[r]
 
-def pick_step_size(value_range, num_steps_hint, min_steps_per_label=1) -> tuple[Decimal, Decimal]:
-    """Try to pick a step size that gives nice round values for step positions.
-    For coming up with nice tick positions for an axis, and with nice bin sizes for binning.
-    For an axis, it is also useful to produce an interval between labeled ticks.
 
-    Parameters
-    ----------
-    value_range: bounds of interval
-    num_steps_hint: approximate number of steps desired for the interval
-    min_steps_per_label: for use with axis/label generation, as labels take more space than ticks
-    return: step size, interval between labeled steps/ticks
-    """
-    num_steps_hint = max(1, num_steps_hint)
-    # if steps are 0,1,2,3,4,5,6... or 0,2,4,6,8,10,... steps_per_label of 5 is sensible,
-    # if steps are 0,5,10,15,20,... steps_per_label of 4 is sensible
-    nominal_step = (value_range.max - value_range.min) / num_steps_hint
-
-    # Figure out the order-of-magnitude (power of 10), aka "decade" of the steps:
-    log_nominal = math.log10(nominal_step)
-    log_decade = math.floor(log_nominal)  # i.e. # of digits
-    decade = Decimal(10) ** log_decade
-
-    # Now figure out where in that decade we are, so we can pick the closest 1/2/5 value
-    log_frac = log_nominal - log_decade  # remainder after decade taken out
-    frac = 10**log_frac  # i.e. fraction through the decade (shift decimal point to front)
-
-    # common-case: label every or every-other, or every 5th, or every 10th
-    if min_steps_per_label <= 2:
-        steps_per_label = min_steps_per_label
-    elif min_steps_per_label <= 5:
-        steps_per_label = 5
-    else:
-        steps_per_label = max(min_steps_per_label, 10)
-
-    if frac < 1.1:
-        step = decade
-    elif frac < 2.2:
-        step = 2 * decade
-        # Steps of .2, don't label every other one
-        if steps_per_label == 2:
-            steps_per_label = 5
-    elif frac < 5.5:
-        step = 5 * decade
-        # ticks every .5, don't label every 5th
-        if steps_per_label == 5:
-            steps_per_label = max(round(min_steps_per_label / 2) * 2, 6)
-    else:
-        step = 10 * decade
-
-    return step, step * steps_per_label
+def most_round(values):
+    """Pick the most round of the input values."""
+    return next(roundness_ordered(values))

densitty/util.pyi

@@ -0,0 +1,37 @@
+from decimal import Decimal
+from typing import Any, Callable, NamedTuple, Protocol, Sequence, SupportsFloat
+
+class FloatLike[T](SupportsFloat, Protocol):
+    def __lt__(self, __other: Any) -> bool: ...
+    def __le__(self, __other: Any) -> bool: ...
+    def __add__(self, __other: Any) -> T: ...
+    def __sub__(self, __other: Any) -> T: ...
+    def __radd__(self, __other: Any) -> T: ...
+    def __rsub__(self, __other: Any) -> T: ...
+    def __mul__(self, __other: Any) -> T: ...
+    def __rmul__(self, __other: Any) -> T: ...
+    def __truediv__(self, __other: Any) -> T: ...
+    def __abs__(self) -> T: ...
+
+class ValueRange(NamedTuple):
+    min: Decimal
+    max: Decimal
+
+type Vec = Sequence[FloatLike]
+
+def clamp(x, min_x, max_x): ...
+def clamp_rgb(rgb): ...
+def interp(piecewise: Sequence[Vec], x: float) -> Vec: ...
+def nearest(stepwise: Sequence, x: float): ...
+def make_decimal(x: FloatLike) -> Decimal: ...
+def make_value_range(v: ValueRange | Sequence[FloatLike]) -> ValueRange: ...
+def partial_first(f: Callable[[FloatLike, FloatLike], FloatLike]) -> Callable: ...
+def partial_second(f: Callable[[FloatLike, FloatLike], FloatLike]) -> Callable: ...
+def sfrexp10(value): ...
+
+round_fractions: tuple[Decimal, ...]
+
+def round_up_ish(value, round_fracs=...): ...
+def roundness(value): ...
+def roundness_ordered(values): ...
+def most_round(values): ...

{densitty-0.8.2.dist-info → densitty-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: densitty
-Version: 0.8.2
+Version: 0.9.0
 Summary: densitty - create textual 2-D density plots, heatmaps, and 2-D histograms in Python
 Author: Bill Tompkins
 License-Expression: MIT
@@ -11,11 +11,14 @@ Classifier: Environment :: Console
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.12
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
@@ -33,4 +36,4 @@ Generate 2-D histograms (density plots, heat maps, eye diagrams) similar to [mat
 
 ## [Color, Size, and Glyph Support](https://billtompkins.github.io/densitty/docs/terminal_support.html)
 
-## API (TODO)
+## [API](https://billtompkins.github.io/densitty/docs/api.html)

densitty-0.9.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+densitty/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+densitty/ansi.py,sha256=YHagUsCwbyNlOkV2pXJuxolWwjvs1E4hxMnJaohqTfE,3661
+densitty/ascii_art.py,sha256=-MUppQkEeCAqSxdLCfuDRD1NKtzSrJAt2WdJEL56_fI,589
+densitty/axis.py,sha256=gI0xNKkYfINAEcYtqCu4K0EsWKPyBjc24CpK_1UvcLA,15637
+densitty/binning.py,sha256=KfQ0_Z_FdZoNYY4RYNKuaiQy0wJ78MI3PSPCxoE2yyk,12117
+densitty/detect.py,sha256=oMb8oPWjZJksJMP0yNdmSn7OmiMcfDkk4owCMvJwcbc,19796
+densitty/lineart.py,sha256=Qkw_F1QEK9yd0ttNjg62bomIavMPza3pk8w7DA85zWs,4124
+densitty/plot.py,sha256=pmxJA8l2xVVaUEeo3DI38WxXT-QSROyCrJ9kN_c0ZKE,8473
+densitty/smoothing.py,sha256=8F4pWA5HS07Y2jDgJAY-cPSqa0uiBiqav_MtLjuiymQ,12348
+densitty/truecolor.py,sha256=6UDLJRUKP8rProemJyfSIgtZ5IdB1v8R_PV41fW6CjA,6016
+densitty/util.py,sha256=PW4KkxuFvlQFmlDgN4yxt6xV_PIAEBstGYYVhTr6mwQ,7304
+densitty/util.pyi,sha256=ZaAduJYuysj2lrD9UVFHlSlDPySMnWVEc6nEkBKko5c,1361
+densitty-0.9.0.dist-info/licenses/LICENSE,sha256=LexlQlxS7F07WxcVOOmZAZ_3vReYv0cM8Zg6pTx7_fI,1073
+densitty-0.9.0.dist-info/METADATA,sha256=XNCk5nlIe5LBU9-krHRisAMyvVi6n0KTaZVDpq1v174,1849
+densitty-0.9.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+densitty-0.9.0.dist-info/top_level.txt,sha256=Q50fHzFeZkhO_61VVAIJZyKU44Upacx_blojlLpYqNo,9
+densitty-0.9.0.dist-info/RECORD,,

densitty-0.8.2.dist-info/RECORD

@@ -1,15 +0,0 @@
-densitty/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-densitty/ansi.py,sha256=YHagUsCwbyNlOkV2pXJuxolWwjvs1E4hxMnJaohqTfE,3661
-densitty/ascii_art.py,sha256=-MUppQkEeCAqSxdLCfuDRD1NKtzSrJAt2WdJEL56_fI,589
-densitty/axis.py,sha256=XANbgvOltS0XhUvUB9dfUBvybEfOmcjI5xGc2NZDgak,10120
-densitty/binning.py,sha256=LioKw7A0xK_lzUEY2tINiL4fySxVNllxrgh2bD4T9AA,9549
-densitty/detect.py,sha256=LBRUDHxpqLq3p0zRUNS7-3YCBSyclfM0vVy0ZmzSVNs,17725
-densitty/lineart.py,sha256=Qkw_F1QEK9yd0ttNjg62bomIavMPza3pk8w7DA85zWs,4124
-densitty/plot.py,sha256=dxdPRensTxWd9CcD2SbekqAe0iOMcKSKR24wrNc5aCw,8340
-densitty/truecolor.py,sha256=uSrT4Qm0T0ZFwXxm1oyNTrdNCDO7ZfUTI687bX5r-8I,5990
-densitty/util.py,sha256=U0B5RSxQOdq5M6no3OC_buZizAcVjTPwwqKvk4QJ5Rc,7888
-densitty-0.8.2.dist-info/licenses/LICENSE,sha256=LexlQlxS7F07WxcVOOmZAZ_3vReYv0cM8Zg6pTx7_fI,1073
-densitty-0.8.2.dist-info/METADATA,sha256=QK1lEOpas0eZ86enDAObh3bxuS1GoQ_Gmk5X2c6lgpg,1646
-densitty-0.8.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-densitty-0.8.2.dist-info/top_level.txt,sha256=Q50fHzFeZkhO_61VVAIJZyKU44Upacx_blojlLpYqNo,9
-densitty-0.8.2.dist-info/RECORD,,