masster 0.5.13__py3-none-any.whl → 0.5.15__py3-none-any.whl

masster/wizard/wizard.py

@@ -228,9 +228,9 @@ class Wizard:
     that process raw MS data through the complete pipeline: file discovery, feature
     detection, sample processing, study assembly, alignment, merging, and export.
     
-    This simplified version focuses on two core functions:
-    - create_script(): Generate standalone analysis scripts
-    - execute(): Create and run analysis scripts
+    This simplified version focuses on three core functions:
+    - create_scripts(): Generate workflow and interactive analysis scripts
+    - analyze(): Create and run analysis scripts with interactive notebook
     """
     
     def __init__(
@@ -290,6 +290,14 @@ class Wizard:
         self.folder_path = Path(self.params.folder) 
         self.folder_path.mkdir(parents=True, exist_ok=True)
         
+        # Initialize logger
+        self.logger = MassterLogger(
+            instance_type="wizard",
+            level="INFO",
+            label="Wizard",
+            sink=None
+        )
+        
         # Auto-infer polarity from the first file if not explicitly set by user
         if polarity == "positive" and "polarity" not in kwargs:
             inferred_polarity = self._infer_polarity_from_first_file()
@@ -298,6 +306,164 @@ class Wizard:
                 # Update adducts based on inferred polarity  
                 self.params.__post_init__()
 
+    def _analyze_source_files(self) -> Dict[str, Any]:
+        """
+        Analyze source files to extract metadata: number of files, file type, polarity, and acquisition length.
+        
+        Returns:
+            Dictionary containing:
+            - number_of_files: Total count of data files found
+            - file_types: List of file extensions found 
+            - polarity: Detected polarity ("positive" or "negative")
+            - length_minutes: Acquisition length in minutes
+            - first_file: Path to first file analyzed
+        """
+        result = {
+            'number_of_files': 0,
+            'file_types': [],
+            'polarity': 'positive',
+            'length_minutes': 0.0,
+            'first_file': None
+        }
+        
+        try:
+            # Find all data files
+            all_files = []
+            file_types_found = set()
+            
+            for extension in self.params.file_extensions:
+                if self.params.search_subfolders:
+                    pattern = f"**/*{extension}"
+                    files = list(self.source_path.rglob(pattern))
+                else:
+                    pattern = f"*{extension}"
+                    files = list(self.source_path.glob(pattern))
+                
+                if files:
+                    all_files.extend(files)
+                    file_types_found.add(extension)
+            
+            result['number_of_files'] = len(all_files)
+            result['file_types'] = list(file_types_found)
+            
+            if not all_files:
+                return result
+                
+            # Analyze first file for polarity and acquisition length
+            first_file = all_files[0]
+            result['first_file'] = str(first_file)
+            
+            # Extract metadata based on file type
+            if first_file.suffix.lower() == '.wiff':
+                metadata = self._analyze_wiff_file(first_file)
+            elif first_file.suffix.lower() == '.mzml':
+                metadata = self._analyze_mzml_file(first_file)
+            elif first_file.suffix.lower() == '.raw':
+                metadata = self._analyze_raw_file(first_file)
+            else:
+                metadata = {'polarity': 'positive', 'length_minutes': 0.0}
+                
+            result['polarity'] = metadata.get('polarity', 'positive')
+            result['length_minutes'] = metadata.get('length_minutes', 0.0)
+            
+        except Exception as e:
+            self.logger.warning(f"Failed to analyze source files: {e}")
+            
+        return result
+    
+    def _analyze_wiff_file(self, file_path: Path) -> Dict[str, Any]:
+        """Analyze WIFF file to extract polarity and acquisition length."""
+        try:
+            from masster.sample.load import _wiff_to_dict
+            
+            # Extract metadata from WIFF file
+            metadata_df = _wiff_to_dict(str(file_path))
+            
+            result = {'polarity': 'positive', 'length_minutes': 0.0}
+            
+            if not metadata_df.empty:
+                # Get polarity from first experiment
+                if 'polarity' in metadata_df.columns:
+                    first_polarity = metadata_df['polarity'].iloc[0]
+                    
+                    # Convert numeric polarity codes to string
+                    if first_polarity == 1 or str(first_polarity).lower() in ['positive', 'pos', '+']:
+                        result['polarity'] = "positive"
+                    elif first_polarity == -1 or str(first_polarity).lower() in ['negative', 'neg', '-']:
+                        result['polarity'] = "negative"
+                
+                # Estimate acquisition length by loading the file briefly
+                # For a rough estimate, we'll load just the scan info
+                from masster.sample import Sample
+                sample = Sample()
+                sample.logger_update(level="ERROR")  # Suppress logs
+                sample.load(str(file_path))
+                
+                if hasattr(sample, 'scans_df') and sample.scans_df is not None:
+                    if not sample.scans_df.is_empty():
+                        rt_values = sample.scans_df.select('rt').to_numpy().flatten()
+                        if len(rt_values) > 0:
+                            # RT is in seconds, convert to minutes
+                            result['length_minutes'] = float(rt_values.max()) / 60.0
+            
+            return result
+            
+        except Exception as e:
+            self.logger.debug(f"Failed to analyze WIFF file {file_path}: {e}")
+            return {'polarity': 'positive', 'length_minutes': 0.0}
+    
+    def _analyze_mzml_file(self, file_path: Path) -> Dict[str, Any]:
+        """Analyze mzML file to extract polarity and acquisition length."""
+        try:
+            from masster.sample import Sample
+            
+            sample = Sample()
+            sample.logger_update(level="ERROR")  # Suppress logs
+            sample.load(str(file_path))
+            
+            result = {'polarity': 'positive', 'length_minutes': 0.0}
+            
+            if hasattr(sample, 'scans_df') and sample.scans_df is not None:
+                if not sample.scans_df.is_empty():
+                    rt_values = sample.scans_df.select('rt').to_numpy().flatten()
+                    if len(rt_values) > 0:
+                        # RT is in seconds, convert to minutes
+                        result['length_minutes'] = float(rt_values.max()) / 60.0
+                        
+            # For mzML, polarity detection would require more detailed parsing
+            # For now, use default
+            return result
+            
+        except Exception as e:
+            self.logger.debug(f"Failed to analyze mzML file {file_path}: {e}")
+            return {'polarity': 'positive', 'length_minutes': 0.0}
+    
+    def _analyze_raw_file(self, file_path: Path) -> Dict[str, Any]:
+        """Analyze RAW file to extract polarity and acquisition length."""
+        try:
+            from masster.sample import Sample
+            
+            sample = Sample()
+            sample.logger_update(level="ERROR")  # Suppress logs
+            sample.load(str(file_path))
+            
+            result = {'polarity': 'positive', 'length_minutes': 0.0}
+            
+            if hasattr(sample, 'scans_df') and sample.scans_df is not None:
+                if not sample.scans_df.is_empty():
+                    rt_values = sample.scans_df.select('rt').to_numpy().flatten()
+                    if len(rt_values) > 0:
+                        # RT is in seconds, convert to minutes
+                        result['length_minutes'] = float(rt_values.max()) / 60.0
+                        
+            # For RAW files, polarity detection would require more detailed parsing
+            # For now, use default
+            return result
+            
+        except Exception as e:
+            self.logger.debug(f"Failed to analyze RAW file {file_path}: {e}")
+            return {'polarity': 'positive', 'length_minutes': 0.0}
+
     def _infer_polarity_from_first_file(self) -> str:
         """
         Infer polarity from the first available raw data file.
@@ -349,69 +515,498 @@ class Wizard:
         """Get the adduct specifications."""
         return self.params.adducts
 
-    def create_script(self, filename: str = "run_masster.py") -> bool:
+    def create_scripts(self) -> Dict[str, Any]:
         """
-        Generate a standalone Python script for the analysis pipeline.
+        Generate analysis scripts based on source file analysis.
+        
+        This method:
+        1. Analyzes the source files to extract metadata
+        2. Creates 1_masster_workflow.py with sample processing logic
+        3. Creates 2_interactive_analysis.py marimo notebook for study exploration
+        4. Returns instructions for next steps
         
-        Parameters:
-            filename: Name for the generated script file
-            
         Returns:
-            True if script was generated successfully, False otherwise
+            Dictionary containing:
+            - status: "success" or "error"
+            - message: Status message
+            - instructions: List of next steps
+            - files_created: List of created file paths
+            - source_info: Metadata about source files
         """
         try:
-            script_path = self.folder_path / filename
-            script_content = self._generate_script_content()
+            # Step 1: Analyze source files to extract metadata
+            source_info = self._analyze_source_files()
+            
+            # Update wizard parameters based on detected metadata
+            if source_info['polarity'] != 'positive':  # Only update if different from default
+                self.params.polarity = source_info['polarity']
+                # Update adducts based on detected polarity
+                self.params.__post_init__()
+            
+            files_created = []
+            
+            # Step 2: Create 1_masster_workflow.py
+            workflow_script_path = self.folder_path / "1_masster_workflow.py"
+            workflow_content = self._generate_workflow_script_content(source_info)
+            
+            with open(workflow_script_path, 'w', encoding='utf-8') as f:
+                f.write(workflow_content)
+            files_created.append(str(workflow_script_path))
             
-            with open(script_path, 'w', encoding='utf-8') as f:
-                f.write(script_content)
+            # Step 3: Create 2_interactive_analysis.py marimo notebook
+            notebook_path = self.folder_path / "2_interactive_analysis.py"
+            notebook_content = self._generate_interactive_notebook_content(source_info)
             
-            print(f"Analysis script created: {script_path}")
-            return True
+            with open(notebook_path, 'w', encoding='utf-8') as f:
+                f.write(notebook_content)
+            files_created.append(str(notebook_path))
+            
+            # Step 4: Generate instructions
+            instructions = self._generate_instructions(source_info, files_created)
+            
+            return {
+                "status": "success",
+                "message": f"Successfully created {len(files_created)} script files",
+                "instructions": instructions,
+                "files_created": files_created,
+                "source_info": source_info
+            }
             
         except Exception as e:
-            print(f"Failed to create script: {e}")
-            return False
+            self.logger.error(f"Failed to create scripts: {e}")
+            return {
+                "status": "error", 
+                "message": f"Failed to create scripts: {e}",
+                "instructions": [],
+                "files_created": [],
+                "source_info": {}
+            }
+
+    def _generate_workflow_script_content(self, source_info: Dict[str, Any]) -> str:
+        """Generate the content for 1_masster_workflow.py script."""
+        
+        # Convert Path objects to strings for JSON serialization
+        params_dict = {}
+        for key, value in self.params.__dict__.items():
+            if key == '_param_metadata':  # Skip metadata in generated script
+                continue
+            if isinstance(value, Path):
+                params_dict[key] = str(value)
+            else:
+                params_dict[key] = value
 
-    def execute(self, filename: str = "run_masster.py") -> bool:
+        # Create readable PARAMS dict with comments including discovered info
+        params_lines = []
+        params_lines.append('# Analysis parameters (auto-detected from source files)')
+        params_lines.append('PARAMS = {')
+        
+        # File Discovery Summary
+        params_lines.append('    # === Source File Analysis ===')
+        params_lines.append(f'    "number_of_files": {source_info.get("number_of_files", 0)},  # Total raw data files found')
+        params_lines.append(f'    "file_types": {source_info.get("file_types", [])!r},  # Detected file extensions')
+        params_lines.append(f'    "length_minutes": {source_info.get("length_minutes", 0.0):.1f},  # Estimated acquisition length per file (minutes)')
+        if source_info.get('first_file'):
+            params_lines.append(f'    "first_file": {source_info["first_file"]!r},  # First file analyzed for metadata')
+        params_lines.append('')
+        
+        # Core Configuration
+        params_lines.append('    # === Core Configuration ===')
+        params_lines.append(f'    "source": {params_dict.get("source", "")!r},  # Directory containing raw data files')
+        params_lines.append(f'    "folder": {params_dict.get("folder", "")!r},  # Output directory for processed study')
+        params_lines.append(f'    "polarity": {params_dict.get("polarity", "positive")!r},  # Ion polarity mode (auto-detected)')
+        params_lines.append(f'    "num_cores": {params_dict.get("num_cores", 4)},  # Number of CPU cores for parallel processing')
+        params_lines.append('')
+        
+        # File Discovery
+        params_lines.append('    # === File Discovery ===')
+        params_lines.append(f'    "file_extensions": {params_dict.get("file_extensions", [".wiff", ".raw", ".mzML"])!r},  # File extensions to search for')
+        params_lines.append(f'    "search_subfolders": {params_dict.get("search_subfolders", True)},  # Whether to search subdirectories recursively')
+        params_lines.append(f'    "skip_patterns": {params_dict.get("skip_patterns", ["blank", "condition"])!r},  # Filename patterns to skip')
+        params_lines.append('')
+        
+        # Processing Parameters - Critical values to review
+        params_lines.append('    # === Processing Parameters (REVIEW THESE VALUES) ===')
+        params_lines.append(f'    "adducts": {params_dict.get("adducts", [])!r},  # Adduct specifications for feature detection and annotation')
+        params_lines.append(f'    "detector_type": {params_dict.get("detector_type", "unknown")!r},  # MS detector type ("orbitrap", "tof", "unknown")')
+        params_lines.append(f'    "noise": {params_dict.get("noise", 50.0)},  # REVIEW: Noise threshold for feature detection. Set to 1e5 for Orbitraps')
+        params_lines.append(f'    "chrom_fwhm": {params_dict.get("chrom_fwhm", 0.5)},  # REVIEW: Chromatographic peak FWHM (seconds)')
+        params_lines.append(f'    "chrom_peak_snr": {params_dict.get("chrom_peak_snr", 5.0)},  # Minimum signal-to-noise ratio for chromatographic peaks')
+        params_lines.append('')
+        
+        # Other parameters...
+        params_lines.append('    # === Alignment & Merging ===')
+        params_lines.append(f'    "rt_tol": {params_dict.get("rt_tol", 5.0)},  # Retention time tolerance for alignment (seconds)')
+        params_lines.append(f'    "mz_tol": {params_dict.get("mz_tol", 0.01)},  # Mass-to-charge ratio tolerance for alignment (Da)')
+        params_lines.append(f'    "alignment_method": {params_dict.get("alignment_method", "kd")!r},  # Algorithm for sample alignment')
+        params_lines.append(f'    "min_samples_per_feature": {params_dict.get("min_samples_per_feature", 1)},  # Minimum samples required per consensus feature')
+        params_lines.append(f'    "merge_method": {params_dict.get("merge_method", "qt")!r},  # Method for merging consensus features')
+        params_lines.append('')
+        
+        # Other params
+        params_lines.append('    # === Sample Processing ===')
+        params_lines.append(f'    "batch_size": {params_dict.get("batch_size", 8)},  # Number of files to process per batch')
+        params_lines.append(f'    "memory_limit_gb": {params_dict.get("memory_limit_gb", 16.0)},  # Memory limit for processing (GB)')
+        params_lines.append('')
+        
+        params_lines.append('    # === Script Options ===')
+        params_lines.append(f'    "resume_enabled": {params_dict.get("resume_enabled", True)},  # Enable automatic resume capability')
+        params_lines.append(f'    "force_reprocess": {params_dict.get("force_reprocess", False)},  # Force reprocessing of existing files')
+        params_lines.append(f'    "cleanup_temp_files": {params_dict.get("cleanup_temp_files", True)},  # Clean up temporary files after processing')
+        
+        params_lines.append('}')
+        
+        # Create script lines
+        script_lines = [
+            '#!/usr/bin/env python3',
+            '"""',
+            'MASSter Workflow Script - Sample Processing',
+            f'Generated by masster wizard v{version}',
+            '',
+            'Source Analysis:',
+            f'  - Files found: {source_info.get("number_of_files", 0)}',
+            f'  - File types: {", ".join(source_info.get("file_types", []))}',
+            f'  - Polarity detected: {source_info.get("polarity", "unknown")}',
+            f'  - Acquisition length: ~{source_info.get("length_minutes", 0.0):.1f} minutes per file',
+            '',
+            'This script processes raw MS data files into sample5 format.',
+            'Review the NOISE and CHROM_FWHM parameters below before running.',
+            '"""',
+            '',
+            'import sys',
+            'import time',
+            'from pathlib import Path',
+            'import concurrent.futures',
+            'import os',
+            '',
+            '# Import masster modules',
+            'from masster.sample import Sample',
+            'from masster import __version__',
+            '',
+        ]
+        
+        # Add the formatted PARAMS
+        script_lines.extend(params_lines)
+        
+        # Add the functions
+        script_lines.extend([
+            '',
+            '',
+            'def discover_raw_files(source_folder, file_extensions, search_subfolders=True, skip_patterns=None):',
+            '    """Discover raw data files in the source folder."""',
+            '    source_path = Path(source_folder)',
+            '    raw_files = []',
+            '    skip_patterns = skip_patterns or []',
+            '    ',
+            '    for ext in file_extensions:',
+            '        if search_subfolders:',
+            '            pattern = f"**/*{ext}"',
+            '            files = list(source_path.rglob(pattern))',
+            '        else:',
+            '            pattern = f"*{ext}"',
+            '            files = list(source_path.glob(pattern))',
+            '        ',
+            '        # Filter out files matching skip patterns',
+            '        for file in files:',
+            '            skip_file = False',
+            '            for skip_pattern in skip_patterns:',
+            '                if skip_pattern.lower() in file.name.lower():',
+            '                    skip_file = True',
+            '                    break',
+            '            if not skip_file:',
+            '                raw_files.append(file)',
+            '    ',
+            '    return raw_files',
+            '',
+            '',
+            'def process_single_file(args):',
+            '    """Process a single raw file to sample5 format - designed for multiprocessing."""',
+            '    raw_file, output_folder, params = args',
+            '    ',
+            '    try:',
+            '        # Create sample5 filename',
+            '        sample_name = raw_file.stem',
+            '        sample5_path = Path(output_folder) / f"{sample_name}.sample5"',
+            '        ',
+            '        # Skip if sample5 already exists and resume is enabled',
+            '        if sample5_path.exists() and params["resume_enabled"]:',
+            '            print(f"    ✓ Skipping {raw_file.name} (sample5 already exists)")',
+            '            return {"status": "skipped", "file": str(sample5_path), "message": "Already exists"}',
+            '        ',
+            '        print(f"    🔄 Processing {raw_file.name}...")',
+            '        start_time = time.time()',
+            '        ',
+            '        # Load and process raw file with full pipeline',
+            '        sample = Sample(log_label=sample_name)',
+            '        sample.load(filename=str(raw_file))',
+            '        sample.find_features(',
+            '            noise=params["noise"],',
+            '            chrom_fwhm=params["chrom_fwhm"],',
+            '            chrom_peak_snr=params["chrom_peak_snr"]',
+            '        )',
+            '        # sample.find_adducts(adducts=params["adducts"])',
+            '        sample.find_ms2()',
+            '        # sample.find_iso()  # Optional - can be uncommented if needed',
+            '        sample.save(str(sample5_path))',
+            '        ',
+            '        elapsed = time.time() - start_time',
+            '        print(f"    ✅ Completed {raw_file.name} -> {sample5_path.name} ({elapsed:.1f}s)")',
+            '        ',
+            '        return {"status": "success", "file": str(sample5_path), "elapsed": elapsed}',
+            '        ',
+            '    except Exception as e:',
+            '        print(f"    ❌ ERROR processing {raw_file.name}: {e}")',
+            '        return {"status": "error", "file": str(raw_file), "error": str(e)}',
+            '',
+            '',
+            'def convert_raw_to_sample5_parallel(raw_files, output_folder, params):',
+            '    """Convert raw data files to sample5 format with parallel processing and progress tracking."""',
+            '    import concurrent.futures',
+            '    import os',
+            '    ',
+            '    # Create output directory',
+            '    os.makedirs(output_folder, exist_ok=True)',
+            '    ',
+            '    print(f"\\n🚀 Processing {len(raw_files)} files using {params[\'num_cores\']} CPU cores...")',
+            '    print("=" * 70)',
+            '    ',
+            '    # Prepare arguments for multiprocessing',
+            '    file_args = [(raw_file, output_folder, params) for raw_file in raw_files]',
+            '    ',
+            '    # Process files in parallel with progress tracking',
+            '    results = []',
+            '    successful = 0',
+            '    skipped = 0',
+            '    failed = 0',
+            '    total_elapsed = 0',
+            '    ',
+            '    with concurrent.futures.ProcessPoolExecutor(max_workers=params["num_cores"]) as executor:',
+            '        # Submit all jobs',
+            '        future_to_file = {executor.submit(process_single_file, args): args[0] for args in file_args}',
+            '        ',
+            '        # Collect results as they complete',
+            '        for i, future in enumerate(concurrent.futures.as_completed(future_to_file), 1):',
+            '            result = future.result()',
+            '            results.append(result)',
+            '            ',
+            '            if result["status"] == "success":',
+            '                successful += 1',
+            '                total_elapsed += result.get("elapsed", 0)',
+            '            elif result["status"] == "skipped":',
+            '                skipped += 1',
+            '            else:',
+            '                failed += 1',
+            '            ',
+            '            # Progress update',
+            '            print(f"\\r    Progress: {i}/{len(raw_files)} files completed ({successful} success, {skipped} skipped, {failed} failed)", end="", flush=True)',
+            '    ',
+            '    print()  # New line after progress',
+            '    print("=" * 70)',
+            '    ',
+            '    # Summary',
+            '    if successful > 0:',
+            '        avg_time = total_elapsed / successful',
+            '        print(f"✅ Successfully processed {successful} files (avg: {avg_time:.1f}s per file)")',
+            '    if skipped > 0:',
+            '        print(f"⏩ Skipped {skipped} files (already exist)")',
+            '    if failed > 0:',
+            '        print(f"❌ Failed to process {failed} files")',
+            '        for result in results:',
+            '            if result["status"] == "error":',
+            '                print(f"    - {Path(result[\'file\']).name}: {result[\'error\']}")',
+            '    ',
+            '    # Return list of successful sample5 files',
+            '    sample5_files = [result["file"] for result in results if result["status"] in ["success", "skipped"]]',
+            '    return sample5_files',
+            '',
+            '',
+            'def main():',
+            '    """Main sample processing workflow."""',
+            '    try:',
+            '        print("=" * 70)',
+            f'        print("MASSter {version} - Sample Processing Workflow")',
+            '        print("=" * 70)',
+            '        print(f"Source: {PARAMS[\'source\']}")',
+            '        print(f"Output: {PARAMS[\'folder\']}")',
+            '        print(f"Polarity: {PARAMS[\'polarity\']} (detected)")',
+            '        print(f"CPU Cores: {PARAMS[\'num_cores\']}")',
+            '        print("=" * 70)',
+            '        print("\\n⚙️  IMPORTANT: Review these parameters before processing:")',
+            '        print(f"   NOISE threshold: {PARAMS[\'noise\']} (adjust based on your instrument)")',
+            '        print(f"   CHROM_FWHM: {PARAMS[\'chrom_fwhm\']}s (adjust based on your chromatography)")',
+            '        print("   You can edit these values in the PARAMS section above.")',
+            '        print("=" * 70)',
+            '        ',
+            '        start_time = time.time()',
+            '        ',
+            '        # Step 1: Discover raw data files',
+            '        print("\\n📁 Step 1/2: Discovering raw data files...")',
+            '        raw_files = discover_raw_files(',
+            '            PARAMS[\'source\'],',
+            '            PARAMS[\'file_extensions\'],',
+            '            PARAMS[\'search_subfolders\'],',
+            '            PARAMS[\'skip_patterns\']',
+            '        )',
+            '        ',
+            '        if not raw_files:',
+            '            print("❌ No raw data files found!")',
+            '            return False',
+            '        ',
+            '        print(f"Found {len(raw_files)} raw data files")',
+            '        for i, f in enumerate(raw_files[:5]):  # Show first 5 files',
+            '            print(f"  {i+1}. {f.name}")',
+            '        if len(raw_files) > 5:',
+            '            print(f"  ... and {len(raw_files) - 5} more files")',
+            '        ',
+            '        # Step 2: Process raw files to sample5',
+            '        print("\\n🔄 Step 2/2: Processing raw files to sample5 format...")',
+            '        sample5_files = convert_raw_to_sample5_parallel(',
+            '            raw_files,',
+            '            PARAMS[\'folder\'],',
+            '            PARAMS',
+            '        )',
+            '        ',
+            '        if not sample5_files:',
+            '            print("❌ No sample5 files were created!")',
+            '            return False',
+            '        ',
+            '        # Summary',
+            '        total_time = time.time() - start_time',
+            '        print("\\n" + "=" * 70)',
+            '        print("🎉 SAMPLE PROCESSING COMPLETE")',
+            '        print("=" * 70)',
+            '        print(f"Processing time: {total_time/60:.1f} minutes")',
+            '        print(f"Raw files found: {len(raw_files)}")',
+            '        print(f"Sample5 files created: {len(sample5_files)}")',
+            '        print("\\nNext steps:")',
+            '        print("1. Run the interactive analysis: uv run marimo edit 2_interactive_analysis.py")',
+            '        print("2. Or use the sample5 files in your own analysis scripts")',
+            '        print("=" * 70)',
+            '        ',
+            '        return True',
+            '        ',
+            '    except KeyboardInterrupt:',
+            '        print("\\n❌ Processing interrupted by user")',
+            '        return False',
+            '    except Exception as e:',
+            '        print(f"❌ Processing failed with error: {e}")',
+            '        import traceback',
+            '        traceback.print_exc()',
+            '        return False',
+            '',
+            '',
+            'if __name__ == "__main__":',
+            '    success = main()',
+            '    sys.exit(0 if success else 1)',
+        ])
+        
+        return '\n'.join(script_lines)
+
+    def analyze(self) -> Dict[str, Any]:
         """
-        Create and execute a standalone analysis script.
+        Execute the complete analysis workflow.
+        
+        This method:
+        1. Checks if 1_masster_workflow.py exists and runs it
+        2. If not, creates scripts first then runs the workflow
+        3. Provides clear feedback about next steps
         
-        Parameters:
-            filename: Name for the generated script file
-            
         Returns:
-            True if execution completed successfully, False otherwise
+            Dictionary containing execution results and instructions
         """
-        # First create the script
-        if not self.create_script(filename):
-            return False
-            
-        # Then execute it
-        script_path = self.folder_path / filename
+        workflow_script = self.folder_path / "1_masster_workflow.py"
         
         try:
-            print("Executing...")
+            # Check if workflow script exists
+            if workflow_script.exists():
+                print("📋 Found existing workflow script, executing...")
+                return self._execute_workflow_script(workflow_script)
+            else:
+                print("📝 Creating analysis scripts...")
+                # Create scripts first
+                result = self.create_scripts()
+                
+                if result["status"] != "success":
+                    return result
+                    
+                # Print instructions
+                print("\n" + "="*70)
+                for instruction in result["instructions"]:
+                    print(instruction)
+                print("="*70)
+                
+                # Ask user if they want to proceed with execution
+                print("\n🤔 Would you like to proceed with sample processing now?")
+                print("   This will execute 1_masster_workflow.py")
+                response = input("   Proceed? [y/N]: ").strip().lower()
+                
+                if response in ['y', 'yes']:
+                    return self._execute_workflow_script(workflow_script)
+                else:
+                    print("✋ Processing paused. Run the scripts manually when ready.")
+                    return {
+                        "status": "scripts_created",
+                        "message": "Scripts created successfully, execution deferred",
+                        "instructions": result["instructions"],
+                        "files_created": result["files_created"]
+                    }
+                    
+        except Exception as e:
+            self.logger.error(f"Analysis failed: {e}")
+            return {
+                "status": "error",
+                "message": f"Analysis failed: {e}",
+                "instructions": [],
+                "files_created": []
+            }
+    
+    def _execute_workflow_script(self, script_path: Path) -> Dict[str, Any]:
+        """Execute the workflow script and return results."""
+        try:
+            print(f"🚀 Executing {script_path.name}...")
             
             import subprocess
             result = subprocess.run([
                 sys.executable, str(script_path)
-            ], cwd=str(self.folder_path), encoding='utf-8', errors='replace')
+            ], cwd=str(self.folder_path), capture_output=False, text=True)
             
             success = result.returncode == 0
             
             if success:
-                print("=" * 70)
-                print("Script execution completed successfully")
+                print("="*70)
+                print("✅ Workflow execution completed successfully!")
+                print("="*70)
+                print("Next step: Run interactive analysis")
+                print("  uv run marimo edit 2_interactive_analysis.py")
+                print("="*70)
+                
+                return {
+                    "status": "success",
+                    "message": "Workflow completed successfully",
+                    "instructions": [
+                        "✅ Sample processing completed",
+                        "Next: uv run marimo edit 2_interactive_analysis.py"
+                    ],
+                    "files_created": []
+                }
             else:
-                print("=" * 70)
-                print(f"Script execution failed with return code: {result.returncode}")
+                return {
+                    "status": "error",
+                    "message": f"Workflow execution failed with code {result.returncode}",
+                    "instructions": [
+                        "❌ Check the error messages above",
+                        "Review parameters in 1_masster_workflow.py",
+                        "Try running: python 1_masster_workflow.py"
+                    ],
+                    "files_created": []
+                }
                 
-            return success
-            
         except Exception as e:
-            print(f"Error during script execution: {e}")
-            return False
+            return {
+                "status": "error",
+                "message": f"Failed to execute workflow: {e}",
+                "instructions": [],
+                "files_created": []
+            }
 
     def _generate_script_content(self) -> str:
         """Generate the complete analysis script content."""
@@ -718,8 +1313,154 @@ class Wizard:
         
         return '\n'.join(script_lines)
 
+    def _generate_notebook_content(self) -> str:
+        """Generate the content for a marimo interactive notebook."""
+        
+        notebook_lines = [
+            'import marimo',
+            '',
+            '__generated_with = "0.9.14"',
+            'app = marimo.App(width="medium")',
+            '',
+            '',
+            '@app.cell',
+            'def __():',
+            '    import marimo as mo',
+            '    return (mo,)',
+            '',
+            '',
+            '@app.cell',
+            'def __(mo):',
+            '    mo.md(r"""',
+            '    # MASSter Interactive Analysis',
+            '    ',
+            '    This notebook provides interactive exploration of your mass spectrometry study results.',
+            '    The study has been processed and is ready for analysis.',
+            '    """)',
+            '',
+            '',
+            '@app.cell',
+            'def __():',
+            '    # Import masster',
+            '    import masster',
+            '    return (masster,)',
+            '',
+            '',
+            '@app.cell',
+            'def __(masster):',
+            '    # Load the processed study',
+            '    study = masster.Study(folder=".")',
+            '    study.load()',
+            '    return (study,)',
+            '',
+            '',
+            '@app.cell',
+            'def __(mo, study):',
+            '    # Display study information',
+            '    mo.md(f"""',
+            '    ## Study Overview',
+            '    ',
+            '    **Samples:** {len(study.samples) if hasattr(study, "samples") else "Not loaded"}',
+            '    ',
+            '    **Features:** {len(study.consensus_df) if hasattr(study, "consensus_df") else "Not available"}',
+            '    ',
+            '    **Polarity:** {study.polarity if hasattr(study, "polarity") else "Unknown"}',
+            '    """)',
+            '',
+            '',
+            '@app.cell',
+            'def __(study):',
+            '    # Print detailed study info',
+            '    study.info()',
+            '',
+            '',
+            '@app.cell',
+            'def __(mo):',
+            '    mo.md(r"""',
+            '    ## Quick Visualizations',
+            '    ',
+            '    Use the cells below to create interactive plots of your data.',
+            '    """)',
+            '',
+            '',
+            '@app.cell',
+            'def __(study):',
+            '    # Generate consensus 2D plot',
+            '    if hasattr(study, "consensus_df") and len(study.consensus_df) > 0:',
+            '        study.plot_consensus_2d(filename="consensus_interactive.html")',
+            '        print("Consensus 2D plot saved as: consensus_interactive.html")',
+            '    else:',
+            '        print("No consensus features available for plotting")',
+            '',
+            '',
+            '@app.cell',
+            'def __(study):',
+            '    # Generate PCA plot',
+            '    if hasattr(study, "samples") and len(study.samples) > 1:',
+            '        study.plot_samples_pca(filename="pca_interactive.html")',
+            '        print("PCA plot saved as: pca_interactive.html")',
+            '    else:',
+            '        print("Not enough samples for PCA analysis")',
+            '',
+            '',
+            '@app.cell',
+            'def __(mo):',
+            '    mo.md(r"""',
+            '    ## Data Export',
+            '    ',
+            '    Export your processed data in various formats.',
+            '    """)',
+            '',
+            '',
+            '@app.cell',
+            'def __(study):',
+            '    # Export options',
+            '    if hasattr(study, "consensus_df"):',
+            '        # Export to Excel',
+            '        study.export_xlsx(filename="study_results.xlsx")',
+            '        print("✓ Results exported to: study_results.xlsx")',
+            '        ',
+            '        # Export to MGF',
+            '        study.export_mgf(filename="study_spectra.mgf")',
+            '        print("✓ Spectra exported to: study_spectra.mgf")',
+            '    else:',
+            '        print("No data available for export")',
+            '',
+            '',
+            '@app.cell',
+            'def __(mo):',
+            '    mo.md(r"""',
+            '    ## Custom Analysis',
+            '    ',
+            '    Add your own analysis code in the cells below.',
+            '    """)',
+            '',
+            '',
+            '@app.cell',
+            'def __(study):',
+            '    # Access consensus features dataframe',
+            '    if hasattr(study, "consensus_df"):',
+            '        df = study.consensus_df',
+            '        print(f"Consensus features shape: {df.shape}")',
+            '        print("\\nFirst 5 features:")',
+            '        print(df.head())',
+            '    return (df,) if "df" in locals() else ()',
+            '',
+            '',
+            '@app.cell',
+            'def __():',
+            '    # Your custom analysis here',
+            '    pass',
+            '',
+            '',
+            'if __name__ == "__main__":',
+            '    app.run()',
+        ]
+        
+        return '\n'.join(notebook_lines)
+
 
-def create_script(
+def create_analysis(
     source: str, 
     folder: str, 
     filename: str = 'run_masster.py', 
@@ -730,16 +1471,14 @@ def create_script(
     **kwargs
 ) -> bool:
     """
-    Create a standalone analysis script without initializing a Wizard instance.
+    Create standalone analysis scripts without initializing a Wizard instance.
     
-    This function generates a Python script that replicates automated processing
-    steps with the specified configuration. The script can be executed independently
-    to perform the same analysis.
+    This function generates analysis scripts with the specified configuration.
     
     Parameters:
         source: Directory containing raw data files
         folder: Output directory for processed study  
-        filename: Filename for the generated script (should end with .py)
+        filename: Filename for the generated script (deprecated, will create standard files)
         polarity: Ion polarity mode ("positive" or "negative")
         adducts: List of adduct specifications (auto-set if None)
         params: Custom wizard_def parameters (optional)
@@ -747,14 +1486,13 @@ def create_script(
         **kwargs: Additional parameters to override defaults
         
     Returns:
-        True if script was generated successfully, False otherwise
+        True if scripts were generated successfully, False otherwise
         
     Example:
-        >>> from masster.wizard import create_script
-        >>> create_script(
+        >>> from masster.wizard import create_analysis
+        >>> create_analysis(
         ...     source=r'D:\\Data\\raw_files',
         ...     folder=r'D:\\Data\\output', 
-        ...     filename='run_masster.py',
         ...     polarity='positive'
         ... )
     """
@@ -794,22 +1532,27 @@ def create_script(
         study_path = Path(folder)
         study_path.mkdir(parents=True, exist_ok=True)
         
-        # Create a temporary Wizard instance to generate the script
+        # Create a temporary Wizard instance to generate the scripts
         temp_wizard = Wizard(params=wizard_params)
         
-        # Generate the script using the instance method
-        success = temp_wizard.create_script(filename)
+        # Generate the scripts using the new method
+        result = temp_wizard.create_scripts()
         
-        return success
+        if result["status"] == "success":
+            print("Scripts created successfully!")
+            for instruction in result["instructions"]:
+                print(instruction)
+                
+        return result["status"] == "success"
         
     except Exception as e:
-        print(f"Failed to create script: {e}")
+        print(f"Failed to create scripts: {e}")
         import traceback
         traceback.print_exc()
         return False
 
 
-def execute(
+def analyze(
     source: str, 
     folder: str, 
     filename: str = 'run_masster.py', 
@@ -822,7 +1565,7 @@ def execute(
     """
     Create and execute a standalone analysis script for automated MS data processing.
     
-    This function generates a Python script with the same parameters as create_script(),
+    This function generates a Python script with the same parameters as create_analysis(),
     but immediately executes it after creation. Combines script generation and execution
     in a single step.
     
@@ -840,8 +1583,8 @@ def execute(
         True if script was created and executed successfully, False otherwise
         
     Example:
-        >>> from masster.wizard import execute
-        >>> execute(
+        >>> from masster.wizard import analyze
+        >>> analyze(
         ...     source=r'D:\\Data\\raw_files',
         ...     folder=r'D:\\Data\\output', 
         ...     polarity='positive'
@@ -849,59 +1592,39 @@ def execute(
     """
     
     try:
-        # First, create the script using create_script()
-        script_created = create_script(
-            source=source,
-            folder=folder,
-            filename=filename,
-            polarity=polarity,
-            adducts=adducts,
-            params=params,
-            num_cores=num_cores,
-            **kwargs
-        )
-        
-        if not script_created:
-            print("Failed to create analysis script")
-            return False
-            
-        # Get the full path to the created script
-        study_path = Path(folder)
-        script_path = study_path / Path(filename).name
-        
-        if not script_path.exists():
-            print(f"Script file not found: {script_path}")
-            return False
-            
-        print(f"Executing...")
-        #print("=" * 70)
-        
-        # Execute the script using subprocess with real-time output
-        import subprocess
-        
-        # Run the script with Python, letting it inherit our stdout/stderr
-        try:
-            # Use subprocess.run for direct output inheritance - no capturing/re-printing
-            result = subprocess.run([
-                sys.executable, str(script_path)
-            ], cwd=str(study_path))
+        # Create parameters (same logic as create_analysis)
+        if params is not None:
+            wizard_params = params
+            wizard_params.source = source
+            wizard_params.folder = folder
+            if polarity != "positive":
+                wizard_params.polarity = polarity
+            if num_cores > 0:
+                wizard_params.num_cores = num_cores
+            if adducts is not None:
+                wizard_params.adducts = adducts
+        else:
+            wizard_params = wizard_def(
+                source=source,
+                folder=folder,
+                polarity=polarity,
+                num_cores=max(1, int(multiprocessing.cpu_count() * 0.75)) if num_cores <= 0 else num_cores
+            )
             
-            return_code = result.returncode
+            if adducts is not None:
+                wizard_params.adducts = adducts
             
-        except Exception as e:
-            print(f"Error during script execution: {e}")
-            return False
+            # Apply any additional kwargs
+            for key, value in kwargs.items():
+                if hasattr(wizard_params, key):
+                    setattr(wizard_params, key, value)
         
-        success = return_code == 0
+        # Create Wizard instance and run analysis
+        wizard = Wizard(params=wizard_params)
+        result = wizard.analyze()
         
-        if success:
-            print("=" * 70)
-            print("Script execution completed successfully")
-        else:
-            print("=" * 70)
-            print(f"Script execution failed with return code: {return_code}")
-            
-        return success
+        # Return success status
+        return result.get("status") in ["success", "scripts_created"]
         
     except Exception as e:
         print(f"Failed to execute script: {e}")
@@ -910,5 +1633,93 @@ def execute(
         return False
 
 
+    def _generate_interactive_notebook_content(self, source_info: Dict[str, Any]) -> str:
+        """Generate the content for 2_interactive_analysis.py marimo notebook."""
+        
+        notebook_lines = [
+            'import marimo',
+            '',
+            '__generated_with = "0.9.14"',
+            'app = marimo.App(width="medium")',
+            '',
+            '',
+            '@app.cell',
+            'def __():',
+            '    import marimo as mo',
+            '    return (mo,)',
+            '',
+            '',
+            '@app.cell',
+            'def __(mo):',
+            '    mo.md(r"""',
+            '    # MASSter Interactive Analysis',
+            '    ',
+            f'    **Source:** {source_info.get("number_of_files", 0)} files ({", ".join(source_info.get("file_types", []))}) detected',
+            f'    **Polarity:** {source_info.get("polarity", "unknown")} (auto-detected)',
+            f'    **Acquisition length:** ~{source_info.get("length_minutes", 0.0):.1f} minutes per file',
+            '    ',
+            '    This notebook provides interactive exploration of your processed mass spectrometry study.',
+            '    Make sure you have run `python 1_masster_workflow.py` first to create the sample5 files.',
+            '    """)',
+            '',
+            '',
+            '@app.cell',
+            'def __():',
+            '    # Import masster',
+            '    import masster',
+            '    return (masster,)',
+            '',
+            '',
+            '@app.cell',
+            'def __(masster):',
+            '    # Load the study from sample5 files',
+            '    study = masster.Study(folder=".")',
+            '    return (study,)',
+            '',
+            '',
+            '@app.cell',
+            'def __(mo, study):',
+            '    # Display study information',
+            '    study.info()',
+            '    return ()',
+            '',
+            '',
+            'if __name__ == "__main__":',
+            '    app.run()',
+        ]
+        
+        return '\n'.join(notebook_lines)
+
+    def _generate_instructions(self, source_info: Dict[str, Any], files_created: List[str]) -> List[str]:
+        """Generate usage instructions for the created scripts."""
+        instructions = [
+            "🎯 NEXT STEPS:",
+            "",
+            f"Source analysis completed: {source_info.get('number_of_files', 0)} files found",
+            f"Polarity detected: {source_info.get('polarity', 'unknown')}",
+            f"Estimated processing time: {source_info.get('number_of_files', 0) * source_info.get('length_minutes', 0.0) * 0.1:.1f} minutes",
+            "",
+            "1. REVIEW PARAMETERS:",
+            "   Edit 1_masster_workflow.py and verify these key settings:",
+            "   - NOISE threshold (adjust based on your instrument sensitivity)",
+            "   - CHROM_FWHM (adjust based on your chromatography peak width)",
+            "",
+            "2. EXECUTE SAMPLE PROCESSING:",
+            "   python 1_masster_workflow.py",
+            "   (This will process all raw files to sample5 format)",
+            "",
+            "3. INTERACTIVE ANALYSIS:",
+            "   uv run marimo edit 2_interactive_analysis.py",
+            "   (This opens an interactive notebook for data exploration)",
+            "",
+            "FILES CREATED:"
+        ]
+        
+        for file_path in files_created:
+            instructions.append(f"  ✅ {Path(file_path).name}")
+            
+        return instructions
+
+
 # Export the main classes and functions
-__all__ = ["Wizard", "wizard_def", "create_script", "execute"]
+__all__ = ["Wizard", "wizard_def", "create_analysis", "analyze"]