FlowCyPy 0.5.0__py3-none-any.whl

FlowCyPy/population.py

@@ -0,0 +1,239 @@
+
+import numpy as np
+from typing import Union
+from FlowCyPy import distribution
+import pandas as pd
+from dataclasses import field
+import pint_pandas
+from pydantic.dataclasses import dataclass
+from pydantic import field_validator
+from FlowCyPy.units import particle
+from FlowCyPy.flow_cell import FlowCell
+from FlowCyPy.utils import PropertiesReport
+import logging
+from PyMieSim.units import Quantity, RIU, meter
+import warnings
+from FlowCyPy.particle_count import ParticleCount
+
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+
+@dataclass(config=config_dict)
+class Population(PropertiesReport):
+    """
+    A class representing a population of scatterers in a flow cytometry setup.
+
+    Parameters
+    ----------
+    name : str
+        Name of the population distribution.
+    refractive_index : Union[distribution.Base, Quantity]
+        Refractive index or refractive index distributions.
+    size : Union[distribution.Base, Quantity]
+        Particle size or size distributions.
+    particle_count : ParticleCount
+        Scatterer density in particles per cubic meter, default is 1 particle/m³.
+
+    """
+    name: str
+    refractive_index: Union[distribution.Base, Quantity]
+    size: Union[distribution.Base, Quantity]
+    particle_count: ParticleCount = field(init=False)
+
+    def __post_init__(self):
+        """
+        Automatically converts all Quantity attributes to their base SI units (i.e., without any prefixes).
+        This strips units like millimeter to meter, kilogram to gram, etc.
+        """
+        # Convert all Quantity attributes to base SI units (without any prefixes)
+        for attr_name, attr_value in vars(self).items():
+            if isinstance(attr_value, Quantity):
+                # Convert the quantity to its base unit (strip prefix)
+                setattr(self, attr_name, attr_value.to_base_units())
+
+    @field_validator('concentration')
+    def _validate_concentration(cls, value):
+        """
+        Validates that the concentration is expressed in units of inverse volume.
+
+        Parameters
+        ----------
+        value : Quantity
+            The concentration to validate.
+
+        Returns
+        -------
+        Quantity
+            The validated concentration.
+
+        Raises
+        ------
+            ValueError: If the concentration is not expressed in units of inverse volume.
+        """
+        if not value.check('particles / [length]**3'):
+            raise ValueError(f"concentration must be in units of particles per volume (e.g., particles/m^3), but got {value.units}")
+        return value
+
+    @field_validator('refractive_index')
+    def _validate_refractive_index(cls, value):
+        """
+        Validates that the refractive index is either a Quantity or a valid distribution.Base instance.
+
+        Parameters
+        ----------
+        value : Union[distribution.Base, Quantity]
+            The refractive index to validate.
+
+        Returns
+        -------
+        Union[distribution.Base, Quantity]
+            The validated refractive index.
+
+        Raises
+        ------
+        TypeError
+            If the refractive index is not of type Quantity or distribution.Base.
+        """
+        if isinstance(value, Quantity):
+            assert value.check(RIU), "The refractive index value provided does not have refractive index units [RIU]"
+            return distribution.Delta(position=value)
+
+        if isinstance(value, distribution.Base):
+            return value
+
+        raise TypeError(f"refractive_index must be of type Quantity<RIU or refractive_index_units> or distribution.Base, but got {type(value)}")
+
+    @field_validator('size')
+    def _validate_size(cls, value):
+        """
+        Validates that the size is either a Quantity or a valid distribution.Base instance.
+
+        Parameters
+        ----------
+        value : Union[distribution.Base, Quantity]
+            The size to validate.
+
+        Returns
+        -------
+        Union[distribution.Base, Quantity]
+            The validated size.
+
+        Raises
+        ------
+        TypeError
+            If the size is not of type Quantity or distribution.Base.
+        """
+        if isinstance(value, Quantity):
+            assert value.check(meter), "The size value provided does not have length units [meter]"
+            return distribution.Delta(position=value)
+
+        if isinstance(value, distribution.Base):
+            return value
+
+        raise TypeError(f"suze must be of type Quantity or distribution.Base, but got {type(value)}")
+
+    def initialize(self, flow_cell: FlowCell) -> None:
+        self.dataframe = pd.DataFrame()
+
+        if isinstance(self.size, Quantity):
+            self.size = distribution.Delta(size_value=self.size)
+
+        self.flow_cell = flow_cell
+
+        self.n_events = self.particle_count.calculate_number_of_events(
+            flow_area=self.flow_cell.flow_area,
+            flow_speed=self.flow_cell.flow_speed,
+            run_time=self.flow_cell.run_time
+        )
+
+        self._generate_longitudinal_positions()
+
+        logging.info(f"Population [{self.name}] initialized with an estimated {self.n_events}.")
+
+        size = self.size.generate(self.n_events)
+        self.dataframe['Size'] = pint_pandas.PintArray(size, dtype=size.units)
+
+        ri = self.refractive_index.generate(self.n_events)
+        self.dataframe['RefractiveIndex'] = pint_pandas.PintArray(ri, dtype=ri.units)
+
+    def _generate_longitudinal_positions(self) -> None:
+        r"""
+        Generate particle arrival times over the entire experiment duration based on a Poisson process.
+
+        In flow cytometry, the particle arrival times can be modeled as a Poisson process, where the time
+        intervals between successive particle arrivals follow an exponential distribution. The average rate
+        of particle arrivals (the particle flux) is given by:
+
+        .. math::
+            \text{Particle Flux} = \rho \cdot v \cdot A
+
+        where:
+        - :math:`\rho` is the scatterer density (particles per cubic meter),
+        - :math:`v` is the flow speed (meters per second),
+        - :math:`A` is the cross-sectional area of the flow tube (square meters).
+
+        The number of particles arriving in a given time interval follows a Poisson distribution, and the
+        time between successive arrivals follows an exponential distribution. The mean inter-arrival time
+        is the inverse of the particle flux:
+
+        .. math::
+            \Delta t \sim \text{Exponential}(1/\lambda)
+
+        where:
+            - :math:`\Delta t` is the time between successive particle arrivals,
+            - :math:`\lambda` is the particle flux (particles per second).
+
+        Steps:
+            1. Compute the particle flux, which is the average number of particles passing through the detection
+            region per second.
+            2. Calculate the expected number of particles over the entire experiment duration.
+            3. Generate random inter-arrival times using the exponential distribution.
+            4. Compute the cumulative arrival times by summing the inter-arrival times.
+            5. Ensure that all arrival times fall within the total experiment duration.
+
+        Returns
+        -------
+        np.ndarray
+            An array of particle arrival times (in seconds) for the entire experiment duration, based on the Poisson process.
+        """
+        # Step 1: Compute the average particle flux (particles per second)
+        particle_flux = self.particle_count.compute_particle_flux(
+            flow_speed=self.flow_cell.flow_speed,
+            flow_area=self.flow_cell.flow_area,
+            run_time=self.flow_cell.run_time
+        )
+
+        # Step 2: Calculate the expected number of particles over the entire experiment
+        expected_particles = self.n_events
+
+        # Step 3: Generate inter-arrival times (exponentially distributed)
+        inter_arrival_times = np.random.exponential(
+            scale=1 / particle_flux.magnitude,
+            size=int(expected_particles.magnitude)
+        ) / (particle_flux.units / particle)
+
+        # Step 4: Compute cumulative arrival times
+        arrival_times = np.cumsum(inter_arrival_times)
+
+        # Step 5: Limit the arrival times to the total experiment duration
+        arrival_times = arrival_times[arrival_times <= self.flow_cell.run_time]
+
+        time = arrival_times[arrival_times <= self.flow_cell.run_time]
+        self.dataframe['Time'] = pint_pandas.PintArray(time, dtype=time.units)
+
+        position = arrival_times * self.flow_cell.flow_speed
+
+        self.dataframe['Position'] = pint_pandas.PintArray(position, dtype=position.units)
+
+        self.n_events = len(arrival_times) * particle
+
+        if self.n_events == 0:
+            warnings.warn("Population has been initialized with 0 events.")
+
+from FlowCyPy.populations_instances import *  # noqa F403

FlowCyPy/populations_instances.py

@@ -0,0 +1,49 @@
+from FlowCyPy.units import Quantity, nanometer, RIU, micrometer
+from FlowCyPy.population import Population
+from FlowCyPy import distribution
+
+_populations = (
+    ('Exosome',          70 * nanometer, 2.0, 1.39 * RIU, 0.02 * RIU),
+    ('MicroVesicle',    400 * nanometer, 1.5, 1.39 * RIU, 0.02 * RIU),
+    ('ApoptoticBodies',  2 * micrometer, 1.2, 1.40 * RIU, 0.03 * RIU),
+    ('HDL',              10 * nanometer, 3.5, 1.33 * RIU, 0.01 * RIU),
+    ('LDL',              20 * nanometer, 3.0, 1.35 * RIU, 0.02 * RIU),
+    ('VLDL',             50 * nanometer, 2.0, 1.445 * RIU, 0.0005 * RIU),
+    ('Platelet',       2000 * nanometer, 2.5, 1.38 * RIU, 0.01 * RIU),
+    ('CellularDebris',   3 * micrometer, 1.0, 1.40 * RIU, 0.03 * RIU),
+)
+
+
+for (name, size, size_spread, ri, ri_spread) in _populations:
+    size_distribution = distribution.RosinRammler(
+        characteristic_size=size,
+        spread=size_spread
+    )
+
+    ri_distribution = distribution.Normal(
+        mean=ri,
+        std_dev=ri_spread
+    )
+
+    population = Population(
+        name=name,
+        size=size_distribution,
+        refractive_index=ri_distribution,
+    )
+
+    locals()[name] = population
+
+
+def get_microbeads(size: Quantity, refractive_index: Quantity, name: str) -> Population:
+
+    size_distribution = distribution.Delta(position=size)
+
+    ri_distribution = distribution.Delta(position=refractive_index)
+
+    microbeads = Population(
+        name=name,
+        size=size_distribution,
+        refractive_index=ri_distribution
+    )
+
+    return microbeads

FlowCyPy/report.py

@@ -0,0 +1,236 @@
+from dataclasses import dataclass, field
+from reportlab.lib.pagesizes import A4
+from reportlab.lib import colors
+from reportlab.platypus import SimpleDocTemplate, Table, TableStyle, Frame, PageTemplate, Spacer, Paragraph, Image
+from reportlab.lib.units import inch
+from reportlab.lib.styles import getSampleStyleSheet
+import matplotlib.pyplot as plt
+from pathlib import Path
+import shutil
+
+
+def df2table(df):
+    paragraphs = [[Paragraph(col) for col in df.columns]] + df.values.tolist()
+    style = [
+        ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
+        ('LINEBELOW', (0, 0), (-1, 0), 1, colors.black),
+        ('INNERGRID', (0, 0), (-1, -1), 0.25, colors.black),
+        ('BOX', (0, 0), (-1, -1), 1, colors.black),
+        ('ROWBACKGROUNDS', (0, 0), (-1, -1), [colors.lightgrey, colors.white])
+    ]
+
+    return Table(paragraphs, hAlign='LEFT', style=style)
+
+
+@dataclass
+class Report:
+    flow_cell: object
+    scatterer: object
+    analyzer: object
+    output_filename: str = "flow_report.pdf"
+    title_color: object = field(default=colors.darkblue)
+    header_color: object = field(default=colors.darkgreen)
+    footer_color: object = field(default=colors.gray)
+    str_format: str = field(default='.2~P')
+
+    # Page size constants
+    width: float = field(default=A4[0], init=False)
+    height: float = field(default=A4[1], init=False)
+
+    temporary_folder = Path('./temporary_')
+
+    def add_background(self, canvas, doc):
+        """Adds a background color to every page."""
+        canvas.saveState()
+        canvas.setFillColorRGB(0.95, 0.95, 0.95)  # Light grey background
+        canvas.rect(0, 0, A4[0], A4[1], fill=True, stroke=False)  # Fill the entire page
+        canvas.restoreState()
+        self.add_watermark(canvas, doc)
+
+    def add_footer(self, canvas, doc):
+        """Adds a footer with page number to every page."""
+        canvas.saveState()
+        canvas.setFont("Helvetica-Oblique", 8)
+        canvas.setFillColor(self.footer_color)
+        canvas.drawString(1 * inch, 0.75 * inch, "Flow Cytometry Report")
+        canvas.drawRightString(A4[0] - inch, 0.75 * inch, f"Page {doc.page}")
+        canvas.restoreState()
+
+    def get_header(self):
+        """Returns a Paragraph for the report header."""
+        style = getSampleStyleSheet()['Title']
+        style.textColor = self.title_color
+        return Paragraph("Flow Cytometry Simulation Report", style)
+
+    def get_flow_cell_section(self):
+        """Returns a Paragraph or Table for the FlowCell section."""
+        style = getSampleStyleSheet()['Heading2']
+
+        table_data = [['Attribute', 'Value']]
+        table_data += self.flow_cell.get_properties()
+
+        table = Table(table_data, hAlign='LEFT')
+        table.setStyle(self.get_table_style())
+
+        return Paragraph("Section 1: FlowCell Parameters", style), table
+
+    def get_image_from(self, plot_function: object, figure_size, scale: float = 1, align: str = 'RIGHT') -> Image:
+        # Generate and save plot image for the scatterer distribution
+        plot_filename = self.temporary_folder / f"{id(plot_function)}.png"
+        plot_function(show=False, figure_size=figure_size)
+        plt.savefig(plot_filename)
+        plt.close()
+
+        # Create an image object to include in the PDF
+        image = Image(
+            filename=plot_filename,
+            hAlign=align,
+            height=figure_size[1] * scale * inch,
+            width=figure_size[0] * scale * inch
+        )
+
+        return image
+
+    def get_scatterer_section(self):
+        """Returns a Table for the scatterer distribution section."""
+        style = getSampleStyleSheet()['Heading2']
+
+        df = self.scatterer.populations[0].dataframe.pint.dequantify().reset_index().describe(percentiles=[])
+        df = df[['Time']]
+        print(df)
+
+        table = df2table(df)
+
+        # df = self.scatterer.dataframe#.reset_index()
+        # _report = df.pint.dequantify().describe(percentiles=[])
+        # print(_report)
+        # import pandas as pd
+        # report = pd.DataFrame()
+        # report['Attribute'] = _report['index']
+        # report['Index'] = _report['Index']
+        # report['Time'] = _report['Time']
+        # print(report)
+
+        # table = df2table(report)
+
+        table.setStyle(self.get_table_style())
+
+        self.get_image_from(self.scatterer.plot, figure_size=(8, 8), scale=0.5)
+
+        # combined_table = Table([[table, image]], hAlign='LEFT')
+        combined_table = Table([[table]], hAlign='LEFT')
+
+        combined_table.setStyle(TableStyle([
+            ('VALIGN', (0, 0), (-1, -1), 'TOP'),  # Align both the table and image at the top
+        ]))
+
+        return Paragraph("Section 2: Scatterer populations", style), combined_table
+
+    def get_detector_section(self):
+        """Returns a Table for the detector properties."""
+        style = getSampleStyleSheet()['Heading2']
+        detector_0, detector_1 = self.analyzer.cytometer.detectors
+        properties_0 = detector_0.get_properties()
+        properties_1 = detector_1.get_properties()
+
+        # Create table data
+        table_data = [['Attribute', f'Detector {detector_0.name}', f'Detector {detector_1.name}']]
+        table_data += [[p0[0], p0[1], p1[1]] for p0, p1 in zip(properties_0, properties_1)]
+
+        # Create and return the table
+        table = Table(table_data, hAlign='LEFT')
+        table.setStyle(self.get_table_style())
+
+        image_0 = self.get_image_from(detector_0.plot, align='CENTER', figure_size=(6, 3))
+        image_1 = self.get_image_from(detector_1.plot, align='CENTER', figure_size=(6, 3))
+
+        return Paragraph("Section 3: Detectors parameters", style), table, image_0, image_1
+
+    def get_analyzer_section(self) -> None:
+        """Adds a section displaying analyzer properties."""
+        style = getSampleStyleSheet()['Heading2']
+
+        image = self.get_image_from(self.analyzer.plot_peak, align='CENTER', figure_size=(7, 6), scale=1)
+
+        return Paragraph("Section 4: Peak Analyzer parameters", style), image
+
+    def get_table_style(self) -> TableStyle:
+        """Returns a consistent table style."""
+        return TableStyle([
+            ('BACKGROUND', (0, 0), (-1, 0), colors.grey),
+            ('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke),
+            ('ALIGN', (0, 0), (-1, -1), 'LEFT'),
+            ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
+            ('FONTSIZE', (0, 0), (-1, -1), 10),
+            ('BOTTOMPADDING', (0, 0), (-1, 0), 12),
+            ('BACKGROUND', (0, 1), (-1, -1), colors.beige),
+            ('GRID', (0, 0), (-1, -1), 1, colors.black),
+        ])
+
+    def add_watermark(self, canvas, doc):
+        """Adds a semi-transparent watermark to the current page."""
+        canvas.saveState()
+        canvas.setFont("Helvetica-Bold", 50)
+        canvas.setFillColorRGB(0.9, 0.9, 0.9)  # Light grey color for watermark
+        canvas.setFillAlpha(0.3)  # Transparency level (0.0 fully transparent, 1.0 fully opaque)
+
+        # Position the watermark in the center of the page
+        width, height = A4
+        canvas.translate(width / 2, height / 2)
+        canvas.rotate(45)
+        canvas.drawCentredString(0, 0, "FLOWCYPY REPORT")  # Watermark text
+
+        canvas.restoreState()
+
+    def generate_report(self):
+        """Generates the PDF report, applying a background to every page."""
+        # Use SimpleDocTemplate from Platypus
+
+        if self.temporary_folder.exists():
+            shutil.rmtree(self.temporary_folder)
+
+        self.temporary_folder.mkdir()
+
+        doc = SimpleDocTemplate(
+            self.output_filename,
+            pagesize=A4,
+            showBoundary=1,
+            leftMargin=0.5 * inch,
+            rightMargin=0.5 * inch,
+            topMargin=0.5 * inch,
+            bottomMargin=1.5 * inch
+        )
+
+        spacer = Spacer(1, 0.2 * inch)
+
+        story = [
+            self.get_header(), spacer,
+            *self.get_flow_cell_section(), spacer,
+            *self.get_scatterer_section(), spacer,
+            *self.get_detector_section(), spacer,
+            *self.get_analyzer_section()
+        ]
+
+        # Create a page template with the background and header/footer functions
+        frame = Frame(
+            doc.leftMargin,
+            doc.bottomMargin,
+            doc.width,
+            doc.height,
+            id='normal'
+        )
+
+        template = PageTemplate(
+            id='background',
+            frames=frame,
+            onPage=self.add_background,
+            onPageEnd=self.add_footer,
+        )
+
+        doc.addPageTemplates([template])
+
+        # Build the PDF
+        doc.build(story)
+        print(f"PDF report saved as {self.output_filename}")
+
+        shutil.rmtree(self.temporary_folder)