### Install Development Dependencies

Source: https://pylluminator.readthedocs.io/en/latest/index.html

Use this command to install the necessary packages for testing, packaging, and building the documentation.

```bash
uv sync --extra dev --extra docs
```

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

### Install uv package manager

Source: https://pylluminator.readthedocs.io/en/latest/index.html

Use this command to install the uv package manager on your system.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

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

### Sync project extras

Source: https://pylluminator.readthedocs.io/en/latest/index.html

Install optional dependencies for GSEA, development, or documentation generation.

```bash
uv sync --extra gsea
uv sync --extra dev
uv sync --extra docs
```

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

### Install pylluminator with pip

Source: https://pylluminator.readthedocs.io/en/latest/index.html

Install the package using pip, with an optional flag for GSEA functionality.

```bash
pip install pylluminator
```

```bash
pip install pylluminator[gsea]
```

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

### Clone and build from source

Source: https://pylluminator.readthedocs.io/en/latest/index.html

Clone the repository and use uv to sync the environment and dependencies.

```bash
git clone https://github.com/eliopato/pylluminator.git
cd pylluminator
uv sync
```

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

### Importing dependencies and configuring logging

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/5%20-%20Pathway%20analysis.ipynb.txt

Initializes the environment by importing necessary libraries and setting the global logging level.

```python
from pylluminator.utils import load_object
from pylluminator.dm import combine_p_values_stouffer
from pylluminator.utils import set_logger
from pylluminator.visualizations import visualize_gene

import numpy as np
import gseapy as gp
import networkx as nx
import matplotlib.pyplot as plt

set_logger('WARNING')  # set the verbosity level, can be DEBUG, INFO, WARNING, ERROR
```

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

### get_logger(level=None)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.utils.html

Get the current logger and sets its level if the parameter level is defined.

```APIDOC
## get_logger(level=None)

### Description
Get the current logger and sets its level if the parameter level is defined.

### Parameters
- **level** (str/int) - Optional - The logging level to set.
```

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

### Samples.__init__

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.Samples.html

Initializes the Samples object with an optional sample sheet dataframe.

```APIDOC
## __init__(sample_sheet_df=None)

### Description
Initialize the object with only a sample-sheet.

### Parameters
- **sample_sheet_df** (pandas.DataFrame | None) - Optional - sample sheet dataframe. Default: None
```

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

### Initialize pylluminator environment

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/2%20-%20QC.ipynb.txt

Import necessary modules and configure the logging verbosity level.

```python
from pylluminator.samples import Samples
from pylluminator.utils import set_logger
from pylluminator.annotations import Channel
from pylluminator.quality_control import *

import matplotlib.pyplot as plt
import pandas as pd

set_logger('WARNING')  # set the verbosity level, can be DEBUG, INFO, WARNING, ERROR
```

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

### Initialize pylluminator CNV environment

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/4%20-%20Copy%20Number%20Variation.ipynb.txt

Import necessary modules and configure the global logger verbosity level.

```python
from pylluminator.samples import Samples
from pylluminator.cnv import copy_number_variation, copy_number_segmentation
from pylluminator.utils import set_logger
from pylluminator.visualizations import cns_manhattan_plot

set_logger('WARNING')  # set the verbosity level, can be DEBUG, INFO, WARNING, ERROR
```

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

### Channel.__init__

Source: https://pylluminator.readthedocs.io/en/latest/_sources/_autosummary/pylluminator.annotations.Channel.rst.txt

Initializes a new instance of the Channel class.

```APIDOC
## Channel.__init__

### Description
Initializes a new instance of the Channel class.

### Signature
`Channel()`
```

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

### IdatDataset.__init__

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.read_idat.IdatDataset.html

Initializes the IdatDataset by reading the specified .idat file.

```APIDOC
## class pylluminator.read_idat.IdatDataset(filepath, bit='float32')

### Description
Initializes the IdatDataset by reading the .idat file provided.

### Parameters
- **filepath** (str) - Required - The IDAT file to parse.
- **bit** (str) - Optional - Either 'float32' or 'float16'. 'float16' will pre-normalize intensities. Default: 'float32'.
```

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

### Load preprocessed samples

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/2%20-%20QC.ipynb.txt

Load previously saved sample data from disk.

```python
my_samples = Samples.load('preprocessed_samples')
my_samples
```

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

### Run Preprocessing Pipeline

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/1%20-%20Read%20data%20and%20get%20betas.ipynb.txt

Execute standard preprocessing steps on the Samples object.

```python
my_samples.mask_quality_probes()
my_samples.infer_type1_channel()
my_samples.dye_bias_correction_nl()
my_samples.poobah()
my_samples.noob_background_correction()
my_samples.calculate_betas(include_out_of_band=True)
```

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

### GenomeInfo.__init__

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.annotations.GenomeInfo.html

Initializes a new GenomeInfo object by loading files corresponding to the specified genome version.

```APIDOC
## __init__(name, genome_version)

### Description
Load the files corresponding to the given genome version and structure the information.

### Parameters
- **name** (str) - Required - Name of the genome to load. Use 'illumina' for default, 'updated' for specific DOI-defined annotations, or a custom folder name.
- **genome_version** (GenomeVersion) - Required - The genome version to load (e.g., hg32, mm10).
```

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

### create_from_idats(idat_folder, output_filename=None)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.sample_sheet.html

Creates a sample sheet file from a folder containing .idat files.

```APIDOC
## create_from_idats

### Description
Creates a sample sheet file from a folder containing .idat files.

### Parameters
- **idat_folder** (str) - Required - Path to the folder containing .idat files.
- **output_filename** (str) - Optional - The path/filename for the generated sample sheet.
```

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

### Inspect sample sheet and create DM object

Source: https://pylluminator.readthedocs.io/en/latest/tutorials/3%20-%20DMPs%20and%20DMRs.html

Displays the sample sheet and initializes the DM object using a formula for the design matrix.

```python
my_samples.sample_sheet
```

```python
my_dms = DM(my_samples, '~ sample_type', probe_ids=probe_ids, use_m_values=True)
```

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

### Samples

Source: https://pylluminator.readthedocs.io/en/latest/_sources/_autosummary/pylluminator.samples.rst.txt

Class for managing and interacting with sample data collections.

```APIDOC
## Samples

### Description
A class representing a collection of samples, providing methods for data manipulation and access.

### Signature
`class pylluminator.samples.Samples`
```

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

### pylluminator.sample_sheet.create_from_idats

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.sample_sheet.create_from_idats.html

Creates a sample sheet file from a folder containing .idat files.

```APIDOC
## pylluminator.sample_sheet.create_from_idats(idat_folder, output_filename='samplesheet.csv')

### Description
Creates a sample sheet file from a folder containing .idat files. The function expects files to follow specific naming conventions: [GSM_id]_[sentrix id]_[sentrix_position]_[Grn|Red].idat or [sentrix id]_[sentrix_position]_[Grn|Red].idat.

### Parameters
- **idat_folder** (str | PathLike | MultiplexedPath) - Required - Path to the folder containing all the .idat files.
- **output_filename** (str) - Optional - Name of the sample sheet file that will be created. Default: 'samplesheet.csv'.

### Returns
- **tuple[pandas.DataFrame, str]** - A tuple containing the sample sheet as a pandas DataFrame and the filepath of the new file.
```

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

### pylluminator.utils.download_from_link(dl_link, output_folder, filename=None, decompress=False, delete_archive=False)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.utils.download_from_link.html

Downloads a file from a given URL to a specified output folder, with options to decompress the file and remove the archive after decompression.

```APIDOC
## pylluminator.utils.download_from_link

### Description
Downloads a file from a provided link and saves it to the target directory. Supports automatic decompression of .zip and .tar files and optional deletion of the archive after extraction.

### Signature
`pylluminator.utils.download_from_link(dl_link: str, output_folder: str | MultiplexedPath | PathLike, filename: str | None = None, decompress: bool = False, delete_archive: bool = False) -> int`

### Parameters
- **dl_link** (str) - Required - The URL link to the file to be downloaded.
- **output_folder** (str | MultiplexedPath | PathLike) - Required - The directory path where the file will be saved.
- **filename** (str | None) - Optional - The expected filename. If None, defaults to the last part of the URL. Default: None.
- **decompress** (bool) - Optional - Set to True to decompress the output (supports .zip and .tar). Default: False.
- **delete_archive** (bool) - Optional - Set to True to delete the archive after decompressing. Default: False.

### Returns
- **int** - Returns 1 if the download/process was successful, or -1 if the file could not be downloaded.
```

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

### Load and inspect samples

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/4%20-%20Copy%20Number%20Variation.ipynb.txt

Load previously saved sample data and inspect the associated sample sheet.

```python
my_samples = Samples.load('preprocessed_samples')
my_samples
```

```python
sample_sheet = my_samples.sample_sheet
sample_sheet
```

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

### Visualize Preprocessed Beta Density

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/1%20-%20Read%20data%20and%20get%20betas.ipynb.txt

Compare beta value distributions after preprocessing.

```python
betas_density(my_samples, color_column='sample_type')
```

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

### Read .idat sample files

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/1%20-%20Read%20data%20and%20get%20betas.ipynb.txt

Reads sample data from the specified path using the provided annotations. The sample sheet is generated automatically if not provided.

```python
# minimum number of detected beads per probe
min_beads = 4

# if no sample sheet is provided, it will be rendered automatically. Use parameter sample_sheet_path or sample_sheet_name to specify one.
my_samples = read_samples(data_path, annotation=annos, min_beads=min_beads, keep_idat=True)  

# let's check the generated sample sheet !
my_samples.sample_sheet
```

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

### Access sample sheet

Source: https://pylluminator.readthedocs.io/en/latest/tutorials/4%20-%20Copy%20Number%20Variation.html

Retrieve the sample sheet metadata from the loaded Samples object.

```python
sample_sheet = my_samples.sample_sheet
sample_sheet
```

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

### load(filepath: str) -> Samples

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.Samples.html

Loads a pickled Samples object from a file.

```APIDOC
## load(filepath: str) -> Samples

### Description
Load a pickled Samples object from filepath.

### Parameters
- **filepath** (str) - Required - Path to the file to read.

### Returns
- **Samples** - The loaded object
```

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

### Save and Load Samples

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/1%20-%20Read%20data%20and%20get%20betas.ipynb.txt

Persist the Samples object to disk to avoid re-reading raw data.

```python
my_samples.save('raw_samples')

# For later use, here is how to load samples :
# my_samples = Samples.load('raw_samples')
```

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

### copy()

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.Samples.html

Creates a copy of the current Samples object.

```APIDOC
## copy()

### Description
Creates a copy of the Samples object.

### Returns
- **Samples** - A copy of the object.
```

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

### Run tests with uv

Source: https://pylluminator.readthedocs.io/en/latest/index.html

Execute tests within the project's virtual environment.

```bash
uv run pytest
```

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

### Select subset of probes for demonstration

Source: https://pylluminator.readthedocs.io/en/latest/tutorials/3%20-%20DMPs%20and%20DMRs.html

Calculates and selects a subset of probe IDs to speed up the computation process.

```python
ten_pct_probes = int(0.1 * my_samples.nb_probes)
probe_ids = my_samples.probe_ids[:ten_pct_probes]
print(f'Selected {ten_pct_probes:,} first probes')
```

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

### noob_background_correction(sample_labels=None, apply_mask=True, use_negative_controls=True, offset=15)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.Samples.html

Performs background correction on sample signals using the Norm-Exp deconvolution method.

```APIDOC
## noob_background_correction(sample_labels: str | list[str] | None = None, apply_mask: bool = True, use_negative_controls: bool = True, offset: int | float = 15) -> None

### Description
Subtract the background for a sample using Norm-Exp deconvolution parameterized by Out-Of-Band (oob) probes.

### Parameters
- **sample_labels** (str | list[str] | None) - Optional - The name(s) of the sample(s) to correct. If None, correct all samples.
- **apply_mask** (bool) - Optional - True removes masked probes, False keeps them. Default: True.
- **use_negative_controls** (bool) - Optional - If True, background is calculated with negative control and oob probes. Default: True.
- **offset** (int | float) - Optional - A constant value to add to the corrected signal for padding. Default: 15.
```

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

### pylluminator.samples.read_samples(datadir, sample_sheet_df=None, sample_sheet_name=None, annotation=None, max_samples=None, min_beads=1, keep_idat=False)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.read_samples.html

Searches for idat files in the provided directory through all sublevels, matching them with sample sheet information.

```APIDOC
## read_samples

### Description
Searches for idat files in the datadir through all sublevels. The idat files are expected to follow the naming convention: *[sentrix ID]*[sentrix position]*[channel].idat.

### Parameters
- **datadir** (str | PathLike | MultiplexedPath) - Required - Directory where sesame files are located.
- **sample_sheet_df** (pandas.DataFrame | None) - Optional - Samples information. Default: None.
- **sample_sheet_name** (str | None) - Optional - Name of the csv file containing the samples' information. Default: None.
- **annotation** (Annotations | None) - Optional - Probes information. Default: None.
- **max_samples** (int | None) - Optional - Set to only load N samples to speed up the process. Default: None.
- **min_beads** (int) - Optional - Filter probes that have less than N beads. Default: 1.
- **keep_idat** (bool) - Optional - If set to True, keep idat data after merging the annotations. Default: False.

### Returns
- **Samples | None** - Returns a Samples object or None if an error was raised.
```

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

### Calculate integer ratio

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.read_idat.IdatHeaderLocation.html

Demonstrates the as_integer_ratio method for returning the ratio of an integer in lowest terms.

```python
>>> (10).as_integer_ratio()
(10, 1)
>>> (-10).as_integer_ratio()
(-10, 1)
>>> (0).as_integer_ratio()
(0, 1)
```

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

### DM.__init__

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.dm.DM.html

Initializes the DM object and performs DMP estimation by fitting a linear regression model to methylation values.

```APIDOC
## DM.__init__(samples, formula, reference_value=None, custom_sheet=None, drop_na=False, apply_mask=True, probe_ids=None, group_column=None, use_m_values=True)

### Description
Initializes the object by calling the compute_dmp function to estimate Differentially Methylated Probes (DMPs) using OLS or LMM models.

### Parameters
- **samples** (Samples) - Required - Samples to use.
- **formula** (str) - Required - R-like formula for the design matrix (e.g., '~age + sex').
- **reference_value** (dict | None) - Optional - Dictionary of reference values for predictors.
- **custom_sheet** (pandas.DataFrame) - Optional - Custom sample sheet to use.
- **drop_na** (bool) - Optional - Whether to drop probes with NA values. Default: False.
- **apply_mask** (bool) - Optional - Whether to apply mask. Default: True.
- **probe_ids** (list[str] | None) - Optional - List of probe IDs to use.
- **group_column** (str | None) - Optional - Column name for random effects to trigger LMM usage.
- **use_m_values** (bool) - Optional - Whether to use M-values instead of beta values. Default: True.

### Returns
- **pandas.DataFrame, list[str]** - A dataframe with probes as rows and p-values/estimates in columns, and a list of contrast levels.
```

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

### Annotations.__init__

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.annotations.Annotations.html

Initializes the Annotations object by loading metadata for a specific array type and genome version.

```APIDOC
## __init__(array_type, genome_version, name='illumina')

### Description
Initializes the Annotations object and loads the corresponding metadata for the specified array type and genome version. Masks and manifests are downloaded automatically if not present.

### Parameters
- **array_type** (ArrayType) - Required - The Illumina array type (e.g., EPIC, MSA).
- **genome_version** (GenomeVersion) - Required - The genome version to load (e.g., hg38, mm10).
- **name** (str) - Optional - The name of the annotation set. Defaults to 'illumina'. Use 'updated' for updated annotations or a custom folder name.
```

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

### Read .idat samples

Source: https://pylluminator.readthedocs.io/en/latest/tutorials/1%20-%20Read%20data%20and%20get%20betas.html

Reads sample data from the specified path using the provided annotations.

```python
# minimum number of detected beads per probe
min_beads = 4

# if no sample sheet is provided, it will be rendered automatically. Use parameter sample_sheet_path or sample_sheet_name to specify one.
my_samples = read_samples(data_path, annotation=annos, min_beads=min_beads, keep_idat=True)

# let's check the generated sample sheet !
my_samples.sample_sheet
```

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

### Mask.__init__

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.mask.Mask.html

Initializes a new Mask object with a name, optional sample label, and a set of probe indexes.

```APIDOC
## Mask(mask_name, sample_label, indexes)

### Description
Create a new Mask object to define a set of probes to be masked.

### Parameters
- **mask_name** (str) - Required - The name of the mask.
- **sample_label** (str | None) - Optional - The name of the sample the mask is applied to. Default: None.
- **indexes** (pandas.MultiIndex) - Required - A MultiIndex of masked probes.
```

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

### read_samples(datadir, sample_sheet_df=None, ...)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.html

Searches for IDAT files in the specified directory and its subdirectories.

```APIDOC
## read_samples(datadir, sample_sheet_df=None)

### Description
Search for idat files in the datadir through all sublevels.

### Parameters
- **datadir** (str) - Required - The root directory to search for IDAT files.
- **sample_sheet_df** (DataFrame) - Optional - The sample sheet dataframe.
```

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

### Samples.controls

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.Samples.html

Retrieves control probes matching a specific pattern.

```APIDOC
## controls(apply_mask=True, pattern=None, sigdf=None)

### Description
Get the subset of control probes, matching the pattern with the probe_ids if a pattern is provided.

### Parameters
- **apply_mask** (bool) - Optional - True removes masked probes, False keeps them. Default: True
- **pattern** (str | None) - Optional - pattern to match against control probe IDs. Default: None
- **sigdf** (pandas.DataFrame | None) - Optional - signal dataframe to use. Default: None
```

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

### betas_stats(samples, sample_label, apply_mask=True)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.quality_control.html

Prints statistical summary of beta values for a specific sample.

```APIDOC
## betas_stats

### Description
Print beta values stats for a given sample.

### Parameters
- **samples** (object) - Required - The collection of samples.
- **sample_label** (str) - Required - The label of the sample to analyze.
- **apply_mask** (bool) - Optional - Whether to apply a mask to the data.
```

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

### pylluminator.utils.get_or_download_file(dl_link, output_folder, filename)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.utils.get_or_download_file.html

Retrieves a file from a URL or returns the path if the file already exists in the specified directory.

```APIDOC
## pylluminator.utils.get_or_download_file

### Description
Checks if a file exists in the output folder; if not, it downloads the file from the provided link.

### Signature
`pylluminator.utils.get_or_download_file(dl_link: str, output_folder: str | MultiplexedPath | PathLike, filename: str) -> Path`

### Parameters
- **dl_link** (str) - The URL to download the file from.
- **output_folder** (str | MultiplexedPath | PathLike) - The directory where the file should be saved or checked.
- **filename** (str) - The name of the file to save or retrieve.

### Returns
- **Path** - The path to the downloaded or existing file.
```

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

### save(filepath: str) -> None

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.Samples.html

Saves the current Samples object to a file as a pickle.

```APIDOC
## save(filepath: str) -> None

### Description
Save the current Samples object to filepath, as a pickle file.

### Parameters
- **filepath** (str) - Required - Path to the file to create.
```

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

### Samples.calculate_betas

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.Samples.html

Calculates beta values for all probes.

```APIDOC
## calculate_betas(include_out_of_band=False)

### Description
Calculate beta values for all probes. Values are stored in a dataframe and can be accessed via the betas() function.

### Parameters
- **include_out_of_band** (bool) - Optional - if set to true, the Type 1 probes beta values will be calculated on in-band AND out-of-band signal values. Default: False
```

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

### Import pylluminator modules and configure logger

Source: https://pylluminator.readthedocs.io/en/latest/tutorials/1%20-%20Read%20data%20and%20get%20betas.html

Imports essential classes and visualization functions, and sets the global logging verbosity level.

```python
from pylluminator.annotations import Annotations, ArrayType, GenomeVersion
from pylluminator.samples import Samples, read_samples
from pylluminator.visualizations import betas_density, betas_dendrogram, betas_2D, nb_probes_per_chr_and_type_hist, plot_mean_beta_diff_per_group
from pylluminator.utils import set_logger, download_from_geo

# path to your data, or a folder where the downloaded data will be saved
data_path = '~/data/pylluminator-tutorial/'

# set the verbosity level, can be DEBUG, INFO, WARNING, ERROR
set_logger('WARNING')
```

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

### Download test data from GEO

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/1%20-%20Read%20data%20and%20get%20betas.ipynb.txt

Downloads specific sample files from the GEO database to the specified data path.

```python
download_from_geo(['GSM7698438', 'GSM7698446', 'GSM7698462', 'GSM7698435', 'GSM7698443', 'GSM7698459'], data_path)
```

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

### pylluminator.read_idat.read_short(infile)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.read_idat.read_short.html

Reads a two-byte element from a binary file and returns it as an integer.

```APIDOC
## pylluminator.read_idat.read_short(infile)

### Description
Converts a two-byte element from a binary file into an unsigned integer value.

### Parameters
- **infile** (file-like) - Required - The binary file to read the bytes from.

### Returns
- **int** - Unsigned integer value converted from the supplied bytes.
```

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

### pylluminator.samples.from_sesame

Source: https://pylluminator.readthedocs.io/en/latest/_sources/_autosummary/pylluminator.samples.from_sesame.rst.txt

The from_sesame function is a public function available in the pylluminator.samples module.

```APIDOC
## pylluminator.samples.from_sesame

### Description
This function is part of the pylluminator.samples module and is available for direct invocation.
```

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

### from_sesame

Source: https://pylluminator.readthedocs.io/en/latest/_sources/_autosummary/pylluminator.samples.rst.txt

Function to load sample data from a Sesame source.

```APIDOC
## from_sesame

### Description
Loads sample data from a Sesame-formatted source.

### Signature
`pylluminator.samples.from_sesame()`
```

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

### Add pylluminator with uv

Source: https://pylluminator.readthedocs.io/en/latest/index.html

Add the pylluminator package to your uv-managed project, optionally including GSEA dependencies.

```bash
uv add pylluminator
```

```bash
uv add "pylluminator[gsea]"
```

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

### Perform PCA Visualization

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/1%20-%20Read%20data%20and%20get%20betas.ipynb.txt

Visualize sample spatial distribution using Principal Component Analysis.

```python
betas_2D(my_samples, model='PCA', color_column='sample_type')
```

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

### pylluminator.quality_control.type1_color_channels_stats

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.quality_control.type1_color_channels_stats.html

Prints channel switch counts for Infinium type I probes for a given sample.

```APIDOC
## pylluminator.quality_control.type1_color_channels_stats(samples, sample_label)

### Description
Print channel switch counts for Infinium type I probes.

### Parameters
- **samples** (Samples) - Required - Samples object
- **sample_label** (str) - Required - Name of the sample to print the stats of

### Returns
- **None**
```

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

### Calculate and Plot Beta Values

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/1%20-%20Read%20data%20and%20get%20betas.ipynb.txt

Calculate beta values and visualize their density distribution.

```python
my_samples.calculate_betas(include_out_of_band=True)
betas_density(my_samples, color_column='sample_type')
```

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

### DM Class Initialization

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.dm.DM.html

Initializes the DM object and performs initial DMP computation using OLS linear regression.

```APIDOC
## class pylluminator.dm.DM(samples, formula, reference_value=None, custom_sheet=None, drop_na=False, apply_mask=True, probe_ids=None, group_column=None, use_m_values=True)

### Description
Initializes the DM object by fitting an Ordinary Least Square (OLS) linear regression model to each probe's methylation value.

### Parameters
- **samples** (Samples) - Required - The samples object.
- **formula** (str) - Required - The linear regression formula.
- **reference_value** (dict | None) - Optional - Reference values for the model.
- **custom_sheet** (None | DataFrame) - Optional - Custom sample sheet data.
- **drop_na** (bool) - Optional - Whether to drop NA values.
- **apply_mask** (bool) - Optional - Whether to apply masking.
- **probe_ids** (None | list[str]) - Optional - List of probe IDs to include.
- **group_column** (str | None) - Optional - Column name for grouping.
- **use_m_values** (bool) - Optional - Whether to use M-values (default) or beta values.
```

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

### Execute Pre-ranked GSEA

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/5%20-%20Pathway%20analysis.ipynb.txt

Runs the pre-rank method with specified permutation settings and thread count.

```python
# we chose a low permutation number to speed up the demo
pre_res = gp.prerank(rnk=rank_data, gene_sets=gene_sets, verbose=True, permutation_num=500, max_size=300, threads=4)
```

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

### Visualize bead counts per probe

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/2%20-%20QC.ipynb.txt

Plot the distribution of beads per probe. Requires that samples were loaded with keep_idat=True.

```python
count_beads = my_samples.idata[sample_name][Channel.RED].groupby('n_beads').count()

# don't display the (very) long tail of the graph, stop at the last bin that contains at least 5 probes
five_probes_min = count_beads[count_beads.mean_value > 5]
max_more_than_five_probe = five_probes_min.index.max()

# plot
plt.figure(figsize=(10, 7))
plt.bar(five_probes_min.index, five_probes_min['std_dev'])
plt.xlabel('Number of detected beads per probe')
_ = plt.ylabel('Probes count')
```

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

### read_from_file(filepath, delimiter=None)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.sample_sheet.html

Read sample sheet from the provided filepath.

```APIDOC
## read_from_file

### Description
Read sample sheet from the provided filepath.

### Parameters
- **filepath** (str) - Required - Path to the sample sheet file.
- **delimiter** (str) - Optional - The delimiter used in the sample sheet file.
```

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

### pylluminator.stats.background_correction_noob_fit

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.stats.background_correction_noob_fit.html

Performs background correction using the Noob method on provided foreground and background signal arrays.

```APIDOC
## background_correction_noob_fit(in_band_signal, out_of_band_signal)

### Description
Perform background correction using the Noob method.

### Parameters
- **in_band_signal** (numpy.ndarray) - Required - Array of foreground signal intensities.
- **out_of_band_signal** (numpy.ndarray) - Required - Array of background signal intensities.

### Returns
- **tuple[float, float, float]** - Returns a tuple containing the estimated background mean (mu), background scale (sigma), and correction factor (alpha).
```

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

### background_correction_noob_fit

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.stats.html

Performs background correction using the Noob method.

```APIDOC
## background_correction_noob_fit

### Description
Perform background correction using the Noob method.
```

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

### pylluminator.utils.load_object(filepath, object_type=None)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.utils.load_object.html

Loads an object from a specified pickle file path, optionally verifying its type.

```APIDOC
## pylluminator.utils.load_object

### Description
Loads any object from a pickle file. The function supports an optional type check to ensure the loaded object matches the expected type.

### Signature
`pylluminator.utils.load_object(filepath: str, object_type=None)`

### Parameters
- **filepath** (str) - Required - The full path to the pickle file to be loaded.
- **object_type** (type) - Optional - The expected type of the object. If provided, the function validates that the loaded object is of this type.

### Returns
- **Any** - The object loaded from the pickle file.
```

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

### read_idata(sample_sheet_df, datadir)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.html

Reads IDAT files for each sample in the provided sample sheet and organizes the data.

```APIDOC
## read_idata(sample_sheet_df, datadir)

### Description
Reads IDAT files for each sample in the provided sample sheet, organizes the data by sample name and channel, and returns a dictionary with the IDAT data and the label column name.

### Parameters
- **sample_sheet_df** (DataFrame) - Required - The sample sheet dataframe.
- **datadir** (str) - Required - The directory containing the IDAT files.
```

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

### Run GSEA Analysis

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/5%20-%20Pathway%20analysis.ipynb.txt

Configures and executes the GSEA algorithm on provided gene expression data and sample classes.

```python
# gs = gp.GSEA(data=genes_betas_df.dropna(), gene_sets=gene_sets, classes=sample_types, permutation_num=1000)  
# gs.pheno_neg = 'PREC'  # control samples
# gs.pheno_pos = 'LNCAP'  # samples of prostate cancer cells
# gs.run()
```

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

### Generate quality control statistics

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/2%20-%20QC.ipynb.txt

Calculate and print various quality control metrics for a specific sample.

```python
sample_name = 'LNCAP_500_3'
detection_stats(my_samples, sample_name)
intensity_stats(my_samples, sample_name)
nb_probes_stats(my_samples, sample_name)
type1_color_channels_stats(my_samples, sample_name)
dye_bias_stats(my_samples, sample_name)
betas_stats(my_samples, sample_name)
```

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

### mask_control_probes(sample_label: str | None = None) -> None

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.Samples.html

Shortcut to mask control probes.

```APIDOC
## mask_control_probes(sample_label: str | None = None) -> None

### Description
Shortcut to mask control probes.

### Parameters
- **sample_label** (str | None) - Optional - The name of the sample to mask. If None, mask indexes for all samples.
```

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

### plot_betas_distribution(samples, group_column=None, what='hyper', annotation_column='cgi', orientation='h', custom_sheet=None, hypo_threshold=0.4, hyper_threshold=0.6, probe_ids=None, save_path=None)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.visualizations.plot_betas_distribution.html

Plots the distribution of hyper (beta > 0.6) or hypo (beta < 0.4) methylated probes in the provided samples.

```APIDOC
## plot_betas_distribution

### Description
Plot the distribution of hyper (beta > 0.6) / hypo (beta < 0.4) methylated probes in the samples.

### Parameters
- **samples** (Samples) - Required - Samples with beta values already calculated.
- **group_column** (str | None) - Optional - Column name in the sample sheet to categorize the data vertically. Default: None.
- **what** (list[str] | str) - Optional - The metric to plot. Can be ‘hypo’, ‘hyper’, ‘mid’, ‘nas’ or ‘all’. Default: ‘hyper’.
- **annotation_column** (str) - Optional - Column name of the probe_infos dataframe to use to annotate probes. Default: ‘cgi’.
- **orientation** (str | None) - Optional - ‘h’ or ‘v’, orientation of the plot. Default: ‘h’.
- **custom_sheet** (pandas.DataFrame | None) - Optional - A sample sheet to use. Default: None.
- **hypo_threshold** (float) - Optional - Max beta value to consider a probe hypo methylated. Default: 0.4.
- **hyper_threshold** (float) - Optional - Min beta value to consider a probe hyper methylated. Default: 0.6.
- **probe_ids** (list[str] | None) - Optional - List of probes to select. Default: None.
- **save_path** (str | None) - Optional - If set, save the graph to save_path. Default: None.

### Returns
- **None**
```

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

### pylluminator.sample_sheet.read_from_file(filepath, delimiter=',')

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.sample_sheet.read_from_file.html

Reads a sample sheet from a specified CSV file path. The function expects a 'sample_id' column and supports optional metadata columns.

```APIDOC
## pylluminator.sample_sheet.read_from_file

### Description
Reads a sample sheet from the provided filepath. The file must be a .csv, but you can define a custom delimiter.

### Signature
`pylluminator.sample_sheet.read_from_file(filepath: str, delimiter: str = ',') -> DataFrame | None`

### Parameters
- **filepath** (str) - Required - Path to the sample sheet.
- **delimiter** (str) - Optional - Delimiter used in the file. Default: ','

### Returns
- **DataFrame | None** - The sample sheet as a pandas DataFrame, or None if the file could not be read.

### Requirements
- **Required columns**: sample_id
- **Recommended columns**: sentrix_id (or sentrix_barcode/sentrix_barcode_a), sentrix_position (or sentrix_position_a), sample_name.
```

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

### load_object(filepath, object_type=None)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.utils.html

Load any object from a pickle file.

```APIDOC
## load_object(filepath, object_type=None)

### Description
Load any object from a pickle file.

### Parameters
- **filepath** (str/Path) - Required - The path to the pickle file.
- **object_type** (type) - Optional - The expected type of the object.
```

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

### Samples.add_annotation_info

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.Samples.html

Merges manifest dataframe with probe signal values to build the signal dataframe.

```APIDOC
## add_annotation_info(annotation, label_column, keep_idat=False, min_beads=1)

### Description
Merge manifest dataframe with probe signal values read from idat files to build the signal dataframe, adding channel information, methylation state and mask names for each probe.

### Parameters
- **annotation** (Annotations) - Required - annotation data corresponding to the sample
- **label_column** (str) - Required - the name of the sample sheet column used for sample labels
- **min_beads** (int) - Optional - filter probes with less than min_beads beads. Default: 1
- **keep_idat** (bool) - Optional - if set to True, keep idat data after merging the annotations. Default: False
```

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

### pylluminator.samples.from_sesame(datadir, annotation, no_suffix=False)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.from_sesame.html

Reads SigDF data from SeSAMe-formatted CSV files and returns a Samples object.

```APIDOC
## pylluminator.samples.from_sesame

### Description
Reads all .csv files in the provided directory or from a specific file path, assuming they are SigDF files saved by SeSAMe.

### Signature
`pylluminator.samples.from_sesame(datadir: str | PathLike | MultiplexedPath, annotation: Annotations, no_suffix: bool = False) -> Samples | None`

### Parameters
- **datadir** (str | os.PathLike | MultiplexedPath) - Required - The directory containing SeSAMe files, or the path to a specific .csv file.
- **annotation** (Annotations) - Required - An Annotations object containing the genome version and array type corresponding to the data.
- **no_suffix** (bool) - Optional - Set to True if probe IDs do not contain a suffix (e.g., 'cg00000155' instead of 'cg00000155_BC21'). Defaults to False.

### Returns
- **Samples** (Samples | None) - Returns a Samples object containing the loaded data, or None.
```

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

### read_samples

Source: https://pylluminator.readthedocs.io/en/latest/_sources/_autosummary/pylluminator.samples.rst.txt

Function to read sample data.

```APIDOC
## read_samples

### Description
Reads sample data from a specified source.

### Signature
`pylluminator.samples.read_samples()`
```

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

### Samples.batch_correction

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.Samples.html

Applies the ComBat algorithm for batch correction on M-values.

```APIDOC
## batch_correction(batch, apply_mask=True, covariates=None, par_prior=True, mean_only=False, ref_batch=None, precision=None, na_cov_action='raise')

### Description
Applies ComBat algorithm for batch correction. The algorithm is applied on M-values, which are converted back to beta values.

### Parameters
- **batch** (str | list) - Required - Name of the column in the sample sheet or a list of batch indices.
- **apply_mask** (bool) - Optional - set to False if you don’t want any mask to be applied. Default: True
- **covariates** (str | list[str] | None) - Optional - a list of column names from the sample sheet to use as covariates. Default: None
- **par_prior** (bool) - Optional - False for non-parametric estimation of batch effects. Default: True
- **mean_only** (bool) - Optional - True if just adjusting the means and not individual batch effects. Default: False
- **ref_batch** (Any) - Optional - batch id of the batch to use as reference. Default: None
- **precision** (float) - Optional - level of precision for precision computing. Default: None
- **na_cov_action** (str) - Optional - choose the way to handle missing covariates. Default: 'raise'
```

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

### Calculate bit length

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.read_idat.IdatHeaderLocation.html

Demonstrates the bit_length method to determine the number of bits required to represent an integer.

```python
>>> bin(37)
'0b100101'
>>> (37).bit_length()
6
```

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

### pylluminator.samples.read_samples

Source: https://pylluminator.readthedocs.io/en/latest/_sources/_autosummary/pylluminator.samples.read_samples.rst.txt

The read_samples function allows users to load sample data into the application. It is part of the pylluminator.samples module.

```APIDOC
## Function: read_samples

### Description
Reads sample data from the specified source for use within the pylluminator library.

### Signature
`pylluminator.samples.read_samples()`
```

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

### pylluminator.utils.download_from_link

Source: https://pylluminator.readthedocs.io/en/latest/_sources/_autosummary/pylluminator.utils.download_from_link.rst.txt

A utility function to download content from a provided link.

```APIDOC
## pylluminator.utils.download_from_link

### Description
Downloads a file or resource from a specified URL.

### Signature
`pylluminator.utils.download_from_link(url)`
```

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

### Generate Hierarchical Clustering

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/1%20-%20Read%20data%20and%20get%20betas.ipynb.txt

Create a dendrogram to visualize sample clustering.

```python
betas_dendrogram(my_samples)
```

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

### pylluminator.samples.read_idata

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.read_idata.html

Reads IDAT files for samples defined in a DataFrame and organizes them by sample name and channel.

```APIDOC
## read_idata(sample_sheet_df, datadir)

### Description
Reads IDAT files for each sample in the provided sample sheet, organizes the data by sample name and channel, and returns a dictionary with the IDAT data and the label column name.

### Parameters
- **sample_sheet_df** (pandas.DataFrame) - Required - A DataFrame containing sample information, including columns for ‘sample_label’, ‘sample_id’, ‘sentrix_id’, and ‘sentrix_position’.
- **datadir** (str | Path) - Required - The directory where the IDAT files are located.

### Returns
- **(dict, str)** - A tuple containing a dictionary of samples (mapped by sample name and channel) and the label column name.

### Example
```python
idata, label_column = read_idata(sample_sheet_df, '/path/to/data')
```
```

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

### get_or_download_annotation_data(annotation_name, data_type, output_folder, dl_link)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.annotations.get_or_download_annotation_data.html

Checks if a specified annotation file exists locally. If not, it downloads the file from the provided link, saves it to the output folder, and returns the content as a pandas DataFrame.

```APIDOC
## pylluminator.annotations.get_or_download_annotation_data

### Description
Checks if the csv file exists, and if not downloads it from the given link and saves it in the output folder under the same name. Reads the file as a pandas dataframe, with the first column being the index, and returns it.

### Signature
`get_or_download_annotation_data(annotation_name: str, data_type: str, output_folder: str | MultiplexedPath | PathLike, dl_link: str) -> DataFrame | None`

### Parameters
- **annotation_name** (str) - Custom annotation name, 'illumina' for pylluminator-data annotations, or 'updated' for the updated annotations (EPICv2 only).
- **data_type** (str) - Data to download (e.g., probe_infos, seq_length). Must match the file name.
- **output_folder** (str | MultiplexedPath | os.PathLike) - Directory where the file is saved locally.
- **dl_link** (str) - URL to download the file from.

### Returns
- **DataFrame | None** - A pandas DataFrame containing the data, or None if no file was found or downloaded.
```

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

### from_sesame(datadir, annotation, no_suffix=False)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.html

Reads all .csv files in the specified directory, assuming they are SigDF files saved from SeSAMe.

```APIDOC
## from_sesame(datadir, annotation, no_suffix=False)

### Description
Reads all .csv files in the directory provided, supposing they are SigDF from SeSAMe saved as csv files.

### Parameters
- **datadir** (str) - Required - The directory containing the .csv files.
- **annotation** (str) - Required - Annotation information.
- **no_suffix** (bool) - Optional - Whether to ignore suffixes.
```

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

### get_or_download_annotation_data(url, output_folder)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.annotations.html

Checks for the existence of an annotation CSV file and downloads it if it is missing.

```APIDOC
## get_or_download_annotation_data(url, output_folder)

### Description
Check if the csv file exists, and if not download it from the given link and save it in the output folder under the same name.

### Parameters
- **url** (str) - Required - The source URL for the annotation data.
- **output_folder** (str) - Required - The local directory where the file should be saved.
```

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

### read_from_file(file_path)

Source: https://pylluminator.readthedocs.io/en/latest/_sources/_autosummary/pylluminator.sample_sheet.read_from_file.rst.txt

Reads a sample sheet from a file path and returns the parsed data structure.

```APIDOC
## read_from_file

### Description
Reads and parses a sample sheet file from the provided file path.

### Signature
`pylluminator.sample_sheet.read_from_file(file_path)`

### Parameters
- **file_path** (str) - Required - The path to the sample sheet file to be read.
```

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

### Define gene sets and organism

Source: https://pylluminator.readthedocs.io/en/latest/_sources/tutorials/5%20-%20Pathway%20analysis.ipynb.txt

Sets the libraries and organism for pathway analysis.

```python
gene_sets = ['GO_Biological_Process_2025', 'KEGG_2021_Human']
```

```python
organism = 'human'
```

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

### pylluminator.annotations.get_or_download_annotation_data

Source: https://pylluminator.readthedocs.io/en/latest/_sources/_autosummary/pylluminator.annotations.get_or_download_annotation_data.rst.txt

Retrieves annotation data, downloading it if necessary.

```APIDOC
## pylluminator.annotations.get_or_download_annotation_data

### Description
Retrieves annotation data from the specified source, performing a download if the data is not already available locally.

### Signature
`pylluminator.annotations.get_or_download_annotation_data()`
```

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

### save_object(object_to_save, filepath)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.utils.html

Save any object as a pickle file.

```APIDOC
## save_object(object_to_save, filepath)

### Description
Save any object as a pickle file.

### Parameters
- **object_to_save** (any) - Required - The object to serialize.
- **filepath** (str/Path) - Required - The destination file path.
```

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

### detection_stats(samples, sample_label, p_value_threshold=0.05)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.quality_control.html

Prints detection statistics for the specified sample.

```APIDOC
## detection_stats

### Description
Print detection statistics of the given sample.

### Parameters
- **samples** (object) - Required - The collection of samples.
- **sample_label** (str) - Required - The label of the sample to analyze.
- **p_value_threshold** (float) - Optional - Threshold for detection p-values.
```

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

### get_betas(sample_label, drop_na, probe_ids, custom_sheet, apply_mask)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.samples.Samples.html

Retrieves beta values for a specific sample or all samples.

```APIDOC
## get_betas(sample_label, drop_na, probe_ids, custom_sheet, apply_mask)

### Description
Get the beta values for the sample. If no sample name is provided, return beta values for all samples.

### Parameters
- **sample_label** (str | None) - Optional - The name of the sample to get beta values for.
- **drop_na** (bool) - Optional - If set to True, drop rows with NA values. Default: False
- **probe_ids** (list[str]) - Optional - The IDs of the probes to select.
- **custom_sheet** (DataFrame | None) - Optional - A custom sample sheet to filter samples.
- **apply_mask** (bool) - Optional - Set to False if you don't want any mask to be applied. Default: True
```

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

### pylluminator.utils.convert_to_path(input_path)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.utils.convert_to_path.html

Converts a given input path (string, PathLike, or MultiplexedPath) into a standard Path or PosixPath object.

```APIDOC
## pylluminator.utils.convert_to_path(input_path)

### Description
Converts the provided input_path into a PathLike format. If the input is a string or a MultiplexedPath, it is converted to a Path object, with user paths expanded if applicable.

### Parameters
- **input_path** (str | os.PathLike | MultiplexedPath) - Required - The path to convert.

### Returns
- **Path | PosixPath** - The converted path object.
```

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

### get_files_matching(root_path, pattern)

Source: https://pylluminator.readthedocs.io/en/latest/_autosummary/pylluminator.utils.get_files_matching.html

Finds all files in the specified root directory subtree that match the provided pattern, functioning similarly to Path.rglob().

```APIDOC
## get_files_matching(root_path, pattern)

### Description
Equivalent to Path.rglob() for MultiplexedPath. This function searches for all files within a given root directory that match a specified pattern.

### Parameters
- **root_path** (str | PathLike | MultiplexedPath) - Required - The root directory to search within.
- **pattern** (str) - Required - The glob-style pattern to match against file names.

### Returns
- **list[os.PathLike]** - A list of paths representing the files that matched the pattern.
```