Getting started

Installation

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

pip install extendedmosaicperm

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

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.

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 extendedmosaicperm.factor_data.FactorModelDataGenerator class provides several convenient synthetic designs:

  • random residual correlation,

  • block correlation,

  • diagonal + common residual factor.

Example:

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)