✨ Two-Stage Hierarchical Framework for Automated MoA Prediction from Contractility Signals

Trustworthy AI for experimental pharmacology.

This repository will host the official implementation of our framework described in:
“Two-Stage Hierarchical Framework for Automated Prediction of Pharmacological Mechanism of Action (MoA) from Contractility Signals.”
Until acceptance, we share a detailed Dataset & Usage guide below so the community can prepare pipelines in advance.

---

🧭 Table of Contents

• 🔑 Access & Licensing at a Glance
• 📦 Dataset Summary
• 📨 How to Request Access
• 🚀 Quickstart (after approval)
• 🧠 Method (high‑level)
• 📂 Repository Status
• 📜 Licenses
• 📝 Citation
• 🙌 Acknowledgements
• 📫 Contact

---

🔑 Access & Licensing at a Glance

• Code (this repository): Apache‑2.0 — includes patent license grant; permissive for academic & commercial use.
• Dataset (on Hugging Face): CC BY 4.0 — attribution required for any reuse or derivative works.
• Access policy (gated, manual approval):
  • Review phase: We collect access requests but do not grant access during peer review (exceptions only for co‑authors / formal collaborators).
  • Post‑acceptance: We will evaluate and approve requests individually. Priority for non‑commercial academic research with a clear purpose.
  • Requester requirements: institutional email, brief usage statement, acceptance of the dataset’s Terms of Use.
  • How to request: see How to Request Access below.

ℹ️ “Gated” = the dataset card is visible, but downloads require approval. The license still applies to any approved use.

↑ back to top

---

📦 Dataset Summary

Hugging Face dataset: pharmaiktu/contractility-signals
Card visibility: public • Downloads: gated (manual approval) • License: CC BY 4.0

• Total recordings: 578 isometric contractility time series (100 Hz)
• Species / tissues: Isolated murine trachea and bladder smooth muscle
• Agents / classes (4):
  kcl → Potassium chloride — Calcium Channel Modulation (237)
  cch → Carbachol — Muscarinic Receptor Activation (179)
  ser → Serotonin — Serotonergic Receptor Pathway (86)
  his → Histamine — Histaminergic Receptor Pathway (76)
• Per‑record metadata: tissue, label, moa, sample_rate_hz=100, length

Feature schema per example

id: string
signal: float[]          # isometric tension trace @ 100 Hz
length: int              # number of samples
sample_rate_hz: int      # 100
label: string            # one of {kcl,cch,ser,his}
label_id: int            # from label_map.json
tissue: string           # {trachea, bladder}
moa: string              # mechanism mapped from label

↑ back to top

---

📨 How to Request Access

1. Open the HF dataset page → pharmaiktu/contractility-signals
2. Click “Request access” and fill the short form.
3. Include:
   • Institutional email (e.g., .edu, .ac, or your research institution’s domain)
   • Brief usage statement: intended use, methods, expected outputs
   • Confirmation that you agree to CC BY 4.0 and the dataset’s Terms of Use
4. During peer‑review: requests are queued but normally not approved (co‑authors/collaborators may be exceptions).
5. After acceptance: we review requests case‑by‑case and approve eligible research uses.

If needed, you may also contact us by email (see Contact) and include your HF username.

↑ back to top

---

🚀 Quickstart (after approval)

1) Authentication

from huggingface_hub import login
login()  # paste your token
# or set env var: HF_TOKEN=hf_...

2) Load all splits directly

from datasets import load_dataset

ds = load_dataset("pharmaiktu/contractility-signals")
print(ds)  # DatasetDict with train/validation/test

3) Work with a split

train = ds["train"]
row = train[0]
print(row.keys())  # ['id','signal','length','sample_rate_hz','label','label_id','tissue','moa']

4) Minimal PyTorch dataloader (example)

import torch
from torch.utils.data import DataLoader

class Contractility(torch.utils.data.Dataset):
    def __init__(self, hf_split):
        self.hf = hf_split
    def __len__(self):
        return len(self.hf)
    def __getitem__(self, i):
        x = torch.tensor(self.hf[i]["signal"], dtype=torch.float32)
        y = self.hf[i]["label_id"]
        return x, y

train_ds = Contractility(ds["train"])
train_loader = DataLoader(train_ds, batch_size=16, shuffle=True)

💡 Tip: For fixed‑length batching, apply windowing/padding and keep class/tissue stratification for fair benchmarking.

↑ back to top

---

🧠 Method (high‑level)

• Signal‑to‑image: 1D traces → GAF (Gramian Angular Field) to capture temporal–amplitude correlations as textures.
• Backbone: Swin Transformer (hierarchical shifted‑window self‑attention) for robust MoA discrimination.
• Status: Code will be released in this repository after manuscript acceptance.

↑ back to top

---

📂 Repository Status

• Now: README + access instructions (no source code yet)
• After acceptance: release training & eval pipelines (PyTorch), configs, and scripts
• Planned extras: preprocessing utilities, baseline models, and reproducible benchmarks

↑ back to top

---

📜 Licenses

• Code (this repository): Apache License, Version 2.0 → LICENSE
  You may use, modify, and distribute the code; includes a patent license grant.
• Dataset (Hugging Face): CC BY 4.0 → pharmaiktu/contractility-signals
  Please cite and provide attribution in any derivative works or publications.

Licenses apply independently: the dataset’s CC BY 4.0 does not convert the code’s license, and vice versa.

↑ back to top

---

📝 Citation

Please cite the dataset and the paper once available. (Will be updated post peer‑review with the final bibliographic reference.)

@dataset{pharmaiktu_contractility_signals_2025,
  title   = {PharmAI KTU Contractility Signals},
  author  = {PharmAI KTU Research Group},
  year    = {2025},
  note    = {CC BY 4.0. Access is gated; requests reviewed post-acceptance.},
  url     = {https://huggingface.co/datasets/pharmaiktu/contractility-signals}
}

@article{contractility_moa_2025,
  title   = {Two-Stage Hierarchical Framework for Automated Prediction of Pharmacological MoA from Contractility Signals},
  author  = {Dogan, Ramazan Ozgur and Dogu, Fatma Tuana and Ay, Ilyas and Kalha, Zain and Kaya Yasar, Yesim and Sezen, F. Sena and Dogan, Hulya},
  year    = {2025},
  note    = {Under review},
  journal = {},
  doi     = {},
  url     = {}
}

↑ back to top

---

🙌 Acknowledgements

This work is supported by the Health Institutes of Türkiye (TÜSEB), Project No. 35726.

↑ back to top

---

📫 Contact

• Group: Innovative Artificial Intelligence Applications in Pharmacology Research (PharmAI KTU)
• Hugging Face dataset: pharmaiktu/contractility-signals
• For access & collaboration inquiries, please reach out with your institutional email and HF username.