Transformations
================

A ``Transform`` is a composable, callable mapping ``Expr -> Expr``.
Bijective transforms additionally implement ``inverse`` and
``log_det_jacobian``, so they can double as a distribution bijector via
:class:`~prophys.distributions.TransformedDistribution`.

.. grid:: 1 2 2 2
   :gutter: 2

   .. grid-item-card:: Linear
      :img-top: /_static/gallery/transformations/linear.png

      ``a * x + b`` — bijective, with closed-form inverse.

   .. grid-item-card:: Affine
      :img-top: /_static/gallery/transformations/affine_diag.png

      ``A @ x + b`` for vector-valued ``x``.

   .. grid-item-card:: Polynomial
      :img-top: /_static/gallery/transformations/polynomial.png

      ``sum_i coeffs[i] * x**i``.

   .. grid-item-card:: PiecewiseLinear
      :img-top: /_static/gallery/transformations/piecewise_linear_smoothness.png

      ``smooth=0`` gives the exact (subgradient) curve; ``smooth=tau``
      blends neighbouring segments for a fully continuous gradient at the
      knots.

   .. grid-item-card:: Decay
      :img-top: /_static/gallery/transformations/decay_exp.png

      Exponential (``exp(-x/scale)``) or power-law decay, typically
      composed after a distance primitive.

   .. grid-item-card:: Logistic
      :img-top: /_static/gallery/transformations/logistic_k.png

      Dose-response / regulatory-acceptance curves.

   .. grid-item-card:: TableLookup1D
      :img-top: /_static/gallery/transformations/table_lookup_1d.png

      Interpolated 1D characteristic curve (e.g. a power curve).

   .. grid-item-card:: TableLookup2D
      :img-top: /_static/gallery/transformations/table_lookup_2d.png

      Bilinearly interpolated 2D lookup (e.g. sound power level over
      wind speed x direction).

Smoothing behavior of PiecewiseLinear
------------------------------------------

Because a hard piecewise-linear kink has a discontinuous gradient at each
knot, ``PiecewiseLinear`` lets the smoothing temperature trade exactness
against gradient continuity:

.. image:: /_static/gallery/transformations/piecewise_linear_shapes.png
   :width: 70%
   :align: center

A ``smooth`` value that is too large *relative to the knot spacing* will
blend in neighbouring segments' slopes even at points deep inside one
segment — worth checking for if a transformed probability unexpectedly
drifts outside its valid range (e.g. below 0 for a probability fed into
:class:`~prophys.distributions.Bernoulli`).

.. autoclass:: prophys.transformations.Transform
   :members:
.. autoclass:: prophys.transformations.Linear
   :members:
.. autoclass:: prophys.transformations.Affine
   :members:
.. autoclass:: prophys.transformations.Polynomial
   :members:
.. autoclass:: prophys.transformations.PiecewiseLinear
   :members:
.. autoclass:: prophys.transformations.Decay
   :members:
.. autoclass:: prophys.transformations.Logistic
   :members:
.. autoclass:: prophys.transformations.TableLookup1D
   :members:
.. autoclass:: prophys.transformations.TableLookup2D
   :members:

Periodic & recurring phenomena
-----------------------------------

For seasonal, diurnal, tidal, or otherwise recurring signals — and for the
"return period" framing common in extreme-event risk (e.g. a "100-year
flood").

.. autoclass:: prophys.transformations.Phase
   :members:
.. autoclass:: prophys.transformations.Periodic
   :members:
.. autoclass:: prophys.transformations.ReturnPeriod
   :members:
.. autoclass:: prophys.transformations.RecurrenceRate
   :members: