AMS-BP 0.3.1__tar.gz → 0.4.0__tar.gz

{ams_bp-0.3.1 → ams_bp-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AMS_BP
-Version: 0.3.1
+Version: 0.4.0
 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
@@ -11,12 +11,16 @@ Keywords: SMS
 Requires-Python: >=3.12
 Requires-Dist: boundedfbm>=0.4.0
 Requires-Dist: jsonschema>=4.23.0
+Requires-Dist: napari[all]>=0.5.6
 Requires-Dist: numpy>=1.21.2
 Requires-Dist: pydantic>=2.9.2
+Requires-Dist: pyqt6>=6.9.0
 Requires-Dist: pyvista>=0.44.2
 Requires-Dist: scikit-image>=0.18.3
 Requires-Dist: scipy>=1.7.1
+Requires-Dist: tifffile>=2024.12.12
 Requires-Dist: tomli>=2.0.2
+Requires-Dist: tomlkit>=0.13.2
 Requires-Dist: typer>=0.12.5
 Description-Content-Type: text/markdown
 
@@ -50,6 +54,7 @@ Find detailed API references for the library at: [joemans3/github.io/AMS_BP](htt
 ## Table of Contents
 - [Installation](#installation)
 - [Command Line Interface](#command-line-interface)
+- [GUI](#gui)
 - [Configuration File](#configuration-file)
 - [Running Experiments](#running-experiments)
 - [Advanced Usage](#advanced-usage)
@@ -90,6 +95,9 @@ run_AMS_BP config [OPTIONS]
 
 # Run a simulation using a configuration file
 run_AMS_BP runsim CONFIG_FILE
+
+#start the GUI
+run_AMS_BP gui
 ```
 
 ### Config Command Options
@@ -97,6 +105,40 @@ run_AMS_BP runsim CONFIG_FILE
 - `-o, --output_path PATH`: Specify the output directory for the configuration file
 - `-r, --recursive_o`: Create output directory if it doesn't exist
 
+## GUI
+In addition to the CLI and programmatic API, AMS-BP comes with a graphical interface to guide users through the configuration, simulation, and analysis pipeline.
+
+### Main GUI Features
+The GUI provides the following tools from a single interface:
+
+**Create Configuration File** — Launches the visual configuration builder
+**Run Simulation from Config** — Select a .toml file and run the simulation with logging and progress tracking
+**Visualize Microscopy Data (Napari)** — Open TIFF, PNG, ND2, or Zarr image files and view with the Napari viewer
+**Package Logs for Sharing** — Package run directories (e.g., run_2024_04_20_001) into a .zip file for archival or collaboration
+
+### Launch the GUI
+To start the GUI, run:
+
+```bash
+
+run_AMS_BP gui
+```
+#### Configuration Builder
+Clicking "Create Configuration File" opens a template selector where you can choose a preconfigured simulation (with preview images), and then visually edit all configuration options through dedicated tabs.
+
+Each section of the configuration is editable via structured UI forms, with contextual help and validation. Tabs include:
+
+- Global/Cell/Molecule/Condensate/Fluorophore parameters
+- Laser and optical configuration
+- Camera and channel settings
+- Experiment setup (e.g., z-stack vs time-series)
+Once ready, click "Preview Configuration TOML" to inspect the final file, and "Save" to export.
+
+#### Running Simulations from GUI
+Clicking "Run Simulation from Config" lets you select any .toml configuration file. A real-time log viewer shows progress, and outputs are saved in a structured AMS_runs/run_*/ directory.
+
+#### Sharing Logs
+Run into an issue? Use the packge logs button to select the logs corresponding to the simulation you just ran, save them and send them over to us! It will help you diagnose the issue!
 
 ## Configuration File
 
@@ -175,32 +217,6 @@ run_AMS_BP config
 run_AMS_BP runsim sim_config.toml
 ```
 4. View the results in the newly created folder, whose name is defined in the config file.
-## Advanced Usage
-
-### Using AMS-BP as a Library
-
-For programmatic control, you can import and use AMS-BP as a Python library:
-
-```python
-from AMS_BP.configio.convertconfig import ConfigLoader
-
-# Configuration loader intialization
-config_loader = ConfigLoader(config_path="path/to/config.toml")
-
-# Setup microscope
-setup_config = config_loader.setup_microscope()
-microscope = setup_config["microscope"]
-config_exp = setup_config["experiment_config"]
-function_exp = setup_config["experiment_func"]
-
-# Run simulation
-frames, metadata = function_exp(microscope=microscope, config=config_exp)
-
-# Save results
-from AMS_BP.configio.saving import save_config_frames
-save_config_frames(metadata, frames, setup_config["base_config"].OutputParameters)
-```
-> **_NOTE:_** Please note that this application DOES NOT currently model the process of stimulated emission, and as such is not suitable for simulating stimulated emission microscopy ([STED](https://en.wikipedia.org/wiki/STED_microscopy))-type experiments. Work in this area is ongoing.
 
 ## High Priority Features
 ~~1. Irregular cell shapes with motion models~~ (supported with release of v0.2.0)
@@ -208,3 +224,6 @@ save_config_frames(metadata, frames, setup_config["base_config"].OutputParameter
 3. STORM workflow examples
 4. CTRW motion models
 5. Simpler configurations
+> **_NOTE:_** Please note that this application DOES NOT currently model the process of stimulated emission, and as such is not suitable for simulating stimulated emission microscopy ([STED](https://en.wikipedia.org/wiki/STED_microscopy))-type experiments. Work in this area is ongoing.
+
+

{ams_bp-0.3.1 → ams_bp-0.4.0}/README.md

@@ -28,6 +28,7 @@ Find detailed API references for the library at: [joemans3/github.io/AMS_BP](htt
 ## Table of Contents
 - [Installation](#installation)
 - [Command Line Interface](#command-line-interface)
+- [GUI](#gui)
 - [Configuration File](#configuration-file)
 - [Running Experiments](#running-experiments)
 - [Advanced Usage](#advanced-usage)
@@ -68,6 +69,9 @@ run_AMS_BP config [OPTIONS]
 
 # Run a simulation using a configuration file
 run_AMS_BP runsim CONFIG_FILE
+
+#start the GUI
+run_AMS_BP gui
 ```
 
 ### Config Command Options
@@ -75,6 +79,40 @@ run_AMS_BP runsim CONFIG_FILE
 - `-o, --output_path PATH`: Specify the output directory for the configuration file
 - `-r, --recursive_o`: Create output directory if it doesn't exist
 
+## GUI
+In addition to the CLI and programmatic API, AMS-BP comes with a graphical interface to guide users through the configuration, simulation, and analysis pipeline.
+
+### Main GUI Features
+The GUI provides the following tools from a single interface:
+
+**Create Configuration File** — Launches the visual configuration builder
+**Run Simulation from Config** — Select a .toml file and run the simulation with logging and progress tracking
+**Visualize Microscopy Data (Napari)** — Open TIFF, PNG, ND2, or Zarr image files and view with the Napari viewer
+**Package Logs for Sharing** — Package run directories (e.g., run_2024_04_20_001) into a .zip file for archival or collaboration
+
+### Launch the GUI
+To start the GUI, run:
+
+```bash
+
+run_AMS_BP gui
+```
+#### Configuration Builder
+Clicking "Create Configuration File" opens a template selector where you can choose a preconfigured simulation (with preview images), and then visually edit all configuration options through dedicated tabs.
+
+Each section of the configuration is editable via structured UI forms, with contextual help and validation. Tabs include:
+
+- Global/Cell/Molecule/Condensate/Fluorophore parameters
+- Laser and optical configuration
+- Camera and channel settings
+- Experiment setup (e.g., z-stack vs time-series)
+Once ready, click "Preview Configuration TOML" to inspect the final file, and "Save" to export.
+
+#### Running Simulations from GUI
+Clicking "Run Simulation from Config" lets you select any .toml configuration file. A real-time log viewer shows progress, and outputs are saved in a structured AMS_runs/run_*/ directory.
+
+#### Sharing Logs
+Run into an issue? Use the packge logs button to select the logs corresponding to the simulation you just ran, save them and send them over to us! It will help you diagnose the issue!
 
 ## Configuration File
 
@@ -153,32 +191,6 @@ run_AMS_BP config
 run_AMS_BP runsim sim_config.toml
 ```
 4. View the results in the newly created folder, whose name is defined in the config file.
-## Advanced Usage
-
-### Using AMS-BP as a Library
-
-For programmatic control, you can import and use AMS-BP as a Python library:
-
-```python
-from AMS_BP.configio.convertconfig import ConfigLoader
-
-# Configuration loader intialization
-config_loader = ConfigLoader(config_path="path/to/config.toml")
-
-# Setup microscope
-setup_config = config_loader.setup_microscope()
-microscope = setup_config["microscope"]
-config_exp = setup_config["experiment_config"]
-function_exp = setup_config["experiment_func"]
-
-# Run simulation
-frames, metadata = function_exp(microscope=microscope, config=config_exp)
-
-# Save results
-from AMS_BP.configio.saving import save_config_frames
-save_config_frames(metadata, frames, setup_config["base_config"].OutputParameters)
-```
-> **_NOTE:_** Please note that this application DOES NOT currently model the process of stimulated emission, and as such is not suitable for simulating stimulated emission microscopy ([STED](https://en.wikipedia.org/wiki/STED_microscopy))-type experiments. Work in this area is ongoing.
 
 ## High Priority Features
 ~~1. Irregular cell shapes with motion models~~ (supported with release of v0.2.0)
@@ -186,3 +198,6 @@ save_config_frames(metadata, frames, setup_config["base_config"].OutputParameter
 3. STORM workflow examples
 4. CTRW motion models
 5. Simpler configurations
+> **_NOTE:_** Please note that this application DOES NOT currently model the process of stimulated emission, and as such is not suitable for simulating stimulated emission microscopy ([STED](https://en.wikipedia.org/wiki/STED_microscopy))-type experiments. Work in this area is ongoing.
+
+

ams_bp-0.4.0/docs/API_Documentation/configio/convertconfig.md

@@ -0,0 +1,193 @@
+# Virtual Microscope Configuration Parser Documentation
+
+## Overview
+
+This module provides functionality to parse TOML configuration files and set up a virtual microscope simulation environment. It handles all aspects of configuration including global parameters, cell parameters, molecule parameters, condensate parameters, fluorophores, PSF (Point Spread Function), lasers, filters, channels, detectors, and experimental settings.
+
+## Key Components
+
+### Configuration Loading
+
+```python
+load_config(config_path: Union[str, Path]) -> Dict[str, Any]
+```
+
+Loads and parses a TOML configuration file from the specified path.
+
+### Data Model Schema Population
+
+```python
+populate_dataclass_schema(config: Dict[str, Any]) -> Tuple[GlobalParameters, CellParameters, MoleculeParameters, CondensateParameters, OutputParameters]
+```
+
+Populates Pydantic schema models from configuration data, returning structured parameter objects.
+
+### Experiment Configuration
+
+```python
+create_experiment_from_config(config: Dict[str, Any]) -> Tuple[BaseExpConfig, Callable]
+```
+
+Creates an experiment configuration and associated callable function based on the experiment type (time-series or z-stack).
+
+### Fluorophore Configuration
+
+```python
+create_fluorophores_from_config(config: Dict[str, Any]) -> List[Fluorophore]
+```
+
+Creates a list of fluorophore objects from configuration data, including states and transitions.
+
+### PSF (Point Spread Function) Configuration
+
+```python
+create_psf_from_config(config: Dict[str, Any]) -> Tuple[Callable, Dict[str, Any]]
+```
+
+Creates a PSF engine function and additional configuration from the config data.
+
+### Laser Configuration
+
+```python
+create_lasers_from_config(config: Dict[str, Any]) -> Dict[str, LaserProfile]
+```
+
+Creates laser profile instances (Gaussian, Widefield, HiLo) from configuration data.
+
+### Filter Configuration
+
+```python
+create_filter_set_from_config(config: Dict[str, Any]) -> FilterSet
+```
+
+Creates a filter set (excitation, emission, dichroic) from configuration data.
+
+### Channel Configuration
+
+```python
+create_channels(config: Dict[str, Any]) -> Channels
+```
+
+Creates channel objects from configuration data.
+
+### Detector Configuration
+
+```python
+create_detector_from_config(config: Dict[str, Any]) -> Tuple[Detector, QuantumEfficiency]
+```
+
+Creates a detector instance (CMOS or EMCCD) and quantum efficiency from configuration data.
+
+### Cell Creation
+
+```python
+create_cell_from_params(cell_params) -> BaseCell
+```
+
+Creates a cell object based on cell parameters.
+
+### Sample Plane Creation
+
+```python
+create_sample_plane(global_params: GlobalParameters, cell: BaseCell) -> SamplePlane
+```
+
+Creates a sample plane object based on global parameters and cell information.
+
+### Condensate Configuration
+
+```python
+create_condensates_dict(condensate_params: CondensateParameters, cell: BaseCell) -> List[dict]
+```
+
+Creates a list of condensate dictionaries based on condensate parameters.
+
+### Sampling Function Creation
+
+```python
+create_sampling_functions(condensate_params, cell) -> List[Callable]
+```
+
+Creates sampling functions for initial molecule positions.
+
+### Molecule Position Generation
+
+```python
+generate_initial_positions(molecule_params: MoleculeParameters, cell: BaseCell, condensate_params: CondensateParameters, sampling_functions: List[Callable]) -> List
+```
+
+Generates initial positions for molecules.
+
+### Track Generation
+
+```python
+create_track_generator(global_params: GlobalParameters, cell: BaseCell) -> Track_generator
+```
+
+Creates a track generator object for molecule motion.
+
+```python
+get_tracks(molecule_params: MoleculeParameters, global_params: GlobalParameters, initial_positions: List, track_generator: Track_generator) -> Tuple[List, List]
+```
+
+Generates tracks for molecules based on parameters.
+
+### Sample Creation
+
+```python
+add_tracks_to_sample(tracks: List, sample_plane: SamplePlane, fluorophore: List[Fluorophore], ID_counter=0) -> SamplePlane
+```
+
+Adds tracks to the sample plane.
+
+### Microscope Setup
+
+```python
+setup_microscope(config: Dict[str, Any]) -> dict
+```
+
+The main function that orchestrates the entire setup process and returns a dictionary containing all created components including:
+- Virtual microscope instance
+- Base configuration
+- PSF engine and configuration
+- Channels
+- Lasers
+- Sample plane
+- Tracks
+- Points per time
+- Condensate dictionary
+- Cell
+- Experiment configuration
+- Experiment function
+
+## Usage
+
+To use this module, create a TOML configuration file with all necessary parameters and call the `setup_microscope` function:
+
+```python
+config = load_config("path/to/config.toml")
+microscope_setup = setup_microscope(config)
+
+# Access the virtual microscope instance
+vm = microscope_setup["microscope"]
+
+# Run an experiment
+experiment_func = microscope_setup["experiment_func"]
+experiment_config = microscope_setup["experiment_config"]
+results = experiment_func(vm, experiment_config)
+```
+
+## Configuration Structure
+
+The TOML configuration file should contain the following sections:
+- Global_Parameters: General simulation parameters
+- Cell_Parameters: Cell-specific parameters
+- Molecule_Parameters: Molecule-specific parameters
+- Condensate_Parameters: Condensate-specific parameters
+- Output_Parameters: Output and saving parameters
+- experiment: Experiment-specific parameters
+- fluorophores: Fluorophore definitions
+- psf: PSF configuration
+- lasers: Laser configurations
+- channels: Channel configurations
+- camera: Camera and detector configurations

ams_bp-0.4.0/docs/API_Documentation/main_cli.md

@@ -0,0 +1,184 @@
+# AMS_BP CLI API Reference
+
+## Module: `main_cli.py`
+
+This module provides the command-line interface for the AMS_BP package.
+
+### Dependencies
+
+```python
+import shutil
+import sys
+from pathlib import Path
+from typing import Optional
+
+import rich
+import typer
+from PyQt6.QtWidgets import QApplication
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from typing_extensions import Annotated
+
+from . import __version__
+from .gui.main import MainWindow
+from .run_sim_util import run_simulation_from_file
+```
+
+## Main Application Object
+
+### `typer_app_asms_bp`
+
+The main Typer application instance that defines the CLI.
+
+```python
+typer_app_asms_bp = typer.Typer(
+    name="AMS_BP CLI Tool",
+    help=cli_help_doc,
+    short_help="CLI tool for AMS_BP.",
+    rich_markup_mode="rich",
+    pretty_exceptions_show_locals=False,
+    add_completion=False,
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+```
+
+## Functions
+
+### `cell_simulation()`
+
+**Description:**  
+Callback function that displays version information when the CLI is invoked without a specific command.
+
+**Usage:**  
+Automatically called when running the CLI without commands.
+
+**Returns:**  
+None
+
+**Example:**
+```bash
+python -m main_cli
+```
+
+---
+
+### `run_gui() -> None`
+
+**Description:**  
+Starts the PyQt GUI for the AMS_BP application.
+
+**Parameters:**  
+None
+
+**Returns:**  
+None
+
+**Example:**
+```bash
+python -m main_cli gui
+```
+
+---
+
+### `generate_config(output_path: Path = Path("."), output_path_make_recursive: Optional[bool] = None) -> None`
+
+**Description:**  
+Generates a sample configuration file for the cell simulation.
+
+**Parameters:**
+- `output_path`: Path where the configuration file will be saved.
+  - Type: `Path`
+  - Default: Current directory (`Path(".")`)
+  - CLI Option: `--output_path, -o`
+  
+- `output_path_make_recursive`: Whether to create the output directory if it doesn't exist.
+  - Type: `Optional[bool]`
+  - Default: `None`
+  - CLI Option: `--recursive_o, -r`
+
+**Returns:**  
+None
+
+**Raises:**
+- `typer.Abort`: If there's an error creating the configuration file or the output directory.
+
+**Example:**
+```bash
+python -m main_cli config --output_path /path/to/directory --recursive_o
+```
+
+---
+
+### `run_cell_simulation(config_file: Path) -> None`
+
+**Description:**  
+Runs the cell simulation using the provided configuration file.
+
+**Parameters:**
+- `config_file`: Path to the configuration file.
+  - Type: `Path`
+  - Required: Yes
+  - CLI Argument: First positional argument
+
+**Returns:**  
+None
+
+**Example:**
+```bash
+python -m main_cli runsim path/to/config.toml
+```
+
+---
+
+### `validate_config(config: dict) -> None`
+
+**Description:**  
+Validates that the configuration dictionary has the required structure.
+
+**Parameters:**
+- `config`: Configuration dictionary to validate.
+  - Type: `dict`
+  - Required: Yes
+
+**Returns:**  
+None
+
+**Raises:**
+- `typer.Abort`: If the configuration doesn't have the required structure.
+
+**Internal Details:**  
+- Checks for the presence of an `Output_Parameters` section
+- Checks for the presence of an `output_path` field within the `Output_Parameters` section
+
+---
+
+## CLI Commands
+
+| Command | Description | Arguments | Options |
+|---------|-------------|-----------|---------|
+| `config` | Generate sample configuration file | - | `--output_path, -o`: Output directory<br>`--recursive_o, -r`: Create directories if they don't exist |
+| `runsim` | Run cell simulation | `CONFIG_FILE`: Path to config file | - |
+| `gui` | Start the PyQt GUI | - | - |
+
+## Import and Use in Other Code
+
+To use this CLI as a module in other Python code:
+
+```python
+from ams_bp.main_cli import typer_app_asms_bp, generate_config, run_cell_simulation, run_gui
+
+# Generate a config file
+generate_config(Path("/path/to/output"), True)
+
+# Run a simulation
+run_cell_simulation(Path("/path/to/config.toml"))
+
+# Run the GUI
+run_gui()
+```
+
+## Related Files
+
+- `run_sim_util.py`: Contains the `run_simulation_from_file()` function used by the `runsim` command
+- `gui/main.py`: Contains the `MainWindow` class used by the `gui` command
+- `sim_config.toml`: Template configuration file that gets copied when using the `config` command

{ams_bp-0.3.1 → ams_bp-0.4.0}/docs/API_Documentation/sim_config.md

@@ -408,7 +408,7 @@ Each channel has its own filter set with the following parameters:
 - **Description**: The type of experiment.
 
 ### `z_position`
-- **Type**: Array of Numbers
+- **Type**: Array of Numbers, or Number ( if "z-stack" or "time-series")
 - **Description**: The z-positions for the experiment.
 
 ### `laser_names_active`