Transformations Module
======================

Unit-specific panel data transformations for difference-in-differences.

This module implements unit-specific outcome transformations that remove
pre-treatment heterogeneity from panel data. Transformation parameters are
estimated using only pre-treatment observations, then applied out-of-sample
to all periods including post-treatment.

The transformations convert panel difference-in-differences estimation into
cross-sectional treatment effects problems, enabling the application of various
estimators (regression adjustment, inverse probability weighting, doubly robust,
matching) to the transformed outcomes.

.. automodule:: lwdid.transformations
   :no-members:

Available Transformations
-------------------------

demean
~~~~~~

Removes unit-specific pre-treatment mean:

.. math::

   \dot{Y}_{it} = Y_{it} - \bar{Y}_{i,pre}

where :math:`\bar{Y}_{i,pre} = T_0^{-1} \sum_{s<g} Y_{is}`.

**Requirements**: At least 1 pre-treatment period per unit.

**Use case**: Standard parallel trends assumption where treatment and control
groups have parallel outcome paths in levels.

detrend
~~~~~~~

Removes unit-specific linear time trend:

.. math::

   \dot{Y}_{it} = Y_{it} - \hat{\alpha}_i - \hat{\beta}_i t

where :math:`(\hat{\alpha}_i, \hat{\beta}_i)` are OLS estimates from
pre-treatment data.

**Requirements**: At least 2 pre-treatment periods per unit.

**Use case**: Heterogeneous linear trends where treatment and control units
may follow different linear growth paths.

demeanq
~~~~~~~

Removes unit-specific mean with seasonal fixed effects:

.. math::

   \dot{Y}_{it} = Y_{it} - \hat{\mu}_i - \sum_{q=2}^{Q} \hat{\gamma}_q D_q

where :math:`D_q` are seasonal dummies with the smallest observed season as
reference category and :math:`Q` is the number of seasons per cycle.

**Supported seasonal periods**: Q=4 (quarterly, default), Q=12 (monthly),
Q=52 (weekly).

**Requirements**: At least Q+1 pre-treatment observations per unit. Each
season appearing in the post-treatment period must also appear in the
pre-treatment period.

**Use case**: Periodic data with seasonal patterns.

detrendq
~~~~~~~~

Removes unit-specific linear trend with seasonal effects:

.. math::

   \dot{Y}_{it} = Y_{it} - \hat{\alpha}_i - \hat{\beta}_i t
                  - \sum_{q=2}^{Q} \hat{\gamma}_q D_q

**Supported seasonal periods**: Q=4 (quarterly, default), Q=12 (monthly),
Q=52 (weekly).

**Requirements**: At least Q+2 pre-treatment observations per unit. Each
season appearing in the post-treatment period must also appear in the
pre-treatment period.

**Use case**: Periodic data with both trends and seasonal patterns.

Main Function
-------------

.. autofunction:: lwdid.transformations.apply_rolling_transform

Unit-Level Functions
--------------------

.. autofunction:: lwdid.transformations.detrend_unit

.. autofunction:: lwdid.transformations.demeanq_unit

.. autofunction:: lwdid.transformations.detrendq_unit

Internal Functions
------------------

.. autofunction:: lwdid.transformations._demean_transform

.. autofunction:: lwdid.transformations._detrend_transform

Example Usage
-------------

The transformation is automatically applied by the main ``lwdid()`` function:

.. code-block:: python

   from lwdid import lwdid

   # Standard demeaning (parallel trends in levels)
   results_dm = lwdid(data, y='y', d='d', ivar='i', tvar='t',
                      post='post', rolling='demean')

   # Detrending (allows heterogeneous linear trends)
   results_dt = lwdid(data, y='y', d='d', ivar='i', tvar='t',
                      post='post', rolling='detrend')

   # Quarterly demeaning with seasonality
   results_dmq = lwdid(data, y='y', d='d', ivar='i',
                       tvar=['year', 'quarter'],  # Composite time variable
                       post='post', rolling='demeanq')

   # Quarterly detrending with seasonality
   results_dtq = lwdid(data, y='y', d='d', ivar='i',
                       tvar=['year', 'quarter'],  # Composite time variable
                       post='post', rolling='detrendq')

Transformation Selection Guide
------------------------------

- **demean**: Pre-periods required >= 1. No seasonal support. Assumes parallel
  levels (common trends).
- **detrend**: Pre-periods required >= 2. No seasonal support. Allows
  heterogeneous linear trends.
- **demeanq**: Pre-periods required >= Q+1. Seasonal support (Q=4/12/52).
  Assumes parallel levels (common trends).
- **detrendq**: Pre-periods required >= Q+2. Seasonal support (Q=4/12/52).
  Allows heterogeneous linear trends.

Staggered Adoption Transformations
----------------------------------

For staggered adoption designs, transformations are applied separately for each
treatment cohort :math:`g`, using cohort-specific pre-treatment periods. This
approach follows Lee and Wooldridge (2025).

Cohort-Specific Demeaning
~~~~~~~~~~~~~~~~~~~~~~~~~~

For cohort :math:`g` (units first treated in period :math:`g`) and calendar
time :math:`r \geq g`, the transformed outcome is computed as:

.. math::

   \dot{Y}_{irg} = Y_{ir} - \bar{Y}_{i,pre(g)}

where the cohort-specific pre-treatment mean is:

.. math::

   \bar{Y}_{i,pre(g)} = \frac{1}{g-1} \sum_{s=1}^{g-1} Y_{is}

The key difference from common timing demeaning is that the pre-treatment
average uses only periods :math:`\{1, 2, \ldots, g-1\}` specific to each
cohort, rather than a fixed set of pre-treatment periods for all units.

**Requirements**: For each cohort :math:`g`, at least :math:`g - 1 \geq 1`
pre-treatment periods must exist. Early cohorts (e.g., :math:`g = 2`) may
have limited pre-treatment data.

Cohort-Specific Detrending
~~~~~~~~~~~~~~~~~~~~~~~~~~~

For cohort :math:`g` and calendar time :math:`r \geq g`, the detrended outcome
is:

.. math::

   \ddot{Y}_{irg} = Y_{ir} - \hat{A}_{ig} - \hat{B}_{ig} \cdot r

where :math:`(\hat{A}_{ig}, \hat{B}_{ig})` are estimated from the unit-specific
regression using only pre-treatment periods for cohort :math:`g`:

.. math::

   Y_{it} = A_i + B_i \cdot t + \varepsilon_{it}, \quad t \in \{1, 2, \ldots, g-1\}

This removes both unit-specific levels and unit-specific linear trends,
allowing for heterogeneous trend paths across units while preserving the
treatment variation for estimation.

**Requirements**: For each cohort :math:`g`, at least :math:`g - 1 \geq 2`
pre-treatment periods must exist to estimate both intercept and slope.

Staggered Transformation Usage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The staggered transformations are applied automatically when the ``gvar``
parameter is specified in ``lwdid()``:

.. code-block:: python

   from lwdid import lwdid

   # Staggered demeaning
   results = lwdid(
       data,
       y='outcome',
       ivar='unit',
       tvar='year',
       gvar='first_treat_year',  # Cohort indicator
       rolling='demean'
   )

   # Staggered detrending
   results = lwdid(
       data,
       y='outcome',
       ivar='unit',
       tvar='year',
       gvar='first_treat_year',
       rolling='detrend'
   )

Staggered Transformation Selection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In staggered adoption designs, only the ``demean`` and ``detrend``
transformations are supported through the main ``lwdid()`` interface.
Seasonal transformations (``demeanq``, ``detrendq``) are restricted to
common timing mode; passing ``rolling='demeanq'`` or ``rolling='detrendq'``
with ``gvar`` raises a ``ValueError``.

- **demean**: Staggered support via ``lwdid()`` = Yes. Pre-periods required:
  :math:`g - 1 \geq 1` per cohort.
- **detrend**: Staggered support via ``lwdid()`` = Yes. Pre-periods required:
  :math:`g - 1 \geq 2` per cohort.
- **demeanq**: Staggered support via ``lwdid()`` = No (common timing only).
- **detrendq**: Staggered support via ``lwdid()`` = No (common timing only).

.. note::

   The staggered module contains low-level implementations of
   ``transform_staggered_demeanq`` and ``transform_staggered_detrendq``
   for advanced users, but these are not exposed through the main
   ``lwdid()`` function.

See Also
--------

:func:`lwdid.lwdid` : Main estimation function.
:doc:`../methodological_notes` : Theoretical foundations of transformations.
:doc:`../user_guide` : Practical guidance on transformation selection.