polish package

Author: mansouralawi

README.md

@@ -188,6 +188,23 @@ After running the complete pipeline, you'll have:
 - **Missing Puncta**: Verify channel names and adjust detection thresholds
 - **Gene Assignment Errors**: Ensure your gene list CSV is properly formatted
 
+## Gene List Configuration
+
+ExSeq-Toolbox requires a `gene_list.csv` file that maps gene symbols to barcodes for RNA identification.
+
+**Required format:**
+```csv
+Symbol,Barcode,Digits
+ACTB,acgtacg,0123012
+GAPDH,tgcatgc,3210321
+MYC,aaaccct,0001113
+```
+
+- **Barcode**: DNA sequence using only `a`, `c`, `g`, `t` 
+- **Digits**: Numerical conversion where `a=0`, `c=1`, `g=2`, `t=3` (based on the channels)
+- **Example file**: [`examples/gene_list_example.csv`](examples/gene_list_example.csv)
+- **Detailed guide**: [`GENE_LIST_FORMAT.md`](GENE_LIST_FORMAT.md)
+
 ## Documentation
 
 Comprehensive documentation is available at [ExSeq Toolbox Documentation](https://exseq-toolbox.readthedocs.io/en/latest/), including:

examples/config_examples/high_memory_config.yaml

@@ -0,0 +1,39 @@
+# ExSeq-Toolbox Configuration Example: High Memory System
+# This configuration is optimized for systems with 32GB+ RAM and GPU
+
+data_paths:
+  raw_data_path: "/path/to/your/raw_data"
+  processed_data_path: "/path/to/processed_data"
+  puncta_dir_name: "puncta/"
+  gene_digit_csv: "./gene_list.csv"
+
+experiment:
+  codes: [0, 1, 2, 3, 4, 5, 6]
+  fovs: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
+  spacing: [0.4, 1.625, 1.625]
+  channel_names: ['640', '594', '561', '488', '405']
+  ref_code: 0
+  ref_channel: '405'
+
+processing:
+  chunk_size: 200  # Larger chunks for high memory systems
+  parallel_processes: 8  # More parallel processes
+  use_gpu_processing: true
+  gpu_memory_fraction: 0.9  # Use more GPU memory
+  auto_cleanup_memory: true
+
+alignment:
+  downsample_factors: [2, 4, 4]
+  low_percentile: 1.0
+  high_percentile: 99.0
+
+puncta:
+  thresholds: [200, 300, 300, 200]
+  min_distance: 7
+  gaussian_sigma: 1.0
+  exclude_border: false
+  consolidation_distance_threshold: 8.0
+
+system:
+  permission: false
+  permission_mode: 511  # 0o777 in decimal

examples/config_examples/low_memory_config.yaml

@@ -0,0 +1,39 @@
+# ExSeq-Toolbox Configuration Example: Low Memory System
+# This configuration is optimized for systems with 8GB or less RAM, no GPU
+
+data_paths:
+  raw_data_path: "/path/to/your/raw_data"
+  processed_data_path: "/path/to/processed_data"
+  puncta_dir_name: "puncta/"
+  gene_digit_csv: "./gene_list.csv"
+
+experiment:
+  codes: [0, 1, 2, 3, 4, 5, 6]
+  fovs: [0, 1, 2, 3]  # Process fewer FOVs at once
+  spacing: [0.4, 1.625, 1.625]
+  channel_names: ['640', '594', '561', '488', '405']
+  ref_code: 0
+  ref_channel: '405'
+
+processing:
+  chunk_size: 50  # Smaller chunks for low memory systems
+  parallel_processes: 2  # Fewer parallel processes
+  use_gpu_processing: false
+  gpu_memory_fraction: 0.6
+  auto_cleanup_memory: true
+
+alignment:
+  downsample_factors: [4, 8, 8]  # More aggressive downsampling
+  low_percentile: 1.0
+  high_percentile: 99.0
+
+puncta:
+  thresholds: [200, 300, 300, 200]
+  min_distance: 7
+  gaussian_sigma: 1.0
+  exclude_border: false
+  consolidation_distance_threshold: 8.0
+
+system:
+  permission: false
+  permission_mode: 511  # 0o777 in decimal

examples/wrappers/1_pipeline_parameter.py

@@ -4,14 +4,37 @@
 # Configure logger for ExSeq-Toolbox
 logger = configure_logger('ExSeq-Toolbox')
 
-# Initialize the configuration object.
+# Initialize the configuration object
 args = Args()
 
 # ================== Mandatory Configuration ==================
 # The absolute path to the raw data directory. Update this path accordingly.
 params = {}
 params["raw_data_path"] = '/path/to/your/raw_data_directory/'
 
+# ================== Processing Parameters ==================
+# Memory and performance optimization
+params["chunk_size"] = 150  # Adjust based on your system memory (default: 100)
+params["parallel_processes"] = 4  # Auto-detected if not specified
+params["use_gpu_processing"] = True  # Enable GPU if available
+params["gpu_memory_fraction"] = 0.8  # Use 80% of GPU memory
+params["auto_cleanup_memory"] = True  # Automatic memory cleanup
+
+# Puncta extraction parameters (previously hardcoded)
+params["puncta_thresholds"] = [200, 300, 300, 200]  # Custom thresholds per channel
+params["puncta_min_distance"] = 7  # Minimum distance between puncta
+params["puncta_gaussian_sigma"] = 1.0  # Gaussian filter sigma
+params["puncta_exclude_border"] = False  # Exclude border puncta
+params["consolidation_distance_threshold"] = 8.0  # Distance for consolidation
+
+# Alignment parameters (previously hardcoded)
+params["alignment_downsample_factors"] = (2, 4, 4)  # Downsampling factors
+params["alignment_low_percentile"] = 1.0  # Intensity normalization
+params["alignment_high_percentile"] = 99.0
+
+# System parameters
+params["permission_mode"] = 0o777  # Permission mode for created files
+
 # ================== Required Raw Data Directory Structure ==================
 # The ExSeq-Toolbox currently assumes the following directory structure:
 #
@@ -80,7 +103,38 @@
 args_file = "ExSeq_toolbox_args"
 params["args_file_name"] = args_file
 
-# Call set_params with the parameters
+# Call enhanced set_params with all parameters
 args.set_params(**params)
 
-# Note: Always ensure that the paths and other configuration parameters are correct before running the script.
+# ================== New Enhanced Features ==================
+
+# Get processing recommendations based on your system
+recommendations = args.get_processing_recommendations()
+logger.info("Processing recommendations for your system:")
+for key, value in recommendations.items():
+    logger.info(f"  {key}: {value}")
+
+# Save configuration in YAML format for easy editing and sharing
+yaml_config_path = args.processed_data_path + "/config.yaml"
+args.save_config_yaml(yaml_config_path)
+logger.info(f"Configuration saved to {yaml_config_path}")
+
+# Get memory configuration object
+memory_config = args.get_memory_config()
+if memory_config:
+    memory_info = memory_config.get_memory_info()
+    logger.info(f"Memory configuration: {memory_info}")
+
+# ================== Configuration Loading Example ==================
+# You can also load configuration from a YAML file:
+# args.load_config_yaml("examples/config_examples/high_memory_config.yaml")
+# args.load_config_yaml("examples/config_examples/low_memory_config.yaml")
+
+logger.info("Enhanced configuration completed successfully!")
+logger.info(f"Using chunk size: {args.chunk_size}")
+logger.info(f"Parallel processes: {args.parallel_processes}")
+logger.info(f"GPU processing enabled: {args.use_gpu_processing}")
+logger.info(f"Auto memory cleanup: {args.auto_cleanup_memory}")
+
+# Note: Configuration parameters are now fully customizable and hardware-aware.
+# Check the generated config.yaml file to see all available options.