Sync from GitHub: Refactor analyzer into mixin modules for maintainability

Split monolithic core/analyzer.py into focused mixin modules
(spectrum, envelope, scoring, isotope, charge) composed via MRO.
Deduplicate adduct parser in webapp, fix typo in index.html.
No algorithmic changes; all validation results unchanged.

.last_sync

@@ -1 +1 @@
-7ae1298887e7521bb82fd86e504071b599dbe48c
+1ba9fe091732330384694b2f4d259c9efde1f1ae

README.md

@@ -108,12 +108,6 @@ Supported formats: .txt, .csv
 - **Frontend:** HTML5, JavaScript, Plotly.js, JSME
 - **Libraries:** PythoMS, IsoSpecPy
 
-## Citation
-
-If you use NucleoSpec in a publication, please cite:
-
-> Lin, I.-H.; Copp, S. M. A Tutorial on Automated Mass Spectral Analysis using NucleoSpec for Compositional Assignment of Nucleic Acid–Silver Complexes and Nanoclusters. *ChemRxiv* 2026. [DOI: 10.26434/chemrxiv.15004738/v1](https://doi.org/10.26434/chemrxiv.15004738/v1)
-
 ## Support
 
 - **Developer:** I-Hsin (Vivian) Lin

core/charge.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Optional
+
+import numpy as np
+import numpy.typing as npt
+
+current_dir = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(current_dir, '..', 'lib'))
+
+
+logger = logging.getLogger(__name__)
+
+
+class ChargeMixin:
+    """Mixin for charge state detection from isotope spacing."""
+
+    def group_isotope_envelope(
+        self, peak_mz: npt.NDArray[np.float64], peak_intensity: npt.NDArray[np.float64], charge: Optional[int]
+    ) -> Optional[int]:
+        """
+        Group peaks that belong to the same isotope envelope
+        Returns the index of the most intense peak (representative peak)
+        """
+        if charge is None or charge <= 0:
+            return None
+
+        # Expected spacing for this charge state
+        spacing = 1.003 / charge
+
+        # Find the most intense peak in this envelope
+        return int(np.argmax(peak_intensity))
+
+    def detect_charge_state(
+        self,
+        mz_values: npt.NDArray[np.float64],
+        intensity_values: npt.NDArray[np.float64],
+        target_mz: float,
+        window: float = 3.0,
+    ) -> dict:
+        """
+        Detect charge state by anchored isotope-grid scoring.
+
+        For each candidate z in [1..10], build the expected isotope grid
+        target_mz + k * (1.003/z) and score how well the experimental peaks fit:
+            score = (fraction of strong-peak intensity on the grid)
+                  - (fraction of grid positions with no peak nearby)
+        Best z = highest score among viable candidates. If best is even and the
+        grid-intensity pattern alternates high-low (Ag doublet for DNA-AgN
+        clusters), halve z — this distinguishes a true z=N envelope from a
+        z=N/2 envelope where 107Ag/109Ag doubles the apparent peak count.
+
+        Returns dict compatible with previous callers:
+            'spacing', 'charge', 'confidence', 'num_peaks', 'scores'
+        """
+        from scipy.signal import find_peaks
+
+        NEUTRON_MASS = 1.003
+        CHARGE_RANGE = (1, 10)
+        DOUBLET_ALT_THRESHOLD = 0.85
+
+        mask = (mz_values >= target_mz - window) & (mz_values <= target_mz + window)
+        region_mz = mz_values[mask]
+        region_int = intensity_values[mask]
+
+        if len(region_mz) < 5:
+            return {'spacing': None, 'charge': None, 'confidence': 0.0, 'num_peaks': 0, 'scores': {}}
+
+        max_intensity = float(np.max(region_int))
+        peaks_idx, _ = find_peaks(region_int, prominence=max_intensity * 0.03, distance=1)
+
+        if len(peaks_idx) < 2:
+            return {'spacing': None, 'charge': None, 'confidence': 0.0, 'num_peaks': int(len(peaks_idx)), 'scores': {}}
+
+        peak_mzs = region_mz[peaks_idx]
+        peak_ints = region_int[peaks_idx]
+
+        strong_mask = peak_ints >= max_intensity * 0.10
+        strong_mzs = peak_mzs[strong_mask]
+        strong_ints = peak_ints[strong_mask]
+        total_strong_int = float(np.sum(strong_ints)) if len(strong_ints) > 0 else 1.0
+
+        results: dict[int, dict[str, float]] = {}
+        for z in range(CHARGE_RANGE[0], CHARGE_RANGE[1] + 1):
+            spacing = NEUTRON_MASS / z
+            tol = spacing * 0.25
+            n_iso = max(1, int(window / spacing))
+            ks = np.arange(-n_iso, n_iso + 1)
+            grid = target_mz + ks * spacing
+
+            grid_ints = np.zeros(len(grid))
+            for i, g in enumerate(grid):
+                d = np.abs(peak_mzs - g)
+                j = int(np.argmin(d))
+                if d[j] <= tol:
+                    grid_ints[i] = peak_ints[j]
+
+            matched_int = 0.0
+            for smz, sint in zip(strong_mzs, strong_ints):
+                if np.min(np.abs(grid - smz)) <= tol:
+                    matched_int += float(sint)
+            coverage = matched_int / total_strong_int
+            gap_frac = float(np.sum(grid_ints == 0)) / len(grid)
+
+            even_vals = grid_ints[(ks % 2 == 0) & (grid_ints > 0)]
+            odd_vals = grid_ints[(ks % 2 == 1) & (grid_ints > 0)]
+            if len(even_vals) > 0 and len(odd_vals) > 0:
+                em, om = float(even_vals.mean()), float(odd_vals.mean())
+                alt = (min(em, om) / max(em, om)) if max(em, om) > 0 else 1.0
+            else:
+                alt = 1.0
+
+            left = sum(1 for k in range(1, n_iso + 1) if np.min(np.abs(peak_mzs - (target_mz - k * spacing))) <= tol)
+            right = sum(1 for k in range(1, n_iso + 1) if np.min(np.abs(peak_mzs - (target_mz + k * spacing))) <= tol)
+
+            results[z] = {
+                'score': float(coverage - gap_frac),
+                'coverage': float(coverage),
+                'gap_frac': float(gap_frac),
+                'alt': float(alt),
+                'left': int(left),
+                'right': int(right),
+                'viable': bool(left + right + 1 >= 5),
+                'spacing': float(spacing),
+            }
+
+        viable_zs = [z for z, r in results.items() if r['viable']]
+        if viable_zs:
+            best_z = max(viable_zs, key=lambda z: results[z]['score'])
+        else:
+            best_z = max(results.keys(), key=lambda z: results[z]['score'])
+
+        while best_z > 1 and best_z % 2 == 0:
+            half = best_z // 2
+            if half in results and results[half]['viable'] and results[best_z]['alt'] < DOUBLET_ALT_THRESHOLD:
+                logger.info(
+                    f'[detect_charge_state] Ag-doublet halving at m/z {target_mz:.4f}: '
+                    f'z={best_z} -> z={half} (alt={results[best_z]["alt"]:.2f})'
+                )
+                best_z = half
+            else:
+                break
+
+        best = results[best_z]
+        confidence = max(0.0, min(1.0, best['score']))
+        num_matched = best['left'] + best['right'] + 1
+
+        logger.debug(
+            f'[detect_charge_state] target={target_mz:.4f} -> z={best_z} '
+            f'(coverage={best["coverage"]:.2f}, gap={best["gap_frac"]:.2f}, '
+            f'alt={best["alt"]:.2f}, score={best["score"]:+.3f})'
+        )
+
+        return {
+            'spacing': float(best['spacing']),
+            'charge': int(best_z),
+            'confidence': float(confidence),
+            'num_peaks': int(num_matched),
+            'scores': results,
+        }
+
+    def detect_charge_for_clicked_peak(
+        self,
+        mz_values: npt.NDArray[np.float64],
+        intensity_values: npt.NDArray[np.float64],
+        target_mz: float,
+        charge_range: tuple[int, int] = (1, 10),
+    ) -> dict:
+        """
+        Determine charge state of a user-clicked peak.
+
+        Primary: isotope-grid scoring via detect_charge_state.
+        Fallback: Senko charge assignment on the surrounding envelope.
+        Returns dict with 'charge', 'confidence', 'method' (and 'spacing',
+        'num_peaks' when produced by the primary method). 'charge' is None
+        only when both methods fail.
+        """
+        logger.info(f'[Charge Detection] Analyzing peak at m/z {target_mz:.4f}')
+
+        result = self.detect_charge_state(mz_values, intensity_values, target_mz, window=3.0)
+        charge = result.get('charge')
+        if charge is not None and charge_range[0] <= charge <= charge_range[1]:
+            num_peaks = int(result.get('num_peaks', 0))
+            confidence = float(result.get('confidence', 0.0))
+            if num_peaks < 3:
+                confidence = min(0.6, confidence)
+            logger.info(f'[Charge Detection] z={charge} via grid (conf={confidence * 100:.0f}%, {num_peaks} matched)')
+            return {
+                'charge': int(charge),
+                'confidence': float(confidence),
+                'method': 'spacing',
+                'spacing': float(result['spacing']),
+                'num_peaks': num_peaks,
+            }
+
+        logger.debug('[Charge Detection] Grid method inconclusive, falling back to Senko')
+        try:
+            from pythoms.senko_charge_assignment import detect_all_peaks_with_charge
+
+            detected = detect_all_peaks_with_charge(
+                mz_values,
+                intensity_values,
+                prominence=0.01,
+                charge_range=charge_range,
+                method='combination',
+                merge_gap=1.5,
+            )
+            closest = min(
+                (p for p in detected if abs(p['mz'] - target_mz) < 5.0 and p.get('charge') is not None),
+                key=lambda p: abs(p['mz'] - target_mz),
+                default=None,
+            )
+            if closest is not None:
+                logger.info(f'[Charge Detection] z={closest["charge"]} via Senko fallback')
+                return {
+                    'charge': int(closest['charge']),
+                    'confidence': float(closest['confidence']) * 0.8,
+                    'method': 'senko_fallback',
+                }
+        except Exception as e:
+            logger.error(f'[Charge Detection] Senko fallback error: {e}')
+
+        logger.warning('[Charge Detection] All methods failed; user input required')
+        return {'charge': None, 'confidence': 0.0, 'method': 'user_input_required'}

core/envelope.py

@@ -0,0 +1,814 @@
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import numpy as np
+import numpy.typing as npt
+from scipy.optimize import curve_fit
+
+logger = logging.getLogger(__name__)
+
+
+class EnvelopeMixin:
+    """Mixin for Gaussian envelope generation, fitting, and peak symmetry analysis."""
+
+    def smooth_gaussian_pattern(self, barip: list[list], fwhm: float, num_points_per_fwhm: int = 100) -> list[list]:
+        """
+        Generate smooth Gaussian isotope pattern with guaranteed high resolution sampling.
+
+        Args:
+            barip: Bar isotope pattern [[mz_values], [intensities]]
+            fwhm: Full width at half maximum
+            num_points_per_fwhm: Number of sampling points per FWHM (default: 100 for very smooth curves)
+
+        Returns:
+            [[mz_values], [intensities]] - smoothed Gaussian pattern
+        """
+        if not barip or len(barip[0]) == 0:
+            return [[], []]
+
+        mz_bar = np.array(barip[0])
+        int_bar = np.array(barip[1])
+
+        # Define m/z range: extend ±3*FWHM from min/max peaks (covers 99.7% of Gaussian)
+        mz_min = np.min(mz_bar) - 3 * fwhm
+        mz_max = np.max(mz_bar) + 3 * fwhm
+
+        # Calculate step size for smooth curve: FWHM / num_points_per_fwhm
+        step = fwhm / num_points_per_fwhm
+
+        # Generate high-resolution m/z grid
+        mz_grid = np.arange(mz_min, mz_max + step, step)
+        intensity_grid = np.zeros_like(mz_grid)
+
+        # Sigma (standard deviation) from FWHM: FWHM = 2.355 * sigma
+        sigma = fwhm / 2.355
+
+        # Sum Gaussian peaks for each isotope
+        for center_mz, height in zip(mz_bar, int_bar):
+            # Generate normalized Gaussian: exp(-(x-center)^2 / (2*sigma^2))
+            gaussian_contrib = np.exp(-0.5 * ((mz_grid - center_mz) / sigma) ** 2)
+            # Scale by height
+            intensity_grid += gaussian_contrib * height
+
+        # Normalize to 100
+        if np.max(intensity_grid) > 0:
+            intensity_grid = (intensity_grid / np.max(intensity_grid)) * 100.0
+
+        return [mz_grid.tolist(), intensity_grid.tolist()]
+
+    def calculate_peak_symmetry(
+        self,
+        mz_values: npt.NDArray[np.float64],
+        intensity_values: npt.NDArray[np.float64],
+        center_mz: float,
+        window: float = 2.0,
+    ) -> dict:
+        """
+        Calculate symmetry of a peak around its center.
+        Returns symmetry score (0-1, where 1 is perfectly symmetric)
+        and skewness indicator.
+
+        A symmetric peak suggests a clean, single species (like a nanocluster).
+        An asymmetric peak may indicate fragmentation, impurities, or overlapping peaks.
+        """
+        # Extract region around peak
+        mask = (mz_values >= center_mz - window) & (mz_values <= center_mz + window)
+        region_mz = mz_values[mask]
+        region_int = intensity_values[mask]
+
+        if len(region_mz) < 5:
+            return {'symmetry_score': 0.0, 'skewness': 0.0, 'is_symmetric': False, 'note': 'Insufficient data points'}
+
+        # Find peak apex
+        max_idx = np.argmax(region_int)
+        apex_mz = region_mz[max_idx]
+        max_intensity = region_int[max_idx]
+
+        # Divide into left and right sides from apex
+        left_mz = region_mz[: max_idx + 1]
+        left_int = region_int[: max_idx + 1]
+        right_mz = region_mz[max_idx:]
+        right_int = region_int[max_idx:]
+
+        if len(left_mz) < 2 or len(right_mz) < 2:
+            return {'symmetry_score': 0.0, 'skewness': 0.0, 'is_symmetric': False, 'note': 'Peak too narrow'}
+
+        # Calculate statistical skewness
+        mean_mz = np.average(region_mz, weights=region_int)
+        variance = np.average((region_mz - mean_mz) ** 2, weights=region_int)
+        std_dev = np.sqrt(variance)
+
+        if std_dev > 0:
+            skewness = np.average(((region_mz - mean_mz) / std_dev) ** 3, weights=region_int)
+        else:
+            skewness = 0.0
+
+        # Compare left and right sides by mirroring around apex
+        max_distance = min(apex_mz - region_mz[0], region_mz[-1] - apex_mz)
+
+        symmetry_scores = []
+        symmetry_weights = []
+        num_points = min(20, int(max_distance / 0.05))  # Finer sampling for better accuracy
+
+        for i in range(1, num_points + 1):
+            offset = (i / num_points) * max_distance
+
+            # Find intensity at left and right positions
+            left_pos = apex_mz - offset
+            right_pos = apex_mz + offset
+
+            # Interpolate intensities
+            left_intensity = np.interp(left_pos, left_mz, left_int, left=0, right=0)
+            right_intensity = np.interp(right_pos, right_mz, right_int, left=0, right=0)
+
+            # Calculate local symmetry, weighted by average intensity
+            # so high-signal regions near apex matter more than low-signal tails
+            avg_intensity = (left_intensity + right_intensity) / 2.0
+            if avg_intensity > 0:
+                local_asym = abs(left_intensity - right_intensity) / (left_intensity + right_intensity)
+                symmetry_scores.append(1.0 - local_asym)
+                symmetry_weights.append(avg_intensity)
+
+        # Overall symmetry score (intensity-weighted average)
+        if symmetry_scores and symmetry_weights:
+            symmetry_score = float(np.average(symmetry_scores, weights=symmetry_weights))
+        else:
+            symmetry_score = 0.0
+
+        # Determine if peak is symmetric
+        is_symmetric = symmetry_score > 0.7 and abs(skewness) < 0.5
+
+        # Generate interpretation
+        if symmetry_score > 0.85 and abs(skewness) < 0.3:
+            note = 'Highly symmetric - likely clean nanocluster'
+        elif symmetry_score > 0.7 and abs(skewness) < 0.5:
+            note = 'Moderately symmetric - good quality'
+        elif symmetry_score > 0.5:
+            note = 'Slightly asymmetric - may have impurities'
+        else:
+            note = 'Asymmetric - possible fragmentation or overlapping peaks'
+
+        return {
+            'symmetry_score': float(symmetry_score),
+            'skewness': float(skewness),
+            'is_symmetric': bool(is_symmetric),  # Convert numpy bool to Python bool
+            'note': note,
+            'apex_mz': float(apex_mz),
+        }
+
+    def generate_experimental_gaussian_envelope(
+        self, exp_mz: npt.NDArray[np.float64], exp_int: npt.NDArray[np.float64], resolution: int
+    ) -> tuple[Optional[npt.NDArray], Optional[npt.NDArray]]:
+        """
+        Generate smooth Gaussian envelope for experimental data.
+        Uses Gaussian smoothing with kernel based on instrument resolution.
+        This will show the natural asymmetry of the experimental data.
+        """
+        try:
+            logger.debug('GENERATE_EXPERIMENTAL_GAUSSIAN_ENVELOPE CALLED')
+            logger.debug(f'Input: {len(exp_mz)} m/z points, resolution={resolution}')
+
+            if len(exp_mz) == 0 or len(exp_int) == 0:
+                logger.warning('FAILED: Empty input data')
+                return None, None
+
+            # Convert to numpy arrays
+            exp_mz = np.array(exp_mz)
+            exp_int = np.array(exp_int)
+
+            # Calculate FWHM and sigma from resolution
+            peak_center = np.average(exp_mz, weights=exp_int)
+            fwhm = peak_center / resolution
+            sigma = fwhm / 2.355  # Convert FWHM to sigma
+
+            logger.debug(f'Peak center: {peak_center:.4f}, FWHM: {fwhm:.6f}, sigma: {sigma:.6f}')
+
+            # SMART APPROACH: Find apex (local maximum) of each isotope peak
+            # Then use the SAME smooth_gaussian_pattern function as theoretical data
+            # This ensures consistent smooth curves!
+
+            from scipy.signal import find_peaks
+
+            # Find local maxima (apex of each isotope peak)
+            # Use a small distance to separate isotope peaks (~0.2 Da for typical spacing)
+            min_distance = int(0.2 / np.median(np.diff(exp_mz))) if len(exp_mz) > 1 else 2
+            peaks_idx, properties = find_peaks(
+                exp_int, distance=max(2, min_distance), prominence=np.max(exp_int) * 0.05
+            )
+
+            if len(peaks_idx) < 3:
+                # Not enough peaks found - use all data points
+                logger.debug(f'Found only {len(peaks_idx)} apex points, using all data')
+                apex_mz = exp_mz
+                apex_int = exp_int
+            else:
+                # Extract apex points
+                all_apex_mz = exp_mz[peaks_idx]
+                all_apex_int = exp_int[peaks_idx]
+                logger.debug(f'Found {len(all_apex_mz)} apex points (local maxima)')
+
+                # FILTER: keep apex points that form a contiguous series with the
+                # most-intense apex. Walk left/right until a gap larger than
+                # 2.5 × median isotope spacing is encountered (the next envelope).
+                # This adapts to envelope width — narrow at low mass, wider at high
+                # mass where many Ag atoms broaden the isotope distribution.
+                max_apex_idx = int(np.argmax(all_apex_int))
+                spacings = np.diff(all_apex_mz)
+                median_spacing = float(np.median(spacings)) if len(spacings) >= 1 else 0.334
+                gap_threshold = max(median_spacing * 3.0, 0.5)
+
+                start = max_apex_idx
+                end = max_apex_idx
+                while end + 1 < len(all_apex_mz) and (all_apex_mz[end + 1] - all_apex_mz[end]) <= gap_threshold:
+                    end += 1
+                while start - 1 >= 0 and (all_apex_mz[start] - all_apex_mz[start - 1]) <= gap_threshold:
+                    start -= 1
+
+                apex_mz = all_apex_mz[start : end + 1]
+                apex_int = all_apex_int[start : end + 1]
+
+                logger.debug(
+                    f'Kept {len(apex_mz)} contiguous apex points '
+                    f'[{apex_mz[0]:.4f}, {apex_mz[-1]:.4f}] around max at '
+                    f'{all_apex_mz[max_apex_idx]:.4f} (gap_threshold={gap_threshold:.3f})'
+                )
+
+                if len(apex_mz) < 3:
+                    logger.debug(f'Too few contiguous points, using all {len(all_apex_mz)} apex points')
+                    apex_mz = all_apex_mz
+                    apex_int = all_apex_int
+
+                # CHECK FOR ALTERNATING INTENSITY PATTERN (same logic as charge detection)
+                # At low charge states (z=2), isotope peaks are ~0.5 Da apart with deep
+                # valleys; find_peaks picks up both real isotope apexes AND minor peaks
+                # in the valleys, creating a high-low-high-low pattern that shifts the
+                # smooth envelope centroid. Replace minor peaks' intensities with
+                # interpolated values from major peaks to correct the envelope shape
+                # while preserving the full m/z range for display.
+                if len(apex_int) >= 4:
+                    intensity_diffs = np.diff(apex_int)
+                    signs = np.sign(intensity_diffs)
+                    sign_changes = np.diff(signs)
+                    alternation_ratio = np.sum(sign_changes != 0) / len(sign_changes) if len(sign_changes) > 0 else 0
+
+                    if alternation_ratio > 0.8:
+                        even_sum = np.sum(apex_int[0::2])
+                        odd_sum = np.sum(apex_int[1::2])
+                        if even_sum >= odd_sum:
+                            major_idx = np.arange(0, len(apex_int), 2)
+                            minor_idx = np.arange(1, len(apex_int), 2)
+                        else:
+                            major_idx = np.arange(1, len(apex_int), 2)
+                            minor_idx = np.arange(0, len(apex_int), 2)
+
+                        # Interpolate minor peak intensities from major peaks
+                        interp_int = np.interp(apex_mz[minor_idx], apex_mz[major_idx], apex_int[major_idx])
+                        apex_int = apex_int.copy()
+                        apex_int[minor_idx] = interp_int
+                        logger.info(
+                            f'Alternating pattern detected (ratio={alternation_ratio:.2f}): '
+                            f'interpolated {len(minor_idx)} minor peaks from {len(major_idx)} major peaks'
+                        )
+
+            # Create SMOOTH envelope by interpolating apex points + Gaussian smoothing
+            # STEP 1: Interpolate apex points to create smooth curve
+            # STEP 2: Apply Gaussian smoothing based on instrument resolution
+            from scipy.interpolate import UnivariateSpline
+            from scipy.ndimage import gaussian_filter1d
+
+            # Create fine m/z grid
+            mz_min = np.min(apex_mz)
+            mz_max = np.max(apex_mz)
+            num_points = int((mz_max - mz_min) / (fwhm / 100)) + 1
+            mz_grid = np.linspace(mz_min, mz_max, num_points)
+
+            # STEP 1: Interpolate apex points with cubic spline
+            if len(apex_mz) >= 4:
+                spline = UnivariateSpline(apex_mz, apex_int, s=0, k=3)  # cubic, no smoothing
+                intensity_interp = spline(mz_grid)
+                logger.debug(f'STEP 1: Cubic spline through {len(apex_mz)} apex -> {len(mz_grid)} points')
+            else:
+                intensity_interp = np.interp(mz_grid, apex_mz, apex_int)
+                logger.debug(f'STEP 1: Linear interpolation through {len(apex_mz)} apex -> {len(mz_grid)} points')
+
+            # STEP 2: Apply STRONGER Gaussian smoothing for better curve fitting
+            mz_step = (mz_max - mz_min) / num_points if num_points > 1 else fwhm / 100
+            sigma_pixels = (sigma / mz_step) * 15.0  # 15x stronger smoothing for better Gaussian fit
+            intensity_grid = gaussian_filter1d(intensity_interp, sigma=sigma_pixels, mode='nearest')
+            logger.debug(f'STEP 2: STRONG Gaussian smoothing (sigma={sigma:.6f} m/z x 15 = {sigma_pixels:.2f} pixels)')
+
+            # Clip negative values (artifacts from edge smoothing)
+            intensity_grid = np.maximum(intensity_grid, 0.0)
+
+            # Normalize to 100
+            if np.max(intensity_grid) > 0:
+                intensity_grid = (intensity_grid / np.max(intensity_grid)) * 100.0
+
+            logger.info(f'SUCCESS: Smooth envelope from {len(apex_mz)} apex points')
+            logger.debug(f'Envelope: {len(mz_grid)} points, m/z [{np.min(mz_grid):.4f}, {np.max(mz_grid):.4f}]')
+
+            return mz_grid, intensity_grid
+
+        except Exception as e:
+            logger.exception(f'[generate_experimental_gaussian_envelope] Exception: {str(e)}')
+            return None, None
+
+    def fit_gaussian_to_smooth_envelope(
+        self,
+        mz_array: Optional[npt.NDArray[np.float64]],
+        int_array: Optional[npt.NDArray[np.float64]],
+        resolution: int,
+        context: str = '',
+    ) -> tuple[Optional[float], Optional[float], bool]:
+        """
+        Fit Gaussian to pre-smoothed isotope envelope to extract X₀ (centroid) and σ.
+
+        This is used by routes to fit experimental envelopes after they've been
+        smoothed by generate_experimental_gaussian_envelope().
+
+        Approach:
+        1. Find apex points in the data
+        2. Find valley boundaries (left/right) by scanning from center
+        3. Fit Gaussian to ALL data points between valleys
+
+        Args:
+            mz_array: Pre-smoothed m/z values
+            int_array: Pre-smoothed intensity values
+            resolution: Instrument resolution (for initial sigma estimate)
+            context: Optional context string for debug messages
+
+        Returns:
+            (x0, sigma, fit_succeeded): Fitted centroid and width, with success flag
+            Falls back to apex values if fit fails (fit_succeeded=False)
+        """
+        from scipy.signal import find_peaks
+
+        # Igor Pro-style 4-parameter Gaussian: f(x) = y0 + A × exp(-((x - x₀) / w)²)
+        def gaussian(x, y0, A, x0, width):
+            return y0 + A * np.exp(-(((x - x0) / width) ** 2))
+
+        if mz_array is None or int_array is None or len(mz_array) <= 3:
+            return None, None, False
+
+        mz_array = np.array(mz_array)
+        int_array = np.array(int_array)
+
+        try:
+            # Step 1: Find apex points to determine valley boundaries
+            peaks_idx, _ = find_peaks(int_array, distance=2, prominence=np.max(int_array) * 0.05)
+
+            if len(peaks_idx) >= 5:
+                mz_apex = mz_array[peaks_idx]
+                int_apex = int_array[peaks_idx]
+
+                # Find center (highest apex)
+                center_idx = np.argmax(int_apex)
+
+                # Scan left to find valley
+                left_bound_idx = 0
+                for i in range(center_idx - 1, 0, -1):
+                    if i > 0 and int_apex[i] < int_apex[i - 1]:
+                        if int_apex[i] < int_apex[i + 1] * 0.9:
+                            left_bound_idx = i
+                            break
+
+                # Scan right to find valley
+                right_bound_idx = len(int_apex) - 1
+                for i in range(center_idx + 1, len(int_apex)):
+                    if i < len(int_apex) - 1 and int_apex[i] < int_apex[i + 1]:
+                        if int_apex[i] < int_apex[i - 1] * 0.9:
+                            right_bound_idx = i
+                            break
+
+                # Get m/z boundaries from valleys
+                left_mz = mz_apex[left_bound_idx]
+                right_mz = mz_apex[right_bound_idx]
+
+                # Extract ALL data points between valleys
+                mask = (mz_array >= left_mz) & (mz_array <= right_mz)
+                mz_fit = mz_array[mask]
+                int_fit = int_array[mask]
+
+                if context:
+                    logger.debug(
+                        f'[{context}] Valley boundaries: [{left_mz:.4f}, {right_mz:.4f}], fitting {len(mz_fit)} points'
+                    )
+            else:
+                # Fallback: use all data
+                mz_fit = mz_array
+                int_fit = int_array
+                if context:
+                    logger.debug(f'[{context}] Too few apexes ({len(peaks_idx)}), using all {len(mz_fit)} points')
+
+            if len(mz_fit) < 3:
+                mz_fit = mz_array
+                int_fit = int_array
+
+            # Step 2: Fit Igor-style 4-parameter Gaussian to data between valleys
+            max_idx = np.argmax(int_fit)
+            A_init = int_fit[max_idx]
+            x0_init = mz_fit[max_idx]
+            fwhm_estimate = x0_init / resolution
+            sigma_init = fwhm_estimate / 2.355
+            width_init = sigma_init * np.sqrt(2)
+            y0_init = np.min(int_fit)
+
+            popt, pcov = curve_fit(
+                gaussian,
+                mz_fit,
+                int_fit,
+                p0=[y0_init, A_init, x0_init, width_init],
+                bounds=(
+                    [-A_init * 0.1, 0, mz_fit[0], 0.001],
+                    [A_init * 0.5, A_init * 2, mz_fit[-1], fwhm_estimate * 2 * np.sqrt(2)],
+                ),
+                maxfev=5000,
+            )
+
+            x0 = float(popt[2])
+            sigma = float(abs(popt[3]) / np.sqrt(2))
+
+            if context:
+                logger.debug(f'[{context}] Gaussian fit: X0={x0:.4f} m/z, sigma={sigma:.6f} m/z')
+
+            return x0, sigma, True
+
+        except Exception as e:
+            if context:
+                logger.warning(f'[{context}] Gaussian fit failed ({str(e)}), using apex fallback')
+            # Fallback: use apex of smooth envelope
+            max_idx = np.argmax(int_array)
+            x0 = float(mz_array[max_idx])
+            fwhm = x0 / resolution
+            sigma = float(fwhm / 2.355)
+
+            return x0, sigma, False
+
+    def detect_peak_asymmetry_visual(
+        self, mz_array: npt.NDArray[np.float64], int_array: npt.NDArray[np.float64], threshold_ratio: float = 0.3
+    ) -> tuple[bool, int, str]:
+        """
+        Detect peak asymmetry using visual characteristics:
+        - Count local maxima (multiple bumps = asymmetric)
+        - Check for shoulders (secondary peaks)
+        - Measure envelope smoothness
+
+        Returns: (is_asymmetric, num_maxima, details)
+        """
+        try:
+            if len(mz_array) < 5:
+                return False, 1, 'Too few points'
+
+            mz_array = np.array(mz_array)
+            int_array = np.array(int_array)
+
+            # Normalize intensity
+            max_int = np.max(int_array)
+            if max_int == 0:
+                return False, 1, 'Zero intensity'
+
+            int_norm = int_array / max_int
+
+            # Find local maxima (peaks)
+            from scipy.signal import find_peaks
+
+            # Detect peaks with minimum height (to avoid noise)
+            # Prominence helps identify significant peaks vs noise
+            peaks, properties = find_peaks(
+                int_norm,
+                height=threshold_ratio,  # At least 30% of max height
+                prominence=0.1,  # Must be prominent enough
+                distance=3,  # Separated by at least 3 points
+            )
+
+            num_maxima = len(peaks)
+
+            # Determine if asymmetric based on number of significant maxima
+            is_asymmetric = num_maxima > 1
+
+            details = f'{num_maxima} local maxima detected'
+            if num_maxima > 1:
+                peak_positions = [f'{mz_array[p]:.2f}' for p in peaks]
+                details += f' at m/z: {", ".join(peak_positions)}'
+
+            logger.debug(f'[Visual asymmetry detection] {details} -> {"ASYMMETRIC" if is_asymmetric else "SYMMETRIC"}')
+
+            return is_asymmetric, num_maxima, details
+
+        except Exception as e:
+            logger.error(f'[detect_peak_asymmetry_visual] Error: {str(e)}')
+            return False, 1, f'Error: {str(e)}'
+
+    def calculate_peak_skewness(
+        self, mz_array: npt.NDArray[np.float64], int_array: npt.NDArray[np.float64]
+    ) -> Optional[float]:
+        """
+        Calculate peak skewness (asymmetry measure).
+        Skewness = 0: perfectly symmetric
+        Skewness > 0: right-tailed (tailing to higher m/z)
+        Skewness < 0: left-tailed (tailing to lower m/z)
+
+        Returns: skewness value
+        """
+        try:
+            mz_array = np.array(mz_array, dtype=float)
+            int_array = np.array(int_array, dtype=float)
+
+            if len(mz_array) < 3 or np.sum(int_array) == 0:
+                return None
+
+            # Calculate mean (weighted by intensity)
+            mean = np.sum(mz_array * int_array) / np.sum(int_array)
+
+            # Calculate standard deviation
+            variance = np.sum(int_array * (mz_array - mean) ** 2) / np.sum(int_array)
+            std_dev = np.sqrt(variance)
+
+            if std_dev == 0:
+                return 0.0
+
+            # Calculate skewness: (mean - mode) / std_dev
+            # Approximate mode as the m/z with maximum intensity
+            mode_idx = np.argmax(int_array)
+            mode = mz_array[mode_idx]
+
+            skewness = (mean - mode) / std_dev
+
+            return float(skewness)
+
+        except Exception as e:
+            logger.error(f'[calculate_peak_skewness] Exception: {str(e)}')
+            return None
+
+    def weighted_average_centroid(
+        self, mz_array: npt.NDArray[np.float64], int_array: npt.NDArray[np.float64]
+    ) -> tuple[Optional[float], Optional[float]]:
+        """
+        Calculate centroid using weighted average method.
+        This is used for general centroid calculations.
+        Returns x₀ = Σ(m/z × intensity) / Σ(intensity) and σ (weighted std dev)
+        """
+        try:
+            if len(mz_array) == 0 or len(int_array) == 0:
+                logger.warning('[weighted_average_centroid] Empty arrays')
+                return None, None
+
+            # Convert to numpy arrays
+            mz_array = np.array(mz_array, dtype=float)
+            int_array = np.array(int_array, dtype=float)
+
+            total_intensity = np.sum(int_array)
+            if total_intensity == 0 or np.isnan(total_intensity) or np.isinf(total_intensity):
+                logger.warning(f'[weighted_average_centroid] Invalid total intensity: {total_intensity}')
+                return None, None
+
+            # Weighted average: x₀ = Σ(m/z × intensity) / Σ(intensity)
+            x0 = np.sum(mz_array * int_array) / total_intensity
+
+            # Weighted standard deviation: σ = sqrt(Σ(intensity × (m/z - x₀)²) / Σ(intensity))
+            sigma = np.sqrt(np.sum(int_array * (mz_array - x0) ** 2) / total_intensity)
+
+            if np.isnan(x0) or np.isinf(x0):
+                return None, None
+
+            logger.debug(f'[weighted_average_centroid] x0={x0:.4f}, sigma={sigma:.4f}')
+            return float(x0), float(sigma)
+
+        except Exception as e:
+            logger.error(f'[weighted_average_centroid] Exception: {str(e)}')
+            return None, None
+
+    def gaussian_fit_centroid(
+        self, mz_array: npt.NDArray[np.float64], int_array: npt.NDArray[np.float64], return_quality: bool = False
+    ) -> tuple:
+        """
+        Fit Gaussian curve to isotope envelope: f(x) = A × exp(-(x - x₀)² / (2σ²))
+        This is the STANDARD method used for composition determination (X₀ error calculation).
+
+        Parameters:
+        - return_quality: If True, also return R² goodness-of-fit metric
+
+        Returns:
+        - (x0, sigma, x0_error) if return_quality=False
+        - (x0, sigma, x0_error, r_squared) if return_quality=True
+        - x0_error is the standard error of the fitted x₀ parameter from covariance matrix
+        """
+        try:
+            if len(mz_array) == 0 or len(int_array) == 0:
+                logger.warning(
+                    f'[gaussian_fit_centroid] Empty arrays: mz length={len(mz_array)}, int length={len(int_array)}'
+                )
+                if return_quality:
+                    return None, None, None, None
+                else:
+                    return None, None, None
+
+            # Convert to numpy arrays
+            mz_array = np.array(mz_array, dtype=float)
+            int_array = np.array(int_array, dtype=float)
+
+            if len(mz_array) < 3:
+                logger.warning('[gaussian_fit_centroid] Need at least 3 points for fitting')
+                if return_quality:
+                    return None, None, None, None
+                else:
+                    return None, None, None
+
+            total_intensity = np.sum(int_array)
+            if total_intensity == 0 or np.isnan(total_intensity) or np.isinf(total_intensity):
+                logger.warning(f'[gaussian_fit_centroid] Invalid total intensity: {total_intensity}')
+                if return_quality:
+                    return None, None, None, None
+                else:
+                    return None, None, None
+
+            # NEW APPROACH: Find apex envelope, then find valleys in envelope, then fit
+            # Step 1: Find apex points of individual isotope peaks
+            from scipy.signal import find_peaks
+
+            # Find local maxima (apex of each isotope peak)
+            peaks_idx, _ = find_peaks(int_array, distance=2, prominence=np.max(int_array) * 0.05)
+
+            if len(peaks_idx) >= 5:
+                # Extract apex points (envelope)
+                mz_apex = mz_array[peaks_idx]
+                int_apex = int_array[peaks_idx]
+                logger.debug(f'[gaussian_fit_centroid] Found {len(peaks_idx)} isotope peak apexes')
+
+                # Step 2: Find the highest apex (center of envelope)
+                center_idx = np.argmax(int_apex)
+
+                # Step 3: Find valleys in the envelope (left and right of center)
+                # A valley must be both a local dip (relative criterion) AND
+                # below 40% of center intensity (absolute criterion) to avoid
+                # triggering on noise fluctuations in broad complex envelopes.
+                center_intensity = int_apex[center_idx]
+                valley_threshold = center_intensity * 0.4
+
+                # Scan left from center to find minimum
+                left_bound_idx = 0
+                for i in range(center_idx - 1, 0, -1):
+                    if i > 0 and int_apex[i] < int_apex[i - 1]:
+                        if int_apex[i] < int_apex[i + 1] * 0.9 and int_apex[i] < valley_threshold:
+                            left_bound_idx = i
+                            break
+
+                # Scan right from center to find minimum
+                right_bound_idx = len(int_apex) - 1
+                for i in range(center_idx + 1, len(int_apex)):
+                    if i < len(int_apex) - 1 and int_apex[i] < int_apex[i + 1]:
+                        if int_apex[i] < int_apex[i - 1] * 0.9 and int_apex[i] < valley_threshold:
+                            right_bound_idx = i
+                            break
+
+                # Step 4: Extract apex points BETWEEN envelope valleys
+                mz_fit = mz_apex[left_bound_idx : right_bound_idx + 1]
+                int_fit = int_apex[left_bound_idx : right_bound_idx + 1]
+
+                logger.debug(
+                    f'[gaussian_fit_centroid] Envelope valleys: left={left_bound_idx}, center={center_idx}, right={right_bound_idx}'
+                )
+                logger.debug(f'[gaussian_fit_centroid] Fitting to {len(mz_fit)} apex points between envelope valleys')
+            else:
+                # Fallback: if too few peaks, use all apex points or top 70%
+                if len(peaks_idx) >= 3:
+                    mz_fit = mz_array[peaks_idx]
+                    int_fit = int_array[peaks_idx]
+                    logger.warning(f'[gaussian_fit_centroid] Only {len(peaks_idx)} apexes, using all')
+                else:
+                    logger.warning('[gaussian_fit_centroid] Too few apexes, using top 70%')
+                    max_intensity = np.max(int_array)
+                    threshold = max_intensity * 0.70
+                    high_intensity_mask = int_array >= threshold
+                    mz_fit = mz_array[high_intensity_mask]
+                    int_fit = int_array[high_intensity_mask]
+
+            if len(mz_fit) < 3:
+                logger.error('[gaussian_fit_centroid] Too few points, using all data')
+                mz_fit = mz_array
+                int_fit = int_array
+
+            # Initial guesses for Gaussian parameters
+            # Amplitude: maximum intensity
+            A_guess = np.max(int_fit)
+
+            # Center: m/z of the maximum intensity point (apex)
+            max_idx = np.argmax(int_fit)
+            x0_guess = mz_fit[max_idx]
+
+            # Width: estimate from data range
+            mz_min_fit = np.min(mz_fit)
+            mz_max_fit = np.max(mz_fit)
+            mz_range_fit = mz_max_fit - mz_min_fit
+            sigma_guess = mz_range_fit / 4.0  # Narrower estimate since we're fitting top only
+
+            # Ensure reasonable initial guesses
+            if sigma_guess < 0.01:
+                sigma_guess = 0.5
+
+            # Overall data range for bounds
+            mz_min_all = np.min(mz_array)
+            mz_max_all = np.max(mz_array)
+
+            # Baseline guess: minimum intensity in fitting region
+            max_int_fit = np.max(int_fit)
+            y0_guess = min(np.min(int_fit), max_int_fit * 0.4)
+
+            logger.debug(
+                f'[gaussian_fit_centroid] Initial guesses: x0={x0_guess:.4f} (apex), sigma={sigma_guess:.4f}, A={A_guess:.2e}, y0={y0_guess:.2e}'
+            )
+
+            # Igor Pro-style 4-parameter Gaussian: f(x) = y0 + A × exp(-((x - x₀) / w)²)
+            # where w = sqrt(2) × σ, so exponent = -(x - x₀)² / (2σ²)
+            def gaussian(x, y0, A, x0, width):
+                return y0 + A * np.exp(-(((x - x0) / width) ** 2))
+
+            # Fit Gaussian curve to HIGH-INTENSITY data only
+            try:
+                from scipy.optimize import curve_fit
+
+                width_guess = sigma_guess * np.sqrt(2)
+
+                # Allow x0 to vary within the full valley boundaries
+                bounds = (
+                    [-max_int_fit * 0.1, 0, mz_min_all, 0.01],  # Lower bounds: [y0_min, A_min, x0_min, width_min]
+                    [max_int_fit * 0.5, np.inf, mz_max_all, (mz_max_all - mz_min_all) * 2],  # Upper bounds
+                )
+
+                logger.debug(f'[gaussian_fit_centroid] x0 bounds: [{mz_min_all:.4f}, {mz_max_all:.4f}]')
+
+                popt, pcov = curve_fit(
+                    gaussian,
+                    mz_fit,  # Fit to high-intensity points only
+                    int_fit,
+                    p0=[y0_guess, A_guess, x0_guess, width_guess],
+                    bounds=bounds,
+                    maxfev=10000,
+                    ftol=1e-10,  # Function tolerance for convergence (more precise)
+                    xtol=1e-10,  # Parameter tolerance for convergence (more precise)
+                )
+
+                y0_fit, A_fit, x0_fit, width_fit = popt
+                sigma_fit = width_fit / np.sqrt(2)
+
+                # Calculate standard errors from covariance matrix
+                # pcov diagonal gives variance of parameters, sqrt gives standard error
+                perr = np.sqrt(np.diag(pcov))
+                y0_err, A_err, x0_err, width_err = perr
+
+                # Validate fitted parameters
+                if np.isnan(x0_fit) or np.isinf(x0_fit) or np.isnan(sigma_fit) or np.isinf(sigma_fit):
+                    raise ValueError('Fit returned invalid parameters')
+
+                # Calculate R² (coefficient of determination) if requested
+                if return_quality:
+                    # Predicted values from fitted Gaussian
+                    y_pred = gaussian(mz_array, y0_fit, A_fit, x0_fit, width_fit)
+
+                    # Calculate R²
+                    ss_res = np.sum((int_array - y_pred) ** 2)  # Residual sum of squares
+                    ss_tot = np.sum((int_array - np.mean(int_array)) ** 2)  # Total sum of squares
+                    r_squared = 1 - (ss_res / ss_tot) if ss_tot > 0 else 0.0
+
+                    logger.debug(
+                        f'[gaussian_fit_centroid] Gaussian fit: x₀={x0_fit:.4f}±{x0_err:.4f}, σ={sigma_fit:.4f}, y0={y0_fit:.2e}, R²={r_squared:.4f}'
+                    )
+                    return float(x0_fit), float(sigma_fit), float(x0_err), float(r_squared)
+                else:
+                    logger.debug(
+                        f'[gaussian_fit_centroid] Gaussian fit: x₀={x0_fit:.4f}±{x0_err:.4f}, σ={sigma_fit:.4f}, y0={y0_fit:.2e}'
+                    )
+                    return float(x0_fit), float(sigma_fit), float(x0_err)
+
+            except Exception as fit_error:
+                # If Gaussian fit fails, fall back to weighted average
+                logger.warning(
+                    f'[gaussian_fit_centroid] Gaussian fit failed ({fit_error}), using weighted average fallback'
+                )
+                x0_fallback = x0_guess
+                sigma_fallback = sigma_guess
+
+                if np.isnan(x0_fallback) or np.isinf(x0_fallback):
+                    if return_quality:
+                        return None, None, None, None
+                    else:
+                        return None, None, None
+
+                if return_quality:
+                    return (
+                        float(x0_fallback),
+                        float(sigma_fallback),
+                        None,
+                        0.0,
+                    )  # No fitting error, R² = 0 indicates fit failed
+                else:
+                    return float(x0_fallback), float(sigma_fallback), None  # No fitting error available
+
+        except Exception as e:
+            logger.exception(f'[gaussian_fit_centroid] Exception: {str(e)}')
+            if return_quality:
+                return None, None, None, None
+            else:
+                return None, None, None

core/isotope.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Any
+
+import numpy as np
+
+current_dir = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(current_dir, '..', 'lib'))
+
+from pythoms.molecule import IPMolecule
+
+try:
+    import IsoSpecPy as isospec
+    ISOSPEC_AVAILABLE = True
+except ImportError:
+    ISOSPEC_AVAILABLE = False
+
+ISOTOPE_LIBRARY = 'isospec' if ISOSPEC_AVAILABLE else 'pythoms'
+
+_isotope_pattern_cache: dict[tuple[str, int, int], dict[str, Any]] = {}
+_ISOTOPE_CACHE_MAX_SIZE = 1000
+
+logger = logging.getLogger(__name__)
+
+
+class IsotopeMixin:
+    """Mixin for isotope pattern generation (IsoSpecPy and PythoMS backends)."""
+
+    def generate_isotope_pattern(self, formula: str, charge: int = 1, resolution: int = 20000) -> dict:
+        """
+        Generate isotope pattern for a given formula.
+        Dispatches to either IsoSpecPy (faster) or PythoMS based on ISOTOPE_LIBRARY setting.
+        Returns both bar pattern and Gaussian pattern.
+
+        Uses global cache for speed optimization.
+
+        Parameters:
+            formula: Chemical formula string
+            charge: Charge state
+            resolution: MS resolution (default 20000 is fallback when webapp cannot parse from uploaded data)
+        """
+        global _isotope_pattern_cache, _ISOTOPE_CACHE_MAX_SIZE, ISOTOPE_LIBRARY
+
+        # Check cache first
+        cache_key = (formula, charge, resolution)
+        if cache_key in _isotope_pattern_cache:
+            logger.debug(f'[generate_isotope_pattern] CACHE HIT for {formula[:30]}... (z={charge})')
+            return _isotope_pattern_cache[cache_key]
+
+        logger.debug(f'[generate_isotope_pattern] CACHE MISS for {formula[:30]}... (z={charge}) - computing...')
+        # Dispatch to appropriate library
+        if ISOTOPE_LIBRARY == 'isospec' and ISOSPEC_AVAILABLE:
+            result = self._generate_isotope_pattern_isospec(formula, charge, resolution)
+        else:
+            result = self._generate_isotope_pattern_pythoms(formula, charge, resolution)
+
+        # Cache the result (with size limit) if successful
+        if 'error' not in result:
+            if len(_isotope_pattern_cache) >= _ISOTOPE_CACHE_MAX_SIZE:
+                # Remove oldest entry (first key)
+                oldest_key = next(iter(_isotope_pattern_cache))
+                del _isotope_pattern_cache[oldest_key]
+            _isotope_pattern_cache[cache_key] = result
+
+        return result
+
+    def _consolidate_formula(self, formula: str) -> str:
+        """
+        Consolidate a formula with duplicate elements into standard form.
+        E.g., 'C304H368N128O184P30Ag28N2H8' -> 'C304H376N130O184P30Ag28'
+
+        IsoSpecPy requires each element to appear only once.
+        """
+        import re
+
+        # Parse formula: find all element-count pairs
+        # Matches element symbols (1-2 letters, first uppercase) followed by optional count
+        pattern = r'([A-Z][a-z]?)(\d*)'
+        matches = re.findall(pattern, formula)
+
+        # Consolidate counts for each element
+        element_counts: dict[str, int] = {}
+        for element, count in matches:
+            if element:  # Skip empty matches
+                count = int(count) if count else 1
+                element_counts[element] = element_counts.get(element, 0) + count
+
+        # Rebuild formula in a standard order (C, H, N, O, P, S, then others alphabetically)
+        priority_order = ['C', 'H', 'N', 'O', 'P', 'S']
+        result = []
+
+        # Add priority elements first
+        for elem in priority_order:
+            if elem in element_counts:
+                count = element_counts.pop(elem)
+                result.append(f'{elem}{count}' if count > 1 else elem)
+
+        # Add remaining elements alphabetically
+        for elem in sorted(element_counts.keys()):
+            count = element_counts[elem]
+            result.append(f'{elem}{count}' if count > 1 else elem)
+
+        return ''.join(result)
+
+    def _generate_isotope_pattern_isospec(self, formula: str, charge: int = 1, resolution: int = 20000) -> dict:
+        """
+        Generate isotope pattern using IsoSpecPy (faster than PythoMS for large molecules).
+        """
+        try:
+            # Consolidate formula to handle duplicate elements (e.g., from adducts)
+            # IsoSpecPy requires each element to appear only once
+            consolidated_formula = self._consolidate_formula(formula)
+
+            # prob_to_cover=0.9999 captures 99.99% of the isotope distribution
+            iso_result = isospec.IsoTotalProb(formula=consolidated_formula, prob_to_cover=0.9999)
+
+            # IsoSpecPy returns CFFI objects - must convert to list first
+            masses = np.array(list(iso_result.masses))
+            probs = np.array(list(iso_result.probs))
+
+            if len(masses) == 0:
+                return {'error': 'IsoSpecPy returned empty pattern'}
+
+            # Sort by mass first
+            sort_idx = np.argsort(masses)
+            masses = masses[sort_idx]
+            probs = probs[sort_idx]
+
+            # Get monoisotopic mass (first peak after sorting, before any filtering)
+            monoisotopic_mass = masses[0]
+
+            # Calculate molecular weight (weighted average of ALL peaks)
+            molecular_weight = np.average(masses, weights=probs)
+
+            # Convert to m/z (apply charge)
+            # The formula passed is already the ION formula (protons already removed)
+            # So we just divide by charge, same as PythoMS does
+            mz_values = masses / abs(charge)
+
+            # Bin peaks FIRST to match PythoMS behavior (combine peaks at similar m/z)
+            # IsoSpecPy returns fine-grained peaks, PythoMS aggregates by nominal mass
+            # Use 0.2 Da bins to match typical isotope spacing
+            bin_width = 0.2 / abs(charge)
+            min_mz = mz_values.min()
+            max_mz = mz_values.max()
+            bins = np.arange(min_mz - bin_width / 2, max_mz + bin_width, bin_width)
+
+            # Digitize: assign each peak to a bin
+            bin_indices = np.digitize(mz_values, bins)
+
+            # Aggregate peaks in each bin
+            binned_mz = []
+            binned_int = []
+            for i in range(1, len(bins)):
+                mask = bin_indices == i
+                if np.any(mask):
+                    # Weighted average for m/z, sum for intensity
+                    bin_probs = probs[mask]
+                    bin_mzs = mz_values[mask]
+                    binned_mz.append(np.average(bin_mzs, weights=bin_probs))
+                    binned_int.append(np.sum(bin_probs))
+
+            if not binned_mz:
+                return {'error': 'IsoSpecPy: no peaks after binning'}
+
+            mz_values = np.array(binned_mz)
+            probs = np.array(binned_int)
+
+            # Normalize AFTER binning to max = 1.0 (like PythoMS)
+            probs = probs / np.max(probs)
+
+            # Filter out low intensity peaks (threshold=0.01 like PythoMS)
+            threshold = 0.01
+            mask = probs >= threshold
+            mz_values = mz_values[mask]
+            probs = probs[mask]
+
+            if len(mz_values) == 0:
+                return {'error': 'IsoSpecPy: all peaks below threshold after filtering'}
+
+            # Create bar isotope pattern in PythoMS format
+            barip = [mz_values.tolist(), probs.tolist()]
+
+            # Calculate FWHM for Gaussian smoothing
+            if len(mz_values) > 0:
+                theoretical_mz = mz_values[0]
+            else:
+                theoretical_mz = monoisotopic_mass / abs(charge)
+
+            fwhm = theoretical_mz / resolution
+
+            # Generate Gaussian pattern using the same smooth function
+            gaussian_pattern = self.smooth_gaussian_pattern(barip, fwhm, num_points_per_fwhm=100)
+
+            # Sort Gaussian pattern by m/z
+            if gaussian_pattern and len(gaussian_pattern[0]) > 0:
+                gaussian_mz = np.array(gaussian_pattern[0])
+                gaussian_int = np.array(gaussian_pattern[1])
+                sort_idx = np.argsort(gaussian_mz)
+                gaussian_mz_sorted = gaussian_mz[sort_idx].tolist()
+                gaussian_int_sorted = gaussian_int[sort_idx].tolist()
+            else:
+                gaussian_mz_sorted = []
+                gaussian_int_sorted = []
+
+            return {
+                'mz': barip[0],
+                'intensity': barip[1],
+                'gaussian_mz': gaussian_mz_sorted,
+                'gaussian_intensity': gaussian_int_sorted,
+                'monoisotopic_mass': monoisotopic_mass,
+                'molecular_weight': molecular_weight,
+            }
+        except Exception as e:
+            # Fall back to PythoMS if IsoSpecPy fails
+            logger.warning(f'IsoSpecPy failed for {formula}: {e}, falling back to PythoMS')
+            return self._generate_isotope_pattern_pythoms(formula, charge, resolution)
+
+    def _generate_isotope_pattern_pythoms(self, formula: str, charge: int = 1, resolution: int = 20000) -> dict:
+        """
+        Generate isotope pattern using PythoMS (original implementation).
+        """
+        try:
+            mol = IPMolecule(
+                formula,
+                charge=charge,
+                resolution=resolution,
+                verbose=False,
+                ipmethod='hybrid',
+                dropmethod='threshold',
+                threshold=0.01,
+            )
+
+            # Get bar isotope pattern
+            barip = mol.bar_isotope_pattern
+
+            # Calculate theoretical m/z for FWHM calculation
+            # Use the first m/z value from bar pattern (monoisotopic peak)
+            if len(barip[0]) > 0:
+                theoretical_mz = barip[0][0]  # First m/z value = monoisotopic peak
+            else:
+                # Fallback to old method if bar pattern is empty
+                theoretical_mass = mol.monoisotopic_mass
+                theoretical_mz = (theoretical_mass - charge * self.m_p) / charge
+
+            # Generate Gaussian pattern using custom smooth function
+            fwhm = theoretical_mz / resolution
+
+            # Use custom smooth Gaussian generation instead of PythoMS version
+            gaussian_pattern = self.smooth_gaussian_pattern(barip, fwhm, num_points_per_fwhm=100)
+
+            # Sort Gaussian pattern by m/z to prevent zigzag plotting
+            if gaussian_pattern and len(gaussian_pattern[0]) > 0:
+                gaussian_mz = np.array(gaussian_pattern[0])
+                gaussian_int = np.array(gaussian_pattern[1])
+
+                # Sort by m/z
+                sort_idx = np.argsort(gaussian_mz)
+                gaussian_mz_sorted = gaussian_mz[sort_idx].tolist()
+                gaussian_int_sorted = gaussian_int[sort_idx].tolist()
+            else:
+                gaussian_mz_sorted = []
+                gaussian_int_sorted = []
+
+            return {
+                'mz': barip[0],
+                'intensity': barip[1],
+                'gaussian_mz': gaussian_mz_sorted,
+                'gaussian_intensity': gaussian_int_sorted,
+                'monoisotopic_mass': mol.monoisotopic_mass,
+                'molecular_weight': mol.molecular_weight,
+            }
+        except Exception as e:
+            return {'error': str(e)}

core/scoring.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import numpy as np
+import numpy.typing as npt
+
+logger = logging.getLogger(__name__)
+
+
+class ScoringMixin:
+    """Mixin for isotope pattern matching and similarity scoring."""
+
+    def calculate_pattern_similarity(
+        self,
+        theo_mz: npt.NDArray[np.float64],
+        theo_int: npt.NDArray[np.float64],
+        exp_mz: npt.NDArray[np.float64],
+        exp_int: npt.NDArray[np.float64],
+        window: float = 3.0,
+    ) -> float:
+        """Mean of cosine similarity and Pearson correlation between matched theo/exp isotope peaks."""
+        try:
+            if len(theo_mz) == 0 or len(exp_mz) == 0:
+                return 0.0
+
+            from scipy.signal import find_peaks
+
+            theo_mz = np.array(theo_mz, dtype=np.float64)
+            theo_int = np.array(theo_int, dtype=np.float64)
+            exp_mz = np.array(exp_mz, dtype=np.float64)
+            exp_int = np.array(exp_int, dtype=np.float64)
+
+            # Filter to significant sticks (>5% of max)
+            sig_mask = theo_int > np.max(theo_int) * 0.05
+            theo_mz = theo_mz[sig_mask]
+            theo_int = theo_int[sig_mask]
+            if len(theo_mz) < 2:
+                return 0.0
+
+            # Find experimental peak apexes
+            spacing = np.median(np.diff(theo_mz))
+            min_distance = int(spacing * 0.4 / np.median(np.diff(exp_mz))) if len(exp_mz) > 1 else 2
+            peaks_idx, _ = find_peaks(exp_int, distance=max(2, min_distance), prominence=np.max(exp_int) * 0.02)
+
+            if len(peaks_idx) < 2:
+                apex_mz = exp_mz
+                apex_int = exp_int
+            else:
+                apex_mz = exp_mz[peaks_idx]
+                apex_int = exp_int[peaks_idx]
+
+            # Match each stick to nearest apex within half-spacing tolerance
+            match_tol = spacing * 0.5
+            paired_theo = []
+            paired_exp = []
+
+            for i in range(len(theo_mz)):
+                diffs = np.abs(apex_mz - theo_mz[i])
+                nearest_idx = np.argmin(diffs)
+                if diffs[nearest_idx] <= match_tol:
+                    paired_theo.append(theo_int[i])
+                    paired_exp.append(apex_int[nearest_idx])
+                else:
+                    paired_theo.append(theo_int[i])
+                    paired_exp.append(0.0)
+
+            if len(paired_theo) < 2:
+                return 0.0
+
+            paired_theo = np.array(paired_theo)
+            paired_exp = np.array(paired_exp)
+
+            # Normalize to max = 1
+            paired_theo = paired_theo / (np.max(paired_theo) + 1e-10)
+            paired_exp = paired_exp / (np.max(paired_exp) + 1e-10)
+
+            # Cosine similarity
+            cosine_sim = np.dot(paired_theo, paired_exp) / (
+                np.linalg.norm(paired_theo) * np.linalg.norm(paired_exp) + 1e-10
+            )
+            cosine_sim = max(0.0, min(1.0, cosine_sim))
+
+            # Pearson correlation
+            if np.std(paired_theo) > 0 and np.std(paired_exp) > 0:
+                correlation = np.corrcoef(paired_theo, paired_exp)[0, 1]
+                correlation = max(0.0, min(1.0, correlation))
+            else:
+                correlation = 0.0
+
+            return float((cosine_sim + correlation) / 2.0)
+
+        except Exception as e:
+            logger.exception(f'[calculate_pattern_similarity] Exception: {str(e)}')
+            return 0.0
+
+    def calculate_multi_parameter_fit_score(
+        self,
+        theo_mz: npt.NDArray[np.float64],
+        theo_int: npt.NDArray[np.float64],
+        exp_mz: npt.NDArray[np.float64],
+        exp_int: npt.NDArray[np.float64],
+        theo_x0: Optional[float],
+        theo_sigma: Optional[float],
+        exp_x0: Optional[float],
+        exp_sigma: Optional[float],
+    ) -> tuple[float, dict]:
+        """
+        Calculate comprehensive fit score combining multiple parameters:
+        1. X₀ error (centroid position)
+        2. σ ratio (width matching)
+        3. R² (curve overlap quality)
+
+        Returns a composite score (lower is better) and individual metrics
+        """
+        try:
+            if theo_x0 is None or exp_x0 is None or theo_sigma is None or exp_sigma is None:
+                return 999.0, {'x0_error': 999.0, 'sigma_ratio': None, 'r_squared': None}
+
+            # 1. X₀ error (absolute difference in centroid positions)
+            x0_error = abs(exp_x0 - theo_x0)
+
+            # 2. σ ratio (how well the widths match)
+            # Ratio close to 1.0 means good width match
+            sigma_ratio = theo_sigma / exp_sigma if exp_sigma > 0 else None
+            sigma_deviation = abs(1.0 - sigma_ratio) if sigma_ratio else 999.0
+
+            # 3. R² (coefficient of determination - curve overlap quality)
+            # Need to align theoretical and experimental on same m/z grid
+            try:
+                # Find overlapping m/z range
+                mz_min = max(np.min(theo_mz), np.min(exp_mz))
+                mz_max = min(np.max(theo_mz), np.max(exp_mz))
+
+                if mz_max <= mz_min:
+                    r_squared = 0.0
+                else:
+                    # Create common m/z grid for comparison
+                    mz_grid = np.linspace(mz_min, mz_max, 200)
+
+                    # Interpolate both patterns onto common grid
+                    theo_interp = np.interp(mz_grid, theo_mz, theo_int, left=0, right=0)
+                    exp_interp = np.interp(mz_grid, exp_mz, exp_int, left=0, right=0)
+
+                    # Normalize both to max=1 for fair comparison
+                    theo_norm = theo_interp / np.max(theo_interp) if np.max(theo_interp) > 0 else theo_interp
+                    exp_norm = exp_interp / np.max(exp_interp) if np.max(exp_interp) > 0 else exp_interp
+
+                    # Calculate R² (coefficient of determination)
+                    ss_res = np.sum((exp_norm - theo_norm) ** 2)  # Residual sum of squares
+                    ss_tot = np.sum((exp_norm - np.mean(exp_norm)) ** 2)  # Total sum of squares
+                    r_squared = 1.0 - (ss_res / ss_tot) if ss_tot > 0 else 0.0
+                    r_squared = max(0.0, min(1.0, r_squared))  # Clamp to [0, 1]
+
+            except Exception as e:
+                logger.error(f'[R-squared calculation failed]: {str(e)}')
+                r_squared = 0.0
+
+            # Composite score (weighted combination - lower is better)
+            # Weight factors - adjust these based on importance
+            w_x0 = 10.0  # X₀ error weight (m/z units)
+            w_sigma = 5.0  # σ deviation weight
+            w_r2 = 20.0  # R² weight (inverted since higher R² is better)
+
+            composite_score = (
+                w_x0 * x0_error  # Centroid position error
+                + w_sigma * sigma_deviation  # Width mismatch
+                + w_r2 * (1.0 - r_squared)  # Shape overlap quality (inverted)
+            )
+
+            metrics = {
+                'x0_error': float(x0_error),
+                'sigma_ratio': float(sigma_ratio) if sigma_ratio else None,
+                'sigma_deviation': float(sigma_deviation),
+                'r_squared': float(r_squared),
+                'composite_score': float(composite_score),
+            }
+
+            logger.debug(
+                f'[Fit Score] X0_err={x0_error:.4f}, sigma_ratio={sigma_ratio:.3f}, R_squared={r_squared:.4f}, Score={composite_score:.2f}'
+            )
+
+            return composite_score, metrics
+
+        except Exception as e:
+            logger.exception(f'[calculate_multi_parameter_fit_score] Exception: {str(e)}')
+            return 999.0, {'x0_error': 999.0, 'sigma_ratio': None, 'r_squared': None}
+
+    def match_isotope_pattern(
+        self,
+        experimental_mz: npt.NDArray[np.float64],
+        experimental_int: npt.NDArray[np.float64],
+        theoretical_pattern: dict,
+        tolerance: float = 0.5,
+    ) -> float:
+        """
+        Match experimental peaks to theoretical isotope pattern using Gaussian fitting
+        Compares X0 (centroid) positions between theory and experiment
+        Returns the X0 centroid difference in m/z units (error metric)
+        """
+        if 'error' in theoretical_pattern:
+            return 999.0  # Large error if pattern generation failed
+
+        # Use smooth Gaussian pattern for theo_x0 calculation (same method as exp_x0)
+        theo_mz = np.array(theoretical_pattern.get('gaussian_mz', theoretical_pattern.get('mz', [])))
+        theo_int = np.array(theoretical_pattern.get('gaussian_intensity', theoretical_pattern.get('intensity', [])))
+
+        if len(theo_mz) == 0:
+            return 999.0
+
+        # Normalize both patterns
+        theo_int_norm = theo_int / np.max(theo_int) * 100
+        exp_int_norm = experimental_int / np.max(experimental_int) * 100
+
+        # Calculate Gaussian centroids (X0) for both patterns
+        theo_fit_result = self.gaussian_fit_centroid(theo_mz, theo_int_norm)
+        exp_fit_result = self.gaussian_fit_centroid(experimental_mz, exp_int_norm)
+
+        theo_x0 = theo_fit_result[0] if theo_fit_result else None
+        exp_x0 = exp_fit_result[0] if exp_fit_result else None
+
+        if theo_x0 is None or exp_x0 is None:
+            return 999.0
+
+        # Find experimental peak closest to each theoretical peak
+        matched_intensities = []
+        matched_masses = []
+
+        for t_mz, t_int in zip(theo_mz, theo_int_norm):
+            # Find experimental peaks within tolerance
+            close_peaks = np.where(np.abs(experimental_mz - t_mz) < tolerance)[0]
+
+            if len(close_peaks) > 0:
+                # Find the closest peak
+                closest_idx = close_peaks[np.argmin(np.abs(experimental_mz[close_peaks] - t_mz))]
+                matched_intensities.append((t_int, exp_int_norm[closest_idx]))
+                matched_masses.append((t_mz, experimental_mz[closest_idx]))
+
+        if len(matched_intensities) == 0:
+            return 999.0
+
+        # Return X0 centroid difference in m/z units
+        # This is the ERROR metric - smaller is better
+        # Different Qcl values shift the centroid position
+        # The Qcl with smallest X0 error is the correct one
+
+        x0_error = abs(exp_x0 - theo_x0)
+
+        return x0_error

core/spectrum.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from typing import Optional
+
+import numpy as np
+import numpy.typing as npt
+
+current_dir = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(current_dir, '..', 'lib'))
+
+from pythoms.tome import autoresolution
+
+logger = logging.getLogger(__name__)
+
+
+class SpectrumMixin:
+    """Mixin for spectrum parsing and peak detection methods."""
+
+    def parse_txt_spectrum(self, txt_content: str) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
+        """
+        Parse mass spectrum from txt file
+        Expected format: two columns (m/z, intensity) separated by whitespace or comma
+        """
+        lines = txt_content.strip().replace('\r\n', '\n').replace('\r', '\n').split('\n')
+        mz_values = []
+        intensity_values = []
+
+        for line in lines:
+            line = line.strip()
+            if not line or line.startswith('#'):
+                continue
+
+            # Try different delimiters
+            parts = None
+            if '\t' in line:
+                parts = line.split('\t')
+            elif ',' in line:
+                parts = line.split(',')
+            else:
+                parts = line.split()
+
+            if len(parts) >= 2:
+                try:
+                    mz = float(parts[0])
+                    intensity = float(parts[1])
+                    mz_values.append(mz)
+                    intensity_values.append(intensity)
+                except ValueError:
+                    continue
+
+        return np.array(mz_values), np.array(intensity_values)
+
+    def estimate_resolution(self, mz_values: npt.NDArray[np.float64], intensity_values: npt.NDArray[np.float64]) -> int:
+        """
+        Estimate the resolution of the spectrum using PythoMS methodology
+        """
+        try:
+            res = autoresolution(list(mz_values), list(intensity_values), n=10, v=False)
+            if res is None or not np.isfinite(res) or res <= 0:
+                return 20000  # Default resolution
+            return int(res)
+        except Exception:
+            return 20000  # Default resolution if estimation fails
+
+    def calculate_fwhm(self, mz: float, resolution: int) -> float:
+        """
+        Calculate Full Width at Half Maximum for a given m/z and resolution
+        FWHM = m/z / resolution
+        """
+        return mz / resolution
+
+    def find_local_maximum(
+        self,
+        mz_values: npt.NDArray[np.float64],
+        intensity_values: npt.NDArray[np.float64],
+        center_mz: float,
+        lookwithin: Optional[float] = None,
+    ) -> tuple[Optional[float], Optional[float]]:
+        """
+        Find the local maximum within a window around center_mz
+        Based on PythoMS localmax function
+        """
+        if lookwithin is None:
+            lookwithin = 1.0
+
+        # Find indices within the window
+        left_idx = np.searchsorted(mz_values, center_mz - lookwithin, side='left')
+        right_idx = np.searchsorted(mz_values, center_mz + lookwithin, side='right')
+
+        if left_idx >= right_idx:
+            return None, None
+
+        # Find maximum in the window
+        window_intensities = intensity_values[left_idx:right_idx]
+        if len(window_intensities) == 0:
+            return None, None
+
+        max_intensity = np.max(window_intensities)
+        max_idx_in_window = np.argmax(window_intensities)
+        max_idx = left_idx + max_idx_in_window
+
+        return mz_values[max_idx], max_intensity
+
+    def find_peak_regions(
+        self,
+        mz_values: npt.NDArray[np.float64],
+        intensity_values: npt.NDArray[np.float64],
+        threshold: float = 0.05,
+        merge_gap: float = 1.5,
+    ) -> list[tuple[int, int]]:
+        """
+        Find isotope envelope regions - each ENVELOPE is one region
+        Merges nearby regions that are likely part of the same isotope envelope
+        merge_gap: merge regions separated by less than this m/z (default 1.5)
+        """
+        norm_intensity = intensity_values / np.max(intensity_values)
+
+        # Find regions above threshold
+        above_threshold = norm_intensity > threshold
+
+        # Find all continuous regions above threshold
+        regions = []
+        in_region = False
+        start_idx = 0
+
+        for i in range(len(above_threshold)):
+            if above_threshold[i] and not in_region:
+                # Start of new region
+                start_idx = i
+                in_region = True
+            elif not above_threshold[i] and in_region:
+                # End of region
+                end_idx = i - 1
+                regions.append((start_idx, end_idx))
+                in_region = False
+
+        # Handle case where last region extends to end
+        if in_region:
+            regions.append((start_idx, len(above_threshold) - 1))
+
+        # Merge regions that are close together (likely same isotope envelope)
+        if len(regions) <= 1:
+            return regions
+
+        merged_regions = []
+        current_start, current_end = regions[0]
+
+        for i in range(1, len(regions)):
+            next_start, next_end = regions[i]
+
+            # Check gap between current region end and next region start
+            gap = mz_values[next_start] - mz_values[current_end]
+
+            if gap < merge_gap:
+                # Merge: extend current region to include next region
+                current_end = next_end
+            else:
+                # Don't merge: save current region and start new one
+                merged_regions.append((current_start, current_end))
+                current_start, current_end = next_start, next_end
+
+        # Add the last region
+        merged_regions.append((current_start, current_end))
+
+        return merged_regions
+
+    def detect_peak_boundaries(
+        self, mz_array: npt.NDArray[np.float64], int_array: npt.NDArray[np.float64], peak_mz: float
+    ) -> tuple[float, float, float]:
+        """
+        Detect the boundaries of a single isotope envelope from experimental data.
+
+        NEW APPROACH:
+        1. Find APEX (highest point) in small window around clicked position
+        2. From apex, scan left/right to find valleys (local minima)
+        3. This ensures we identify the correct peak without jumping to adjacent ones
+
+        Returns: (left_boundary_mz, right_boundary_mz, apex_mz)
+        """
+        # Find the index closest to the clicked peak
+        peak_idx = np.argmin(np.abs(mz_array - peak_mz))
+
+        # STEP 1: Find the APEX (highest point) in a SMALL window around clicked position
+        # Use small window (±10 points) to avoid jumping to adjacent peaks
+        search_window = 10  # Small window to stay on same peak
+        search_start = max(0, peak_idx - search_window)
+        search_end = min(len(int_array), peak_idx + search_window)
+
+        # Find apex within this small region
+        local_region_intensities = int_array[search_start:search_end]
+        apex_idx_in_region = np.argmax(local_region_intensities)
+        apex_idx = search_start + apex_idx_in_region
+
+        apex_mz = mz_array[apex_idx]
+        apex_intensity = int_array[apex_idx]
+
+        logger.debug(f'Detecting isotope envelope boundaries around clicked m/z={peak_mz:.4f}')
+        logger.debug(f'Clicked at index={peak_idx}, mz={mz_array[peak_idx]:.4f}')
+        logger.debug(f'Found APEX at index={apex_idx}, mz={apex_mz:.4f}, intensity={apex_intensity:.0f}')
+
+        # STEP 2: From APEX, scan LEFT to find valley (local minimum)
+        left_idx = apex_idx
+        min_intensity_left = apex_intensity
+
+        for i in range(apex_idx - 1, max(0, apex_idx - 200), -1):
+            current_intensity = int_array[i]
+
+            # Track the minimum intensity as we scan left
+            if current_intensity < min_intensity_left:
+                min_intensity_left = current_intensity
+                left_idx = i
+
+            # Stop if intensity starts rising significantly (found the valley)
+            # Look for 2 consecutive points rising by >10%
+            if i >= 1:
+                if int_array[i - 1] > current_intensity * 1.1 and int_array[i] > int_array[i + 1] * 1.1:
+                    # Found a valley - intensity is rising on the left
+                    logger.debug(
+                        f'Left valley at index={left_idx}, mz={mz_array[left_idx]:.4f}, intensity={int_array[left_idx]:.0f}'
+                    )
+                    break
+
+        # If we hit the edge without finding a valley, use the minimum we found
+        if left_idx == apex_idx:
+            logger.debug(f'Left boundary at edge: index={left_idx}, mz={mz_array[left_idx]:.4f}')
+
+        # STEP 3: From APEX, scan RIGHT to find valley (local minimum)
+        right_idx = apex_idx
+        min_intensity_right = apex_intensity
+
+        for i in range(apex_idx + 1, min(len(int_array), apex_idx + 200)):
+            current_intensity = int_array[i]
+
+            # Track the minimum intensity as we scan right
+            if current_intensity < min_intensity_right:
+                min_intensity_right = current_intensity
+                right_idx = i
+
+            # Stop if intensity starts rising significantly (found the valley)
+            # Look for 2 consecutive points rising by >10%
+            if i < len(int_array) - 1:
+                if int_array[i + 1] > current_intensity * 1.1 and int_array[i] > int_array[i - 1] * 1.1:
+                    # Found a valley - intensity is rising on the right
+                    logger.debug(
+                        f'Right valley at index={right_idx}, mz={mz_array[right_idx]:.4f}, intensity={int_array[right_idx]:.0f}'
+                    )
+                    break
+
+        # If we hit the edge without finding a valley, use the minimum we found
+        if right_idx == apex_idx:
+            logger.debug(f'Right boundary at edge: index={right_idx}, mz={mz_array[right_idx]:.4f}')
+
+        left_boundary_mz = mz_array[left_idx]
+        right_boundary_mz = mz_array[right_idx]
+        width = right_boundary_mz - left_boundary_mz
+        num_points = right_idx - left_idx + 1
+
+        logger.debug(
+            f'Final envelope: [{left_boundary_mz:.4f}, {right_boundary_mz:.4f}] m/z (width={width:.4f}, {num_points} points)'
+        )
+        logger.debug(f'Apex at {apex_mz:.4f} (Gaussian will use MIDPOINT of boundaries as initial guess)')
+
+        return left_boundary_mz, right_boundary_mz, apex_mz
+
+    def weighted_centroid(
+        self,
+        mz_values: npt.NDArray[np.float64],
+        intensity_values: npt.NDArray[np.float64],
+        start_idx: int,
+        end_idx: int,
+    ) -> tuple[Optional[float], Optional[float]]:
+        """
+        Calculate peak centroid (position of maximum intensity) matching PythoMS isotope overlay method
+
+        This uses the m/z value at maximum intensity for peak position, which is consistent
+        with how PythoMS's plot_mass_spectrum and localmax functions work.
+        """
+        region_mz = mz_values[start_idx : end_idx + 1]
+        region_int = intensity_values[start_idx : end_idx + 1]
+
+        if len(region_mz) == 0 or np.sum(region_int) == 0:
+            return None, None
+
+        # Find the m/z at maximum intensity (peak apex)
+        # This matches PythoMS isotope overlay behavior
+        max_idx = np.argmax(region_int)
+        centroid_mz = region_mz[max_idx]
+        max_intensity = region_int[max_idx]
+
+        return centroid_mz, max_intensity

templates/index.html

@@ -2696,7 +2696,7 @@
                 <div style="display: flex; align-items: center; gap: 10px;">
                     <span style="font-size: 1.5em;">✅</span>
                     <div style="flex: 1;">
-                        <strong style="color: #2e7d32; font-size: 1.05em;">Check boxes to overlay theoritical spectra</strong>
+                        <strong style="color: #2e7d32; font-size: 1.05em;">Check boxes to overlay theoretical spectra</strong>
                         <div style="font-size: 0.9em; color: #555; margin-top: 4px;">
                             Toggle checkboxes to compare theoretical isotope patterns with experimental data on both main and zoomed plots
                         </div>