FlowCal

https://github.com/taborlab/flowcal
Admin
FlowCal is a Python library for processing and analyzing flow cytometry data, providing FCS file...
Tokens:21,587
Snippets:163
Trust Score:4.9
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Import FlowCal in Python

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/excel_ui.rst

This snippet demonstrates how to import the FlowCal library into a Python session. Ensure FlowCal is installed and accessible in your Python environment.

```python
import FlowCal
```

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

### Remove Transient Events with start_end Gating

Source: https://context7.com/taborlab/flowcal/llms.txt

Shows how to remove transient events from the beginning and end of a flow cytometry acquisition. This helps ensure data quality by excluding fluidic instability at the start and end of the run.

```python
import FlowCal
sample = FlowCal.io.FCSData('sample.fcs')
sample = FlowCal.transform.to_rfi(sample)
sample_gated = FlowCal.gate.start_end(sample, num_start=250, num_end=100)
```

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

### Get Full Output from FlowCal Density Gate

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/gate.rst

Performs a 2D density gate and returns additional outputs beyond the gated data, including a boolean mask indicating retained events and a contour defining the gated region. This is achieved by setting 'full_output=True'. The contour is useful for visualizing the gate on plots.

```python
import FlowCal
import matplotlib.pyplot as plt

density_gate_output = FlowCal.gate.density2d(s_g1,
                                             channels=['FSC', 'SSC'],
                                             gate_fraction=0.75,
                                             full_output=True)
s_g5    = density_gate_output.gated_data
m_g5    = density_gate_output.mask
contour = density_gate_output.contour
```

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

### Batch Process Excel Files

Source: https://github.com/taborlab/flowcal/blob/master/doc/excel_ui/cmd_interface.rst

Demonstrates how to create a batch script to process multiple Excel files sequentially. Each command specifies an input and output file, allowing for automated processing of several datasets.

```bash
flowcal -i input_excel_file_1.xlsx -o output_excel_file_1.xlsx
flowcal -i input_excel_file_2.xlsx -o output_excel_file_2.xlsx
flowcal -i input_excel_file_3.xlsx -o output_excel_file_3.xlsx
...
```

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

### Visualize 1D Fluorescence Histograms

Source: https://context7.com/taborlab/flowcal/llms.txt

Shows how to generate 1D histograms for single samples or overlaid histograms for multiple samples to compare fluorescence distributions.

```python
import FlowCal
import matplotlib.pyplot as plt
plt.figure(figsize=(6, 4))
FlowCal.plot.hist1d(samples, channel='FL1', histtype='step', bins=128)
plt.xlabel('FL1 Fluorescence (a.u.)')
plt.ylabel('Count')
plt.savefig('histogram.png')
```

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

### Generate 2D Density Plots

Source: https://context7.com/taborlab/flowcal/llms.txt

Illustrates the creation of 2D density plots using scatter or mesh modes, supporting logicle scaling and custom axis limits for detailed population visualization.

```python
import FlowCal
import matplotlib.pyplot as plt
sample = FlowCal.io.FCSData('sample.fcs')
sample = FlowCal.transform.to_rfi(sample)
plt.figure(figsize=(5, 5))
FlowCal.plot.density2d(sample, channels=['FSC', 'SSC'], mode='scatter', xscale='logicle', yscale='logicle')
plt.savefig('density_plot.png')
```

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

### Load and Visualize FCS Data

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/transform.rst

Demonstrates how to load an FCS file into an FCSData object and visualize the raw channel data using matplotlib.

```python
import FlowCal
import matplotlib.pyplot as plt

s = FlowCal.io.FCSData('FCFiles/sample006.fcs')
plt.hist(s[:, 'FL1'], bins=100)
plt.show()
```

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

### Create 1D Histograms with FlowCal

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/plot.rst

Demonstrates how to load FCS data, transform it, and plot 1D histograms using FlowCal.plot.hist1d. It shows how to customize scaling, binning, and plotting multiple datasets simultaneously.

```python
import FlowCal
import numpy as np
import matplotlib.pyplot as plt

# Load and transform data
s = FlowCal.io.FCSData('FCFiles/sample006.fcs')
s = FlowCal.transform.to_rfi(s)

# Basic histogram
FlowCal.plot.hist1d(s, channel='FL1')
plt.show()

# Histogram with log scale and custom bins
FlowCal.plot.hist1d(s, channel='FL1', xscale='log', bins=1024)
plt.show()

# Multiple datasets
filenames = ['FCFiles/sample{:03d}.fcs'.format(i + 9) for i in range(3)]
d = [FlowCal.io.FCSData(filename) for filename in filenames]
d = [FlowCal.transform.to_rfi(di) for di in d]
FlowCal.plot.hist1d(d, channel='FL1', alpha=0.7, bins=128)
plt.legend(filenames, loc='upper left')
plt.show()
```

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

### Access Channels by Name

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/read.rst

Explains how to retrieve channel names and slice the FCSData object using those names instead of integer indices for better readability.

```python
# View channel names
print(s.channels)
# Slice channels using names
s_sub_ch_2 = s[:, ['FL1', 'FL2', 'FL3']]
```

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

### Perform Flow Cytometry Workflow with FlowCal

Source: https://context7.com/taborlab/flowcal/llms.txt

This script demonstrates a full analysis pipeline. It processes calibration beads to generate a MEF transformation function, applies this to experimental samples, performs gating, calculates fluorescence statistics, and generates comparative visualizations.

```python
import os
import numpy as np
import matplotlib.pyplot as plt
import FlowCal

# Create output directories
os.makedirs('plots_beads', exist_ok=True)
os.makedirs('plots_samples', exist_ok=True)

# === PART 1: Process Calibration Beads ===
beads = FlowCal.io.FCSData('FCFiles/beads.fcs')
beads = FlowCal.transform.to_rfi(beads)
beads = FlowCal.gate.start_end(beads, num_start=250, num_end=100)
beads = FlowCal.gate.high_low(beads, channels=['FSC', 'SSC'])

beads_output = FlowCal.gate.density2d(
    beads, channels=['FSC', 'SSC'],
    gate_fraction=0.85, sigma=5.0, full_output=True
)
beads_gated = beads_output.gated_data

# Generate MEF transformation function
mefl_values = np.array([0, 792, 2079, 6588, 16471, 47497, 137049, 271647])
mef_transform_fxn = FlowCal.mef.get_transform_fxn(
    beads_gated,
    mef_values=mefl_values,
    mef_channels='FL1',
    clustering_channels=['FL1', 'FL3'],
    verbose=True,
    plot=True,
    plot_dir='plots_beads',
    plot_filename='calibration'
)

# === PART 2: Process Cell Samples ===
sample_files = ['sample001.fcs', 'sample002.fcs', 'sample003.fcs']
concentrations = [0, 10, 100]
samples = []

for i, (filename, conc) in enumerate(zip(sample_files, concentrations)):
    sample = FlowCal.io.FCSData(f'FCFiles/{filename}')
    sample = FlowCal.transform.to_rfi(sample)
    sample = mef_transform_fxn(sample, channels=['FL1'])
    sample_gated = FlowCal.gate.start_end(sample, num_start=250, num_end=100)
    sample_gated = FlowCal.gate.high_low(sample_gated, channels=['FSC', 'SSC', 'FL1'])
    gate_output = FlowCal.gate.density2d(sample_gated, channels=['FSC', 'SSC'], gate_fraction=0.85, full_output=True)
    samples.append(gate_output.gated_data)

# === PART 3: Analysis and Visualization ===
for i, (sample, conc) in enumerate(zip(samples, concentrations)):
    mean_fl = FlowCal.stats.mean(sample, channels='FL1')
    print(f"Concentration {conc}: Mean={mean_fl:.0f} MEFL")

plt.figure(figsize=(6, 4))
FlowCal.plot.hist1d(samples, channel='FL1', histtype='step', bins=128)
plt.savefig('plots_samples/histograms_overlay.png')
```

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

### Generate Violin Plots for Sample Comparison

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/plot.rst

Creates violin plots to compare data across multiple samples. This method is more compact than standard histograms and supports logarithmic scaling for axes.

```python
filenames = ['FCFiles/sample{:03d}.fcs'.format(i+6) for i in range(10)]
d = [FlowCal.io.FCSData(filename) for filename in filenames]
d = [FlowCal.transform.to_rfi(di) for di in d]
dapg = np.array([0, 2.33, 4.36, 8.16, 15.3, 28.6, 53.5, 100, 187, 350])
FlowCal.plot.violin(data=d, channel='FL1', positions=dapg, xlabel='DAPG (uM)', xscale='log', ylim=(1e0,2e3))
plt.show()
```

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

### Plot Dose-Response Data with Mathematical Models

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/plot.rst

Visualizes dose-response datasets including minimum/maximum controls and a custom mathematical model overlay. This function is ideal for biological sensor characterization.

```python
def dapg_sensor_model(dapg_concentration):
    mn = 20
    mx = 250.
    K  = 20.
    n  = 3.57
    if dapg_concentration <= 0:
        return mn
    else:
        return mn + ((mx-mn)/(1+((K/dapg_concentration)**n)))

FlowCal.plot.violin_dose_response(
    data=d,
    channel='FL1',
    positions=dapg,
    min_data=d[0],
    max_data=d[-1],
    model_fxn=dapg_sensor_model,
    xscale='log',
    yscale='log',
    ylim=(1e0,2e3),
    draw_model_kwargs={'color':'gray', 'linewidth':3, 'zorder':-1, 'solid_capstyle':'butt'})
plt.xlabel('DAPG Concentration (\u03bcM)')
plt.ylabel('FL1 Fluorescence (a.u.)')
plt.show()
```

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

### Run FlowCal Excel User Interface

Source: https://context7.com/taborlab/flowcal/llms.txt

This snippet shows how to launch the FlowCal Excel User Interface, which allows users to process flow cytometry data using an Excel spreadsheet for configuration without writing Python code. It demonstrates running with a file dialog and with specified input/output files.

```python
import FlowCal

FlowCal.excel_ui.run()

FlowCal.excel_ui.run(
    input_path='experiment.xlsx',
    output_path='experiment_output.xlsx',
    verbose=True,
    plot=True,
    hist_sheet=True
)
```

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

### Load and Inspect FCS Data

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/read.rst

Demonstrates how to import the FlowCal library, load an FCS file into an FCSData object, and inspect the data dimensions using the shape property.

```python
import FlowCal
# Load the FCS file
s = FlowCal.io.FCSData('FCFiles/sample006.fcs')
# Inspect dimensions (events, channels)
print(s.shape)
```

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

### Loading and Gating Calibration Bead Data

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/mef.rst

Loads FCS data for calibration beads, transforms it to RFI (Relative Fluorescence Intensity), and applies a density-based 2D gate to isolate single beads. It then visualizes the gated data and a histogram of fluorescence.

```python
b = FlowCal.io.FCSData('FCFiles/sample001.fcs')
b = FlowCal.transform.to_rfi(b)
density_gate_output = FlowCal.gate.density2d(b,
                                             channels=['FSC', 'SSC'],
                                             gate_fraction=0.3,
                                             full_output=True)
b_g = density_gate_output.gated_data
c   = density_gate_output.contour
FlowCal.plot.density_and_hist(b,
                              gated_data=b_g,
                              gate_contour=c,
                              density_channels=['FSC', 'SSC'],
                              density_params={'mode':'scatter',
                                              'xlim': [1e2, 1e3],
                                              'ylim': [1e2, 1e3],
                                              'sigma': 5.},
                              hist_channels=['FL1'])
plt.tight_layout()
plt.show()
```

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

### Importing Libraries for Flow Cytometry Analysis

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/mef.rst

Imports necessary Python libraries including FlowCal for data handling and matplotlib for plotting. This is a prerequisite for most operations in the tutorial.

```python
import FlowCal
import numpy as np
import matplotlib.pyplot as plt
```

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

### Run FlowCal Excel UI

Source: https://github.com/taborlab/flowcal/blob/master/doc/excel_ui/cmd_interface.rst

Executes the FlowCal Excel UI from the command line. It can take input and output file paths, and control verbosity and plotting. If no input path is specified, a file dialog will appear.

```bash
flowcal [-h] [-i [INPUTPATH]] [-o [OUTPUTPATH]] [-v] [-p] [-H]
python -m FlowCal.excel_ui [-h] [-i [INPUTPATH]] [-o [OUTPUTPATH]] [-v] [-p] [-H]
```

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

### Process and Plot Flow Cytometry Data with FlowCal

Source: https://context7.com/taborlab/flowcal/llms.txt

This snippet demonstrates loading FCS data, applying transformations and gates (start/end, high/low, density2d), and generating combined density and histogram plots to visualize the effects of gating. It shows how to create plots with and without model overlays and how to handle multiple fluorescence channels.

```python
import FlowCal
sample = FlowCal.io.FCSData('sample.fcs')
sample = FlowCal.transform.to_rfi(sample)
sample_pregated = FlowCal.gate.start_end(sample, num_start=250, num_end=100)
sample_pregated = FlowCal.gate.high_low(sample_pregated, channels=['FSC', 'SSC', 'FL1'])

density_output = FlowCal.gate.density2d(
    sample_pregated,
    channels=['FSC', 'SSC'],
    gate_fraction=0.85,
    full_output=True
)
sample_gated = density_output.gated_data
gate_contour = density_output.contour

density_params = {
    'mode': 'scatter',
    'title': f'Sample ({100*sample_gated.shape[0]/sample.shape[0]:.1f}% retained)'
}
hist_params = {'xlabel': 'FL1 Fluorescence (a.u.)'}

FlowCal.plot.density_and_hist(
    sample,
    sample_gated,
    density_channels=['FSC', 'SSC'],
    hist_channels=['FL1'],
    gate_contour=gate_contour,
    density_params=density_params,
    hist_params=hist_params,
    savefig='density_hist_sample.png'
)

FlowCal.plot.density_and_hist(
    sample,
    sample_gated,
    density_channels=['FSC', 'SSC'],
    hist_channels=['FL1', 'FL3'],
    gate_contour=gate_contour,
    density_params={'mode': 'scatter'},
    hist_params={'xscale': 'logicle'},
    savefig='density_hist_multi.png'
)
```

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

### Enable Verbose Output and Plotting

Source: https://github.com/taborlab/flowcal/blob/master/doc/excel_ui/cmd_interface.rst

Runs the FlowCal Excel UI with verbose output to show processing steps and generates density plots/histograms. This is equivalent to the default macOS/Windows batch scripts.

```bash
flowcal -v -p
python -m FlowCal.excel_ui -v -p
```

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

### Apply Density-Based 2D Gate with FlowCal

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/gate.rst

Applies a 2D density gate to identify the region with the highest event density in specified channels. It automatically determines the gate shape to capture a given fraction of total events, requiring only the 'gate_fraction' parameter. The output can be visualized using FlowCal's plotting functions.

```python
import FlowCal
import matplotlib.pyplot as plt

s_g4 = FlowCal.gate.density2d(s_g1,
                               channels=['FSC', 'SSC'],
                               gate_fraction=0.75)
FlowCal.plot.density2d(s_g4,
                       channels=['FSC', 'SSC'],
                       mode='scatter')
plt.show()
```

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

### Load and Access FCS Data with FCSData

Source: https://context7.com/taborlab/flowcal/llms.txt

Demonstrates how to load flow cytometry data from an FCS file using the FCSData class and access event data, channel information, and metadata. It shows how to retrieve specific channel data and calculate histogram bins.

```python
import FlowCal
sample = FlowCal.io.FCSData('sample.fcs')
print(f"Number of events: {sample.shape[0]}")
print(f"Channel names: {sample.channels}")
fl1_data = sample[:, 'FL1']
bins = sample.hist_bins(channel='FL1', nbins=256, scale='logicle')
```

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

### Calculate Flow Cytometry Statistics with FlowCal

Source: https://context7.com/taborlab/flowcal/llms.txt

Demonstrates how to load, transform, and gate flow cytometry data before calculating various statistical metrics such as mean, geometric mean, median, and robust CV.

```python
import FlowCal
sample = FlowCal.io.FCSData('sample.fcs')
sample = FlowCal.transform.to_rfi(sample)
sample_gated = FlowCal.gate.density2d(FlowCal.gate.high_low(FlowCal.gate.start_end(sample, num_start=250, num_end=100), channels=['FSC', 'SSC', 'FL1']), channels=['FSC', 'SSC'], gate_fraction=0.85).gated_data
fl1_mean = FlowCal.stats.mean(sample_gated, channels='FL1')
fl1_cv = FlowCal.stats.cv(sample_gated, channels='FL1')
print(f"Mean: {fl1_mean:.2f}")
print(f"CV: {fl1_cv:.4f}")
```

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

### Transforming Cell Sample Data to MEF

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/mef.rst

Loads a cell sample FCS file, transforms its fluorescence data to RFI, and then applies the previously generated MEF transformation function to the 'FL1' channel. Finally, it gates the transformed data based on FSC and SSC.

```python
# Load sample
s = FlowCal.io.FCSData('FCFiles/sample006.fcs')

# Transform all channels to a.u., and then FL1 to MEF.
s = FlowCal.transform.to_rfi(s)
s = to_mef(s, channels='FL1')

# Gate
s_g = FlowCal.gate.high_low(s, channels=['FSC', 'SSC'])
s_g = FlowCal.gate.density2d(s_g,
                             channels=['FSC', 'SSC'],
```

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

### Set Matplotlib Backend Environment Variable

Source: https://github.com/taborlab/flowcal/blob/master/doc/excel_ui/cmd_interface.rst

Temporarily sets the MPLBACKEND environment variable to 'TkAgg' to resolve conflicts between matplotlib and TkInter on macOS when running the Excel UI.

```bash
export MPLBACKEND="TkAgg"
```

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

### Transform Multiple Channels to RFI

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/transform.rst

Shows how to transform all available channels in an FCSData object to arbitrary fluorescence units by omitting the channel argument.

```python
import FlowCal

s = FlowCal.io.FCSData('FCFiles/sample006.fcs')
s_transformed = FlowCal.transform.to_rfi(s)
```

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

### Gaussian Mixture Model Clustering for Beads

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/mef.rst

Implements Gaussian Mixture Models for clustering bead subpopulations. This is the default clustering algorithm used by FlowCal's MEF transformation function generation.

```python
import FlowCal

# This function is typically passed as an argument to get_transform_fxn
# FlowCal.mef.clustering_gmm(data, channels, k)
```

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

### Generate 2D Density Plots with FlowCal

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/plot.rst

Illustrates how to visualize 2D relationships between flow cytometry channels using FlowCal.plot.density2d. It covers both mesh and scatter modes for identifying cell populations.

```python
import FlowCal
import matplotlib.pyplot as plt

# Load data
s = FlowCal.io.FCSData('FCFiles/sample006.fcs')

# Default density plot (mesh mode)
FlowCal.plot.density2d(s, channels=['FSC', 'SSC'])
plt.show()

# Scatter mode for identifying populations
FlowCal.plot.density2d(s, channels=['FSC', 'SSC'], mode='scatter')
plt.show()
```

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

### Generate MEF Transformation Function with FlowCal

Source: https://context7.com/taborlab/flowcal/llms.txt

The get_transform_fxn function processes calibration bead data to create a transformation function that converts fluorescence from RFI to Molecules of Equivalent Fluorophore (MEF). This enables absolute quantification and comparison across experiments. It requires gated bead data and corresponding MEF values, and can output fitting details.

```python
import FlowCal
import numpy as np

# Load and process calibration beads
beads = FlowCal.io.FCSData('beads.fcs')
beads = FlowCal.transform.to_rfi(beads)
beads = FlowCal.gate.start_end(beads, num_start=250, num_end=100)
beads = FlowCal.gate.high_low(beads, channels=['FSC', 'SSC'])

beads_gated_output = FlowCal.gate.density2d(
    data=beads,
    channels=['FSC', 'SSC'],
    gate_fraction=0.85,
    sigma=5.0,
    full_output=True
)
beads_gated = beads_gated_output.gated_data

# MEF values from bead manufacturer datasheet (MEFL for GFP channel)
mefl_values = np.array([0, 792, 2079, 6588, 16471, 47497, 137049, 271647])

# Generate MEF transformation function
mef_transform_fxn = FlowCal.mef.get_transform_fxn(
    beads_gated,
    mef_values=mefl_values,
    mef_channels='FL1',
    clustering_channels=['FL1', 'FL3'],  # Channels for subpopulation identification
    verbose=True,
    plot=True,
    plot_dir='plots',
    plot_filename='beads_calibration'
)

# Apply MEF transformation to cell samples
sample = FlowCal.io.FCSData('cells.fcs')
sample = FlowCal.transform.to_rfi(sample)
sample = mef_transform_fxn(sample, channels=['FL1'])
# FL1 channel is now in MEF units

# Get full output with fitting details
mef_output = FlowCal.mef.get_transform_fxn(
    beads_gated,
    mef_values=mefl_values,
    mef_channels='FL1',
    clustering_channels=['FL1', 'FL3'],
    full_output=True
)
mef_transform_fxn = mef_output.transform_fxn
# Access fitting parameters: mef_output.fitting
```

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

### Generate Dose-Response Violin Plots with FlowCal

Source: https://context7.com/taborlab/flowcal/llms.txt

This snippet illustrates how to generate dose-response violin plots using FlowCal. It processes samples at varying concentrations, applies gating, and then visualizes the fluorescence distribution across these concentrations. The function supports overlaying a model function for further analysis.

```python
import FlowCal
import matplotlib.pyplot as plt
import numpy as np

concentrations = np.array([0, 2.33, 4.36, 8.16, 15.3, 28.6, 53.5, 100, 187, 350])
samples = []

for i, conc in enumerate(concentrations):
    sample = FlowCal.io.FCSData(f'sample_{i:03d}.fcs')
    sample = FlowCal.transform.to_rfi(sample)
    sample = FlowCal.gate.start_end(sample, num_start=250, num_end=100)
    sample = FlowCal.gate.density2d(sample, channels=['FSC', 'SSC'], gate_fraction=0.85).gated_data
    samples.append(sample)

min_sample = samples[0]
max_sample = samples[-1]

plt.figure(figsize=(6, 4))
FlowCal.plot.violin_dose_response(
    data=samples,
    channel='FL1',
    positions=concentrations,
    min_data=min_sample,
    max_data=max_sample,
    violin_kwargs={'facecolor': '#ffc400', 'edgecolor': 'black'},
    violin_width_to_span_fraction=0.075,
    xscale='log',
    yscale='log',
    ylim=(1e0, 2e3)
)
plt.xlabel(r'Inducer Concentration ($\mu M$)')
plt.ylabel('FL1 Fluorescence (a.u.)')
plt.tight_layout()
plt.savefig('dose_response_violin.png', dpi=200)
plt.close()

def sensor_model(concentration):
    mn, mx, K, n = 86, 3147, 20, 3.57
    if concentration <= 0:
        return mn
    return mn + ((mx - mn) / (1 + ((K / concentration) ** n)))

plt.figure(figsize=(6, 4))
FlowCal.plot.violin_dose_response(
    data=samples,
    channel='FL1',
    positions=concentrations,
    min_data=min_sample,
    max_data=max_sample,
    model_fxn=sensor_model,
    draw_model_kwargs={'color': 'gray', 'linewidth': 3, 'zorder': -1},
    xscale='log',
    yscale='log',
    ylim=(1e1, 3e4)
)
plt.xlabel(r'Inducer Concentration ($\mu M$)')
plt.ylabel('FL1 Fluorescence (MEF)')
plt.tight_layout()
plt.savefig('dose_response_with_model.png', dpi=200)
plt.close()
```

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

### Slice FCSData Objects

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/read.rst

Shows how to slice FCSData objects by event index or channel index, similar to standard numpy arrays. The resulting objects maintain the FCSData type.

```python
# Slice first 100 events
s_sub = s[:100]
# Slice specific channels by index
s_sub_ch = s[:, [3, 4, 5]]
```

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

### gate.start_end - Remove Transient Events

Source: https://context7.com/taborlab/flowcal/llms.txt

The start_end gating function removes events from the beginning and end of the acquisition, which can be affected by transient system states.

```APIDOC
## gate.start_end - Remove Transient Events

### Description
The start_end gating function removes events from the beginning and end of the acquisition. This is important because transients in the fluidics system can cause the first and last events to be slightly different from the rest of the population.

### Method
`FlowCal.gate.start_end(sample, num_start=250, num_end=100)`

### Endpoint
N/A (Python Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **sample** (FCSData object) - Required - The FCSData object to gate.
- **num_start** (integer, optional) - The number of events to remove from the beginning of the acquisition. Defaults to 250.
- **num_end** (integer, optional) - The number of events to remove from the end of the acquisition. Defaults to 100.

### Request Example
```python
import FlowCal

sample = FlowCal.io.FCSData('sample.fcs')
sample = FlowCal.transform.to_rfi(sample)

# Remove first 250 and last 100 events (recommended defaults)
sample_gated = FlowCal.gate.start_end(sample)

print(f"Events before gating: {sample.shape[0]}")
print(f"Events after gating: {sample_gated.shape[0]}")

# Use different values based on your instrument
sample_gated = FlowCal.gate.start_end(sample, num_start=500, num_end=200)
```

### Response
#### Success Response (200)
- **sample_gated** (FCSData object) - The FCSData object with transient events removed.

#### Response Example
```python
print(f"Events after custom gating: {sample_gated.shape[0]}")
```
```

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

### Create Combined Density and Histogram Plots

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/plot.rst

Uses FlowCal.plot.density_and_hist to generate a combined visualization of density plots for two channels and a histogram for a third. It accepts dictionaries for fine-tuning the underlying plot parameters.

```python
FlowCal.plot.density_and_hist(s, density_channels=['FSC', 'SSC'], density_params={'mode':'scatter'}, hist_channels=['FL1'])
plt.tight_layout()
plt.show()
```

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

### Generating MEF Transformation Function

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/mef.rst

Generates a transformation function to convert fluorescence data to MEF using calibration bead data and manufacturer-provided MEF values. The function `FlowCal.mef.get_transform_fxn` is used, and plotting is enabled to visualize the process.

```python
# Obtain transformation function
# The following MEFL values were provided by the beads' manufacturer
mefl_values = np.array([0, 792, 2079, 6588, 16471, 47497, 137049, 271647])
to_mef = FlowCal.mef.get_transform_fxn(b_g, 
                                         mef_values=mefl_values,
                                         mef_channels='FL1',
                                         plot=True)
plt.show()
```

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

### Filter Saturated Events with high_low Gating

Source: https://context7.com/taborlab/flowcal/llms.txt

Demonstrates the use of the high_low gating function to remove events that fall outside the detector's valid range. This ensures that saturated measurements do not skew downstream analysis.

```python
import FlowCal
sample = FlowCal.io.FCSData('sample.fcs')
sample = FlowCal.transform.to_rfi(sample)
sample = FlowCal.gate.start_end(sample, num_start=250, num_end=100)
sample_gated = FlowCal.gate.high_low(sample, channels=['FSC', 'SSC', 'FL1'])
```

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

### Apply Ellipse Gate to Flow Cytometry Data

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/gate.rst

Demonstrates how to isolate a specific cluster of events by defining an elliptical region in log space, which is useful for selecting the densest cell populations.

```python
s_g3 = FlowCal.gate.ellipse(s_g1,
                             channels=['FSC', 'SSC'],
                             log=True,
                             center=(2.3, 2.78),
                             a=0.3,
                             b=0.2,
                             theta=30/180.*np.pi)
FlowCal.plot.density2d(s_g3, channels=['FSC', 'SSC'], mode='scatter')
plt.show()
```

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

### Visualize FlowCal Density Gate with Density and Histogram Plot

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/gate.rst

Visualizes the result of a 2D density gating process using FlowCal's density_and_hist function. It displays the ungated data with the gating contour overlaid and shows how the gating affects histograms of other channels. This function requires the original data, the gated data, the gate contour, and channel information.

```python
import FlowCal
import matplotlib.pyplot as plt

FlowCal.plot.density_and_hist(s_g1,
                              gated_data=s_g5,
                              gate_contour=contour,
                              density_channels=['FSC', 'SSC'],
                              density_params={'mode':'scatter'},
                              hist_channels=['FL1'])
plt.tight_layout()
plt.show()
```

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

### FlowCal.io Module

Source: https://github.com/taborlab/flowcal/blob/master/doc/reference/modules.rst

Provides functions for reading and writing flow cytometry data files.

```APIDOC
## GET /FlowCal.io

### Description
Provides utilities to read flow cytometry data files (e.g., FCS files) and export processed data.

### Method
GET

### Endpoint
FlowCal.io

### Parameters
#### Query Parameters
- **filename** (string) - Required - The path to the flow cytometry data file.

### Response
#### Success Response (200)
- **data** (object) - The loaded flow cytometry data object.
```

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

### FlowCal.plot Module Overview

Source: https://github.com/taborlab/flowcal/blob/master/doc/reference/FlowCal.plot.rst

This section provides an overview of the FlowCal.plot module, listing its members, undocumented members, and inheritance information.

```APIDOC
## FlowCal.plot Module

### Description
This module provides plotting functionalities for FlowCal.

### Members
Lists all public members of the module.

### Undocumented Members
Lists members that are not explicitly documented.

### Inheritance
Shows the inheritance hierarchy for classes within the module.
```

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

### Transform Data to Relative Fluorescence Intensity

Source: https://context7.com/taborlab/flowcal/llms.txt

Explains the use of the to_rfi function to convert raw instrument data into Relative Fluorescence Intensity (RFI) units. This process uses gain and offset metadata to linearize data across specified channels.

```python
import FlowCal
sample = FlowCal.io.FCSData('sample.fcs')
sample_rfi = FlowCal.transform.to_rfi(sample, channels=['FSC', 'SSC', 'FL1'])
```

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

### Process Beads Table with FlowCal

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/excel_ui.rst

This function processes the beads table using the instruments table to perform density gating and standard curve calculations. It can optionally display verbose output and generate plots.

```python
beads_samples, mef_transform_fxns = FlowCal.excel_ui.process_beads_table(
    beads_table,
    instruments_table,
    verbose=True,
    plot=True)
```

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

### mef.get_transform_fxn - Calibration Bead Processing

Source: https://context7.com/taborlab/flowcal/llms.txt

Processes calibration bead data to generate a transformation function for converting fluorescence to Molecules of Equivalent Fluorophore (MEF).

```APIDOC
## mef.get_transform_fxn - Calibration Bead Processing

### Description
The get_transform_fxn function processes calibration bead data to generate a transformation function that converts fluorescence from arbitrary units (RFI) to Molecules of Equivalent Fluorophore (MEF). This enables absolute quantification and comparison of fluorescence across different experiments and instruments.

### Method
FlowCal.mef.get_transform_fxn

### Parameters
#### Data
- **beads_gated** (FlowCal.io.FCSData) - Gated FCS data from calibration beads.
- **mef_values** (numpy.ndarray) - Array of known MEF values for the calibration beads.
- **mef_channels** (str or list of str) - The channel(s) to use for MEF calculation.
- **clustering_channels** (list of str) - Channels used for identifying subpopulations within the beads.
- **verbose** (bool) - If True, prints detailed information during processing.
- **plot** (bool) - If True, generates plots of the bead data and fitting.
- **plot_dir** (str) - Directory to save the generated plots.
- **plot_filename** (str) - Base filename for the plots.
- **full_output** (bool) - If True, returns an object with transform_fxn and fitting details.

### Request Example
```python
import FlowCal
import numpy as np

# Load and process calibration beads
beads = FlowCal.io.FCSData('beads.fcs')
beads = FlowCal.transform.to_rfi(beads)
beads = FlowCal.gate.start_end(beads, num_start=250, num_end=100)
beads = FlowCal.gate.high_low(beads, channels=['FSC', 'SSC'])

beads_gated_output = FlowCal.gate.density2d(
    data=beads,
    channels=['FSC', 'SSC'],
    gate_fraction=0.85,
    sigma=5.0,
    full_output=True
)
beads_gated = beads_gated_output.gated_data

# MEF values from bead manufacturer datasheet (MEFL for GFP channel)
mefl_values = np.array([0, 792, 2079, 6588, 16471, 47497, 137049, 271647])

# Generate MEF transformation function
mef_transform_fxn = FlowCal.mef.get_transform_fxn(
    beads_gated,
    mef_values=mefl_values,
    mef_channels='FL1',
    clustering_channels=['FL1', 'FL3'],  # Channels for subpopulation identification
    verbose=True,
    plot=True,
    plot_dir='plots',
    plot_filename='beads_calibration'
)

# Apply MEF transformation to cell samples
sample = FlowCal.io.FCSData('cells.fcs')
sample = FlowCal.transform.to_rfi(sample)
sample = mef_transform_fxn(sample, channels=['FL1'])
# FL1 channel is now in MEF units

# Get full output with fitting details
mef_output = FlowCal.mef.get_transform_fxn(
    beads_gated,
    mef_values=mefl_values,
    mef_channels='FL1',
    clustering_channels=['FL1', 'FL3'],
    full_output=True
)
mef_transform_fxn = mef_output.transform_fxn
# Access fitting parameters: mef_output.fitting
```

### Response
#### Success Response (200)
- **transform_fxn** (function) - A callable function that applies the MEF transformation to FCS data.
- **fitting** (dict) - Dictionary containing fitting parameters and statistics (if full_output=True).

#### Response Example
(No specific JSON response example provided, as the output is typically a function or a dictionary.)
```

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

### Transform Data to Arbitrary Fluorescence Units

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/transform.rst

Uses FlowCal.transform.to_rfi to convert raw channel data into arbitrary fluorescence units (a.u.) and visualizes the result on a logarithmic scale.

```python
import FlowCal
import numpy as np
import matplotlib.pyplot as plt

s = FlowCal.io.FCSData('FCFiles/sample006.fcs')
s_transformed = FlowCal.transform.to_rfi(s, channels='FL1')

bins = np.logspace(0, 4, 100)
plt.hist(s_transformed[:, 'FL1'], bins=bins)
plt.xscale('log')
plt.show()
```

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

### Process Cell Samples using FlowCal Excel UI

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/excel_ui.rst

This function processes cell samples by applying density gating and transformations based on provided instrument and sample tables. It optionally accepts MEF transformation functions to calibrate data, returning a dictionary of processed FCSData objects.

```python
samples = FlowCal.excel_ui.process_samples_table(
    samples_table,
    instruments_table,
    mef_transform_fxns=mef_transform_fxns,
    verbose=True,
    plot=True)
```

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

### Generating MEF Transformation Function with FlowCal

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/mef.rst

This function generates a transformation function to convert fluorescence values to Molecules of Equivalent Fluor (MEF). It involves several steps including bead subpopulation identification, statistic calculation, population selection, and standard curve fitting. Customization is possible through various arguments.

```python
import FlowCal

# Example usage:
# transform_fxn = FlowCal.mef.get_transform_fxn(
#     beads_filename='<beads_filename>',
#     mef_values=[1000, 10000, 100000],
#     clustering_fxn=FlowCal.mef.clustering_gmm,
#     clustering_channels=['FSC-A', 'FL1'],
#     mef_channels=['FL1'],
#     statistic_fxn=FlowCal.mef.statistic_median,
#     selection_fxn=FlowCal.mef.selection_std
# )
```

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

### FlowCal.gate Module

Source: https://github.com/taborlab/flowcal/blob/master/doc/reference/modules.rst

Contains functions for defining and applying gates to flow cytometry data.

```APIDOC
## POST /FlowCal.gate

### Description
Applies a gate to a flow cytometry data object to filter populations.

### Method
POST

### Endpoint
FlowCal.gate

### Request Body
- **data** (object) - Required - The flow cytometry data object.
- **gate_type** (string) - Required - The type of gate to apply (e.g., 'polygon', 'rectangle').

### Response
#### Success Response (200)
- **filtered_data** (object) - The data object containing only the gated population.
```

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

### Load Data Tables from Excel with FlowCal

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/excel_ui.rst

This code loads instrument, beads, and samples data from an Excel file into pandas DataFrames using FlowCal's read_table function. It specifies the input file, sheet names, and the column to be used as the DataFrame index.

```python
input_file = 'experiment.xlsx'
instruments_table = FlowCal.excel_ui.read_table(input_file,
                                                 sheetname='Instruments',
                                                 index_col='ID')
beads_table = FlowCal.excel_ui.read_table(input_file,
                                           sheetname='Beads',
                                           index_col='ID')
samples_table = FlowCal.excel_ui.read_table(input_file,
                                             sheetname='Samples',
                                             index_col='ID')
```

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

### Plotting 1D Histogram with FlowCal

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/mef.rst

This snippet demonstrates how to plot a histogram for a specific channel after data transformation. It utilizes FlowCal's plotting capabilities and requires matplotlib for display.

```python
import FlowCal
import matplotlib.pyplot as plt

# Assuming 's_g' is a transformed sample object
FlowCal.plot.hist1d(s_g, channel='FL1')
plt.show()
```

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

### Specify Custom High/Low Thresholds in FlowCal

Source: https://context7.com/taborlab/flowcal/llms.txt

This function allows setting custom minimum and maximum acceptable values for specified channels. It's useful for filtering out events outside a defined range, such as setting bounds for 10-bit data or removing saturation.

```python
sample_gated = FlowCal.gate.high_low(
    sample,
    channels='FL1',
    low=1,
    high=1023
)

beads_gated = FlowCal.gate.high_low(beads_sample, channels=['FSC', 'SSC'])
```

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

### transform.to_rfi - Convert to Relative Fluorescence Intensity

Source: https://context7.com/taborlab/flowcal/llms.txt

The to_rfi function transforms raw channel unit data to Relative Fluorescence Intensity (RFI) values, also known as arbitrary fluorescence units (a.u.).

```APIDOC
## transform.to_rfi - Convert to Relative Fluorescence Intensity

### Description
The to_rfi function transforms raw channel unit data to Relative Fluorescence Intensity (RFI) values, also known as arbitrary fluorescence units (a.u.). This conversion uses gain and offset information stored in the FCS file to linearize the data from the instrument's detectors.

### Method
`FlowCal.transform.to_rfi(sample, channels=None)`

### Endpoint
N/A (Python Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **sample** (FCSData object) - Required - The FCSData object to transform.
- **channels** (string or list of strings, optional) - The channel(s) to transform. If None, all channels are transformed.

### Request Example
```python
import FlowCal

sample = FlowCal.io.FCSData('sample.fcs')

# Transform all channels to RFI
sample_rfi = FlowCal.transform.to_rfi(sample)

# Transform specific channels only
sample_rfi = FlowCal.transform.to_rfi(sample, channels=['FSC', 'SSC', 'FL1'])
```

### Response
#### Success Response (200)
- **sample_rfi** (FCSData object) - The FCSData object with specified channels transformed to RFI.

#### Response Example
```python
# Data is now ready for gating and analysis
print(f"Transformed sample: {sample_rfi}")
```
```

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

### Standard Deviation Based Population Selection

Source: https://github.com/taborlab/flowcal/blob/master/doc/python_tutorial/mef.rst

A method for selecting valid bead populations for MEF transformation by discarding populations close to saturation based on standard deviation. This is the default selection function in FlowCal.

```python
import FlowCal

# This function is typically passed as an argument to get_transform_fxn
# FlowCal.mef.selection_std(data, channels, populations, statistics)
```

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

### gate.density2d - Density-Based Population Gating

Source: https://context7.com/taborlab/flowcal/llms.txt

Identifies and retains the densest population in a 2D projection of the data, useful for isolating cell or bead populations.

```APIDOC
## gate.density2d - Density-Based Population Gating

### Description
The density2d gating function identifies and retains the densest population in a 2D projection of the data. This is the primary method for isolating the population of interest (cells or beads) from debris and aggregates based on forward and side scatter characteristics.

### Method
FlowCal.gate.density2d

### Parameters
#### Data
- **data** (FlowCal.io.FCSData) - The input FCS data.
- **channels** (list of str) - The channels to use for density gating (e.g., ['FSC', 'SSC']).
- **gate_fraction** (float) - The fraction of events to retain in the densest region (default is 0.85).
- **sigma** (float) - The smoothing factor for density estimation. Lower values are suitable for tight clusters like beads.
- **xscale** (str) - The scaling for the x-axis ('linear', 'log', 'logicle').
- **yscale** (str) - The scaling for the y-axis ('linear', 'log', 'logicle').
- **full_output** (bool) - If True, returns an object with gated_data and contour.

### Request Example
```python
import FlowCal

# Load, transform, and pre-gate data
sample = FlowCal.io.FCSData('sample.fcs')
sample = FlowCal.transform.to_rfi(sample)
sample = FlowCal.gate.start_end(sample, num_start=250, num_end=100)
sample = FlowCal.gate.high_low(sample, channels=['FSC', 'SSC', 'FL1'])

# Apply density gating to retain 85% of events in densest region
sample_gated = FlowCal.gate.density2d(
    data=sample,
    channels=['FSC', 'SSC'],
    gate_fraction=0.85
)

# Get the gate contour for plotting
density_gate_output = FlowCal.gate.density2d(
    data=sample,
    channels=['FSC', 'SSC'],
    gate_fraction=0.85,
    full_output=True
)
sample_gated = density_gate_output.gated_data
gate_contour = density_gate_output.contour

# For beads (tighter distribution), use lower smoothing
beads_gated_output = FlowCal.gate.density2d(
    data=beads_sample,
    channels=['FSC', 'SSC'],
    gate_fraction=0.85,
    sigma=5.0,  # Lower smoothing for tight bead clusters
    full_output=True
)

# Use logicle scaling for better visualization
density_gate_output = FlowCal.gate.density2d(
    data=sample,
    channels=['FSC', 'SSC'],
    gate_fraction=0.85,
    xscale='logicle',
    yscale='logicle',
    full_output=True
)
```

### Response
#### Success Response (200)
- **gated_data** (FlowCal.io.FCSData) - The data subsetted by the density gate.
- **contour** (numpy.ndarray) - The contour of the density gate (if full_output=True).

#### Response Example
(No specific JSON response example provided, as the output is typically FCSData objects or numpy arrays.)
```

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

### Elliptical Region Gating with FlowCal

Source: https://context7.com/taborlab/flowcal/llms.txt

This function retains events within an elliptical region defined by a center point and covariance matrix. It offers precise control over the gated region when density-based gating is not ideal. The function can also return the gate contour for visualization.

```python
import FlowCal
import numpy as np

# Load and transform data
sample = FlowCal.io.FCSData('sample.fcs')
sample = FlowCal.transform.to_rfi(sample)

# Define ellipse parameters
center = [500, 400]  # Center coordinates [FSC, SSC]
covariance = [[10000, 5000], [5000, 8000]]  # Covariance matrix

# Apply ellipse gate
sample_gated = FlowCal.gate.ellipse(
    data=sample,
    channels=['FSC', 'SSC'],
    center=center,
    a=covariance
)

# Get gate contour for plotting
ellipse_output = FlowCal.gate.ellipse(
    data=sample,
    channels=['FSC', 'SSC'],
    center=center,
    a=covariance,
    full_output=True
)
sample_gated = ellipse_output.gated_data
gate_contour = ellipse_output.contour
```
Tokens:
Raw