Data Summarization And Tabulation

data-summarization-and-tabulation

Summary

Extract and compute summary statistics from structural clustering outputs (cluster count, size distribution, feature coverage) and tabulate results across parameterized conditions (e.g., adduct mode selection) to enable side-by-side comparison of method effects on LC-MS feature grouping.

When to use

After obtaining structural clusters from the MAMSI framework using different parameter configurations (e.g., adducts='all' vs adducts='most-common'), use this skill to compute cluster-level descriptive statistics and consolidate them into a single results table for quantitative comparison of how parameter choice affects clustering performance.

When NOT to use

• Input is a single clustering result with no comparison group — data summarization alone is insufficient without a parameterization or method comparison context.
• Features have not yet been assigned to structural clusters; use MamsiStructSearch.get_structural_clusters() first.
• Cluster outputs are already in the required table format; skip directly to statistical comparison and visualization.

Inputs

• Structural cluster objects from MamsiStructSearch.get_structural_clusters() calls (one per parameterization)
• Cluster metadata: cluster IDs, member feature counts, feature composition lists

Outputs

• Summary statistics table (rows=parameter configurations, columns=Adduct Mode, Total Clusters, Mean Cluster Size, Median Cluster Size, Max Cluster Size, Feature Coverage %)
• Size-distribution histograms (one histogram per adduct mode for visual comparison)
• Effect-size difference report (absolute and percentage changes in cluster count and mean cluster size between modes)

How to apply

For each adduct mode or parameterization, extract cluster metadata (cluster ID, member count, constituent features) and compute summary statistics: total cluster count, mean/median/max cluster sizes, and feature coverage (percentage of input features appearing in ≥1 cluster). Generate size-distribution histograms for visual comparison. Compute effect-size differences (absolute and percentage changes in cluster count and mean cluster size) between modes. Consolidate outputs into a single results table with columns: Adduct Mode, Total Clusters, Mean Cluster Size, Median Cluster Size, Max Cluster Size, Feature Coverage (%), enabling practitioners to quantitatively assess whether parameter choice materially affects the structural clustering output.

Related tools

• MAMSI (MamsiStructSearch) (Generates structural clusters from LC-MS features via isotopologue and adduct signature detection; outputs are the input to this summarization skill) — https://github.com/kopeckylukas/py-mamsi
• pandas (Tabulate cluster metadata into DataFrames, compute summary statistics (count, mean, median, max, percentages))
• numpy (Compute descriptive statistics (mean, median, percentiles) on cluster size arrays)
• matplotlib (Generate size-distribution histograms for visual side-by-side comparison of adduct modes)

Examples

struct_all = MamsiStructSearch(rt_win=5, ppm=10); struct_all.load_lcms(selected); struct_all.get_structural_clusters(adducts='all'); struct_mc = MamsiStructSearch(rt_win=5, ppm=10); struct_mc.load_lcms(selected); struct_mc.get_structural_clusters(adducts='most-common'); results = pd.DataFrame({'Adduct Mode': ['all', 'most-common'], 'Total Clusters': [len(struct_all.clusters), len(struct_mc.clusters)], 'Mean Cluster Size': [np.mean([len(c.members) for c in struct_all.clusters]), np.mean([len(c.members) for c in struct_mc.clusters])]}); results.to_csv('cluster_summary.csv', index=False)

Evaluation signals

• Total cluster count is a positive integer; mean/median/max cluster sizes are positive and satisfy: mean ≤ max, median ≤ max
• Feature coverage (%) is between 0 and 100; sum of all feature memberships ≥ number of unique features in coverage denominator
• Effect-size differences (absolute and percentage changes) are correctly computed as: Δ = (value_mode2 − value_mode1) and % change = 100 × (value_mode2 − value_mode1) / value_mode1
• Results table has consistent row and column structure across all parameterizations; no missing or NaN values in summary statistics
• Size-distribution histograms show reasonable distributions (e.g., no negative bin counts or out-of-range cluster sizes)

Limitations

• Summary statistics assume cluster membership is non-overlapping; if clusters can overlap, feature coverage calculation and mean cluster size may require clarification of counting semantics.
• Effect-size comparisons are valid only when the same input feature set (same p-value threshold, same LC-MS assays) is used across parameterizations; different input feature sets will confound method effects.
• Cluster count and size distribution are sensitive to retention time window width (rt_win parameter) and mass tolerance (ppm parameter); these must be held constant to isolate the effect of adduct mode selection.
• No statistical significance test (e.g., bootstrap CI, permutation test) is performed by default; effect sizes are descriptive only.

Evidence

• [methods] Extract cluster metadata (cluster ID, size, member count, feature composition) and compute summary statistics (total cluster count, mean/median/max cluster sizes, size distribution histogram).: "Extract cluster metadata (cluster ID, size, member count, feature composition) and compute summary statistics (total cluster count, mean/median/max cluster sizes, size distribution histogram)."
• [methods] Compare outputs side-by-side: tabulate cluster counts, generate size-distribution plots for both modes, and compute effect-size differences (absolute and percentage change in cluster count and mean cluster size).: "Compare outputs side-by-side: tabulate cluster counts, generate size-distribution plots for both modes, and compute effect-size differences (absolute and percentage change in cluster count and mean"
• [methods] Produce a consolidated results table with columns: Adduct Mode, Total Clusters, Mean Cluster Size, Median Cluster Size, Max Cluster Size, Feature Coverage (% features in ≥1 cluster).: "Produce a consolidated results table with columns: Adduct Mode, Total Clusters, Mean Cluster Size, Median Cluster Size, Max Cluster Size, Feature Coverage (% features in ≥1 cluster)."
• [other] tools: Python, pandas, numpy, matplotlib, MAMSI (MamsiStructSearch): "tools: Python, pandas, numpy, matplotlib, MAMSI (MamsiStructSearch)"