TUTORIAL QSAR/ADMET STUDIO V1.0.1
=================================


BAGIAN KHUSUS V1.0.1 — PERBAIKAN VISIBILITAS RUANG KANAN
----------------------------------------------------------
Versi 1.0.1 memperbaiki seluruh tampilan main/right pane, bukan hanya Job
Specification. Prinsipnya dibuat sederhana dan konsisten:

    PERMUKAAN / BACKGROUND : putih atau biru sangat muda
    TEKS NORMAL            : biru-hitam gelap (#10243E)
    HEADING                : biru sangat gelap (#071B2F)
    HERO GELAP             : teks putih + aksen kuning

Komponen yang dipaksa memakai kontras eksplisit:
- markdown dan caption;
- heading;
- text input, textarea dan number input;
- selectbox dan multiselect;
- dropdown/menu/popover yang dirender di luar panel utama;
- radio, checkbox, toggle dan slider;
- file uploader;
- tombol biasa, tombol primary dan tombol download;
- tabs dan tab panel;
- expander;
- info/success/warning/error alert;
- st.status, spinner dan progress;
- metric;
- code, log, JSON dan preformatted text;
- toast, dialog dan exception;
- Plotly container;
- Job Specification.

PERUBAHAN PENTING PADA TABEL/DATAFRAME:
Output tabel utama tidak lagi hanya bergantung pada canvas st.dataframe. V1.0.1
memakai renderer tabel HTML kontras-tinggi dengan header biru muda, sel putih,
dan teks gelap. Ini sengaja dilakukan karena canvas/grid dapat mewarisi warna
dari theme browser/Streamlit dan menyebabkan tulisan tidak tampak.

JOB SPECIFICATION:
Tetap memakai panel HTML putih dengan border biru dan teks monospace gelap.
Tidak memakai warna bawaan st.json.

PAKET DEB:
Launcher memaksa theme Streamlit light melalui parameter:
    --theme.base light
    --theme.backgroundColor '#FFFFFF'
    --theme.secondaryBackgroundColor '#F3F7FB'
    --theme.textColor '#10243E'
    --theme.primaryColor '#11698E'

Setelah upgrade dari 1.0.0 ke 1.0.1, cukup jalankan:
    sudo apt install ./qsar-admet-studio_1.0.1_all.deb

Kemudian restart aplikasi. Bila browser masih menampilkan CSS lama, lakukan
hard refresh (Ctrl+F5) satu kali. Data run lama tetap berada di:
    ~/.local/share/qsar-admet-studio/

A. TUJUAN
---------
QSAR/ADMET Studio menyatukan:
1. kurasi dataset;
2. descriptor/fingerprint;
3. descriptor eksternal dari QM/Docking/eksperimen;
4. preprocessing anti-data-leakage;
5. train/validation/test split;
6. cross-validation;
7. model regression/classification;
8. evaluasi;
9. Y-randomization;
10. applicability domain;
11. explainability;
12. prediction/screening dan ekspor model.

Port default:
    http://localhost:8807

B. INSTALASI DI WSL/UBUNTU
--------------------------
1. Simpan file:
       qsar-admet-studio_1.0.1_all.deb

2. Jalankan:
       sudo apt update
       sudo apt install ./qsar-admet-studio_1.0.1_all.deb

3. Jalankan aplikasi:
       qsar-admet-studio

4. Buka browser:
       http://localhost:8807

5. Jika ingin port lain, contoh 8812:
       QSARADMET_PORT=8812 qsar-admet-studio

6. Cek paket:
       dpkg -s qsar-admet-studio | grep '^Version:'

C. FIRST RUN DAN DEPENDENSI
---------------------------
Launcher DEB membuat virtual environment user-writable di:
    ~/.local/share/qsar-admet-studio/venv

Pada eksekusi pertama launcher memasang dependensi inti:
    streamlit
    numpy
    pandas
    scipy
    plotly
    rdkit
    scikit-learn
    joblib
    psutil
    openpyxl
    XlsxWriter
    reportlab

Karena itu koneksi internet mungkin diperlukan pada first run bila paket belum
tersedia pada cache Python lokal.

D. DATA RUNTIME
---------------
Data penelitian tidak ditulis ke /opt. Workspace default:
    ~/.local/share/qsar-admet-studio/

Subfolder utama:
    runs/
    cache/
    imports/

Database:
    qsar_admet_studio.sqlite3

Lokasi dapat diubah:
    QSARADMET_HOME=/lokasi/yang/writable qsar-admet-studio

E. UJI CEPAT DENGAN 20 CONTOH JURNAL
------------------------------------
1. Buka menu "Aplikasi".
2. Pilih sumber dataset:
       20 contoh jurnal Delaney ESOL
3. SMILES column:
       SMILES
4. Endpoint:
       measured log(solubility:mol/L)
5. Tipe endpoint:
       Regression
6. Unit/konteks endpoint:
       log10(mol/L)
7. Descriptor mode:
       Core physicochemical
8. Aktifkan Morgan fingerprint bila ingin.
9. Pilih model Random Forest untuk demo.
10. Klik tombol menjalankan model.

PENTING:
20 contoh hanya cocok untuk uji workflow. Jangan memakai angka validation dari
20 baris sebagai bukti kinerja model publikasi.

F. UPLOAD DATASET SENDIRI
-------------------------
Format minimal CSV:

    SMILES,Endpoint
    CCO,-0.30
    CCCO,-0.80
    CCN,-0.20

Format yang lebih lengkap:

    Name,SMILES,pIC50,HOMO_eV,LUMO_eV,Gap_eV,Dipole_D,DockingScore_kcalmol
    Mol01,...,...,...,...,...,...,...

Aplikasi dapat memakai kolom numerik tambahan sebagai descriptor eksternal.
Hal ini berguna untuk menggabungkan hasil QM Komputasi/QMScreen/DockFlow.

G. KURASI DATASET
-----------------
Aplikasi dapat:
- parse dan validasi SMILES;
- canonicalize SMILES;
- FragmentParent/salt removal opsional;
- membuang struktur invalid;
- membuang endpoint missing;
- menangani duplicate canonical structure;
- menghitung Bemis-Murcko scaffold;
- menyimpan data curated dan audit trail.

Periksa selalu apakah penggabungan duplikat memang sesuai dengan definisi
endpoint eksperimen Anda.

H. DESCRIPTOR DAN FINGERPRINT
-----------------------------
Pilihan utama:
1. Core physicochemical RDKit
   - MW
   - LogP
   - TPSA
   - HBD
   - HBA
   - Rotatable bonds
   - ring count
   - aromatic rings
   - FractionCSP3
   - heavy atoms
   - MolMR

2. All RDKit 2D descriptors

3. Morgan fingerprint
   128 / 256 / 512 / 1024 bit

4. MACCS keys

5. External numeric descriptors
   Contoh:
   - HOMO
   - LUMO
   - HOMO-LUMO gap
   - dipole
   - atomic/summary charge
   - docking score
   - ligand efficiency
   - interaction/contact descriptors

I. ADMET HEURISTIC PANEL
------------------------
Aplikasi menampilkan beberapa physicochemical flags seperti Lipinski violation
dan Veber-like criteria.

Ini adalah HEURISTIC.
Bukan:
- prediksi toksisitas klinis;
- prediksi PK manusia yang tervalidasi;
- jaminan bioavailability;
- pengganti eksperimen ADME/Tox.

J. PREPROCESSING ANTI-DATA-LEAKAGE
----------------------------------
Preprocessing dimasukkan ke scikit-learn Pipeline:
    SimpleImputer
    -> VarianceThreshold
    -> CorrelationPruner
    -> StandardScaler / RobustScaler / None
    -> SelectKBest / mutual information / None
    -> Model

Dengan cara ini transformasi di-fit pada training fold, bukan seluruh dataset.

K. SPLIT TRAIN / VALIDATION / TEST
----------------------------------
Pilihan:
1. Random
2. Scaffold

Random split cocok untuk baseline.
Scaffold split menguji generalisasi ke kerangka kimia berbeda dan biasanya
lebih sulit.

Atur:
- Test fraction
- Validation fraction
- Random seed

Split assignment disimpan sebagai artifact agar dapat diaudit.

L. CROSS-VALIDATION
-------------------
Aplikasi mendukung:
- KFold untuk regression random split;
- StratifiedKFold untuk classification;
- GroupKFold untuk scaffold split.

Jumlah fold harus disesuaikan dengan ukuran dataset dan distribusi endpoint.

M. PILIHAN MODEL
----------------
Regression:
- Linear / Ridge
- PLS
- Random Forest
- Gradient Boosting
- SVM

Classification:
- Logistic Regression
- Random Forest
- Gradient Boosting
- SVM

Jangan memilih model hanya dari satu metric tertinggi. Pertimbangkan ukuran
data, interpretability, variance CV, applicability domain dan external test.

N. METRIC
---------
Regression:
- R²
- Q² / mean CV R²
- RMSE
- MAE

Classification:
- Accuracy
- Balanced Accuracy
- Precision
- Recall
- F1
- MCC
- ROC-AUC bila binary dan probability/decision score tersedia

Untuk class imbalance, Accuracy saja tidak cukup.

O. Y-RANDOMIZATION
------------------
Aplikasi dapat mengacak target Y beberapa kali dan mengulang evaluasi.
Tujuan: melihat apakah performa model asli secara nyata lebih baik daripada
hubungan target acak.

Jika model Y-randomized sering memberi score tinggi, periksa data leakage,
overfitting, descriptor redundancy, atau ukuran dataset.

P. APPLICABILITY DOMAIN
-----------------------
Aplikasi menggunakan pendekatan kNN distance pada feature space hasil
preprocessing.

Output memberi:
- distance terhadap tetangga training;
- threshold berdasarkan distribusi training;
- status inside/outside AD.

Outside AD = warning dukungan data rendah.
Bukan berarti prediksi pasti salah; inside AD juga bukan jaminan pasti benar.

Q. EXPLAINABILITY
-----------------
Jika model mendukung, aplikasi menampilkan:
- feature importance;
- coefficient;
- ranking feature.

Interpretasi harus mempertimbangkan scaling, correlation dan jenis model.
Feature importance tidak otomatis sama dengan causal mechanism.

R. PREDICTION / SCREENING MOLEKUL BARU
--------------------------------------
Masukkan SMILES baru pada bagian prediction.
Aplikasi menghitung descriptor yang sama, menjalankan pipeline tersimpan, dan
menampilkan prediction serta AD warning.

Jika model dilatih dengan external descriptor yang tidak tersedia untuk
molekul baru, aplikasi akan membutuhkan/impute nilai yang hilang sesuai pipeline;
untuk penggunaan riset sebaiknya sediakan external descriptor tersebut secara
konsisten sebelum screening final.

S. JOB SPECIFICATION DAN KONTRAS RUANG KANAN
--------------------------------------------
Job Specification dirender dengan panel khusus:
    background putih
    teks #10243E
    heading #071B2F
    border biru
    monospace JSON

Seluruh main/right pane juga dipaksa:
- light color-scheme;
- background putih/terang;
- teks gelap;
- alert terang + teks gelap;
- code/log terang + teks gelap;
- input/selectbox putih + teks gelap;
- tabel/dataframe light surface;
- hero gelap + teks putih/kuning.

T. PUSAT HASIL
--------------
Pusat Hasil menampilkan:
- run history;
- status;
- job specification;
- metrics;
- prediction;
- CV results;
- applicability domain;
- Y-randomization;
- feature importance;
- provenance;
- log;
- file artifact;
- export.

U. EKSPOR
---------
Output dapat mencakup:
- curated_dataset.csv
- descriptor/features.csv
- split_assignment.csv
- predictions_test.csv
- cross_validation.csv
- feature_importance.csv
- y_randomization.csv
- applicability_domain_test.csv
- model.joblib
- result.json
- XLSX
- PDF
- ZIP proyek
- integration_manifest.json

V. SUMBER 20 CONTOH
--------------------
John S. Delaney.
ESOL: Estimating Aqueous Solubility Directly from Molecular Structure.
Journal of Chemical Information and Computer Sciences. 2004;44(3):1000-1005.
DOI: 10.1021/ci034243x

File:
    QSAR_ADMET_20_Contoh_Delaney_ESOL.csv

W. SCIENTIFIC CHECKLIST SEBELUM PUBLIKASI
-----------------------------------------
[ ] Endpoint jelas dan satuan konsisten
[ ] Struktur dan duplikat dikurasi
[ ] Missing value didokumentasikan
[ ] Split dilakukan sebelum preprocessing fit
[ ] Feature selection berada di dalam CV/pipeline
[ ] Seed dan split assignment disimpan
[ ] CV sesuai task dan struktur dataset
[ ] Test set tidak dipakai untuk tuning
[ ] Y-randomization diperiksa
[ ] Applicability domain dilaporkan
[ ] External validation digunakan bila tersedia
[ ] Model, descriptor, parameter dan versi library disimpan
[ ] Raw input tidak ditimpa
[ ] Semua angka penting mempunyai provenance

Copyright © Kasmui, 2026.
