Integrate kernel mixtures, nested groups, and reconstruction statistics

.github/workflows/candidate.yml

@@ -0,0 +1,58 @@
+name: release-candidate (no publication)
+on:
+  workflow_dispatch:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  wheel:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: pyvista/setup-headless-display-action@v5
+      - if: runner.os == 'Linux'
+        run: sudo apt-get install -y --no-install-recommends libegl1 libegl-mesa0
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - name: Install the built wheel
+        shell: python
+        run: |
+          import glob, subprocess, sys
+          wheel, = glob.glob('dist/*.whl')
+          subprocess.run([sys.executable, '-m', 'pip', 'install', wheel + '[dev]'], check=True)
+      - run: python scripts/check_installed.py
+        env:
+          HTFA_DATA_DIR: ${{ runner.temp }}/htfa-data
+      - name: Install tutorial dependencies
+        shell: python
+        run: |
+          import glob, subprocess, sys
+          wheel, = glob.glob('dist/*.whl')
+          subprocess.run([sys.executable, '-m', 'pip', 'install', wheel + '[docs,tutorials]'], check=True)
+      - name: Execute all notebooks against the installed wheel
+        run: python scripts/check_tutorials.py "${{ runner.temp }}/executed-tutorials"
+        env:
+          HTFA_DATA_DIR: ${{ runner.temp }}/htfa-data
+          HTFA_DATA: ${{ runner.temp }}/htfa-data
+          NILEARN_DATA: ${{ runner.temp }}/nilearn-data
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: tutorials-${{ matrix.os }}-${{ matrix.python }}
+          path: ${{ runner.temp }}/executed-tutorials/*.ipynb
+      - uses: actions/upload-artifact@v4
+        with:
+          name: candidate-${{ matrix.os }}-${{ matrix.python }}
+          path: dist/*

README.md

@@ -23,6 +23,7 @@ htfa is a from-scratch Python implementation of these algorithms, ported from th
 - Analytic Jacobian for the center/width least-squares problem (`htfa/_kernels.py`).
 - A NumPy engine and a torch engine (CUDA, Apple Metal, CPU), chosen with the estimators' `backend` argument; `auto` uses a GPU only for large problems when torch is already installed.
 - Two solver modes: `mode='fast'` (the default) and `mode='exact'`, the reference that the equivalence tests and the BrainIAK cross-checks use. On real fMRI the fast mode fitted TFA 2.8 (K = 50) and 5.2 (K = 100) times faster and can end at a different local minimum of the same objective; its HTFA template differs from the exact one by 15.8 mm (median center distance) on 12 adults (see the Performance and Validation pages of the docs).
+- Factor shapes: Gaussian (`kernel='rbf'`, the default), `'laplace'` and `'mexican_hat'`, and mixtures of several components per factor (`n_components`).
 - Inputs: NIfTI files and folders, nilearn/nibabel objects, numpy arrays and 2D images.
 - Synthetic data with ground truth (`htfa.synthetic`), factor-level connectivity, a results object, and BrainNet Viewer-style 3D network plots (`htfa.brainnet`).
 

docs/_static/validation/groups_power.csv

@@ -0,0 +1,101 @@
+seed,center_p0,center_p1,center_rejections,center_fwe_rejections,width_p0,width_p1,width_rejections,width_fwe_rejections,connectivity_p0,connectivity_p1,connectivity_rejections,connectivity_fwe_rejections,center_shift_est,width_ratio_est,seconds
+0,0.025,0.85,1.0,1.0,0.7,0.025,1.0,1.0,1.0,0.9,0.0,0.0,3.0513183158698034,1.7895344474972865,4.058916500071064
+1,0.025,0.425,2.0,1.0,0.675,0.025,1.0,1.0,0.6,0.35,0.0,0.0,2.2402582398380586,1.7619521618446732,4.364262250019237
+2,0.025,0.55,1.0,1.0,0.225,0.025,1.0,1.0,0.1,0.05,2.0,1.0,2.6579227774930727,1.8388024976087074,3.5305851249722764
+3,0.05,0.975,1.0,1.0,0.375,0.05,2.0,1.0,0.075,0.4,0.0,0.0,2.3401555951551707,1.6810487345210805,3.807262458023615
+4,0.05,0.3,1.0,1.0,0.95,0.05,1.0,1.0,0.55,0.45,0.0,0.0,2.3532922796453066,1.7160316330890433,4.013186249998398
+5,0.075,0.225,0.0,0.0,0.775,0.075,0.0,0.0,0.5,0.975,0.0,0.0,2.834756251594854,1.7543138724836127,4.384822416934185
+6,0.05,0.05,2.0,1.0,0.075,0.05,2.0,1.0,0.15,0.125,0.0,0.0,2.638513509353019,1.817190320707756,3.936771792010404
+7,0.025,0.475,1.0,1.0,0.55,0.025,1.0,1.0,0.5,0.975,0.0,0.0,2.780211318999436,1.7127894244483124,4.192237708950415
+8,0.025,0.775,1.0,1.0,0.7,0.025,1.0,1.0,0.25,0.125,1.0,0.0,2.799351594064487,1.74994761395829,4.32629925000947
+9,0.025,0.875,1.0,1.0,0.1,0.025,1.0,1.0,0.725,0.3,0.0,0.0,2.360963892892581,1.640341863868602,3.6720519999507815
+10,0.025,0.775,1.0,1.0,0.35,0.025,1.0,1.0,0.525,0.95,0.0,0.0,2.3428722539675144,1.7027436818154225,3.3640992909204215
+11,0.025,0.45,1.0,1.0,0.3,0.025,1.0,1.0,0.125,0.1,1.0,1.0,2.3541317194662756,1.7875388149306697,4.111222542007454
+12,0.05,0.425,1.0,1.0,0.375,0.05,1.0,1.0,0.725,0.175,2.0,1.0,2.2389556639338366,1.740114053902086,4.515884166001342
+13,0.025,0.725,1.0,1.0,0.7,0.025,2.0,1.0,0.875,0.85,0.0,0.0,2.8519693645626276,1.7294531920073912,3.959485459025018
+14,0.025,0.45,1.0,1.0,0.375,0.025,2.0,1.0,0.225,0.025,3.0,1.0,2.748460436687786,1.6763864074101604,3.7510809999657795
+15,0.025,0.075,2.0,1.0,0.3,0.025,1.0,1.0,0.375,0.2,0.0,0.0,2.017200869712494,1.7323092460690388,3.514311583014205
+16,0.025,0.25,1.0,1.0,0.6,0.025,2.0,1.0,0.75,0.825,0.0,0.0,2.581405321057648,1.740165312031251,3.3849037080071867
+17,0.025,0.975,1.0,1.0,0.025,0.025,3.0,1.0,0.975,0.9,0.0,0.0,2.334507748157944,1.7124089454782072,3.3231987910112366
+18,0.025,0.3,1.0,1.0,0.85,0.025,1.0,1.0,0.8,0.825,0.0,0.0,2.296884213353813,1.7164002232503626,3.207467084052041
+19,0.025,0.425,1.0,1.0,0.725,0.025,1.0,1.0,0.175,0.975,1.0,1.0,2.421559951279625,1.7189942230245363,3.8650663750013337
+20,0.025,0.5,1.0,1.0,0.625,0.025,1.0,1.0,0.975,0.5,0.0,0.0,2.6356773237196887,1.7725947739673125,4.2111422079615295
+21,0.025,0.4,2.0,1.0,0.35,0.025,1.0,1.0,0.225,0.825,0.0,0.0,2.1567303866874106,1.7825554840317894,3.8255510419839993
+22,0.025,0.225,1.0,1.0,0.7,0.025,1.0,1.0,0.7,0.625,0.0,0.0,2.192625100149705,1.6456776868893679,3.2341785830212757
+23,0.05,0.325,1.0,1.0,1.0,0.05,1.0,1.0,0.35,0.6,0.0,0.0,2.428932204723859,1.7530606762259995,3.9349855839973316
+24,0.05,0.8,1.0,1.0,0.05,0.05,3.0,1.0,0.65,0.925,0.0,0.0,2.302405282464414,1.770428680188229,3.9445256249746308
+25,0.05,0.825,1.0,1.0,0.9,0.05,1.0,1.0,0.575,0.6,0.0,0.0,2.662725681972245,1.7568018310340257,3.583227875060402
+26,0.075,0.8,0.0,0.0,0.175,0.075,0.0,0.0,0.75,1.0,0.0,0.0,2.4779231344971535,1.636606946495382,3.0800306249875575
+27,0.025,0.325,1.0,1.0,0.4,0.025,1.0,1.0,0.325,0.55,0.0,0.0,2.5360054330270536,1.7126576665803073,3.350157167064026
+28,0.05,0.95,1.0,1.0,0.975,0.05,1.0,1.0,0.55,0.65,0.0,0.0,2.4114030331112923,1.7929673484778506,4.011566916946322
+29,0.05,0.975,1.0,1.0,0.425,0.05,1.0,1.0,0.05,0.05,2.0,0.0,2.3110191027438285,1.7360948226556658,3.640291540999897
+30,0.025,0.55,1.0,1.0,0.775,0.025,1.0,1.0,0.15,0.95,0.0,0.0,2.064419868696177,1.696286824415056,3.70204141701106
+31,0.025,0.525,1.0,1.0,0.775,0.025,1.0,1.0,0.4,0.55,0.0,0.0,2.6101339089158073,1.5995990352060594,3.7858831669436768
+32,0.05,0.85,1.0,1.0,0.075,0.05,1.0,1.0,0.05,0.425,2.0,2.0,2.121151347333356,1.7817420159305506,4.147853250033222
+33,0.05,0.975,1.0,1.0,0.825,0.05,1.0,1.0,0.3,0.375,0.0,0.0,2.707102861937657,1.682751482797564,5.133728125016205
+34,0.05,0.925,1.0,1.0,0.125,0.05,2.0,1.0,0.45,0.2,0.0,0.0,2.389881562045524,1.7090359653816827,5.433329334016889
+35,0.05,0.525,1.0,1.0,0.425,0.05,1.0,1.0,0.175,0.225,0.0,0.0,2.3393037175085354,1.7195608892967884,3.760250790975988
+36,0.025,0.175,1.0,1.0,0.9,0.025,1.0,1.0,0.75,0.675,0.0,0.0,2.747871587199045,1.784772859181196,4.308625042089261
+37,0.075,0.575,0.0,0.0,0.95,0.075,0.0,0.0,0.15,0.575,0.0,0.0,2.484365674405659,1.6868120687194144,3.8817500829463825
+38,0.025,0.525,1.0,1.0,0.375,0.025,2.0,1.0,0.25,1.0,0.0,0.0,2.6032463149219103,1.7292939613859224,5.8635629588970914
+39,0.025,0.1,1.0,1.0,0.2,0.025,2.0,1.0,1.0,0.85,0.0,0.0,2.2823048176896688,1.7124016291742512,3.9528843340231106
+40,0.025,0.625,1.0,1.0,0.45,0.025,1.0,1.0,0.075,0.675,1.0,0.0,2.6312581027322697,1.6728852748829235,3.6922613329952583
+41,0.075,0.2,0.0,0.0,0.15,0.075,0.0,0.0,0.425,0.85,0.0,0.0,2.292502786065402,1.7751905108602812,3.679486583918333
+42,0.025,0.3,1.0,1.0,0.725,0.025,1.0,1.0,0.725,0.675,0.0,0.0,2.502384386611931,1.7015736744471328,3.3339597919257358
+43,0.05,0.925,1.0,1.0,1.0,0.05,1.0,1.0,0.45,0.375,0.0,0.0,2.4015100563356357,1.7524346638320485,3.976284958072938
+44,0.025,0.675,1.0,1.0,0.475,0.025,1.0,1.0,0.2,0.925,0.0,0.0,2.1204410979978476,1.7186288783490469,3.659761124989018
+45,0.05,0.65,1.0,1.0,0.475,0.05,1.0,1.0,0.65,0.275,0.0,0.0,2.292297392629308,1.7406774280200887,3.364021792076528
+46,0.025,0.15,1.0,1.0,0.325,0.025,1.0,1.0,0.65,0.125,0.0,0.0,2.95215898849445,1.662094498424341,3.5837658329401165
+47,0.025,0.175,1.0,1.0,1.0,0.025,2.0,1.0,0.675,0.5,0.0,0.0,2.554727927172552,1.6979608025519173,4.951951208990067
+48,0.05,0.075,1.0,1.0,0.05,0.05,2.0,1.0,0.15,0.175,0.0,0.0,2.284414893319193,1.8236587937659225,4.486850499990396
+49,0.025,0.7,1.0,1.0,0.85,0.025,2.0,1.0,0.25,0.85,0.0,0.0,2.6528753295011227,1.7259803529624536,4.270357458037324
+50,0.025,0.625,1.0,1.0,0.225,0.025,1.0,1.0,0.9,0.525,0.0,0.0,2.782213554255126,1.75121240191858,3.856307709007524
+51,0.05,0.7,1.0,1.0,0.525,0.05,1.0,1.0,0.1,0.95,0.0,0.0,2.2003653931949128,1.7191258801474314,3.765124208992347
+52,0.025,0.35,1.0,1.0,0.15,0.025,1.0,1.0,0.425,0.95,0.0,0.0,2.5629245672127805,1.7626510385699632,4.101947333081625
+53,0.025,0.175,1.0,1.0,0.925,0.025,2.0,1.0,0.7,0.15,1.0,0.0,2.1838802604695493,1.772254634108803,4.070564290974289
+54,0.025,0.125,1.0,1.0,0.975,0.025,1.0,1.0,0.2,0.175,0.0,0.0,2.1124653185310143,1.7333885886223968,4.5942366670351475
+55,0.025,0.125,1.0,1.0,0.1,0.025,1.0,1.0,0.05,0.95,1.0,0.0,2.263412223426462,1.7624427160376244,4.0621338749770075
+56,0.025,0.3,1.0,1.0,0.575,0.025,1.0,1.0,0.375,0.575,0.0,0.0,2.5622863267155136,1.6797712477064377,3.1999645839678124
+57,0.025,0.5,1.0,1.0,0.825,0.025,1.0,1.0,0.725,0.925,1.0,0.0,2.4367209475614056,1.656037738401617,3.372488541994244
+58,0.025,0.325,1.0,1.0,0.325,0.025,2.0,1.0,0.625,0.325,0.0,0.0,1.955827653794484,1.7557277853912414,3.4439675000030547
+59,0.025,0.05,2.0,1.0,0.7,0.025,1.0,1.0,0.1,0.475,0.0,0.0,2.357262404857979,1.691969796886943,3.884835791075602
+60,0.05,0.125,1.0,1.0,0.875,0.05,1.0,1.0,0.375,0.825,1.0,0.0,2.1200722636094023,1.6872250569619978,3.791390624945052
+61,0.025,0.575,1.0,1.0,0.225,0.025,1.0,1.0,0.55,0.7,0.0,0.0,2.476787425632768,1.7894935960318181,3.92867799999658
+62,0.025,0.25,2.0,1.0,0.125,0.025,1.0,1.0,0.275,0.95,0.0,0.0,2.370361014345388,1.7382996496059269,3.596996665932238
+63,0.025,0.15,1.0,1.0,0.7,0.025,2.0,1.0,0.125,0.475,1.0,0.0,2.0864388457659437,1.7448609860461854,3.7710618330165744
+64,0.05,0.95,1.0,1.0,0.525,0.05,1.0,1.0,0.575,0.875,0.0,0.0,2.073594756646149,1.6778248910669329,3.452708457945846
+65,0.025,0.3,1.0,1.0,0.475,0.025,2.0,1.0,0.25,0.675,0.0,0.0,2.520979245008906,1.7407887311244368,3.7153547500493005
+66,0.025,0.3,1.0,1.0,1.0,0.025,1.0,1.0,0.075,0.1,1.0,0.0,2.0415744107590204,1.6949205423049956,3.1821133330231532
+67,0.025,0.575,1.0,1.0,0.275,0.025,1.0,1.0,0.375,0.15,0.0,0.0,2.7293394687119132,1.7431690748907807,3.3887569999787956
+68,0.025,0.2,1.0,1.0,0.075,0.025,1.0,1.0,0.15,0.725,0.0,0.0,2.638568575637425,1.714941086054886,3.925408999901265
+69,0.025,0.85,1.0,1.0,0.8,0.025,1.0,1.0,0.2,0.5,0.0,0.0,2.6986200302969046,1.663757988786127,4.335220208042301
+70,0.025,0.225,1.0,1.0,0.875,0.025,2.0,1.0,0.15,0.475,1.0,0.0,2.4534871650825956,1.826449395175172,4.266264042002149
+71,0.025,0.325,1.0,1.0,0.35,0.025,2.0,1.0,0.025,0.025,2.0,1.0,2.3818036028991654,1.7533933172890095,3.197398875025101
+72,0.05,0.1,1.0,1.0,0.75,0.05,1.0,1.0,0.875,0.35,0.0,0.0,2.183340016224533,1.6944310505854319,3.099579208996147
+73,0.025,0.9,1.0,1.0,0.85,0.025,1.0,1.0,0.375,0.65,0.0,0.0,2.0614779261416594,1.694900282720776,3.983821625006385
+74,0.025,0.675,2.0,1.0,0.075,0.025,2.0,1.0,0.575,0.175,0.0,0.0,2.5141110488689726,1.7073060691664896,3.7643916660454124
+75,0.025,0.15,1.0,1.0,0.725,0.025,2.0,1.0,0.15,0.5,1.0,0.0,2.2999835495916194,1.7136206707191532,3.2931041669799015
+76,0.025,0.175,1.0,1.0,0.475,0.025,1.0,1.0,0.275,0.475,0.0,0.0,2.397342288964314,1.6371233313268343,3.963362667011097
+77,0.025,0.075,1.0,1.0,0.975,0.025,1.0,1.0,0.4,0.8,0.0,0.0,2.185324037036274,1.7379439555031018,3.053826667019166
+78,0.025,0.175,1.0,1.0,0.15,0.025,2.0,1.0,0.175,0.2,0.0,0.0,2.490484714978299,1.7540723498463282,3.912870709085837
+79,0.025,0.925,1.0,1.0,0.05,0.025,2.0,1.0,0.1,0.875,1.0,0.0,2.2193167325687666,1.7561281914338456,3.193307541892864
+80,0.05,0.525,1.0,1.0,0.875,0.05,1.0,1.0,0.675,0.4,0.0,0.0,2.6313908510853308,1.6540464316777197,3.0421330420067534
+81,0.025,0.725,1.0,1.0,0.8,0.025,1.0,1.0,0.575,0.75,0.0,0.0,2.2586013665624582,1.7000313261058175,3.5726526249200106
+82,0.025,0.025,2.0,1.0,0.825,0.025,1.0,1.0,0.15,0.475,0.0,0.0,2.542897332226353,1.7298912305160303,3.7010924170026556
+83,0.025,0.15,2.0,1.0,0.925,0.025,1.0,1.0,0.375,0.95,0.0,0.0,2.5332489158721936,1.7157663825715346,4.711602958035655
+84,0.025,0.775,1.0,1.0,0.425,0.025,1.0,1.0,0.1,0.2,1.0,0.0,2.838141242720586,1.71348072617555,3.5521365829044953
+85,0.05,1.0,1.0,1.0,0.375,0.05,2.0,1.0,0.05,0.05,2.0,0.0,2.307529425837478,1.723775656740041,3.3959440420148894
+86,0.05,0.975,1.0,1.0,0.6,0.05,1.0,1.0,0.375,0.65,0.0,0.0,2.580029374504422,1.7229608949817956,3.023648082977161
+87,0.025,0.7,1.0,1.0,0.15,0.025,1.0,1.0,0.475,0.8,0.0,0.0,2.29291069674396,1.7051408577294604,3.935616333037615
+88,0.05,0.4,1.0,1.0,0.775,0.05,1.0,1.0,0.925,0.4,0.0,0.0,2.5033608840562755,1.7565389988825775,4.376982624991797
+89,0.025,0.575,2.0,1.0,0.475,0.025,2.0,1.0,0.5,0.025,2.0,0.0,3.3021778371758863,1.6087784290399703,3.5222368750255555
+90,0.025,0.075,1.0,1.0,0.65,0.025,1.0,1.0,0.275,0.725,0.0,0.0,1.9421868628974535,1.6875630505462487,3.8664235830074176
+91,0.05,0.625,1.0,1.0,0.725,0.05,1.0,1.0,0.8,0.425,0.0,0.0,2.884477086394881,1.8432251923733975,4.0067495830589905
+92,0.025,0.525,1.0,1.0,0.1,0.025,2.0,1.0,0.25,0.05,1.0,1.0,2.1841119503252546,1.65163415429219,3.452333708992228
+93,0.025,0.325,1.0,1.0,0.75,0.025,1.0,1.0,0.5,0.375,0.0,0.0,1.9176631928101253,1.6705006496627273,3.2954436249565333
+94,0.025,0.525,1.0,1.0,0.2,0.025,1.0,1.0,0.55,0.675,0.0,0.0,2.346634970977332,1.738492495774633,4.791000584024005
+95,0.025,0.4,1.0,1.0,0.45,0.025,1.0,1.0,0.2,0.475,0.0,0.0,2.246487330454925,1.7570924280456623,3.466205291915685
+96,0.025,0.725,1.0,1.0,0.575,0.025,1.0,1.0,0.8,0.5,0.0,0.0,2.3962733545693258,1.7273443576346328,3.783368958043866
+97,0.05,1.0,1.0,1.0,0.225,0.05,1.0,1.0,0.325,0.425,0.0,0.0,2.7882028797720446,1.7750742312661212,4.243240874959156
+98,0.025,0.95,1.0,1.0,0.725,0.025,1.0,1.0,0.9,0.375,0.0,0.0,2.732196469281898,1.6464949493985672,4.2331772920442745
+99,0.025,0.85,1.0,1.0,0.675,0.025,1.0,1.0,0.05,0.1,2.0,1.0,1.6099515807403968,1.7327797388227963,3.2806519999867305