### Install Development Requirements

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/README.rst

Installs all necessary dependencies for developing the Ambrosia library. Requires Python 3.9+ and Poetry to be installed.

```bash
make install
```

--------------------------------

### Install Ambrosia Python Library

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/README.rst

Installs the latest stable release of the Ambrosia library using pip. This is the standard installation for general use.

```bash
pip install ambrosia
```

--------------------------------

### Import Ambrosia Libraries and Pandas

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/10_synthetic_experiment_full_pipeline_short.ipynb

Imports necessary libraries from Ambrosia for preprocessing, design, splitting, and testing, along with pandas for data manipulation. These are foundational imports for any Ambrosia pipeline.

```python
import pandas as pd

from ambrosia.preprocessing import AggregatePreprocessor
from ambrosia.designer import Designer
from ambrosia.splitter import Splitter
from ambrosia.tester import Tester
```

--------------------------------

### Display Aggregated Data

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/10_synthetic_experiment_full_pipeline_short.ipynb

Displays the first few rows of the DataFrame after aggregation using Ambrosia's AggregatePreprocessor. This allows verification of the data transformation and the resulting aggregated metrics per user.

```python
df.head()
```

--------------------------------

### YAML Configuration for Designer and Splitter

Source: https://context7.com/mobiletelesystems/ambrosia/llms.txt

This code illustrates how to use YAML files to configure experiment setups for the Designer and Splitter classes in Ambrosia. It shows creating a Designer configuration, saving it to YAML, loading it back, and running an experiment.

```python
import yaml
from ambrosia.designer import Designer, load_from_config
from ambrosia.splitter import Splitter

# Assume 'data' is a pandas DataFrame

# Create and save Designer config
designer = Designer(
    effects=[1.05, 1.10],
    sizes=[1000, 5000],
    first_type_errors=[0.01, 0.05],
    metrics=['revenue', 'retention']
)

with open('designer_config.yaml', 'w') as f:
    yaml.dump(designer, f)

# Load Designer from config
loaded_designer = load_from_config('designer_config.yaml')
loaded_designer.set_dataframe(data)
results = loaded_designer.run('size')

# YAML config format example:
# !designer
# effects: [1.05, 1.1, 1.2]
# sizes: [1000, 3000, 7000]
# first_type_errors: [0.01, 0.05]
# second_type_errors: [0.2]
# metrics: ['revenue']
# method: theory

```

--------------------------------

### Load and Inspect Synthetic Data

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/10_synthetic_experiment_full_pipeline_short.ipynb

Loads synthetic weekly user metrics from a CSV file into a pandas DataFrame and displays the first few rows. This step is crucial for understanding the initial data structure before preprocessing.

```python
dataframe = pd.read_csv('../tests/test_data/week_metrics.csv')
dataframe.head()
```

--------------------------------

### Get IQRPreprocessor Parameters

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/00_preprocessing.ipynb

Retrieves the parameters that have been fitted by the IQRPreprocessor. This includes column names, medians, and quartiles for the specified columns.

```python
iqr_transformer.get_params_dict()
```

--------------------------------

### Load and Get Parameters for Multicuped

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/01_vr_transformations.ipynb

Loads parameters from a specified store path and retrieves them as a dictionary for the multicuped model. This is a crucial step for initializing and inspecting the model's configuration.

```python
new_multicuped.load_params(store_path_multicuped)
new_multicuped.get_params_dict()
```

--------------------------------

### Aggregate User Metrics with Ambrosia

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/10_synthetic_experiment_full_pipeline_short.ipynb

Uses Ambrosia's AggregatePreprocessor to transform raw user data into aggregated weekly metrics. It groups data by user ID and applies specified aggregation functions (sum, max, simple, mode) to different metrics.

```python
transformer = AggregatePreprocessor()
df = transformer.fit_transform(dataframe,
                               groupby_columns='id',
                               agg_params={
                                   'watched': 'sum',
                                   'sessions': 'max',
                                   'gender': 'simple',
                                   'platform': 'mode'
                               })
```

--------------------------------

### Aggregate Experiment Results (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/10_synthetic_experiment_full_pipeline_short.ipynb

Aggregates daily experiment data to weekly values for analysis. It uses the AggregatePreprocessor to sum up real-valued metrics ('watched') grouped by unique identifiers ('id') and categorical variables ('group').

```python
import pandas as pd
from ambrosia.preprocessor import AggregatePreprocessor

# Load experiment results from CSV
experiment_result = pd.read_csv('../tests/test_data/watch_result.csv')

# Initialize the preprocessor for summing real metrics
transformer = AggregatePreprocessor(real_method='sum')

# Aggregate the data
df_to_test = transformer.fit_transform(dataframe=experiment_result,
                                       groupby_columns='id',
                                       real_cols='watched',
                                       categorial_cols='group')

print(df_to_test.head())
```

--------------------------------

### Install Ambrosia with Spark Support

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/README.rst

Installs Ambrosia with optional PySpark data processing capabilities enabled. This is required if you plan to use Ambrosia with Spark DataFrames.

```bash
pip install ambrosia[spark]
```

--------------------------------

### Initialize Ambrosia Splitter

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

Initializes the Ambrosia Splitter class with the generated synthetic DataFrame. It specifies the 'object_id' column as the unique identifier for objects. This setup is crucial before applying any splitting methods.

```python
splitter = Splitter(dataframe=dataframe, id_column='object_id')
```

--------------------------------

### Clean Virtual Environment

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/README.rst

Removes the virtual environment and its associated files, effectively cleaning up the development setup.

```bash
make clean
```

--------------------------------

### Load and inspect initial data using pandas

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/11_cuped_example.ipynb

Loads data from a CSV file into a pandas DataFrame and displays the first few rows. This step is crucial for understanding the data structure and preparing it for transformations.

```python
dataframe = pd.read_csv('../tests/test_data/kion_data.csv', sep=';')
dataframe.head()
```

--------------------------------

### Get RobustPreprocessor Parameters

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/00_preprocessing.ipynb

Retrieves the parameters that have been set during the fitting process of the `RobustPreprocessor`. This includes the tail direction, column names, alpha values, and calculated quantiles.

```python
robust_transformer.get_params_dict()
```

--------------------------------

### Visualize Group Size Estimation Comparison (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

Generates a histogram comparing the group size estimations from the 'binary' method with different iteration counts against the theoretical estimation. This visualization highlights the convergence and noise in the 'binary' method.

```python
plt.figure(figsize=(8, 6))
plt.title('Group size estimation for 10% MDE')
for key in group_size_estimation_dict:
    label = f'amount number={key}'
    sns.histplot(group_size_estimation_dict[key], label=label)
plt.plot(2382, 0.5, 'ro', label='Theoretical estimation')
plt.legend();
```

--------------------------------

### Import Ambrosia and Data Handling Libraries (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

Imports necessary libraries for data manipulation (numpy, pandas), visualization (matplotlib, seaborn), and Ambrosia's A/B testing design functionalities. These are foundational for the subsequent steps in designing an experiment.

```python
import numpy as np
import pandas as pd

import matplotlib.pyplot as plt
import seaborn as sns

from ambrosia.designer import Designer, design_binary
```

--------------------------------

### Get Fitted Parameters from AggregatePreprocessor

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/00_preprocessing.ipynb

Retrieves the parameters that have been fitted by the AggregatePreprocessor instance. This includes the aggregation methods used for different columns and the column(s) used for grouping.

```python
aggregator.get_params_dict()
```

--------------------------------

### Split Users into A/B Test Groups (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/10_synthetic_experiment_full_pipeline_short.ipynb

Splits a DataFrame into experimental groups using a hash-based method with stratification. This ensures deterministic splitting and accounts for specified categorical variables. It requires the DataFrame, stratification columns, and columns to fit the splitter on.

```python
from ambrosia.splitter import Splitter

# Assuming 'df' is your pandas DataFrame and 'gender', 'platform' are stratification columns
# 'sessions' is used for fitting the splitter
splitter = Splitter(dataframe=df,
                    strat_columns=['gender', 'platform'],
                    fit_columns=['sessions'])

# Split into groups of 900 users with a specific salt for reproducibility
splitted_groups = splitter.run(groups_size=900, method='hash', salt='exp_322')

print(splitted_groups.head())
```

--------------------------------

### Initialize Experiment Designer with Binary Metric (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

Initializes the Ambrosia Designer class with the historical data and specifies 'retention' as the binary metric for the experiment design. This sets up the designer object for subsequent calculations.

```python
designer = Designer(dataframe=data, metrics='retention')
```

--------------------------------

### Estimate Group Size using 'binary' Method with Iterations (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

Estimates the required group size for a 10% MDE using Ambrosia's 'binary' method with varying numbers of interval constructions. This demonstrates how the 'binary' method's accuracy improves with more iterations.

```python
interval_amounts = [2000, 5000, 20000]
group_size_estimation_dict = {}

for amount in interval_amounts:
    group_size_estimation_dict[amount] = []
    for step in range(200):
        estimated_size = designer.run(to_design='size',
                                      method='binary',
                                      interval_type='wald',
                                      amount=amount,
                                      effects=1.1).values[0][0]
        group_size_estimation_dict[amount].append(estimated_size)
```

--------------------------------

### Import necessary libraries for Ambrosia and data manipulation

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/11_cuped_example.ipynb

Imports the required modules from the Ambrosia library and other common data science libraries like numpy and pandas. These are essential for performing data transformations and experiment design.

```python
import numpy as np
import pandas as pd
from tqdm.notebook import tqdm

from ambrosia.designer import Designer
from ambrosia.splitter import Splitter
from ambrosia.tester import Tester

from ambrosia.preprocessing import Cuped
```

--------------------------------

### Initialize Designer for Binary Metrics in Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/07_spark_designer.ipynb

Initializes the Designer object in Python for binary metrics. This setup requires a Spark DataFrame, specified error rates, sizes, effects, and the metric type.

```python
designer = Designer(dataframe=sdf,
                    second_type_errors=0.5,
                    sizes=150,
                    effects=1.2,
                    metrics='retention')
```

--------------------------------

### Load Historical Data (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

Loads historical experiment data from a CSV file into a pandas DataFrame. This data, containing metrics like LTV and retention, is crucial for designing experiments based on past performance.

```python
data = pd.read_csv('../tests/test_data/ltv_retention.csv')
```

--------------------------------

### Get and Store Multi-CUPED Parameters

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/01_vr_transformations.ipynb

Retrieves the parameters learned by the MultiCuped model using `get_params_dict()` and stores them to a JSON file using `store_params()`. This allows for later loading and reuse of the multi-covariate transformation parameters.

```python
store_path_multicuped = '_examples_configs/multicuped_config.json'
multicuped.store_params(store_path_multicuped)
```

--------------------------------

### Calculate Group Size using 'theory' Method (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

Calculates the required group size for different MDEs using Ambrosia's 'theory' method. This method provides a theoretical estimation based on statistical approximations, useful for initial planning.

```python
designer.run(to_design='size', method='theory', effects=effects)
```

--------------------------------

### Define Experiment Parameters Grid (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

Defines lists of Minimum Detectable Effects (MDEs) and group sizes to be used in the experiment design calculations. These parameters form a grid for exploring various experimental scenarios.

```python
# Create grid of MDEs and group sizes
# I and II type errros will have default values
effects = [1.02, 1.05, 1.1]
group_sizes = [500, 1000, 2000]
```

--------------------------------

### Create and Configure Designer Instance (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/03_pandas_designer.ipynb

This snippet shows how to create a Designer instance with specific attributes like effects, sizes, first-type errors, and metrics. This instance can then be configured for theoretical calculations.

```python
storable_designer = Designer(effects=[1.05, 1.1, 1.2],
                             sizes=[1000, 3000, 7000],
                             first_type_errors=[0.01, 0.05],
                             metrics=['sum_dur', 'ln_vod_cnt'])
```

--------------------------------

### Hash Splitting with Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

Demonstrates how to perform hash splitting using the 'hash' method. This method is fast and requires a 'groups_size' and an optional 'salt' for reproducibility. If no salt is provided, a random value is generated.

```python
splitter.run(method='hash', groups_size=groups_size, salt=salt)
```

```python
splitter.run(method='hash', groups_size=groups_size, salt='salt')
```

--------------------------------

### Load and Run Designer in Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/03_pandas_designer.ipynb

This snippet demonstrates how to load the 'power' design from the loaded designer object and execute it. It assumes the 'loaded_designer' object is already initialized.

```python
design_results = loaded_designer.run('power')
```

--------------------------------

### Load From Config

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/docs/source/ambrosia_elements/designer.rst

Loads experiment design configuration from a file.

```APIDOC
## POST /api/designer/load_from_config

### Description
Loads experiment design configuration from a specified configuration file.

### Method
POST

### Endpoint
/api/designer/load_from_config

### Parameters
#### Request Body
- **config_path** (string) - Required - The path to the configuration file.

### Request Example
```json
{
  "config_path": "/path/to/your/config.yaml"
}
```

### Response
#### Success Response (200)
- **configuration** (object) - The loaded configuration object.

#### Response Example
```json
{
  "configuration": {
    "metric_values": {
      "metric_name": [10.5, 11.2, 10.8, 12.1]
    },
    "effect_uplift": 0.05,
    "statistical_power": 0.8
  }
}
```
```

--------------------------------

### Initialize Tester for Multiple Groups and Metrics

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/06_pandas_tester.ipynb

Sets up synthetic data with multiple groups and metrics. Initializes the Tester class to handle multi-group and multi-metric analysis.

```python
total_size = 1000
groups = ['A', 'B', 'C', "D"]

np.random.seed(42)
multi_groups_result = pd.DataFrame(np.random.normal(size=(total_size, 2)),
                                   columns=['metric_1', 'metric_2'])
multi_groups_result['groups'] = np.random.choice(groups, size=total_size)
multi_groups_result = multi_groups_result.sort_values('groups')


multi_tester = Tester(dataframe=multi_groups_result,
                      column_groups='groups',
                      metrics=['metric_1', 'metric_2'])
```

--------------------------------

### Import Libraries and Initialize Tester

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/06_pandas_tester.ipynb

Imports necessary libraries (pandas, numpy) and the Tester class from ambrosia.tester. Initializes the Tester with experimental data, group column, metrics, and first-type error rate.

```python
import pandas as pd
import numpy as np

from ambrosia.tester import Tester

data = pd.read_csv('../tests/test_data/watch_result_agg.csv')


	ester = Tester(dataframe=data,
                column_groups='group',
                metrics='watched',
                first_type_errors=0.01)
```

--------------------------------

### Save Designer Configuration to YAML (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/03_pandas_designer.ipynb

This snippet demonstrates how to save a Designer instance's configuration to a YAML file. This allows for persistence and easy reloading of experiment parameters.

```python
store_path = '_examples_configs/designer_config.yaml'
with open(store_path, 'w') as outfile:
    yaml.dump(storable_designer, outfile, default_flow_style=True)
```

--------------------------------

### Load Designer Configuration from YAML (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/03_pandas_designer.ipynb

This snippet shows how to load a Designer instance from a previously saved YAML configuration file. After loading, the DataFrame needs to be set for the designer to perform calculations.

```python
loaded_designer = load_from_config(store_path)
loaded_designer.set_dataframe(data)
```

--------------------------------

### Set Python Path for Ambrosia

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

This code snippet modifies the Python path to include the parent directory, likely to import modules from the Ambrosia library. It's a common setup step for projects that structure their imports this way.

```python
import sys, os
sys.path.insert(1, os.path.realpath(os.path.pardir))
```

--------------------------------

### Get Box-Cox Transformer Parameters

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/00_preprocessing.ipynb

Retrieves the current parameters of the Box-Cox transformer. This is useful for inspecting the state of the transformer before or after operations. The output is a dictionary containing column names and their corresponding lambda values.

```python
boxcox_transformer.get_params_dict()
```

--------------------------------

### Import Ambrosia and Data Handling Libraries

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

Imports necessary libraries for data manipulation (pandas, numpy) and configuration loading (yaml), along with specific components from the ambrosia library like Splitter, split, and load_from_config.

```python
import pandas as pd
import numpy as np

import yaml

from ambrosia.splitter import Splitter, split, load_from_config
```

--------------------------------

### Save CUPED transformation parameters

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/11_cuped_example.ipynb

Saves the parameters learned during the CUPED transformation process to a JSON file. These parameters can be loaded later to apply the same transformation to new data, ensuring consistency.

```python
transformer.store_params('_examples_configs/kion_cuped_params.json')
```

--------------------------------

### Initialize and Fit IQRPreprocessor

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/00_preprocessing.ipynb

Initializes the IQRPreprocessor and fits it to the aggregated data using specified column names. This transformer removes outliers based on the interquartile range.

```python
iqr_transformer = IQRPreprocessor()
iqr_transformer.fit(dataframe=data_aggregated,
                    column_names=['watched', 'sessions'])
```

--------------------------------

### Initialize and Apply AggregatePreprocessor

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/00_preprocessing.ipynb

Initializes an AggregatePreprocessor with specified methods for categorical ('mode') and real ('sum') data. It then fits and transforms the provided DataFrame, grouping by 'id' and specifying columns for real and categorical aggregation.

```python
aggregator = AggregatePreprocessor(categorial_method='mode', real_method='sum')

aggregator.fit_transform(dataframe=data,
                        groupby_columns='id',
                        real_cols=['watched', 'sessions'],
                        categorial_cols=['gender', 'platform'])
```

--------------------------------

### Run Analysis with Multiple Groups and Metrics (Theory Method)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/06_pandas_tester.ipynb

Performs an analysis using the theoretical method on data with multiple groups and metrics. Demonstrates the effect of Bonferroni correction on p-values and confidence intervals.

```python
multi_tester.run(method='theory')
```

--------------------------------

### Retrieve experiment design information for the original metric

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/11_cuped_example.ipynb

Extracts and displays the experiment design results for the original 'ln_vod_cnt' metric. This shows the sample size needed for a given error rate and effect size.

```python
designer_info['ln_vod_cnt']
```

--------------------------------

### Theoretical Design: Calculate Effect Size with Ambrosia Designer

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/07_spark_designer.ipynb

Runs a theoretical calculation for effect size using the initialized Designer class. This helps in understanding the required effect size for a given experiment setup.

```python
designer.run('effect', 'theory')
```

--------------------------------

### Import Libraries for Ambrosia Splitter with Spark

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/08_spark_splitter.ipynb

Imports necessary libraries including os, pandas, pyspark, and the Splitter class from ambrosia.splitter. This setup is required to utilize Ambrosia's splitting functionalities on Spark DataFrames.

```python
import os

import pandas as pd
import pyspark

from ambrosia.splitter import Splitter
```

--------------------------------

### Get and Store CUPED Parameters

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/01_vr_transformations.ipynb

Retrieves the parameters learned by the Cuped model after transformation using `get_params_dict()` and stores them to a JSON file using `store_params()`. This allows for later loading and reuse of the learned transformation parameters.

```python
store_path_cuped = '_examples_configs/cuped_config.json'
cuped.store_params(store_path_cuped)
```

--------------------------------

### Metric Splitting with Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

Illustrates the 'metric' splitting method, which identifies similar objects based on specified features ('fit_columns') and Euclidean distance. This method is computationally intensive as it finds nearest neighbors. It creates dependent pairs between groups, necessitating paired statistical tests.

```python
metric_split = splitter.run(method='metric', groups_size=groups_size, fit_columns=['a', 'b'])
```

--------------------------------

### Initialize and Load RobustPreprocessor

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/00_preprocessing.ipynb

Initializes the RobustPreprocessor and loads its parameters from a JSON configuration file. This transformer is used for robust data cleaning and transformation.

```python
robust_transformer = RobustPreprocessor()
robust_transformer.load_params('_examples_configs/robust.json')
```

--------------------------------

### Design an abstract experiment for original and transformed metrics

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/11_cuped_example.ipynb

Uses the 'Designer' class to determine the required sample size for an experiment, comparing the original metric with the CUPED-transformed metric. This helps quantify the efficiency gains from the transformation.

```python
designer = Designer(transformed, effects=1.05)
designer_info = designer.run(to_design='size',
                             method='theory',
                             metrics=['ln_vod_cnt', 'ln_vod_cnt_transformed'])
```

--------------------------------

### Chaining Transformations with Preprocessor Pipeline

Source: https://context7.com/mobiletelesystems/ambrosia/llms.txt

The Preprocessor class allows chaining multiple data transformations (like outlier removal and CUPED) into a single, reproducible pipeline. This section shows how to create, apply, save, and load these transformation pipelines.

```python
import pandas as pd
import numpy as np
from ambrosia.preprocessing import Preprocessor

data = pd.DataFrame({
    'user_id': range(10000),
    'revenue': np.random.lognormal(5, 2, 10000),
    'pre_revenue': np.random.lognormal(5, 2, 10000),
    'category': np.random.choice(['A', 'B', 'C'], 10000)
})

# Chain transformations
preprocessor = Preprocessor(data, verbose=True)
processed_data = (
    preprocessor
    .robust(column_names='revenue', alpha=0.05, tail='both')
    .cuped(target='revenue', by='pre_revenue', transformed_name='cuped_revenue')
    .data()
)

# Save transformation pipeline for production
preprocessor.store_transformations('pipeline_config.json')

# Apply saved pipeline to new data
# Assume 'new_data' is a pandas DataFrame
new_preprocessor = Preprocessor(new_data)
new_processed = new_preprocessor.transform_from_config('pipeline_config.json')

# Access individual transformations
transformations = preprocessor.transformations()
for t in transformations:
    print(t, t.get_params_dict())
```

--------------------------------

### Split Data into Groups with Splitter

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/README.rst

Shows how to use the Splitter class to divide a dataset into specified group sizes. It requires a DataFrame and an ID column, and supports different splitting methods.

```python
from ambrosia.splitter import Splitter
splitter = Splitter(dataframe=df, id_column='id') # loaded data frame df with column with id - 'id'
splitter.run(groups_size=500, method='simple')
```

--------------------------------

### Retrieve experiment design information for the transformed metric

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/11_cuped_example.ipynb

Extracts and displays the experiment design results for the CUPED-transformed metric 'ln_vod_cnt_transformed'. This result is compared with the original metric's design to show the improvement in sample size efficiency.

```python
designer_info['ln_vod_cnt_transformed']
```

--------------------------------

### Run Design Calculation for Size with Unequal Groups (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/03_pandas_designer.ipynb

Calculates required group sizes for group A when group B is a fraction of group A, defined by `groups_ratio`. This allows for unequal group sizes in the experimental design.

```python
designer.run(to_design='size',
             method='theory',
             effects=effects,
             sizes=sizes,
             groups_ratio=0.1)
```

--------------------------------

### Calculate Statistical Power using 'theory' Method (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

Calculates the statistical power of the experiment for various combinations of MDEs and group sizes using the 'theory' method. Power is the probability of detecting a true effect.

```python
designer.run(to_design='power',
             method='theory',
             effects=effects,
             sizes=group_sizes)
```

--------------------------------

### Design an A/B Test Experiment with Designer

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/README.rst

Demonstrates the usage of the Designer class to set up an A/B test. It takes a DataFrame, desired effect size, and metric as input, then runs the design process.

```python
from ambrosia.designer import Designer
designer = Designer(dataframe=df, effects=1.2, metrics='portfel_clc') # 20% effect, and loaded data frame df
designer.run('size')
```

--------------------------------

### Apply CUPED transformation to the target metric

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/11_cuped_example.ipynb

Initializes and applies the CUPED transformation to the DataFrame. This transformation aims to reduce the variance of the target metric by using a covariate, thereby improving experiment efficiency. The target and covariate columns are specified.

```python
transformer = Cuped()
transformed = transformer.fit_transform(dataframe,
                                        target_column='ln_vod_cnt',
                                        covariate_column='sum_dur')
```

--------------------------------

### Save and Load Splitter Configuration using YAML in Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

This snippet illustrates how to serialize a configured Ambrosia Splitter object to a YAML file and then load it back. This allows for reusing pre-defined splitting configurations. Note that dataset-related attributes are not serialized and must be set after loading.

```python
import yaml
import pandas as pd
import numpy as np
from ambrosia.tools.splitters import Splitter
from ambrosia.tools.splitters import load_from_config

# Define the path for the configuration file
store_path = '_examples_configs/splitter_config.yaml'

# Create a Splitter instance with desired parameters
storable_splitter = Splitter(id_column='object_id',
                             groups_size=322,
                             strat_columns=['l', 'e'])

# Get the state of the splitter instance (serializable attributes)
print("Original splitter state:")
print(storable_splitter.__getstate__())

# Save the splitter configuration to a YAML file
with open(store_path, "w") as outfile:
    yaml.dump(storable_splitter, outfile, default_flow_style=False)

print(f'\nSplitter configuration saved to {store_path}')

# Load the splitter configuration from the YAML file
loaded_splitter = load_from_config(store_path)

# Display the state of the loaded splitter instance
print("\nLoaded splitter state:")
print(loaded_splitter.__getstate__())

# Example: Set dataframe and perform a split using the loaded configuration
# Assuming 'dataframe' is a pre-defined pandas DataFrame with 'object_id'
# and other columns like 'm', 'a', 'b', 'l', 'e'.
# For demonstration, let's create a dummy dataframe if it doesn't exist:
if 'dataframe' not in locals():
    data = {
        'object_id': np.arange(200000),
        'm': np.random.rand(200000),
        'a': np.random.rand(200000),
        'b': np.random.rand(200000),
        'l': np.random.randint(0, 2, 200000),
        'e': np.random.randint(0, 2, 200000)
    }
    dataframe = pd.DataFrame(data)

loaded_splitter.set_dataframe(dataframe)
split_result = loaded_splitter.run(method='hash', salt='from_yaml')

print("\nSplit result using loaded configuration:")
print(split_result.head())
print(f'\nTotal rows in split result: {len(split_result)}')

```

--------------------------------

### Analyze A/B Test Results for Significance (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/10_synthetic_experiment_full_pipeline_short.ipynb

Evaluates the aggregated experiment results to determine statistical significance and calculate the relative effect with confidence intervals. It uses the Tester class, requiring the aggregated DataFrame, metric column, and group column.

```python
from ambrosia.tester import Tester

# Assuming 'df_to_test' is the aggregated DataFrame from the previous step
# 'watched' is the metric column and 'group' is the column defining experimental groups

tester = Tester(dataframe=df_to_test, metrics='watched', column_groups='group')

# Run the test to calculate relative effect and confidence interval
result = tester.run(effect_type='relative', method='theory')

print(result)
```

--------------------------------

### Split DataFrame into Two Groups using Hash Method (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

Demonstrates splitting a data frame into two groups (A and B) using a specified ratio (e.g., 1/3) with the 'hash' method in Ambrosia. This method utilizes a salt for reproducible splitting. The output shows the resulting data frame with an added 'group' column and the distribution of rows across the groups.

```python
part_of_table = 1/3
fractional_hash_split = splitter.run(method='hash',
                                     part_of_table=part_of_table,
                                     salt='fractional_split')
```

```python
fractional_hash_split
```

```text
Result:
          m         a         b  l  e  object_id group
1       0.0 -0.138264 -0.094228  0  0      82374     A
3       0.0  1.523030 -1.388638  1  0      36327     A
5       0.0 -0.234137 -1.580520  0  0      63304     A
6       0.0  1.579213  0.587148  1  1     187546     A
15      0.0 -0.562288 -1.362157  0  0     133839     A
...     ...       ...       ... .. ..        ...   ...
199991  0.0  0.383196  0.230814  1  1     199822     B
199994  0.0 -0.590488 -0.518154  0  0      12123     B
199996  0.0  0.565654 -2.316381  1  0     147356     B
199998  0.0  0.855673  0.462531  1  1     132270     B
199999  0.0 -1.064948 -0.137357  0  0      86886     B

[200000 rows x 7 columns]
```

```python
fractional_hash_split.group.value_counts(normalize=True)
```

```text
Result:
B    0.666665
A    0.333335
Name: group, dtype: float64
```

--------------------------------

### Run Statistical Theory Test in Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/06_pandas_tester.ipynb

This Python code snippet demonstrates how to run a statistical test using the 'multi_tester' library. It specifies the 'theory' method and sets the correction method to None. The output includes various statistical metrics and confidence intervals.

```python
multi_tester.run(method='theory', correction_method=None)
```

--------------------------------

### Create Multiple Groups using Metric Split

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

Performs a data split using the 'metric' method to create multiple experimental groups (e.g., A/B/C). The `groups_number` parameter controls the total number of groups, and `fit_columns` specifies the columns used for metric calculation.

```python
metric_multisplit = splitter.run(method='metric',
                                 groups_size=groups_size,
                                 fit_columns=['a', 'b'],
                                 groups_number=3)
```

--------------------------------

### Calculate MDE using 'theory' Method (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

Calculates the Minimum Detectable Effect (MDE) for given group sizes using the 'theory' method. This helps understand the smallest effect that can be reliably detected with a specific sample size.

```python
designer.run(to_design='effect', method='theory', sizes=group_sizes)
```

--------------------------------

### Print empirical Type I and Type II error rates

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/11_cuped_example.ipynb

Calculates and prints the empirical Type I and Type II error rates based on the results of the simulated experiments. These values should ideally be close to the theoretical alpha level (0.05) and the complement of the power.

```python
print('Empirical I type error: {}'.format(amount_first_type_errors.loc[0] /
                                          tests_amounts))
print('Empirical II type error: {}'.format(amount_second_type_errors.loc[0] /
                                           tests_amounts))
```

--------------------------------

### Load Sample Data

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/00_preprocessing.ipynb

Loads a sample dataset named 'week_metrics.csv' into a pandas DataFrame. This dataset contains daily content views by users and is used to demonstrate the preprocessing tools.

```python
data = pd.read_csv('../tests/test_data/week_metrics.csv')
```

--------------------------------

### Perform Simple Data Split with Ambrosia

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

Executes a 'simple' non-deterministic split on the data using the initialized Splitter. This method creates groups of a specified size (2000 objects per group) and assigns them labels (e.g., 'A', 'B'). The result is a DataFrame with an added 'group' column.

```python
splitter.run(method='simple', groups_size=2000)
```

```text
          m         a         b  l  e  object_id group
191060  0.0 -0.230298  1.253592  0  1     136859     A
121593  0.0  1.974664 -1.780258  1  0     164797     A
185512  0.0 -1.254767 -0.152099  0  0      49954     A
79803   0.0 -1.572960 -0.706893  0  0     154922     A
98956   0.0  0.714251  0.662607  1  1      99718     A
...     ...       ...       ... .. ..        ...   ...
53739   0.0  0.070655  0.644952  1  1      62827     B
178405  0.0 -0.423988 -0.706336  0  0     103080     B
95002   0.0 -1.05022  0.714893  0  1     155745     B
166811  0.0 -1.459109  0.339358  0  1     157092     B
41369   0.0  0.721402 -0.980647  1  0        113     B

[4000 rows x 7 columns]
```

--------------------------------

### Set Known Retention Rate for Binary Experiment Design - Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

This snippet initializes the known retention rate for binary metric experiments. It sets the baseline probability of conversion or retention, which is a crucial input for subsequent experimental design calculations.

```python
retention = 0.1
```

--------------------------------

### Load Aggregation Parameters from File

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/00_preprocessing.ipynb

Initializes an `AggregatePreprocessor` and loads previously stored aggregation parameters from a JSON file. This is crucial for consistent data processing across different sessions or environments.

```python
aggregator_loaded = AggregatePreprocessor()
aggregator_loaded.load_params('_examples_configs/aggregator.json')
```

--------------------------------

### Instantiate Ambrosia Designer

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/03_pandas_designer.ipynb

Creates an instance of the Designer class, passing the loaded pandas DataFrame and the target metric ('sum_dur') to the constructor. This initializes the designer with the data for analysis.

```python
designer = Designer(dataframe=data, metrics='sum_dur')
```

--------------------------------

### Conduct artificial testing for Type I and Type II errors

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/11_cuped_example.ipynb

Performs a series of simulated experiments to empirically estimate the Type I and Type II error rates of the experimental design. This involves splitting data, applying the stored CUPED transformation, and using the Tester module.

```python
tests_amounts: int = 100
group_size = 2700
amount_first_type_errors: int = 0
amount_second_type_errors: int = 0
alpha = 0.05

for exp_num in tqdm(range(tests_amounts)):
    # Checking for I type error
    splitter = Splitter(dataframe, id_column='profile_id')
    exp_data = splitter.run(method='hash',
                            salt=f'exp {exp_num}',
                            groups_size=group_size)
    transformer = Cuped(verbose=False)
    transformer.load_params('_examples_configs/kion_cuped_params.json')
    transformed = transformer.transform(exp_data)
    tester = Tester(transformed,
                    metrics='ln_vod_cnt_transformed',
                    column_groups='group')
    pvalue = tester.run(method='empiric')['pvalue']
    amount_first_type_errors += (
        pvalue < alpha)  # Reject equality of means when it is true

    # Checking for II type error
    splitter = Splitter(dataframe, id_column='profile_id')
    exp_data = splitter.run(method='hash',
                            salt=f'exp {exp_num}',
                            groups_size=group_size)
    mean_b = exp_data[exp_data.group == 'B']['ln_vod_cnt'].mean()
    # Let's add an effect
    exp_data.loc[exp_data.group == 'B', 'ln_vod_cnt'] += 0.05 * mean_b
    transformer = Cuped(verbose=False)
    transformer.load_params('_examples_configs/kion_cuped_params.json')
    transformed = transformer.transform(exp_data)
    tester = Tester(transformed,
                    metrics='ln_vod_cnt_transformed',
                    column_groups='group')
    pvalue = tester.run(method='empiric')['pvalue']
    amount_second_type_errors += (
        pvalue > alpha)  # Do not reject the equality of averages when
    # it is necessary to reject
```

--------------------------------

### Create Multiple Groups using Hash Split

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

Performs a data split using the 'hash' method to create a specified number of groups. The `groups_size` is set to 1000, and `groups_number` is set to 10, resulting in 10,000 rows distributed across 10 groups.

```python
hash_multisplit = splitter.run(method='hash',
                               groups_size=1000,
                               groups_number=10)
```

--------------------------------

### Define MDEs and Group Sizes for Experiment Design - Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

This code defines the range of Minimum Detectable Effects (MDEs) and group sizes to be considered in the experiment design. These parameters, along with error rates, influence the required sample size or the detectable effect.

```python
# Create grid of MDEs and group sizes
# I and II type errros will have default values
effects = [1.01, 1.03, 1.05]
group_sizes = [20_000, 50_000, 100_000]
```

--------------------------------

### Display Initial Data Head

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/01_vr_transformations.ipynb

Displays the first few rows of the loaded pandas DataFrame using the .head() method. This is useful for inspecting the structure and initial values of the data before applying transformations.

```python
data.head()
```

--------------------------------

### Calculate Statistical Power for Binary Experiments - Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

This code calculates the statistical power of a binary experiment for various combinations of MDEs and group sizes, using a known retention rate and a theoretical method. Power represents the probability of detecting a true effect if it exists.

```python
design_binary(to_design='power',
              prob_a=retention,
              method='theory',
              effects=effects,
              sizes=group_sizes)
```

--------------------------------

### Initialize and Fit LogTransformer

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/00_preprocessing.ipynb

Initializes the LogTransformer and fits it to the data, specifying the column to which the logarithmic transformation will be applied. This transformer is useful for reducing variance and making distributions more normal.

```python
log_transformer = LogTransformer()
log_transformer.fit(dataframe=data_aggregated, column_names=['watched'])
```

--------------------------------

### Calculate A/B Test Sample Size (Python)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/10_synthetic_experiment_full_pipeline_short.ipynb

Calculates the required sample size for an A/B test based on desired effect size and statistical error rates. It uses a theoretical approach and requires a pandas DataFrame and metric name as input. The output provides the number of users needed per group.

```python
from ambrosia.designer import Designer

# Assuming 'df' is your pandas DataFrame and 'watched' is the metric
designer = Designer(dataframe=df, metrics='watched')

# Calculate sample size for a 5% effect (1.05 multiplier)
# Errors (alpha, beta) are set to (0.05, 0.2) by default
result = designer.run('size', method='theory', effects=1.05)

print(result)
```

--------------------------------

### Perform Simple Data Split using Ambrosia's split Function in Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

This snippet shows how to use the standalone 'split' function from Ambrosia, which replicates the behavior of the Splitter class for straightforward splitting tasks. It requires the dataframe, id column, and desired group size as parameters.

```python
from ambrosia.tools.splitters import split
import pandas as pd
import numpy as np

# Assuming 'dataframe' is a pre-defined pandas DataFrame with 'object_id'
# and other columns like 'm', 'a', 'b', 'l', 'e'.
# For demonstration, let's create a dummy dataframe if it doesn't exist:
if 'dataframe' not in locals():
    data = {
        'object_id': np.arange(200000),
        'm': np.random.rand(200000),
        'a': np.random.rand(200000),
        'b': np.random.rand(200000),
        'l': np.random.randint(0, 2, 200000),
        'e': np.random.randint(0, 2, 200000)
    }
    dataframe = pd.DataFrame(data)

# Use the 'split' function for a simple split
split_result = split(method='simple',
                     dataframe=dataframe,
                     id_column='object_id',
                     groups_size=1000)

print("Split result using the 'split' function:")
print(split_result.head())
print(f'\nTotal rows in split result: {len(split_result)}')

```

--------------------------------

### Calculate Minimum Detectable Effect (MDE) for Binary Experiments - Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

This snippet calculates the Minimum Detectable Effect (MDE) for binary experiments, given a known retention rate, specified group sizes, and a theoretical approach. It indicates the smallest effect that can be reliably detected with the given sample size.

```python
design_binary(to_design='effect',
              prob_a=retention,
              method='theory',
              sizes=group_sizes)
```

--------------------------------

### Calculate Group Size for Binary Experiments - Python

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/04_binary_design.ipynb

This function call calculates the required group size for a binary experiment, given a known retention rate, desired MDEs, and a theoretical calculation method. It helps determine how many users are needed per group to detect a specific effect.

```python
design_binary(to_design='size',
              prob_a=retention,
              method='theory',
              effects=effects)
```

--------------------------------

### Data Transformations with BoxCoxTransformer and LogTransformer

Source: https://context7.com/mobiletelesystems/ambrosia/llms.txt

This code demonstrates how to normalize skewed data distributions using Box-Cox and Log transformations. It includes fitting the transformers, applying them to dataframes, and performing inverse transformations to revert to the original scale.

```python
import pandas as pd
import numpy as np
from ambrosia.preprocessing import BoxCoxTransformer, LogTransformer

data = pd.DataFrame({
    'revenue': np.random.lognormal(5, 2, 10000),  # Highly skewed
    'sessions': np.random.exponential(10, 10000)
})

# Box-Cox transformation (auto-selects optimal lambda)
boxcox = BoxCoxTransformer()
transformed = boxcox.fit_transform(
    dataframe=data,
    column_names=['revenue', 'sessions']
)

# Inverse transform to original scale
original_scale = boxcox.inverse_transform(transformed)

# Simple log transformation
log_transformer = LogTransformer()
log_transformed = log_transformer.fit_transform(
    dataframe=data,
    column_names='revenue'
)

# Inverse log transform
back_to_original = log_transformer.inverse_transform(log_transformed)
```

--------------------------------

### Perform Simple Data Split with Stratification

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/05_pandas_splitter.ipynb

Executes a simple data split using the 'simple' method. Stratification is applied using the 'l' column to ensure the distribution of this feature is maintained across groups. The `strat_columns` parameter specifies the column(s) for stratification.

```python
stratified_split = splitter.run(method='simple', groups_size=groups_size, strat_columns=['l'])
```

--------------------------------

### Save and Load CUPED Parameters

Source: https://context7.com/mobiletelesystems/ambrosia/llms.txt

Demonstrates how to save the parameters of a CUPED model to a JSON file and then load them back to apply the transformation to new data. This is useful for reproducibility and applying learned transformations.

```python
import pandas as pd
from ambrosia.cuped import Cuped, MultiCuped

# Assume 'new_data' is a pandas DataFrame
# Assume 'data' is a pandas DataFrame

# Save parameters for production use
cuped.store_params('cuped_params.json')

# Load and apply to new data
cuped_loaded = Cuped()
cuped_loaded.load_params('cuped_params.json')
new_transformed = cuped_loaded.transform(new_data)

# Multi-covariate CUPED for greater variance reduction
multi_cuped = MultiCuped(verbose=True)
multi_transformed = multi_cuped.fit_transform(
    dataframe=data,
    target_column='experiment_revenue',
    covariate_columns=['pre_experiment_revenue', 'age', 'tenure_days'],
    transformed_name='multi_cuped_revenue'
)
```

--------------------------------

### Load CUPED Parameters

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/01_vr_transformations.ipynb

Creates a new Cuped instance and loads previously stored parameters from a JSON file using `load_params()`. This demonstrates how to reuse learned transformation configurations without refitting.

```python
new_cuped = Cuped()
new_cuped.load_params(store_path_cuped)
```

--------------------------------

### Import Libraries for Ambrosia Designer

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/03_pandas_designer.ipynb

Imports necessary libraries including numpy, pandas, yaml, and specific components from the ambrosia.designer module. These are foundational for data manipulation and using the Designer class.

```python
import numpy as np
import pandas as pd

import yaml

from ambrosia.designer import Designer, design, load_from_config
```

--------------------------------

### Estimate Absolute Uplift using Bootstrap (Empiric Method)

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/06_pandas_tester.ipynb

Estimates the absolute uplift using the empiric (bootstrap) method. This approach is robust and does not rely on distributional assumptions.

```python
tester.run(effect_type='absolute',
           method='empiric',
           metrics='watched',
           first_type_errors=0.01)
```

--------------------------------

### Initialize and Apply MLVarianceReducer

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/01_vr_transformations.ipynb

Initializes the MLVarianceReducer and applies it to transform the data. This method reduces the variance of the target column using machine learning, with options for covariate columns, transformed name, and in-place modification.

```python
mltransformer = MLVarianceReducer()
mltransformer.fit_transform(dataframe=data,
                            target_column=target_column,
                            covariate_columns=['feature_2', 'feature_3'],
                            transformed_name='target_mlreducer',
                            inplace=True)
```

--------------------------------

### Store RobustPreprocessor Parameters

Source: https://github.com/mobiletelesystems/ambrosia/blob/main/examples/00_preprocessing.ipynb

Saves the configuration parameters of the `RobustPreprocessor` to a JSON file. This allows for consistent application of the outlier removal process in the future.

```python
robust_transformer.store_params('_examples_configs/robust.json')
```