MLCIL · Thematiq · Feb 24, 2026 · Feb 24, 2026 · Feb 24, 2026 · Feb 24, 2026
@@ -19,3 +19,9 @@ wheels/
 
 # OS dependent files
 .DS_Store
+
+# unrelated files
+.coverage
+*.ipynb
+!examples/*.ipynb
+
@@ -13,12 +13,18 @@ test:  ## Run tests without regression
 	uv run ruff check
 	uv run pytest tests -m "not slow"
 
+fix-and-test:
+	$(MAKE) ruff-fix
+	$(MAKE) test-all
+
 test-all:
-	uv run ruff check
 	uv run pytest tests
 
 test-coverage:  ## Run tests and calculate test coverage
 	uv run pytest --cov=bbttest tests
 
+ruff-fix:
+	uv run ruff check --fix
+
 help:
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
@@ -28,6 +28,8 @@ pip install git+https://github.com/scikit-fingerprints/bbt-test
 
 To generate results from BBT model you need to first fit posterior MCMC samples. BBT-Test supports unpaired (1 metric readout per algorithm per dataset) and paired (multiple metric readouts per algorithm per dataset) data.
 
+For hands-on example of using the package, check out our example notebook: [01_simple_bbt_comparison.ipynb](examples/01_simple_bbt_comparison.ipynb).
+
 ### Unpaired posterior fitting
 
 Start with single dataframe in shape (n_datasets, n_algorithms), optionally this dataframe can contain a dataset column:

@@ -20,6 +20,8 @@
     "in_rope",
     "weak_interpretation",
     "strong_interpretation",
+    "weak_interpretation_raw",
+    "strong_interpretation_raw",
 ]
 
 ALL_PROPERTIES_COLUMNS: list[ReportedPropertyColumnType] = list(

@@ -31,6 +31,9 @@ def _validate_params(func):
 
     @wraps(func)
     def wrapper(*args, **kwargs):
+        for kwarg in kwargs:
+            if kwarg not in sig.parameters:
+                raise ValueError(f"Unexpected keyword argument '{kwarg}'")
         bound_args = sig.bind(*args, **kwargs)
         bound_args.apply_defaults()
         for name, value in bound_args.arguments.items():

@@ -4,7 +4,12 @@
 import numpy as np
 import pandas as pd
 
-from ._types import HyperPriorType, ReportedPropertyColumnType, TieSolverType
+from ._types import (
+    ALL_PROPERTIES_COLUMNS,
+    HyperPriorType,
+    ReportedPropertyColumnType,
+    TieSolverType,
+)
 from ._utils import _validate_params
 from .alg import _construct_win_table, _get_pwin, _hdi
 from .model import _mcmcbbt_pymc
@@ -79,6 +84,8 @@ class PyBBT:
         <http://jmlr.org/papers/v24/22-0907.html>`_
     """
 
+    ALL_PROPERTIES_COLUMNS = ALL_PROPERTIES_COLUMNS
+
     _WEAK_INTERPRETATION_THRESHOLD = 0.95
     _STRONG_INTERPRETATION_BETTER_THRESHOLD = 0.70
     _STRONG_INTERPRETATION_EQUAL_THRESHOLD = 0.55
@@ -231,7 +238,7 @@ def posterior_table(
 
         out_table["strong_interpretation_raw"] = np.where(
             out_table["mean"] > self._STRONG_INTERPRETATION_BETTER_THRESHOLD,
-            out_table["left_model"] + ">",
+            ">",
             np.where(
                 out_table["mean"] <= self._STRONG_INTERPRETATION_EQUAL_THRESHOLD,
                 "=",
@@ -262,6 +269,7 @@ def posterior_table(
                 )
         return out_table[["pair", *columns]]
 
+    @_validate_params
     def rope_comparison_control_table(
         self,
         rope_values: Sequence[tuple[float, float]],
@@ -306,8 +314,9 @@ def rope_comparison_control_table(
                 selected_models=selected_models,
                 columns=(
                     "left_model",
-                    "weak_interpretation",
-                    "strong_interpretation",
+                    "right_model",
+                    "weak_interpretation_raw",
+                    "strong_interpretation_raw",
                 ),
             )
             better_models: list[str] = []
@@ -316,18 +325,29 @@ def rope_comparison_control_table(
             unknown_models: list[str] = []
             for _, row in posterior_df.iterrows():
                 interpretation_col = (
-                    "weak_interpretation"
+                    "weak_interpretation_raw"
                     if interpretation == "weak"
-                    else "strong_interpretation"
+                    else "strong_interpretation_raw"
                 )
-                if row[interpretation_col] == f"{row['left_model']} better":
-                    better_models.append(row["left_model"])
-                elif row[interpretation_col] == "Equivalent":
-                    equivalent_models.append(row["left_model"])
-                elif row[interpretation_col] == "Unknown":
-                    unknown_models.append(row["left_model"])
+                non_control_model = (
+                    row["right_model"]
+                    if row["left_model"] == control_model
+                    else row["left_model"]
+                )
+
+                if row[interpretation_col] == ">":
+                    if row["left_model"] == control_model:
+                        worse_models.append(non_control_model)
+                    else:
+                        better_models.append(non_control_model)
+                elif row[interpretation_col] == "=":
+                    equivalent_models.append(non_control_model)
+                elif row[interpretation_col] == "?":
+                    unknown_models.append(non_control_model)
                 else:
-                    worse_models.append(row["left_model"])
+                    raise RuntimeError(
+                        f"Unexpected interpretation value {row[interpretation_col]} in row {row['pair']}. Please report this as a bug."
+                    )
             if not return_as_array:
                 better_models_str = join_char.join(better_models)
                 equivalent_models_str = join_char.join(equivalent_models)

@@ -0,0 +1,26 @@
+dataset,AtomPair_count,CDDD,CLAMP,ChemBERTa-10M-MTR,ChemFM-3B,ChemGPT-4.7M,ECFP_count,GEM,GNN-GraphCL-sum,GraphFP-CP,GraphMVP_CP-max,MoLFormer-XL-both-10pct,SELFormer-Lite,SimSon,TT,chemformer_mask,coati,grover_large,mat_masking_2M,mol2vec,mol_r_tag_1024,molbert,rmat_4M,unimolv1,unimolv2
+AMES,0.8145254459652627,0.8355244864790773,0.8459975719125106,0.8426452446689773,0.8194070767001508,0.7335193561651882,0.8481701227750689,0.7126309502829505,0.7789569014470619,0.5807867786719928,0.8080058352425151,0.8166421899782647,0.7205085276782393,0.7463177269968083,0.8370175644715973,0.8017074937829212,0.8062239323268519,0.8149405706005599,0.8176819597015802,0.8063541483091503,0.8127807476159705,0.8539838258043041,0.8554191388121953,0.7725518416260353,0.8058469913254617
+Bioavailability_Ma,0.7120053209178583,0.6687728633189225,0.641835716661124,0.744595942800133,0.6704356501496508,0.695710009976721,0.6910542068506818,0.7005320917858331,0.6769205187894911,0.6614566012637179,0.648819421350183,0.7223145992683738,0.6696042567342868,0.6311938809444629,0.6915530428999002,0.7031925507149982,0.6217159960093117,0.8839374792151646,0.6867309610907882,0.7263052876621217,0.5874625872963086,0.6835716661124045,0.7283006318589956,0.6601263717991352,0.7653807781842367
+CYP1A2_Veith,0.9288641730543384,0.923714467918524,0.9507841998257334,0.9261630403212568,0.9038250262031344,0.8679914508328177,0.9278665597494602,0.8753829446008915,0.8971167081286542,0.7630870449178547,0.8894167750571418,0.9142961774994002,0.8789724582959755,0.8582107363396432,0.9151504628168052,0.9044431676116632,0.8970137897940371,0.8569611941052419,0.9269052519920696,0.9133440250539848,0.9013234161310284,0.9293585599009964,0.9308565583603784,0.901898622283398,0.9156012830064784
+CYP2C19_Veith,0.8581617924425365,0.8721135770601274,0.9223048361905296,0.8712846316196391,0.8536529402778946,0.7899815755263134,0.8744442262188677,0.770266453429103,0.8349491378530968,0.6038650867134916,0.8503511873030125,0.8550894880739722,0.7905159164383093,0.7917155336082976,0.8512889337810075,0.8396796448534616,0.8488420015649891,0.7794356686587545,0.8746050896439495,0.8515386461908725,0.8513609482213056,0.8851874713578931,0.8807565568992016,0.8265592996829495,0.8631962564961079
+CYP2C9_Substrate_CarbonMangels,0.5963103635377102,0.6551817688551276,0.6977753662506783,0.692078133478025,0.667932718393923,0.6524688008681498,0.6272381985892567,0.5973955507325014,0.6587086272381986,0.5879001627780792,0.6740368963646228,0.6250678241996744,0.6367335865436788,0.5755561584373305,0.5826098752034725,0.6405317417254477,0.6724091155724362,0.5721649484536082,0.6245252306022789,0.644872490504612,0.6049918610960392,0.6466359196961478,0.6663049376017363,0.5949538795442213,0.6793271839392295
+CYP2C9_Veith,0.8717376922652849,0.8812034842053036,0.9155552755310185,0.8796941081962307,0.8565025635371301,0.8259968654753372,0.8819434052908887,0.8048740701046527,0.8287907665409181,0.6694722500059067,0.8384621139927386,0.8659746560292346,0.8167854583257859,0.8095870775676718,0.8695888102194955,0.863039386326227,0.8663519015853764,0.8590219968024698,0.876420183818607,0.8636198246871382,0.8579658667590747,0.8845333259826892,0.8793838060060013,0.8477920502784055,0.8649319146590219
+CYP2D6_Substrate_CarbonMangels,0.7936046511627907,0.8100353892821032,0.8431496461071789,0.8145854398382204,0.7834934277047523,0.7296511627906976,0.804726996966633,0.7669362992922144,0.8211577350859454,0.4970930232558139,0.7930990899898888,0.8303842264914054,0.7306622851365014,0.7831142568250758,0.7832406471183013,0.7906976744186046,0.8312689585439839,0.7520222446916077,0.8303842264914054,0.8120576339737109,0.782355915065723,0.8224216380182002,0.8162285136501517,0.7554347826086957,0.7960060667340749
+CYP2D6_Veith,0.8584982043680441,0.8681169595964715,0.8934522769316356,0.8601299390219312,0.8567858136286035,0.7904575578371347,0.872068073736207,0.7947070531932723,0.8134802170269133,0.5143666067260971,0.8281027517167855,0.8552481777411953,0.8198453264451658,0.758300079932249,0.847481927349548,0.8301848161816788,0.8464835497777305,0.8185724079667531,0.8598931410271655,0.842437302819137,0.8385404764292931,0.8682570736938108,0.8752777723202793,0.8240435791034559,0.8543082241287849
+CYP3A4_Substrate_CarbonMangels,0.6839963833634719,0.6589059674502713,0.64376130198915,0.6583408679927667,0.6338155515370705,0.6499773960216997,0.6637658227848102,0.6177667269439421,0.6317811934900542,0.523508137432188,0.6778933092224231,0.6306509945750453,0.66873869801085,0.6353978300180831,0.589624773960217,0.6421790235081375,0.6017179023508138,0.5752712477396021,0.6808318264014466,0.6348327305605785,0.6192359855334539,0.6772151898734177,0.6462477396021701,0.6625226039783002,0.60623869801085
+CYP3A4_Veith,0.8669962030469048,0.8633300413060452,0.903643473444684,0.8622570183575008,0.8446845993180165,0.8035443789746224,0.87512161594053,0.7692566913791147,0.7938341218628425,0.6597229358655252,0.831473004264065,0.8499916587146413,0.7942605283703799,0.7804099908579513,0.8613992005712112,0.8433620051115396,0.8393291604663111,0.8504447573353264,0.8771281955464209,0.8439282115616888,0.8600512488572438,0.8658360970792156,0.8824839680495404,0.8243925876001788,0.8605303722882482
+DILI,0.9286956521739133,0.9234782608695652,0.888695652173913,0.8965217391304348,0.8860869565217392,0.8130434782608695,0.9152173913043478,0.8910869565217392,0.895,0.6552173913043479,0.9021739130434784,0.9204347826086956,0.7130434782608696,0.8843478260869565,0.9169565217391304,0.8817391304347826,0.883695652173913,0.8956521739130435,0.9352173913043478,0.9221739130434784,0.9230434782608696,0.9215217391304348,0.912608695652174,0.9221739130434782,0.9208695652173912
+HIA_Hou,0.9868312757201646,0.94320987654321,0.9728395061728394,0.9641975308641976,0.9716049382716048,0.8934156378600823,0.9497942386831276,0.920576131687243,0.8,0.6325102880658435,0.931275720164609,0.9806584362139916,0.8987654320987655,0.9238683127572016,0.9139917695473252,0.962962962962963,0.937448559670782,0.9530864197530864,0.9786008230452676,0.9925925925925928,0.9613168724279836,0.9732510288065844,0.9872427983539096,0.9386831275720164,0.9485596707818932
+PAMPA_NCATS,0.7048673705897502,0.7622971928920937,0.7482616533608034,0.7296420293587433,0.7262941024980686,0.6829770795776461,0.7644604687097605,0.6549060005150656,0.6740664434715427,0.4690703064640741,0.6934329126963689,0.7164563481843935,0.7187226371362349,0.5711048158640227,0.728920937419521,0.7227916559361318,0.7376770538243627,0.6671130569147568,0.7455060520216328,0.7203193407159412,0.6732938449652331,0.739943342776204,0.726191089363894,0.7263456090651559,0.7356682977079578
+Pgp_Broccatelli,0.903425753132498,0.91762196747534,0.9329512130098642,0.928918954945348,0.9049586776859504,0.8626699546787523,0.9277525993068516,0.8675686483604372,0.9162556651559584,0.7138762996534258,0.8774993335110637,0.9292188749666755,0.8533724340175954,0.8679018928285791,0.9264196214342842,0.8866302319381498,0.8844308184484136,0.8661690215942415,0.922354038922954,0.8943615035990402,0.9253199146894162,0.9186883497733938,0.9265529192215408,0.8856971474273527,0.8776992801919489
+SARSCoV2_3CLPro_Diamond,0.7265745007680491,0.7402457757296466,0.7379416282642088,0.7714285714285715,0.7204301075268817,0.6728110599078341,0.7331797235023042,0.7503840245775729,0.7152073732718893,0.6287250384024577,0.7516129032258064,0.7485407066052226,0.6359447004608295,0.7585253456221198,0.708141321044547,0.7268817204301076,0.7084485407066051,0.7397849462365591,0.7156682027649769,0.7247311827956988,0.7185867895545314,0.72642089093702,0.7658986175115207,0.6924731182795699,0.7353302611367126
+SARSCoV2_Vitro_Touret,0.5645802805107808,0.6276952061963575,0.6324052752773708,0.5295164329076826,0.52857441909148,0.5626962528783757,0.5938873770148628,0.6161817039983253,0.5480427046263345,0.5545321331379527,0.5520200962947457,0.5869792756960435,0.4967552857441909,0.629997906635964,0.5688716767845928,0.55714883818296,0.4975926313585932,0.486079129160561,0.6083315888633033,0.5449026585723257,0.4785430186309399,0.6133556625497174,0.5830018840276324,0.517479589700649,0.5534854511199497
+hERG,0.8435415403274712,0.8770466949666464,0.9003941782898727,0.8424802910855064,0.751516070345664,0.7612189205579138,0.8045785324439054,0.7328684050939963,0.7152819890842934,0.6704063068526379,0.8154942389326865,0.8308065494238932,0.7897210430563978,0.747725894481504,0.8423286840509401,0.832929047907823,0.8606731352334749,0.9530018192844149,0.8211036992116435,0.8233778047301394,0.8521831412977562,0.8573377804730139,0.8365676167374165,0.8091267434808975,0.78077622801698
+hERG_Karim,0.8707022332602238,0.8634323749475452,0.8596954388812743,0.8684191029915945,0.8326721774356292,0.7821298268757524,0.8783917297552222,0.7649976419540876,0.8106986726938284,0.5694962849028115,0.846036188402616,0.8413800843810004,0.7679469962144103,0.7809715370312728,0.8624753345080254,0.8289131260501322,0.8316733943310697,0.6962339270006486,0.8532706622045324,0.8538285211320167,0.8334478722574932,0.8761459190877873,0.8699798916459933,0.7781623386065469,0.8066255837753172
+ogbg-molbace,0.8709789601808381,0.8112502173535037,0.8342027473482871,0.8262910798122066,0.864545296470179,0.789340984176665,0.8596765779864372,0.7625630325160841,0.7815162580420796,0.6442357850808555,0.8177708224656582,0.8365501651886628,0.7723874108850635,0.7122239610502521,0.8730655538167275,0.8125543383759346,0.8334202747348287,0.8535037384802643,0.838810641627543,0.823074247956877,0.8135106937923839,0.8194227090940706,0.8302903842809947,0.8036863154234045,0.8258563728047296
+ogbg-molbbbp,0.7381365740740741,0.7231867283950617,0.7009066358024691,0.7208236882716049,0.6943479938271606,0.6887056327160495,0.7201003086419753,0.6756847993827161,0.7038966049382716,0.5511188271604938,0.6868248456790123,0.714940200617284,0.646701388888889,0.7098765432098765,0.679783950617284,0.6837384259259259,0.6879822530864199,0.7307098765432098,0.7261766975308642,0.7304205246913581,0.7055844907407406,0.7426215277777777,0.7265142746913581,0.6687885802469136,0.6610725308641976
+ogbg-molclintox,0.685350415319918,0.9361415215653563,0.761158030097661,0.7393515622284781,0.918466096687867,0.7579775310186634,0.7629661488200743,0.6992831821499322,0.6730128940326,0.5836126750773294,0.7893932679943002,0.8836496020574844,0.8100345810308275,0.7490446773016369,0.6624643763250269,0.7107483578354709,0.8784537587321448,0.6691351266812637,0.8898203176589163,0.8933166510270044,0.8905540784763494,0.871610537656831,0.8641139262503041,0.9166136655892676,0.8237766308692177
+ogbg-molhiv,0.8114312752274087,0.8144556673554917,0.93112651847274,0.7870854979818073,0.7817841209756851,0.7468844221105528,0.7893238571621699,0.7427734827986084,0.7545863935059914,0.5222922303826827,0.7017665249323541,0.7801743950250101,0.7613857750289911,0.7546559721685351,0.8008690781977249,0.7757971378358021,0.7881602580196605,0.7304640877575852,0.7759180517974488,0.7801533433886375,0.7757557015848473,0.7794491689215307,0.7774246231155778,0.771157713578528,0.7609693778792924
+ogbg-molmuv,0.7847982062603639,0.7505515332745804,0.9538875049933596,0.7610820032921798,0.6592362259713641,0.6078312235391929,0.7394131645651287,0.6466112111932127,0.6648343348475036,0.5777699271769144,0.6569077928851594,0.7981076630230599,0.597234324900685,0.6090277349727774,0.7801389611725246,0.7427803814620861,0.7555934977158004,0.6485992802102507,0.7541811833214094,0.784767265466513,0.7583653622561716,0.7660191429147382,0.7735443844162032,0.7465818892952342,0.7388285736382725
+ogbg-molsider,0.6869266781940169,0.639254436731632,0.6921749849321256,0.6917469549305515,0.6728463472551298,0.6329586662880131,0.6863617997542489,0.652717459185894,0.6409775235393228,0.5307502431492865,0.6729195664622901,0.6655429178829346,0.5950587662813914,0.5991447413702715,0.6808944388372183,0.6298043585963656,0.6395070055414712,0.5790117403415879,0.655327943527307,0.6825739326709382,0.6628242686972917,0.6399717638635757,0.6873461835744622,0.6144490489451263,0.6218491127682689
+ogbg-moltox21,0.7793677101920942,0.7833803433436679,0.8320623962565512,0.7887222679343062,0.7582697383714505,0.7083346524640269,0.7817977043382754,0.7198347490077192,0.7551421822081971,0.5520488086890106,0.759697908862892,0.7502529731163675,0.7122280489638442,0.7210298631507531,0.7561706408668748,0.7466120217303461,0.748534989937518,0.689452274900356,0.7703849859168921,0.7778255851570117,0.7703945599045738,0.7638956942207354,0.7797656511703458,0.749669751655326,0.7250482371061816