Getting started
===============

Installation
------------

Once the package is on PyPI, you can install it via:

.. code-block:: bash

   pip install extendedmosaicperm

For development, clone the repository and install in editable mode
with extra dependencies:

.. code-block:: bash

   git clone https://github.com/<your-user>/extendedmosaicperm.git
   cd extendedmosaicperm
   pip install -e ".[dev,docs]"

Basic usage
-----------

Below is a minimal example that:

1. simulates a simple factor model,
2. builds an adaptive tiling,
3. runs the extended mosaic factor test with sign-flip inference.

.. code-block:: python

   import numpy as np
   from mosaicperm import statistics
   from extendedmosaicperm.factor import ExtendMosaicFactorTest
   from extendedmosaicperm.tilings import build_adaptive_tiling

   # dimensions
   T, N, K = 60, 12, 3
   rng = np.random.default_rng(0)

   # factor model Y = F B + eps
   F = rng.standard_normal((T, K))
   B = rng.standard_normal((K, N))
   Y = F @ B + rng.standard_normal((T, N))

   # exposures as (N, K)
   exposures = B.T

   # build adaptive tiling based on residual covariance
   tiles = build_adaptive_tiling(Y, exposures, batch_size=10, D=3, seed=0)

   # extended mosaic test with sign-flipping
   mpt = ExtendMosaicFactorTest(
       outcomes=Y,
       exposures=exposures,
       tiles=tiles,
       test_stat=statistics.mean_maxcorr_stat,
       sign_flipping=True,
       seed=0,
   )

   # run the test
   mpt.fit(nrand=200, verbose=False)
   print("p-value:", mpt.pval)

Factor-model data generators
----------------------------

The :class:`extendedmosaicperm.factor_data.FactorModelDataGenerator`
class provides several convenient synthetic designs:

* random residual correlation,
* block correlation,
* diagonal + common residual factor.

Example:

.. code-block:: python

   from extendedmosaicperm.factor_data import FactorModelDataGenerator

   gen = FactorModelDataGenerator(
       n_timepoints=250,
       n_assets=50,
       n_factors=5,
       seed=0,
   )

   Y, L_time, X, eps = gen.generate_data_random_correlation(
       violation_strength=0.1,
       symmetric_residuals=True,
   )

   print(Y.shape, L_time.shape, X.shape, eps.shape)