FlowCyPy 0.5.2__tar.gz → 0.5.3__tar.gz

{flowcypy-0.5.2 → flowcypy-0.5.3}/FlowCyPy/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.5.2'
-__version_tuple__ = version_tuple = (0, 5, 2)
+__version__ = version = '0.5.3'
+__version_tuple__ = version_tuple = (0, 5, 3)

{flowcypy-0.5.2 → flowcypy-0.5.3}/FlowCyPy/distribution/base_class.py

@@ -4,6 +4,12 @@ import matplotlib.pyplot as plt
 from MPSPlots.styles import mps
 from FlowCyPy.units import particle, Quantity
 
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
 
 class Base:
     """

{flowcypy-0.5.2 → flowcypy-0.5.3}/FlowCyPy/distribution/delta.py

@@ -1,17 +1,10 @@
 
-from FlowCyPy.distribution.base_class import Base
+from FlowCyPy.distribution.base_class import Base, config_dict
 import numpy as np
 from typing import Tuple
 from PyMieSim.units import Quantity
 from pydantic.dataclasses import dataclass
 
-config_dict = dict(
-    arbitrary_types_allowed=True,
-    kw_only=True,
-    slots=True,
-    extra='forbid'
-)
-
 
 @dataclass(config=config_dict)
 class Delta(Base):

{flowcypy-0.5.2 → flowcypy-0.5.3}/FlowCyPy/distribution/lognormal.py

@@ -1,17 +1,10 @@
-from FlowCyPy.distribution.base_class import Base
+from FlowCyPy.distribution.base_class import Base, config_dict
 import numpy as np
 from typing import Tuple
 from scipy.stats import lognorm
 from PyMieSim.units import Quantity
 from pydantic.dataclasses import dataclass
 
-config_dict = dict(
-    arbitrary_types_allowed=True,
-    kw_only=True,
-    slots=True,
-    extra='forbid'
-)
-
 
 @dataclass(config=config_dict)
 class LogNormal(Base):

{flowcypy-0.5.2 → flowcypy-0.5.3}/FlowCyPy/distribution/normal.py

@@ -1,17 +1,10 @@
-from FlowCyPy.distribution.base_class import Base
+from FlowCyPy.distribution.base_class import Base, config_dict
 import numpy as np
 from typing import Tuple
 from scipy.stats import norm
 from PyMieSim.units import Quantity
 from pydantic.dataclasses import dataclass
 
-config_dict = dict(
-    arbitrary_types_allowed=True,
-    kw_only=True,
-    slots=True,
-    extra='forbid'
-)
-
 
 @dataclass(config=config_dict)
 class Normal(Base):

{flowcypy-0.5.2 → flowcypy-0.5.3}/FlowCyPy/distribution/particle_size_distribution.py

@@ -1,16 +1,9 @@
-from FlowCyPy.distribution.base_class import Base
+from FlowCyPy.distribution.base_class import Base, config_dict
 import numpy as np
 from typing import Tuple
 from PyMieSim.units import Quantity
 from pydantic.dataclasses import dataclass
 
-config_dict = dict(
-    arbitrary_types_allowed=True,
-    kw_only=True,
-    slots=True,
-    extra='forbid'
-)
-
 
 @dataclass(config=config_dict)
 class RosinRammler(Base):

{flowcypy-0.5.2 → flowcypy-0.5.3}/FlowCyPy/distribution/uniform.py

@@ -1,18 +1,10 @@
-from FlowCyPy.distribution.base_class import Base
+from FlowCyPy.distribution.base_class import Base, config_dict
 import numpy as np
 from typing import Tuple
 from scipy.stats import uniform
 from PyMieSim.units import Quantity
 from pydantic.dataclasses import dataclass
 
-config_dict = dict(
-    arbitrary_types_allowed=True,
-    kw_only=True,
-    slots=True,
-    extra='forbid'
-)
-
-
 @dataclass(config=config_dict)
 class Uniform(Base):
     r"""

{flowcypy-0.5.2 → flowcypy-0.5.3}/FlowCyPy/distribution/weibull.py

@@ -1,18 +1,10 @@
+from FlowCyPy.distribution.base_class import Base, config_dict
 import numpy as np
 from typing import Tuple
 from PyMieSim.units import Quantity
-from FlowCyPy.distribution.base_class import Base
 from pydantic.dataclasses import dataclass
 
 
-config_dict = dict(
-    arbitrary_types_allowed=True,
-    kw_only=True,
-    slots=True,
-    extra='forbid'
-)
-
-
 @dataclass(config=config_dict)
 class Weibull(Base):
     r"""
@@ -78,3 +70,6 @@ class Weibull(Base):
         pdf = a * b ** (self.shape - 1) * c
 
         return x, self.scale_factor * pdf
+
+    def __repr__(self) -> str:
+        return f"Weibull({self.scale:.2f~P}, {self.shape:.2f~P})"

{flowcypy-0.5.2 → flowcypy-0.5.3}/FlowCyPy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: FlowCyPy
-Version: 0.5.2
+Version: 0.5.3
 Summary: A package for flow-cytometry simulations.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License
@@ -60,7 +60,7 @@ Requires-Dist: numpydoc==1.8.0; extra == "documentation"
 Requires-Dist: sphinx>=5.1.1; extra == "documentation"
 Requires-Dist: sphinx-rtd-theme==3.0.2; extra == "documentation"
 Requires-Dist: sphinx-gallery==0.18.0; extra == "documentation"
-Requires-Dist: pydata-sphinx-theme==0.16.0; extra == "documentation"
+Requires-Dist: pydata-sphinx-theme==0.16.1; extra == "documentation"
 Provides-Extra: dev
 Requires-Dist: flake8==7.1.1; extra == "dev"
 

{flowcypy-0.5.2 → flowcypy-0.5.3}/FlowCyPy.egg-info/SOURCES.txt

@@ -57,6 +57,7 @@ FlowCyPy/peak_locator/base_class.py
 FlowCyPy/peak_locator/basic.py
 FlowCyPy/peak_locator/derivative.py
 FlowCyPy/peak_locator/moving_average.py
+developments/create_images.py
 developments/dev_beads_analysis.py
 developments/dev_canto.py
 developments/dev_classifier.py
@@ -93,6 +94,12 @@ docs/images/example_2.png
 docs/images/example_3.png
 docs/images/flow_cytometer.png
 docs/images/logo.png
+docs/images/distributions/Delta.png
+docs/images/distributions/LogNormal.png
+docs/images/distributions/Normal.png
+docs/images/distributions/RosinRammler.png
+docs/images/distributions/Uniform.png
+docs/images/distributions/Weibull.png
 docs/source/code.rst
 docs/source/conf.py
 docs/source/examples.rst
@@ -103,9 +110,15 @@ docs/source/theory.rst
 docs/source/_static/default.css
 docs/source/_static/logo.png
 docs/source/_static/thumbnail.png
+docs/source/code/analysis.rst
 docs/source/code/base.rst
+docs/source/code/detector.rst
 docs/source/code/distributions.rst
+docs/source/code/flow_cell.rst
+docs/source/code/flow_cytometer.rst
 docs/source/code/peak_locator.rst
+docs/source/code/scatterer.rst
+docs/source/code/source.rst
 docs/source/internal/core_components.rst
 docs/source/internal/getting_started.rst
 docs/source/internal/ressources.rst

{flowcypy-0.5.2 → flowcypy-0.5.3}/FlowCyPy.egg-info/requires.txt

@@ -18,7 +18,7 @@ numpydoc==1.8.0
 sphinx>=5.1.1
 sphinx-rtd-theme==3.0.2
 sphinx-gallery==0.18.0
-pydata-sphinx-theme==0.16.0
+pydata-sphinx-theme==0.16.1
 
 [testing]
 pytest>=0.6

{flowcypy-0.5.2 → flowcypy-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: FlowCyPy
-Version: 0.5.2
+Version: 0.5.3
 Summary: A package for flow-cytometry simulations.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License
@@ -60,7 +60,7 @@ Requires-Dist: numpydoc==1.8.0; extra == "documentation"
 Requires-Dist: sphinx>=5.1.1; extra == "documentation"
 Requires-Dist: sphinx-rtd-theme==3.0.2; extra == "documentation"
 Requires-Dist: sphinx-gallery==0.18.0; extra == "documentation"
-Requires-Dist: pydata-sphinx-theme==0.16.0; extra == "documentation"
+Requires-Dist: pydata-sphinx-theme==0.16.1; extra == "documentation"
 Provides-Extra: dev
 Requires-Dist: flake8==7.1.1; extra == "dev"
 

flowcypy-0.5.3/developments/create_images.py

@@ -0,0 +1,42 @@
+import numpy as np
+import matplotlib.pyplot as plt
+from FlowCyPy import distribution
+from FlowCyPy.units import nanometer, particle
+from pathlib import Path
+import FlowCyPy
+
+
+
+save_path = Path(FlowCyPy.__file__).parent.parent / "docs/images/distributions"
+
+
+# Set random seed for reproducibility
+np.random.seed(3)
+
+# Define the number of particles to generate
+n_particles = 10000 * particle
+
+
+# 1. Normal Distribution
+distributions = [
+    distribution.Normal(mean=100 * nanometer, std_dev=10 * nanometer),
+    distribution.LogNormal(mean=100 * nanometer, std_dev=0.25 * nanometer),
+    distribution.RosinRammler(characteristic_size=50 * nanometer, spread=2.0),
+    distribution.Weibull(scale=100 * nanometer, shape=1.5 * nanometer),
+    distribution.Delta(position=100 * nanometer),
+    distribution.Uniform(lower_bound=50 * nanometer, upper_bound=150 * nanometer)
+]
+
+
+for dist in distributions:
+    name = type(dist).__name__
+    sizes = dist.generate(n_particles)
+    figure, ax = plt.subplots(1, 1, figsize=(8, 4))
+    ax.hist(sizes, bins=50, color='skyblue', edgecolor='black')
+    ax.set_title(f'{repr(dist)} Distribution')
+    ax.set_xlabel('Size (nm)')
+    ax.set_ylabel('Frequency')
+    plt.tight_layout()
+    file_directory = save_path / f'{name}.png'
+    plt.savefig(file_directory)
+    # plt.show()

flowcypy-0.5.3/docs/source/code/analysis.rst

@@ -0,0 +1,10 @@
+.. _analysis-tools:
+
+Analysis Tools
+--------------
+Classes for processing and analyzing data from flow cytometry experiments.
+
+
+.. autoclass:: FlowCyPy.event_correlator.EventCorrelator
+   :members:
+   :show-inheritance:

flowcypy-0.5.3/docs/source/code/base.rst

@@ -0,0 +1,18 @@
+Classes and Methods
+===================
+
+This section documents the main classes and methods available in the **FlowCyPy** library, grouped by functionality.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   ./flow_cell.rst
+   ./source.rst
+   ./scatterer.rst
+   ./detector.rst
+   ./flow_cytometer.rst
+   ./analysis.rst
+
+
+

flowcypy-0.5.3/docs/source/code/detector.rst

@@ -0,0 +1,11 @@
+.. _detectors:
+
+Detectors
+---------
+
+Classes for modeling the signal detection process in flow cytometry.
+
+.. autoclass:: FlowCyPy.detector.Detector
+   :members:
+   :show-inheritance:
+   :exclude-members: resistance, responsitivity, sampling, sampling_freq, saturation_level, temperature, n_bins, name, noise_level, numerical_aperture, phi_angle, dark_current, gamma_angle

{flowcypy-0.5.2 → flowcypy-0.5.3}/docs/source/code/distributions.rst

@@ -13,15 +13,25 @@ Normal Distribution
 
 The `Normal` class generates particle sizes that follow a **normal (Gaussian) distribution**. This distribution is characterized by a symmetric bell curve, where most particles are concentrated around the mean size, with fewer particles at the extremes.
 
+.. image:: ./../../images/distributions/Normal.png
+   :width: 600
+   :align: center
+
 .. autoclass:: FlowCyPy.distribution.Normal
    :members:
    :show-inheritance:
 
+
+
 LogNormal Distribution
 ----------------------
 
 The `LogNormal` class generates particle sizes based on a **log-normal distribution**. In this case, the logarithm of the particle sizes follows a normal distribution. This type of distribution is often used to model phenomena where the particle sizes are positively skewed, with a long tail towards larger sizes.
 
+.. image:: ./../../images/distributions/LogNormal.png
+   :width: 600
+   :align: center
+
 .. autoclass:: FlowCyPy.distribution.LogNormal
    :members:
    :show-inheritance:
@@ -31,6 +41,10 @@ Rosin-Rammler Distribution
 
 The `RosinRammler` class generates particle sizes using the **Rosin-Rammler distribution**, which is commonly used to describe the size distribution of powders and granular materials. It provides a skewed distribution where most particles are within a specific range, but some larger particles may exist.
 
+.. image:: ./../../images/distributions/RosinRammler.png
+   :width: 600
+   :align: center
+
 .. autoclass:: FlowCyPy.distribution.RosinRammler
    :members:
    :show-inheritance:
@@ -40,6 +54,10 @@ Weibull Distribution
 
 The `Weibull` class generates particle sizes according to the **Weibull distribution**. This distribution is flexible and can model various types of particle size distributions, ranging from light-tailed to heavy-tailed distributions, depending on the shape parameter.
 
+.. image:: ./../../images/distributions/Weibull.png
+   :width: 600
+   :align: center
+
 .. autoclass:: FlowCyPy.distribution.Weibull
    :members:
    :show-inheritance:
@@ -49,6 +67,10 @@ Delta Distribution
 
 The `Delta` class models particle sizes as a **delta function**, where all particles have exactly the same size. This distribution is useful for simulations where all particles are of a fixed size, without any variation.
 
+.. image:: ./../../images/distributions/Delta.png
+   :width: 600
+   :align: center
+
 .. autoclass:: FlowCyPy.distribution.Delta
    :members:
    :show-inheritance:
@@ -58,6 +80,10 @@ Uniform Distribution
 
 The `Uniform` class generates particle sizes that are **evenly distributed** between a specified lower and upper bound. This results in a flat distribution, where all particle sizes within the range are equally likely to occur.
 
+.. image:: ./../../images/distributions/Uniform.png
+   :width: 600
+   :align: center
+
 .. autoclass:: FlowCyPy.distribution.Uniform
    :members:
    :show-inheritance:

flowcypy-0.5.3/docs/source/code/flow_cell.rst

@@ -0,0 +1,9 @@
+
+FlowCell Class
+--------------
+
+.. autoclass:: FlowCyPy.FlowCell
+   :members:
+   :show-inheritance:
+   :exclude-members: flow_speed, flow_area, run_time
+   :undoc-members:

flowcypy-0.5.3/docs/source/code/flow_cytometer.rst

@@ -0,0 +1,9 @@
+.. _cytometry-systems:
+
+FlowCytometer
+-------------
+Classes related to the overall configuration of a flow cytometry system.
+
+.. autoclass:: FlowCyPy.cytometer.FlowCytometer
+   :members:
+   :show-inheritance:

flowcypy-0.5.3/docs/source/code/scatterer.rst

@@ -0,0 +1,15 @@
+.. _scatterers:
+
+Scatterers
+----------
+Classes representing particles and populations within the cytometer.
+
+
+.. autoclass:: FlowCyPy.Scatterer
+   :members:
+   :show-inheritance:
+
+.. autoclass:: FlowCyPy.population.Population
+   :members:
+   :show-inheritance:
+   :exclude-members: name, refractive_index, size

flowcypy-0.5.3/docs/source/code/source.rst

@@ -0,0 +1,15 @@
+.. _laser-sources:
+
+Laser Sources
+-------------
+Classes representing laser beam sources.
+
+.. autoclass:: FlowCyPy.source.GaussianBeam
+   :members:
+   :show-inheritance:
+   :exclude-members: numerical_aperture, optical_power, polarization, wavelength
+
+.. autoclass:: FlowCyPy.source.AstigmaticGaussianBeam
+   :members:
+   :show-inheritance:
+   :exclude-members: numerical_aperture_x, numerical_aperture_y, optical_power, polarization, wavelength

{flowcypy-0.5.2 → flowcypy-0.5.3}/docs/source/conf.py

@@ -14,7 +14,7 @@ from FlowCyPy.directories import doc_css_path
 package_name = "FlowCyPy"
 version = FlowCyPy.__version__
 
-current_dir = Path(".")
+current_dir = Path("../")
 
 sys.path.append(str(current_dir.resolve()))
 

flowcypy-0.5.3/docs/source/internal/core_components.rst

@@ -0,0 +1,95 @@
+Core Components
+===============
+
+**FlowCyPy** provides a modular framework to simulate key elements of a flow cytometry system. Below are its core components, their attributes, and functionalities. For more details, refer to the `API Reference <https://martinpdes.github.io/FlowCyPy/docs/latest/code.html>`_.
+
+Scatterer
+---------
+The **Scatterer** represents particle distributions and their interactions with light.
+
+- **Attributes**:
+
+  - `populations`: List of particle populations, each with size and refractive index distributions.
+  - `medium_refractive_index`: Refractive index of the surrounding medium (e.g., water).
+  - `dataframe`: Contains particle data, including size, refractive index, and time of arrival.
+
+- **Key Features**:
+
+  - Add populations with `add_population(name, size, refractive_index, concentration)`.
+  - Initialize the scatterer using `initialize(flow_cell)`.
+  - Visualize particle distributions with `plot()`.
+
+Source
+------
+The **Source** models the laser used for illumination in flow cytometry.
+
+- **Attributes**:
+
+  - `wavelength`: Wavelength of the laser (e.g., 800 nm).
+  - `optical_power`: Power of the laser beam (e.g., 20 mW).
+  - `numerical_aperture`: Numerical aperture defining the beam's focus.
+
+- **Key Features**:
+
+  - Simulates the laser profile for scattering calculations.
+  - Models coherent light sources using Gaussian beam theory.
+
+Detector
+--------
+The **Detector** emulates the response of flow cytometer detectors.
+
+- **Attributes**:
+
+  - `phi_angle`: Angle of detection relative to the beam (e.g., forward or side scatter).
+  - `responsitivity`: Sensitivity of the detector (e.g., current per unit power).
+  - `saturation_level`: Maximum signal level the detector can handle.
+  - `noise_levels`: Configurable noise types (thermal, shot, dark current).
+  - `dataframe`: Stores raw and processed signal data.
+
+- **Key Features**:
+
+  - Add various noise models using `NoiseSetting`.
+  - Simulate digitization with configurable bit-depth (e.g., 12-bit, 14-bit).
+  - Visualize signal data using `plot()`.
+
+FlowCytometer
+-------------
+The **FlowCytometer** integrates all components to simulate a complete flow cytometry experiment.
+
+- **Attributes**:
+
+  - `scatterer`: The scatterer object defining particle distributions.
+  - `source`: The laser source illuminating particles.
+  - `detectors`: List of detectors for signal acquisition.
+  - `background_power`: Ambient light contribution.
+
+- **Key Features**:
+
+  - Combines the scatterer, source, and detectors for realistic simulations.
+  - Computes Forward Scatter (FSC) and Side Scatter (SSC) signals.
+  - Uses **PyMieSim** for accurate scattering computations.
+
+EventCorrelator
+---------------
+The **EventCorrelator** (previously called Analyzer) provides tools for signal analysis and particle event detection.
+
+- **Attributes**:
+
+  - `cytometer`: The associated FlowCytometer object.
+  - `coincidence_dataframe`: Stores data for coinciding signals across detectors.
+  - `algorithm`: Peak detection algorithm for identifying particle events.
+
+- **Key Features**:
+
+  - Detect peaks in signals using customizable algorithms (e.g., MovingAverage).
+  - Correlate events between detectors to identify coincidences.
+  - Generate 2D density plots of Forward Scatter (FSC) and Side Scatter (SSC) signals.
+
+Example Use Cases
+-----------------
+
+- Simulate a scatterer with two distinct populations to analyze overlapping signals.
+- Configure detectors with high noise to study the effect on signal clarity.
+- Use EventCorrelator to investigate coincidence events in a multi-detector setup.
+
+For further details on classes and methods, visit the `API Reference <https://martinpdes.github.io/FlowCyPy/docs/latest/code.html>`_.

flowcypy-0.5.3/docs/source/internal/prerequisites/programming.rst

@@ -0,0 +1,92 @@
+.. _programming-skills:
+
+**Programming Skills**
+----------------------
+
+A solid grasp of programming concepts and tools is crucial for contributing to the development and validation of **FlowCyPy**.
+Below, we highlight the essential skills and resources to enhance your proficiency.
+
+.. _python-programming:
+
+Python Programming
+~~~~~~~~~~~~~~~~~~
+
+Python is the backbone of **FlowCyPy**. It is essential to understand its key concepts, features, and best practices to effectively contribute to the project.
+
+Key areas of focus include:
+
+- **Object-Oriented Programming (OOP)**:
+
+  - Writing and understanding functions and classes.
+  - Classes in Python should always start with an uppercase letter (e.g., ``class Detector``).
+  - All other objects are fully lowercase (e.g., ``object``, ``function``).
+
+- **Popular Libraries**:
+
+  - ``numpy`` for numerical operations.
+  - ``matplotlib`` for creating visualizations.
+  - ``pandas`` for efficient data manipulation and analysis.
+
+- **Debugging and Troubleshooting**:
+
+  - Use tools like `pdb`, `ipdb`, or IDE-based debuggers (e.g., in VS Code or PyCharm).
+
+Additional Python Essentials
+****************************
+
+- **What is pip?**
+
+  - ``pip`` is the Python package manager used to install, update, and manage libraries in Python projects.
+  - Example: ``pip install numpy``
+
+- **What is conda?**
+
+  - ``conda`` is an environment and package manager that supports Python and other languages.
+  - It is useful for managing dependencies and creating isolated environments.
+  - Example: ``conda create --name flowcypy-env python=3.10``
+
+- **PEP Standards**:
+
+  - Python Enhancement Proposals (PEPs) define Python's design and best practices.
+  - Follow `PEP 8 <https://peps.python.org/pep-0008/>`_ for consistent and clean coding style.
+
+  - Example:
+
+    - Indentations should be 4 spaces.
+    - Use snake_case for variable and method names.
+
+- **Interactive Python**:
+
+  - Use Jupyter notebooks or Python's interactive shell for rapid testing and prototyping.
+
+*Suggested Practice*: Enhance your skills with hands-on exercises available on `CodeChef Practice <https://www.codechef.com/practice>`_.
+
+.. _git-and-version-control:
+
+Git and Version Control
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Version control is essential for collaborative software development. You will use Git to manage the **FlowCyPy** codebase effectively.
+Familiarity with the following Git commands is expected:
+
+- ``git clone``: Clone repositories to your local machine for development.
+- ``git pull``: Fetch and merge changes from the remote repository.
+- ``git commit``: Save changes locally with descriptive commit messages.
+- ``git push``: Upload your changes to the remote repository.
+- ``git branch``: Create and manage branches for new features or experimental changes.
+- ``git merge``: Integrate updates from different branches.
+- ``git stash``: Temporarily save changes without committing them.
+
+Best Practices for Git
+**********************
+
+- Commit frequently with clear and concise commit messages.
+- Always pull the latest changes before starting new work to avoid conflicts.
+- Use branches to isolate different tasks or features.
+
+.. note::
+
+   **Mini Objective**:
+   Try creating a new branch, making a change, committing it, and merging it back into the main branch.
+
+*Recommended Resource*: Master Git workflows through the `Pro Git Book <https://git-scm.com/book/en/v2>`_.

{flowcypy-0.5.2 → flowcypy-0.5.3}/pyproject.toml

@@ -65,7 +65,7 @@ documentation = [
     "sphinx >=5.1.1",
     "sphinx-rtd-theme ==3.0.2",
     "sphinx-gallery ==0.18.0",
-    "pydata-sphinx-theme ==0.16.0",
+    "pydata-sphinx-theme ==0.16.1",
 ]
 
 dev = [