AMS-BP 0.0.21__tar.gz → 0.0.22__tar.gz

{ams_bp-0.0.21 → ams_bp-0.0.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AMS_BP
-Version: 0.0.21
+Version: 0.0.22
 Summary: Advanced Microscopy Simulations developed for the Weber Lab by Baljyot Singh Parmar
 Project-URL: Documentation, https://joemans3.github.io/AMS_BP/
 Project-URL: Source code, https://github.com/joemans3/AMS_BP

{ams_bp-0.0.21 → ams_bp-0.0.22}/docs/API_Documentation/optics/psf/psf_engine.md

@@ -12,14 +12,35 @@ This module provides functionality for generating Point Spread Functions (PSFs)
   - [_calculate_sigma_z](#_calculate_sigma_z)
   - [_generate_grid](#_generate_grid)
   - [calculate_psf_size](#calculate_psf_size)
+  - [_generate_pinhole_mask](#_generate_pinhole_mask)
 
 ---
 
 ## Classes
 
 ### `PSFParameters`
-
-
+#### Description
+This is a frozen dataclass (enum-ish?) with the following parameters / cached properties
+```python
+emission_wavelength: float
+numerical_aperture: float
+pixel_size: float
+z_step: float
+refractive_index: float = 1.0
+pinhole_diameter: Optional[float] = None  # um
+
+@cached_property
+def wavelength_um(self) -> float:
+    """Emission wavelength in micrometers."""
+    return self.emission_wavelength / 1000.0
+@cached_property
+def pinhole_radius(self) -> Optional[float]:
+  """Pinhole radius in micrometers."""
+  return (
+    self.pinhole_diameter / 2.0 if self.pinhole_diameter is not None else None
+  )
+```
+### `PSFEngine`
 #### Methods
 
 - **`__init__`**: Initializes the PSF engine with the given parameters.
@@ -29,6 +50,7 @@ This module provides functionality for generating Point Spread Functions (PSFs)
 - **`_3d_normalization_A`**: Computes the normalization factor for a 3D Gaussian PSF.
 - **`_2d_normalization_A`**: Computes the normalization factor for a 2D Gaussian PSF.
 - **`normalize_psf`**: Normalizes the PSF using different schemes.
+- **`_generate_pinhole_mask`**: Generate a binary mask representing the pinhole's spatial filtering.
 
 ---
 
@@ -105,4 +127,21 @@ Calculates the appropriate PSF size based on physical parameters.
 
 #### Returns
 
-- **`Tuple[int, ...]`**: Tuple of dimensions (z, y, x) or (y, x) for the PSF calculation.
+- **`Tuple[int, ...]`**: Tuple of dimensions (z, y, x) or (y, x) for the PSF calculation.
+
+---
+
+### `_generate_pinhole_mask`
+
+
+#### Description
+
+Generate a binary mask representing the pinhole's spatial filtering.
+
+The pinhole blocks emission light based on position in the image plane,
+affecting what portion of the diffracted light reaches the detector.
+
+#### Parameters
+#### Returns
+
+- **`NDArray[np.float64]`**: Same dimensions as the psf generated but with binary values (0,1) indicating the transmittance of the psf due to the pinhole. Note, if the pinhole size is smaller than 1*airy disk diameter, then diffraction due to the pinhole is NOT non negligiable and diffraction effects will be introduced. A ValueError is thrown if this is the case.   

{ams_bp-0.0.21 → ams_bp-0.0.22}/docs/API_Documentation/sim_config.md

@@ -224,6 +224,7 @@ Each fluorophore has transitions defined with the following parameters:
 - **Properties**:
   - **`numerical_aperture`**: The numerical aperture (typical range: 0.1 - 1.5).
   - **`refractive_index`**: The refractive index (default is air: 1.0).
+  - **`pinhole_diameter`**: None or float. In units of um. None = no pinhole before the detector.
 
 ---
 

{ams_bp-0.0.21 → ams_bp-0.0.22}/src/AMS_BP/__init__.py

@@ -10,4 +10,4 @@ Last updated: 2024-12-16
 
 """
 
-__version__ = "0.0.21"
+__version__ = "0.0.22"

{ams_bp-0.0.21 → ams_bp-0.0.22}/src/AMS_BP/configio/convertconfig.py

@@ -324,11 +324,12 @@ class ConfigLoader:
         ):
             # Create PSFParameters instance
             parameters = PSFParameters(
-                wavelength=wavelength,
+                emission_wavelength=wavelength,
                 numerical_aperture=float(params_config["numerical_aperture"]),
                 pixel_size=pixel_size,
                 z_step=float(params_config["z_step"]) if z_step is None else z_step,
                 refractive_index=float(params_config.get("refractive_index", 1.0)),
+                pinhole_diameter=params_config.get("pinhole_diameter", None),
             )
 
             # Create PSF engine

{ams_bp-0.0.21 → ams_bp-0.0.22}/src/AMS_BP/metadata/metadata.py

@@ -1,4 +1,4 @@
-from typing import Iterator, List, Literal, Union
+from typing import Dict, Iterator, List, Literal, Union
 
 from pydantic import BaseModel
 
@@ -77,7 +77,7 @@ class MetaData(BaseModel):
     PhysicalSizeXUnit: Literal["nm", "m"]
     PhysicalSizeY: float
     PhysicalSizeYUnit: Literal["nm", "m"]
-    # Channel: Dict[Literal["Name"], List[str]]
+    Channel: Dict[Literal["Name"], List[str]]
 
     def __post_init__(self):
         if isinstance(self.notes, (list, str)):

{ams_bp-0.0.21 → ams_bp-0.0.22}/src/AMS_BP/optics/psf/psf_engine.py

@@ -5,52 +5,61 @@ from typing import Literal, Optional, Tuple
 import numpy as np
 from numpy.typing import NDArray
 
+AIRYFACTOR = 1.0
+
 
 @dataclass(frozen=True)
 class PSFParameters:
-    """Parameters for PSF (Point Spread Function) generation.
+    """Parameters for emission PSF (Point Spread Function) at the detector.
+
+
+    This class defines parameters that determine how light from a point source
+    (e.g., a fluorescent molecule) diffracts through the collection optics
+    to form a pattern at the detector.
 
     Attributes:
-        wavelength: Light wavelength in nanometers
-        numerical_aperture: Numerical aperture of the optical system
-        pixel_size: Size of pixels in micrometers
+        emission_wavelength: Emission wavelength in nanometers
+        numerical_aperture: Numerical aperture of the collection objective
+        pixel_size: Size of pixels in micrometers at the detector
         z_step: Axial step size in micrometers
         refractive_index: Refractive index of the medium (default: 1.0 for air)
+        pinhole_diameter: Diameter of the pinhole in micrometers (default: None for widefield)
+                         The pinhole spatially filters the emitted light before it reaches
+                         the detector.
     """
 
-    wavelength: float
+    emission_wavelength: float
     numerical_aperture: float
     pixel_size: float
     z_step: float
     refractive_index: float = 1.0
-
-    # def __post_init__(self) -> None:
-    #     """Validate parameters after initialization."""
-    #     if any(
-    #         param <= 0
-    #         for param in (
-    #             self.wavelength,
-    #             self.numerical_aperture,
-    #             self.pixel_size,
-    #             self.z_step,
-    #             self.refractive_index,
-    #         )
-    #     ):
-    #         raise ValueError("All parameters must be positive numbers")
-    #     if self.numerical_aperture >= self.refractive_index:
-    #         raise ValueError("Numerical aperture must be less than refractive index")
+    pinhole_diameter: Optional[float] = None  # um
 
     @cached_property
     def wavelength_um(self) -> float:
-        """Wavelength in micrometers."""
-        return self.wavelength / 1000.0
+        """Emission wavelength in micrometers."""
+        return self.emission_wavelength / 1000.0
+
+    @cached_property
+    def pinhole_radius(self) -> Optional[float]:
+        """Pinhole radius in micrometers."""
+        return (
+            self.pinhole_diameter / 2.0 if self.pinhole_diameter is not None else None
+        )
 
 
 class PSFEngine:
-    """Engine for generating various microscope Point Spread Functions.
+    """Engine for calculating emission light PSF at the detector.
+
+    This class calculates how light from a point source (like a fluorescent molecule)
+    spreads due to diffraction through the collection optics to form a pattern at
+    the detector. For confocal systems, it can include the effect of a pinhole
+    that spatially filters the light before detection.
 
-    This class implements calculations for both 2D and 3D Point Spread Functions
-    using Gaussian approximations.
+    Note: This PSF describes only the diffraction of emitted light through the
+    collection optics. While a confocal microscope uses focused illumination to
+    excite molecules, that illumination pattern does not affect how the emitted
+    light diffracts to form the PSF we calculate here.
     """
 
     def __init__(self, params: PSFParameters):
@@ -79,34 +88,69 @@ class PSFEngine:
         self._norm_sigma_xy = self._sigma_xy / 2.355
         self._norm_sigma_z = self._sigma_z / 2.355
 
+        # Generate pinhole mask if specified
+        if self.params.pinhole_radius is not None:
+            if self.params.pinhole_radius < AIRYFACTOR * self._sigma_xy:
+                raise ValueError(
+                    f"Pinhole size ({self.params.pinhole_radius} um) is smaller than {AIRYFACTOR} times the Airy lobe. This will diffract the emission light in the pinhole; an ideal pinhole size for this setup is {self._sigma_xy} um."
+                )
+            self._pinhole_mask = self._generate_pinhole_mask()
+        else:
+            self._pinhole_mask = None
+
+    def _generate_pinhole_mask(self) -> NDArray[np.float64]:
+        """Generate a binary mask representing the pinhole's spatial filtering.
+
+        The pinhole blocks emission light based on position in the image plane,
+        affecting what portion of the diffracted light reaches the detector.
+        """
+        x, y = self._grid_xy
+        r = np.sqrt(x**2 + y**2)
+        return (r <= self.params.pinhole_radius).astype(np.float64)
+
     @lru_cache(maxsize=128)
     def psf_z(self, z_val: float) -> NDArray[np.float64]:
-        """Generate z=z_val Gaussian approximation of PSF.
+        """Calculate the PSF at the detector for a point source at z_val.
+
+        This represents how light from a point source at position z_val
+        diffracts through the collection optics to form a pattern at the
+        detector. If a pinhole is present, it spatially filters this pattern.
 
         Args:
-            z_val: Z-position in micrometers
+            z_val: Z-position of the point source in micrometers
 
         Returns:
-            2D array containing the PSF at given z position
+            2D array containing the light intensity pattern at the detector
         """
         x, y = self._grid_xy
 
-        # Vectorized calculation
+        # Calculate how light from the point source diffracts through collection optics
         r_squared = (x / self._norm_sigma_xy) ** 2 + (y / self._norm_sigma_xy) ** 2
         z_term = (z_val / self._norm_sigma_z) ** 2
-        return np.exp(-0.5 * (r_squared + z_term))
+        psf_at_detector = np.exp(-0.5 * (r_squared + z_term))
+
+        if self._pinhole_mask is not None:
+            # Apply pinhole's spatial filtering
+            return psf_at_detector * self._pinhole_mask
+
+        return psf_at_detector
 
     @lru_cache(maxsize=128)
     def psf_z_xy0(self, z_val: float) -> float:
-        """Generate z=z_val Gaussian approximation of PSF with x=y=0.
+        """Calculate the PSF intensity at the center of the detector.
+
+        For a point source at z_val, this gives the intensity of light
+        that reaches the detector center (x=y=0). This point is always
+        within the pinhole if one is present.
 
         Args:
-            z_val: Z-position in micrometers
+            z_val: Z-position of the point source in micrometers
 
         Returns:
-            PSF value at x=y=0 and given z position
+            Light intensity at detector center
         """
-        return np.exp(-0.5 * (z_val / self._norm_sigma_z) ** 2)
+        z_term = (z_val / self._norm_sigma_z) ** 2
+        return np.exp(-0.5 * z_term)
 
     @cache
     def _3d_normalization_A(

{ams_bp-0.0.21 → ams_bp-0.0.22}/src/AMS_BP/run_cell_simulation.py

@@ -1,14 +1,14 @@
 """
 run_cell_simulation.py
 
-This file contains the command-line interface (CLI) for the SMS_BP package, which is used for simulating single molecule localization microscopy experiments.
+This file contains the command-line interface (CLI) for the AMS_BP package.
 
 The CLI is built using Typer and provides two main commands:
 1. 'config': Generates a sample configuration file.
 2. 'runsim': Runs the cell simulation using a provided configuration file.
 
 Main Components:
-- typer_app_sms_bp: The main Typer application object.
+- typer_app_asms_bp: The main Typer application object.
 - cell_simulation(): Callback function that displays the version information.
 - generate_config(): Command to generate a sample configuration file.
 - run_cell_simulation(): Command to run the cell simulation using a configuration file.
@@ -37,7 +37,7 @@ from .configio.saving import save_config_frames
 
 cli_help_doc = str(
     """
-CLI tool to run [underline]A[/underline]dvanced [underline]M[/underline]olecule [underline]S[/underline]imulation: [underline]ASMS[/underline]-BP. GitHub: [green]https://github.com/joemans3/AMS_BP[/green].
+CLI tool to run [underline]A[/underline]dvanced [underline]M[/underline]olecule [underline]S[/underline]imulation: [underline]AMS[/underline]-BP. GitHub: [green]https://github.com/joemans3/AMS_BP[/green].
 [Version: [bold]{0}[/bold]]
 """.format(__version__)
 )

{ams_bp-0.0.21 → ams_bp-0.0.22}/src/AMS_BP/sim_config.toml

@@ -275,6 +275,7 @@ custom_path = ""
 [psf.parameters]
 numerical_aperture = 1.4 # typical range: 0.1 - 1.5
 refractive_index = 1.0   # default is air (1.0)
+#pinhole_diameter = 1.0  # Do not include for no pinhole else float in um units
 
 # Multiple Laser Configuration File
 

{ams_bp-0.0.21 → ams_bp-0.0.22}/src/AMS_BP/sim_microscopy.py

@@ -276,7 +276,7 @@ class VirtualMicroscope:
             PhysicalSizeXUnit="m",
             PhysicalSizeY=self.camera.pixel_size * 1e-6,
             PhysicalSizeYUnit="m",
-            # Channel={"Name": self.channels.names},
+            Channel={"Name": self.channels.names},
         )
 
         # return frames in the format ZCTYX