Skip to content

Scale

This pages contains classes defined in hakowan.scale module.

Composable transformations from source attributes to visual values.

ScaleLike = float | Scale module-attribute

Type alias for scale-like objects.

  • A scalar value will be converted to Uniform scale with the scalar value as the factor.
  • A Scale object will be unchanged.

Affine dataclass

Bases: Scale

Scale the data using an affine transformation.

Attributes:

Name Type Description
matrix NDArray

The affine transformation matrix.
Source code in hakowan/grammar/scale/scale.py 
 98
 99
100
101
102
103
104
105
106
107
@dataclass(slots=True)
class Affine(Scale):
    """Scale the data using an affine transformation.

    Attributes:
        matrix: The affine transformation matrix.

    """

    matrix: npt.NDArray

Clip dataclass

Bases: Scale

Clip the data to the range [min, max].

Attributes:

Name Type Description
domain tuple[float, float]

The clip minimum and maximum values.
Source code in hakowan/grammar/scale/scale.py 
110
111
112
113
114
115
116
117
118
119
@dataclass(slots=True)
class Clip(Scale):
    """Clip the data to the range [min, max].

    Attributes:
        domain: The clip minimum and maximum values.

    """

    domain: tuple[float, float]

Custom dataclass

Bases: Scale

Scale the data using a custom function.

Attributes:

Name Type Description
function Callable

The scaling function. E.g. lambda x: x ** 2 for squaring the data.
Source code in hakowan/grammar/scale/scale.py 
86
87
88
89
90
91
92
93
94
95
@dataclass(slots=True)
class Custom(Scale):
    """Scale the data using a custom function.

    Attributes:
        function: The scaling function. E.g. `lambda x: x ** 2` for squaring the data.

    """

    function: Callable

Log dataclass

Bases: Scale

Logarithmic scale.

Attributes:

Name Type Description
base float

The base of the logarithm.
Source code in hakowan/grammar/scale/scale.py 
62
63
64
65
66
67
68
69
70
71
@dataclass(slots=True)
class Log(Scale):
    """Logarithmic scale.

    Attributes:
        base: The base of the logarithm.

    """

    base: float = 10.0

Norm dataclass

Bases: Scale

Reduce a vector attribute to its per-element magnitude (a scalar field).

Unlike the other scales, Norm changes the dimensionality of the attribute: an N x d vector field becomes an N scalar field holding the row-wise order-norm. It is therefore only meaningful as the leading scale of an attribute (any chained child scales operate on the resulting scalar field). The hakowan.norm() helper is the convenient shorthand for constructing an attribute carrying this scale.

Attributes:

Name Type Description
order float

The order of the norm (e.g. 2 for Euclidean length, 1 for Manhattan, numpy.inf for max-abs). Default 2.
Source code in hakowan/grammar/scale/scale.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
@dataclass(slots=True)
class Norm(Scale):
    """Reduce a vector attribute to its per-element magnitude (a scalar field).

    Unlike the other scales, `Norm` changes the dimensionality of the attribute:
    an `N x d` vector field becomes an `N` scalar field holding the row-wise
    `order`-norm. It is therefore only meaningful as the *leading* scale of an
    attribute (any chained child scales operate on the resulting scalar field).
    The `hakowan.norm()` helper is the convenient shorthand for constructing an
    attribute carrying this scale.

    Attributes:
        order: The order of the norm (e.g. ``2`` for Euclidean length,
            ``1`` for Manhattan, ``numpy.inf`` for max-abs). Default ``2``.

    """

    order: float = 2.0

Normalize dataclass

Bases: Scale

Map an inferred or explicit input domain to an output range.

Scalars and vectors are both supported when bounds have matching shapes.

Attributes:

Name Type Description
range_min ArrayLike

The minimum value of the output range.
range_max ArrayLike

The maximum value of the output range.
domain_min ArrayLike | None

The minimum value of the input range. If not specified, the minimum value of the input data will be used.
domain_max ArrayLike | None

The maximum value of the input range. If not specified, the maximum value of the input data will be used.
Source code in hakowan/grammar/scale/scale.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
@dataclass(slots=True)
class Normalize(Scale):
    """Map an inferred or explicit input domain to an output range.

    Scalars and vectors are both supported when bounds have matching shapes.

    Attributes:
        range_min: The minimum value of the output range.
        range_max: The maximum value of the output range.
        domain_min: The minimum value of the input range. If not specified, the minimum value of the
            input data will be used.
        domain_max: The maximum value of the input range. If not specified, the maximum value of the
            input data will be used.

    """

    range_min: npt.ArrayLike
    range_max: npt.ArrayLike
    domain_min: npt.ArrayLike | None = None
    domain_max: npt.ArrayLike | None = None

Scale dataclass

Base class for all scales.

Source code in hakowan/grammar/scale/scale.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
@dataclass(kw_only=True, slots=True)
class Scale:
    """Base class for all scales."""

    _child: Optional["Scale"] = None

    def __imul__(self, other: "Scale") -> "Scale":
        """Append ``other`` to this scale chain in place.

        A deep copy prevents later mutations of a reused scale from aliasing
        this chain.
        """
        # `other` may be reused across multiple scale chains (and may gain its own
        # child later), so it must be deep copied to avoid aliasing side effects.
        # This mirrors `Transform.__imul__`.
        s = self
        while s._child is not None:
            s = s._child
        s._child = copy.deepcopy(other)
        return self

    def __mul__(self, other: "Scale") -> "Scale":
        """Return a new chain that applies this scale before ``other``.

        Neither operand is modified.
        """
        r = copy.deepcopy(self)
        r *= other
        return r

__imul__(other)

Append other to this scale chain in place.

A deep copy prevents later mutations of a reused scale from aliasing this chain.

Source code in hakowan/grammar/scale/scale.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
def __imul__(self, other: "Scale") -> "Scale":
    """Append ``other`` to this scale chain in place.

    A deep copy prevents later mutations of a reused scale from aliasing
    this chain.
    """
    # `other` may be reused across multiple scale chains (and may gain its own
    # child later), so it must be deep copied to avoid aliasing side effects.
    # This mirrors `Transform.__imul__`.
    s = self
    while s._child is not None:
        s = s._child
    s._child = copy.deepcopy(other)
    return self

__mul__(other)

Return a new chain that applies this scale before other.

Neither operand is modified.

Source code in hakowan/grammar/scale/scale.py 
30
31
32
33
34
35
36
37
def __mul__(self, other: "Scale") -> "Scale":
    """Return a new chain that applies this scale before ``other``.

    Neither operand is modified.
    """
    r = copy.deepcopy(self)
    r *= other
    return r

Uniform dataclass

Bases: Scale

Scale the data uniformly by multiplying it with a factor.

Attributes:

Name Type Description
factor float

The scaling factor.
Source code in hakowan/grammar/scale/scale.py 
74
75
76
77
78
79
80
81
82
83
@dataclass(slots=True)
class Uniform(Scale):
    """Scale the data uniformly by multiplying it with a factor.

    Attributes:
        factor: The scaling factor.

    """

    factor: float

to_scale(value)

Coerce a scale-like value into a Scale.

This is the single coercion point for ScaleLike values: a scalar is wrapped as Uniform(factor=value), while an existing Scale is returned unchanged.

Parameters:

Name Type Description Default
value ScaleLike

A float/int (uniform factor) or a Scale.

 required

Returns:

Type Description
Scale

The corresponding Scale object.
Source code in hakowan/grammar/scale/scale.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
def to_scale(value: ScaleLike) -> Scale:
    """Coerce a scale-like value into a `Scale`.

    This is the single coercion point for [`ScaleLike`][hakowan.grammar.scale.scale.ScaleLike]
    values: a scalar is wrapped as `Uniform(factor=value)`, while an existing
    `Scale` is returned unchanged.

    Args:
        value: A float/int (uniform factor) or a `Scale`.

    Returns:
        The corresponding `Scale` object.

    """
    if isinstance(value, (int, float)):
        return Uniform(factor=float(value))
    assert isinstance(value, Scale), f"Cannot convert {type(value)} to Scale"
    return value

Attribute-offset scale model.

Offset dataclass

Bases: Scale

Offset the data by a constant.

Attributes:

Name Type Description
offset Attribute

The offset to apply to the data.
Source code in hakowan/grammar/scale/offset.py 
 9
10
11
12
13
14
15
16
17
18
@dataclass(slots=True)
class Offset(Scale):
    """Offset the data by a constant.

    Attributes:
        offset (Attribute): The offset to apply to the data.

    """

    offset: Attribute