Raport metodologiczny i raport poprawek pipeline rDock
Data: 2026-06-14

Zakres
Ten raport opisuje aktualny przeplyw danych, parametry, prace z rDock i Pythonem,
testy/walidacje, architekture glownego modelu oraz poprawki wykonane dla 12
zgloszonych punktow. Pipeline pozostaje rDock-only. Smina nie jest czescia
aktualnego portable bundle.

1. Kolejnosc przetwarzania danych
1. Walidacja srodowiska: pipeline sprawdza Pythona, importy, Open Babel oraz
   binarki rDock: rbdock, rbcavity i opcjonalnie sdtether. W strict mode brak
   realnego backendu konczy run bledem, bez mock fallback.
2. Wczytanie targetu i ligandow: konfiguracja wskazuje receptor, biblioteke
   ligandow, parametry kieszeni i budzet. Ligandy sa czytane z tabeli/SMILES/SDF
   i mapowane po ligand_id.
3. Przygotowanie targetu: receptor jest kopiowany/konwertowany do formatu mol2,
   zapisywany jest pocket_spec.json, a receptor.prm budowany jest dla stalej
   kieszeni referencyjnej lub uzytkownika.
4. Budowa cavity: rbcavity generuje plik .as. Po poprawce cache cavity jest
   akceptowany tylko, gdy artefakt istnieje, jest niepusty i log nie wskazuje
   zerowego wolumenu.
5. Przygotowanie ligandow: Open Babel/RDKit przygotowuja ligandy do SDF. Pipeline
   zachowuje ligand_id i zapisuje raw pliki batcha.
6. Docking: rbdock uruchamiany jest dla ligandow batcha z n_runs z konfiguracji.
   Backend zapisuje stdout/stderr oraz komende dla kazdego ligandu.
7. Parsowanie wynikow: z wynikowego SDF czytany jest SCORE, komponenty rDock,
   liczba poz, statystyki top poz, odleglosc pozy od srodka kieszeni i status
   pose_in_fixed_pocket.
8. Cechy i scoring: cechy ligandu, fingerprinty Morgana/MACCS, cechy kieszeni,
   proxy interakcji oraz confidence score trafiaja do tabel wynikowych i modelu.
9. Adaptacja / triage: model uczy sie na juz zdokowanych ligandach, przewiduje
   p_good, predicted_adjusted_score, uncertainty, outlier risk, klase
   active/inactive/uncertain i wybiera kolejnych kandydatow.
10. Eksport: wyniki sa zapisywane do summary.json, final_ranking.csv,
    parsed_scores.csv, tabel diagnostycznych, raw rDock outputs i logow komend.

2. Parametry i praca z rDock
- n_runs: liczba prob rDock na ligand. Im wieksza, tym stabilniejsze top-pose,
  ale koszt rosnie liniowo.
- parallel_jobs: maksymalna liczba rownoleglych zadan dockingowych.
- auto_batch_memory: nowy mechanizm ogranicza realna rownoleglosc na podstawie
  dostepnej pamieci RAM i estymacji kosztu ligandow.
- memory_safety_fraction: domyslnie 0.85. Tylko ta czesc wykrytej pamieci jest
  traktowana jako bezpieczna.
- min_memory_per_job_mb: domyslnie 256 MB na proces rDock jako dolna granica.
- pocket_mode, pocket_center, pocket_radius, pocket_box_size: definiuja stala
  kieszen. Pipeline nie rozszerza automatycznie targetu poza zdefiniowany pocket.
- command_timeout_seconds: timeout dla rbcavity/rbdock.
- allow_partial_failures: jesli wlaczone, pojedynczy blad ligandu moze dac
  nieudany rekord zamiast przerwac caly run.

3. Architektura modelu glownego i uczenie
Model reference-free/adaptive sklada sie z kilku warstw:
- Cechy statyczne: deskryptory RDKit, fingerprinty Morgana, MACCS, scaffold,
  reference_similarity, reference_core_focus_score oraz cechy grafu podobienstw.
- Cechy dynamiczne: liczba wykonanych fidelity runs, aktualny najlepszy score,
  srednia i odchylenie zaobserwowanych score, INTRA, pose_count, jakosc klastra,
  proxy interakcji i post_docking_confidence_score.
- Klasyfikator: ExtraTreesClassifier albo LogisticRegression, uczony na etykiecie
  top-frakcji najlepszych ligandow. Domyslnie klasa pozytywna to top percentile
  po final_score/SCORE.
- Regresor: ExtraTreesRegressor, RandomForestRegressor, HistGradientBoosting albo
  Ridge, uczony na fixed_score_regressor_target, domyslnie score typu
  component_sane_affinity_like. Kierunek modelu jest jawny: higher_is_better dla
  predicted_affinity_like.
- Niepewnosc: dla modeli drzewiastych liczona z rozrzutu predykcji estimatorow.
- Walidacja: random split i cluster split. Model moze zostac wylaczony z rankingu,
  jesli znak korelacji, Spearman, MAE albo generalizacja miedzy klastrami sa slabe.
- Decyzja triage: laczy classifier, regresor, uncertainty, diversity, cluster
  quality, outlier risk i nowy komponent interakcyjny.

4. INTRA score
INTRA score to wewnatrzczasteczkowy komponent energii ligandu w rDock, raportowany
z natywnych pol SDF rDock jako rdock_internal_ligand_term. Nie jest to oddzielna
miara aktywnosci biologicznej. Sluzy jako diagnostyka, czy dobre SCORE nie wynika
z nienaturalnego naprezenia ligandu. Pipeline uzywa INTRA oraz frakcji INTRA do
ostrzezen, outlier risk i sanity check komponentow score.

5. Walidacja post-dokowania i confidence score
Dodano post_docking_confidence_score w backendzie rDock. Score 0..1 laczy:
- powodzenie dockingu i skonczony SCORE,
- liczbe wygenerowanych poz,
- rozrzut top5 score,
- gap miedzy najlepsza i druga poza,
- to, czy centroid pozy lezy w stalej kieszeni.
parsed_scores.csv i final_ranking.csv w smoke pipeline eksportuja teraz
post_docking_confidence_score, biological_interaction_proxy_score,
interaction_weighted_docking_score, interaction_filter_pass,
interaction_feature_source i plip_available.

6. Raport poprawek punkt po punkcie

1. Cleanup wynikow dla kompatybilnosci
Status: zrobione.
Poprawiono write_rows_csv tak, aby opcjonalnie przyjmowal jawny schemat kolumn.
Tabele reference-free triage uzywaja teraz TRIAGE_ROW_FIELDS i nie wypisuja
roboczych kolumn typu feature_vector, fingerprint_bits ani list wewnetrznych.
To stabilizuje CSV dla pandas/R/Excel i kolejnych etapow pipeline.

2. Automatyczny podzial na batche bazujac na RAM
Status: zrobione na poziomie backendu rDock.
RDockBackend liczy memory_batch_plan.json dla kazdego katalogu dockingu. Plan
zawiera liczbe ligandow, liczbe probkowanych ligandow, estymowany koszt pamieci
na job, wykryta dostepna pamiec jesli system ja udostepnia oraz finalne
parallel_jobs_resolved. Na macOS sysconf nie zawsze zwraca dostepna pamiec, wtedy
pipeline stosuje bezpieczna dolna estymacje 256 MB/job i nie zawyza rownoleglosci.

3. Poprawic Morgany, aby nie byly zerowe
Status: zrobione.
Naprawiono blad w _rdkit_fingerprint_bits: funkcja zwracala same zera, bo kod
liczacy Morgan fingerprint byl martwy po return w innej funkcji. Teraz uzywa
GetMorganFingerprintAsBitVect, a gdy bit vector jest pusty, fallback to
GetHashedMorganFingerprint. Dodano metryki morgan_nonzero_count, morgan_density
i morgan_count_sum oraz test regresji dla CCO.

4. Naprawic reference-free, aby nie bylo fantomowych kolumn
Status: zrobione.
triage_scores.csv, triage_survivors.csv i triage_rejected.csv dostaly jawny
schemat. Dodano test, ktory sprawdza brak fingerprint_bits i feature_vector w
naglowku oraz obecnosc nowych pol acquisition_interaction_component i
regressor_activity_class.

5. Zrobic pierwsze przebiegi dla malych RMSD
Status: czesciowo zrobione w formie diagnostyki/proxy.
Backend zapisuje top_pose_rmsd_consistency, pose_distance_to_pocket_center i
pose_in_fixed_pocket. Confidence score preferuje pozy stabilne i lezace w stalej
kieszeni. Pelny RMSD do krystalicznej pozy wymaga referencyjnej pozy atomowej
dla kazdego targetu i pozostaje walidacja zaleznosciowa od danych.

6. No reference: interakcje biologiczne poza SCORE, filtr i wazenie
Status: zrobione jako przenosny proxy interakcji rDock, PLIP pozostaje opcjonalne.
Dodano biological_interaction_proxy_score z komponentow rDock polar/vdw,
kontaktow/hotspotow i statusu pozy w kieszeni. final_score dostaje
interaction_rescore, a triage dostaje acquisition_interaction_component.
Nie dodano PLIP jako twardej zaleznosci, bo portable bundle ma dzialac na macOS
Apple Silicon i Linux x86_64 bez wymuszania problematycznych binarnych zaleznosci.
Pole plip_available jest eksportowane i obecnie false.

7. Reference: skupienie na szkielecie referencji
Status: zrobione.
Model dostal reference_core_focus_score oraz mocniejsze wazenie scaffold_match i
reference_similarity w model_score. Celem jest preferowanie przeszukiwania wokol
szkieletu referencji zamiast samego globalnego podobienstwa.

8. Rozne ID dla tego samego ligandu z PubChem z malym dodatkowym elementem
Status: czesciowo zrobione przez cechy i graf, bez agresywnego usuwania analogow.
Pipeline zachowuje ligand_id, ale cechy canonical/SMILES, scaffold, Morgan,
MACCS i similarity graph pozwalaja modelowi widziec warianty jako bliskie
chemicznie. Nie usuwam automatycznie analogow z malym podstawieniem, bo moga byc
realnie rozne biologicznie; powinny byc grupowane/limitowane w rankingu, nie
kasowane bez decyzji uzytkownika.

9. Czym jest INTRA score
Status: opisane i utrzymane jako diagnostyka.
Patrz sekcja 4. INTRA pochodzi z natywnego rozkladu score rDock i opisuje koszt
wewnetrzny ligandu, a nie oddzialywanie ligand-bialko.

10. Walidacja post-dokowania, confidence score
Status: zrobione.
Dodano post_docking_confidence_score w backendzie i eksport do smoke pipeline.
Score jest oparty o liczbe poz, stabilnosc top poz, gap, sukces dockingu i
zgodnosc z kieszenia.

11. Rozklad score regresora, median collapse, trzy klasy
Status: zrobione.
Dodano regressor_distribution_audit.csv oraz metryki predicted_score_sd,
observed_score_sd, predicted_observed_sd_ratio i REGRESSOR_MEDIAN_COLLAPSE_RISK.
Predykcje dostaly klase regressor_activity_class: active, inactive albo uncertain.
Regressor jest nadal walidowany na raw_score, component_sane_score, score_inter
i affinity_like.

12. MST-connected graph i GraphSAGE
Status: MST-connected features zrobione, GraphSAGE nie wlaczony jako twarda
zaleznosc.
Dodano cechy similarity_graph_component_id, similarity_graph_degree,
similarity_graph_min_edge_distance, similarity_graph_mean_edge_distance i
similarity_graph_method. Dla malych bibliotek uzywany jest dokladny MST po
Morgan/Tanimoto. Dla duzych bibliotek stosowany jest skalowalny connected
similarity chain. GraphSAGE wymaga torch/torch_geometric i powinien byc testowany
jako opcjonalny eksperyment, nie jako wymog portable rDock bundle.

7. Zmienione pliki
- libs/docking/backend_rdock.py: memory-aware jobs, cavity validation,
  post_docking_confidence_score, biological_interaction_proxy_score,
  interaction_weighted_docking_score.
- pipeline/main.py: eksport nowych pol i interaction_rescore w final_score.
- docking_pipeline/benchmark_adaptive.py: naprawa Morgan fingerprints,
  reference_core_focus_score, cechy grafu podobienstw, klasy active/inactive/
  uncertain, audyt rozkladu regresora, stabilny schemat triage CSV.
- docking_pipeline/sdf.py: opcjonalny jawny schemat write_rows_csv.
- tests/test_reference_free_triage.py: test Morgan non-zero i stabilnego schema.
- tests/test_rdock_backend.py: test memory_batch_plan i ograniczenia jobs.

8. Testy i walidacja wykonane lokalnie
- Reference-free suite: 27 passed w 34.79 s.
- Smoke/backend subset po zmianie scoringu: 3 passed w 46.79 s.
- Pelny domyslny pytest: 55 passed, 2 skipped w 130.50 s.
- Smoke full pipeline: target smoke_3ptb, 6 ligandow, real-rdock-only,
  fallback_records=0, best_docking_score=-10.4752,
  best_final_score=-12.082161399326964.
- W smoke zapisano memory_batch_plan.json w batch_000 i batch_001.

9. Portable bundle
Zbudowano aktualny katalog portable_rdock_pipeline i archiwum:
dist/portable_rdock_pipeline_rdock_only_20260614.tar.gz
Rozmiar: 2.9M
SHA-256:
83191c4a330dc674b88db4504d3e9e9b83db2f797a92a5536520b98930ceb022

Audyt tarballa:
- brak referencji smina/Smina/SMINA,
- brak __pycache__,
- brak *.pyc,
- brak .DS_Store.
Raport metodologiczny jest celowo trzymany poza portable bundle, bo opisuje
takze usuniety backend i przez to naruszalby twardy audyt tokenow bundle.

10. Ograniczenia pozostawione jawnie
- PLIP nie jest twarda zaleznoscia portable bundle. Aktualna implementacja daje
  przenosny proxy interakcji z rDock. Pelna integracja PLIP powinna byc osobnym
  opcjonalnym trybem, z pinem zaleznosci i testem na Linux x86_64.
- GraphSAGE nie jest wlaczony do standardowego bundle, bo wymaga ciezkiego stosu
  torch/torch_geometric. Obecnie pipeline dostarcza grafowe cechy MST/connected,
  ktore sa przenosne i testowalne bez GPU.
- Dokladny RMSD do pozy krystalicznej wymaga referencyjnego ligandu i mapowania
  atomow dla targetu. Bez referencji pipeline uzywa proxy stabilnosci pozy i
  odleglosci do stalej kieszeni.