🇯🇵 日本語はこちら
An integrated Chemoinformatics environment that makes RDKit easy to use from MATLAB
Clone the repo → run one setup command → RDKit is ready to use in MATLAB
A personal hobby project built with MATLAB Home License, shared for personal enjoyment and learning. Not affiliated with MathWorks.
In the Chemoinformatics field, Python + RDKit is the de-facto standard toolchain. However, getting started involves several barriers:
- Managing Python versions and virtual environments
- Complex RDKit installation via conda/pip
- Environment conflicts with commercial tools (e.g., PyMOL)
- The Python ecosystem is unfamiliar to MATLAB users
EasyMolKit removes these barriers. Leveraging MATLAB's pyenv-based Python integration,
users can access RDKit functionality as standard MATLAB functions — no Python knowledge required.
- Zero configuration: One call to
emk.setup.install()automatically deploys Python + RDKit - MATLAB native: Results are returned as MATLAB
table/struct/double— immediately usable in your workspace - Desktop & Online: Supports Windows Desktop and MATLAB Online (macOS / Linux Desktop untested)
- Rich API: 76 functions across 15 modules — descriptors, fingerprints, scaffolds, filters, clustering, 3D conformers, and more
- Reproducible research: 10 published papers reproduced with locked environments under
repro/
- Chemistry, pharmacy, and medical researchers who use MATLAB as their primary research environment
- Students learning Chemoinformatics (MATLAB Online Basic free tier covers Layers 1–3)
- MATLAB users who want to avoid spending time on Python environment setup
| Item | Desktop | MATLAB Online |
|---|---|---|
| MATLAB | R2025b or later | R2025b or later |
| Python | Auto-deployed (Embedded Python) | Pre-installed |
| RDKit | Auto-deployed | Installed via emk.setup.installOnline() |
| OS | Windows | — |
% 1. Clone the repository
% git clone https://github.com/ynoda/EasyMolKit.git
% cd EasyMolKit
% 2. Open main_emk.m in MATLAB, then run each section with Ctrl+Enter:
%
% Section 0a — Path setup & config (edit cfg.useCase.* here if needed)
% Section 0b — Python + RDKit setup (first time only; ~2-5 min)
% Section 1 — Basic molecule operations
% Section 2 — Descriptor calculation
% Section 3 — Fingerprints & similarity
⚠️ Use Ctrl+Enter (Run Section), not F5 (Run File). Running all sections at once will fail on first setup.
For more details, see docs/quickstart.md.
Use these files first when evaluating or citing the repository:
- docs/quickstart.md: one-time environment setup for MATLAB Desktop and MATLAB Online
- LICENSE: MIT license for EasyMolKit
- CONTRIBUTING.md: pull request and reproduction-submission workflow
- CITATION.cff: citation metadata for GitHub and downstream tools
If you are on a corporate PC, local Python deployment may be blocked by IT policy:
| Issue | Symptom | Solution |
|---|---|---|
| Proxy server | pip install times out / SSL error |
Set cfg.python.proxy = "http://proxy.example.com:8080" in Section 0a of main_emk.m |
| Windows Defender / Smart App Control | Embedded Python extraction is quarantined | Whitelist the python_env/ directory, or use MATLAB Online |
| IT policy (executable downloads blocked) | Setup fails at the download step | Use MATLAB Online — no local Python deployment needed |
| Antivirus quarantine | Python binaries disappear after extraction | Whitelist python_env/, or use MATLAB Online |
💡 Recommended for corporate environments: Use MATLAB Online — no local Python installation is needed, and all L1–L3 tutorials run on the free Basic tier.
EasyMolKit manages add-on libraries via two tracks.
| Track | Libraries | Installation | License |
|---|---|---|---|
| Track 1 | pubchempy, mordred, biopython, torch, torch_geometric, transformers, datasets, etc. | emk.setup.installExtra() — added directly to Embedded Python |
MIT / BSD-3 / Apache-2.0 |
| Track 2 | Open Babel, MDAnalysis, PyMOL OSS | Requires a separate CPython environment; connect with emk.setup.useExternal() |
GPLv2 / GPLv2+ / BSD |
% Review installation steps and license before installing
emk.setup.recipe("pubchempy") % Show installation recipe and license
emk.setup.installExtra("pubchempy") % Install into Embedded Python
emk.setup.installExtra("mordred") % 1800+ descriptor library
emk.setup.installExtra("biopython") % PDB / sequence analysis
% PyTorch + HuggingFace stack (required for R09 / R10)
emk.setup.installExtra("torch") % CPU-only, ~800 MB (must be installed first)
emk.setup.installExtra("torch_geometric") % GNN library (requires torch)
emk.setup.installExtra("transformers") % HuggingFace Transformers
emk.setup.installExtra("datasets") % HuggingFace Datasets (used with transformers)
% Verify installation
T = emk.setup.validate()For bulk installation of all libraries, see
main_setup_extra.m.
Open Babel, MDAnalysis, and PyMOL require a separate CPython 3.10+ environment due to GPL
licensing or technical constraints. Connect via emk.setup.useExternal() — which must be called
before Python is loaded in the MATLAB session.
For step-by-step setup instructions, see docs/quickstart.md — Track 2.
EasyMolKit provides progressive learning content under examples/.
| Layer | Audience | Content | Release |
|---|---|---|---|
| L1 Foundation | All users | One API concept at a time (6 modules, 5–15 min each) | ✅ v1.0.0 |
| L2 Application Stories | After Foundation | Practical workflows combining multiple features (7 modules, 20–40 min each) | ✅ v1.1.0 |
| L3 Analytics | All users | QSAR, clustering, MS analysis, optimization (A01–A10, 30–60 min each) | ✅ v1.2.0 |
| L4 Research | All users | Research-level applications (R01–R10, 30–90 min each) | ✅ v1.3.0 |
L1–L3 run entirely on MATLAB Online Basic (free tier).
For the full per-module listing with Toolbox requirements and platform support, see docs/tutorials.md.
repro/ contains MATLAB reproductions of 10 published Chemoinformatics papers,
each with a locked environment snapshot (RF02) and defined success criteria (RF03).
For the full listing with methods, datasets, and results, see docs/repro.md.
Some reproductions depend on a benchmark dataset that is cached locally under
data/benchmark/ (gitignored, not committed) and fetched on demand. For
example, RP09 fetches its ChEMBL oral-drug snapshot via a one-time
RP09_REFRESH_DATASET=true run, after which Tier 1 and Tier 2 can be rerun
against that local snapshot on a fresh clone after the standard EasyMolKit
setup. See repro/rp09_qed/README.md for the exact
run steps, expected outputs, and current open work.
Experiments under repro/ establish evidence-based boundaries for MATLAB in Chemoinformatics workflows.
Results are stated as conditions, not verdicts — "MATLAB is X, Python is Y."
| Zone | Task type | Key condition | Outcome |
|---|---|---|---|
| A — MATLAB native | Statistics, filters, visualization | Default settings | Equivalent to or better than Python alternatives |
| B — Conditionally equivalent | Classical ML (LR, Ridge, RF) and linear SHAP | Solver and regularization configured explicitly | Gap < 1σ (practical tie); SHAP Spearman ρ = 0.915–0.927 |
| C — Division of labor | Full ML / DL / LLM pipeline | RDKit (Python) for feature extraction; MATLAB for model training | Fully functional: GCN Δ = −0.017 < 1σ, ChemBERTa AUC = 0.914 |
| D — Python advantage | Non-linear SHAP (TreeSHAP / KernelSHAP) | Requires shap library |
TreeExplainer / KernelExplainer unavailable in MATLAB |
Zone B — conditions required for practical parity:
- Use the
lbfgssolver explicitly — the default SGD solver fails on high-dimensional sparse features - Set regularization scale explicitly —
Lambda = 1/n(MATLAB) ≡C ≈ n(sklearn) give equivalent performance despite opposite conventions - Preprocessing (SMILES → fingerprints) requires RDKit; only the ML training step runs in MATLAB
Zone C — tested pipelines (RP03, RP04, all RP):
- Descriptor pipeline (SMILES → features → ML/statistics): Fully functional across all RP — no capability gap
- GCN / deep learning (RP03): MATLAB Deep Learning Toolbox 3-layer GCN achieves AUC = 0.887 ± 0.015 vs Python 0.904 ± 0.020 (Δ = −0.017 < 1σ — practical tie); requires Python for RDKit graph featurization
- LLM embedding (RP04): Python tokenizes → MATLAB runs ONNX inference + logistic regression, AUC = 0.914 ± 0.009 (RF03 PASS); ONNX fidelity confirmed (F1-a and F1-b results match exactly)
| Module | Example functions | Description |
|---|---|---|
emk.setup |
install(), verify(), snapshot(), verifyLock() |
Python environment deployment, initialization & RF02 version lock |
emk.mol |
fromSmiles(), toSmiles(), isValid(), hasSubstruct() |
Molecular object creation & conversion |
emk.descriptor |
molWeight(), calculate(), qed(), saScore(), bcut() |
Molecular descriptor calculation |
emk.fingerprint |
morgan(), maccs(), toArray() |
Fingerprint generation |
emk.similarity |
tanimoto(), dice(), rankBy(), matrix() |
Molecular similarity calculation |
emk.scaffold |
genericMurcko(), brics(), rgroup() |
Scaffold analysis & fragment decomposition |
emk.dataset |
esol(), freesolv(), bbbp(), tox21() |
Benchmark dataset loaders with local cache |
emk.filter |
lipinski(), veber(), pains(), reos() |
Medicinal chemistry filters |
emk.cluster |
butina() |
Butina sphere-exclusion clustering |
emk.diversity |
pick() |
MaxMin diverse subset selection |
emk.conformer |
embed(), optimize() |
3D conformer generation & force-field optimization |
emk.shape |
compare() |
3D shape similarity comparison |
emk.repro |
verify() |
RF03 reproduction success verification |
emk.io |
readSdf(), writeSdf(), readSmilesList() |
SDF / SMILES file I/O |
emk.viz |
draw2d() |
2D structure rendering (※) |
※ Rendering note:
emk.viz.draw2d()generates a PNG via RDKit (Python) and transfers it to MATLAB. Rendering takes 0.5–2 seconds per molecule. On MATLAB Online, inter-process communication overhead adds further latency when rendering many molecules in sequence (this is a structural constraint and cannot be improved).
For full API details, see docs/function_reference.md.
EasyMolKit/
├─ main_emk.m # RDKit setup & basic operations (run section by section)
├─ config/
│ └─ settings.example.json # Configuration template
├─ examples/
│ ├─ japanese/ # Distribution materials — Japanese (plain-text Live Code)
│ └─ english/ # Distribution materials — English (comments differ only)
├─ repro/ # Reproducible research (RP00–RP09)
├─ src/
│ └─ +emk/ # Main package (15 modules, 76 functions)
├─ tests/
│ ├─ unit/ # matlab.unittest class-based tests
│ └─ smoke/ # Smoke tests
├─ data/ # Curated sample data
└─ docs/ # Documentation
EasyMolKit: MIT License
| Library | License | Purpose |
|---|---|---|
| RDKit | BSD-3-Clause | Chemoinformatics core |
| Python (CPython) | PSF License | Runtime environment |
For details, see THIRD_PARTY_NOTICES.md and docs/compliance.md.
Bug reports, feature requests, and pull requests are welcome. See CONTRIBUTING.md for guidelines.
| File | Description |
|---|---|
| docs/quickstart.md | Setup steps, Track 2 setup & FAQ |
| docs/tutorials.md | Full tutorial listing (F01–R10, RP00–RP09) |
| docs/repro.md | Reproducible research index (RP00–RP09 with methods and results) |
| docs/function_reference.md | Full function signature reference |
| docs/function_catalog.md | Compact function catalog (76 functions) |
| docs/python_integration.md | Python integration architecture |
| docs/platform_support.md | Desktop / Online platform support |
| docs/compliance.md | License & compliance |
| CITATION.cff | Repository citation metadata |
| File | Description |
|---|---|
| docs/ja/README.ja.md | このリポジトリの概要（日本語版） |
| docs/ja/tutorials.ja.md | チュートリアル一覧（日本語版） |
| docs/ja/quickstart.ja.md | セットアップ手順・Track 2・FAQ（日本語版） |
| docs/ja/function_catalog.ja.md | コンパクト関数カタログ・76 関数（日本語版） |
| docs/ja/function_reference.ja.md | 関数シグネチャ詳細リファレンス（日本語版） |
| docs/ja/test_catalog.ja.md | テストクラスカタログ（日本語版） |