Merge pull request #18 from OpenMS/copilot/add-experimentaldesign-support

Add Py_ExperimentalDesign wrapper with pandas DataFrame and file storage support

Author: timosachsenberg

README.md

@@ -189,6 +189,56 @@ search engine can be when built with the high-level helpers in
 `openms_python`. Reuse the test as inspiration for bespoke pipelines or as a
 regression harness when experimenting with search-related utilities.
 
+## Experimental design support
+
+Managing multi-sample, multi-fraction experiments? The `Py_ExperimentalDesign`
+wrapper makes it straightforward to work with OpenMS experimental design files
+that describe sample layouts, fractionation schemes, and labeling strategies.
+`tests/test_py_experimentaldesign.py` provides comprehensive examples of loading
+and querying experimental designs, including support for fractionated workflows,
+label-free and labeled quantitation setups, and integration with feature maps,
+consensus maps, and identification results. The wrapper exposes Pythonic
+properties for quick access to sample counts, fraction information, and design
+summaries—perfect for building sample-aware quantitation pipelines or validating
+experimental metadata before analysis.
+
+```python
+from openms_python import Py_ExperimentalDesign
+import pandas as pd
+
+# Load an experimental design from a TSV file
+design = Py_ExperimentalDesign.from_file("design.tsv")
+
+# Quick access to design properties
+print(f"Samples: {design.n_samples}")
+print(f"MS files: {design.n_ms_files}")
+print(f"Fractionated: {design.is_fractionated}")
+
+# Get a summary
+design.print_summary()
+
+# Convert to pandas DataFrame for analysis
+df = design.to_dataframe()
+
+# Create from a pandas DataFrame
+df = pd.DataFrame({
+    'Fraction_Group': [1, 1, 2, 2],
+    'Fraction': [1, 2, 1, 2],
+    'Spectra_Filepath': ['f1.mzML', 'f2.mzML', 'f3.mzML', 'f4.mzML'],
+    'Label': [1, 1, 1, 1],
+    'Sample': [1, 1, 2, 2]
+})
+design = Py_ExperimentalDesign.from_dataframe(df)
+
+# Store to file
+design.store("output_design.tsv")
+
+# Create from existing OpenMS objects
+from openms_python import Py_ConsensusMap
+consensus = Py_ConsensusMap.from_file("results.consensusXML")
+design = Py_ExperimentalDesign.from_consensus_map(consensus)
+```
+
 ### Iterate over containers and metadata
 
 All sequence-like wrappers (feature maps, consensus maps, identification containers,

openms_python/__init__.py

@@ -26,6 +26,7 @@
 from .py_feature import Py_Feature
 from .py_featuremap import Py_FeatureMap
 from .py_consensusmap import Py_ConsensusMap
+from .py_experimentaldesign import Py_ExperimentalDesign
 from .py_identifications import (
     ProteinIdentifications,
     PeptideIdentifications,
@@ -101,6 +102,7 @@ def get_example(name: str, *, load: bool = False, target_dir: Union[str, Path, N
     "Py_Feature",
     "Py_FeatureMap",
     "Py_ConsensusMap",
+    "Py_ExperimentalDesign",
     "ProteinIdentifications",
     "PeptideIdentifications",
     "Identifications",

openms_python/examples/experimental_design.tsv

@@ -0,0 +1,7 @@
+Fraction_Group	Fraction	Spectra_Filepath	Label	Sample
+1	1	sample1_fraction1.mzML	1	1
+1	2	sample1_fraction2.mzML	1	1
+1	3	sample1_fraction3.mzML	1	1
+2	1	sample2_fraction1.mzML	1	2
+2	2	sample2_fraction2.mzML	1	2
+2	3	sample2_fraction3.mzML	1	2