Merge branch 'dev' of https://github.com/ChEB-AI/python-chebi-utils into dev

Author: sfluegel05

.github/workflows/python-publish.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

README.md

@@ -1,6 +1,6 @@
 # python-chebi-utils
 
-Common processing functionality for the ChEBI ontology — download data files, extract classes and relations, extract molecules, and generate stratified train/val/test splits.
+Common processing functionality for the ChEBI ontology — download versioned data files, build an ontology graph, extract molecules, assemble labeled datasets, and generate stratified train/val/test splits.
 
 ## Installation
 
@@ -21,22 +21,34 @@ pip install -e ".[dev]"
 ```python
 from chebi_utils import download_chebi_obo, download_chebi_sdf
 
-obo_path = download_chebi_obo(dest_dir="data/")   # downloads chebi.obo
-sdf_path = download_chebi_sdf(dest_dir="data/")   # downloads chebi.sdf.gz
+obo_path = download_chebi_obo(version=248, dest_dir="data/")   # downloads chebi.obo
+sdf_path = download_chebi_sdf(version=248, dest_dir="data/")   # downloads chebi.sdf.gz
 ```
 
+A specific ChEBI release `version` (e.g. `230`, `245`, `248`) must be provided.
 Files are fetched from the [EBI FTP server](https://ftp.ebi.ac.uk/pub/databases/chebi/).
+Versions below 245 are automatically fetched from the legacy archive path.
 
-### Extract ontology classes and relations
+### Build the ChEBI ontology graph
 
 ```python
-from chebi_utils import extract_classes, extract_relations
+from chebi_utils import build_chebi_graph
 
-classes = extract_classes("chebi.obo")
-# DataFrame: id, name, definition, is_obsolete
+graph = build_chebi_graph("chebi.obo")
+# networkx.DiGraph — nodes are string ChEBI IDs (e.g. "1" for CHEBI:1)
+# node attributes: name, smiles, subset
+# edge attribute:  relation  ("is_a", "has_part", …)
+```
+
+Obsolete terms are excluded automatically. `xref:` lines are stripped before
+parsing to work around known fastobo compatibility issues in some ChEBI releases.
 
-relations = extract_relations("chebi.obo")
-# DataFrame: source_id, target_id, relation_type  (is_a, has_role, …)
+To obtain only the `is_a` hierarchy as a subgraph:
+
+```python
+from chebi_utils.obo_extractor import get_hierarchy_subgraph
+
+hierarchy = get_hierarchy_subgraph(graph)
 ```
 
 ### Extract molecules
@@ -45,28 +57,45 @@ relations = extract_relations("chebi.obo")
 from chebi_utils import extract_molecules
 
 molecules = extract_molecules("chebi.sdf.gz")
-# DataFrame: chebi_id, name, smiles, inchi, inchikey, formula, charge, mass, …
+# DataFrame columns: chebi_id, name, inchi, inchikey, smiles, charge, mass, mol, …
+# mol column contains RDKit Mol objects (None when parsing fails)
 ```
 
 Both plain `.sdf` and gzip-compressed `.sdf.gz` files are supported.
+Molecules that cannot be parsed are excluded from the returned DataFrame.
 
-### Generate train/val/test splits
+### Build a labeled dataset
 
 ```python
-from chebi_utils import create_splits
+from chebi_utils import build_labeled_dataset
 
-splits = create_splits(molecules, train_ratio=0.8, val_ratio=0.1, test_ratio=0.1)
-train_df = splits["train"]
-val_df   = splits["val"]
-test_df  = splits["test"]
+dataset, labels = build_labeled_dataset(graph, molecules, min_molecules=50)
+# dataset — DataFrame with columns: chebi_id, mol, <label1>, <label2>, …
+#            one boolean column per selected ontology class
+# labels  — sorted list of ChEBI IDs selected as label classes
 ```
 
-Pass `stratify_col` to preserve class proportions across splits:
+Each molecule is assigned to every label class that it belongs to directly or
+through a chain of `is_a` relationships. Only classes with at least
+`min_molecules` descendant molecules are kept as labels.
+
+### Generate stratified train/val/test splits
 
 ```python
-splits = create_splits(classes, stratify_col="is_obsolete", seed=42)
+from chebi_utils import create_multilabel_splits
+
+splits = create_multilabel_splits(dataset, train_ratio=0.8, val_ratio=0.1, test_ratio=0.1)
+train_df = splits["train"]
+val_df   = splits["val"]
+test_df  = splits["test"]
 ```
 
+Columns 0 and 1 (`chebi_id`, `mol`) are treated as metadata; all remaining
+columns are treated as binary label columns. When multiple label columns are
+present, `MultilabelStratifiedShuffleSplit` from the
+`iterative-stratification` package is used; for a single label column,
+`StratifiedShuffleSplit` from scikit-learn is used.
+
 ## Running Tests
 
 ```bash