bargcc 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- bargcc-0.1.0/ARCHITECTURE_MAPPING.md +19 -0
- bargcc-0.1.0/LICENSE +21 -0
- bargcc-0.1.0/MANIFEST.in +3 -0
- bargcc-0.1.0/PKG-INFO +103 -0
- bargcc-0.1.0/PUBLISH_PYPI.md +11 -0
- bargcc-0.1.0/README.md +79 -0
- bargcc-0.1.0/WINDOWS_INSTALL.ps1 +9 -0
- bargcc-0.1.0/examples/neural_reference.py +11 -0
- bargcc-0.1.0/examples/quickstart.py +16 -0
- bargcc-0.1.0/pyproject.toml +31 -0
- bargcc-0.1.0/setup.cfg +4 -0
- bargcc-0.1.0/setup.py +3 -0
- bargcc-0.1.0/src/bargcc/__init__.py +11 -0
- bargcc-0.1.0/src/bargcc/cli.py +39 -0
- bargcc-0.1.0/src/bargcc/core.py +150 -0
- bargcc-0.1.0/src/bargcc/estimators.py +69 -0
- bargcc-0.1.0/src/bargcc/neural.py +73 -0
- bargcc-0.1.0/src/bargcc/selection.py +63 -0
- bargcc-0.1.0/src/bargcc.egg-info/PKG-INFO +103 -0
- bargcc-0.1.0/src/bargcc.egg-info/SOURCES.txt +24 -0
- bargcc-0.1.0/src/bargcc.egg-info/dependency_links.txt +1 -0
- bargcc-0.1.0/src/bargcc.egg-info/entry_points.txt +2 -0
- bargcc-0.1.0/src/bargcc.egg-info/requires.txt +9 -0
- bargcc-0.1.0/src/bargcc.egg-info/top_level.txt +1 -0
- bargcc-0.1.0/tests/test_core.py +95 -0
- bargcc-0.1.0/tests/test_neural.py +15 -0
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Implementation map to the BARG-CC manuscript
|
|
2
|
+
|
|
3
|
+
| Manuscript concept | Module | Status / assumptions |
|
|
4
|
+
|---|---|---|
|
|
5
|
+
| Reliability score r in [0,1] and binary availability a | `bargcc.core` | Strict validation; all-missing rows rejected |
|
|
6
|
+
| Masked-softmax α with logits κ(2r−1) | `certified_weights` | Implemented; no post-softmax floor approximation |
|
|
7
|
+
| Sufficient participation floor ρ | `certified_strength` | Implemented; shared κ checked against maximum active views |
|
|
8
|
+
| b=[sqrt(Mα_m) e_m]_m | `fuse_blocks` | Implemented; unavailable blocks exactly zero |
|
|
9
|
+
| Dimension balancing and row normalization | `fuse_blocks` options | Exploratory geometry controls, not a trained preprocessing pipeline |
|
|
10
|
+
| Fixed-mask block perturbation bound | `block_perturbation_bound` | Implemented; requires independently justified max norm and score-error bound |
|
|
11
|
+
| Frozen-centroid assignment certificate | `centroid_assignment_certificate` | Implemented; does not permit reclustering |
|
|
12
|
+
| Fit K-means on training representations and assign held-out | `BARGCCKMeans` | Implemented; user must preserve train/test separation |
|
|
13
|
+
| Select candidate only when all lower bounds clear margins | `conservative_adopt` | Implemented as a decision rule, NOT a confidence guarantee |
|
|
14
|
+
| One-sided Bonferroni bounds under additional assumptions | `bonferroni_normal_bounds` | Illustrative helper; requires independent group-level units and justified normal approximation |
|
|
15
|
+
| Per-view neural encoders, score-centered residual modulation, learned projection | `bargcc.neural.NeuralBARGCC` | Optional PyTorch reference scaffold; no checkpoint or experiment-specific loss supplied |
|
|
16
|
+
| Original FUNSD OCR/text reconstruction, proxy training, exact published losses | Not part of v0.1.0 | Must be ported and separately verified before exact manuscript replication |
|
|
17
|
+
| Matched HSACC/ToRES official-code experiments | Not part of v0.1.0 | No official external implementations or results included |
|
|
18
|
+
|
|
19
|
+
This package should not be cited as evidence that the neural gate beats masking. It provides reusable algorithmic primitives and a testable software basis for future experiments.
|
bargcc-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Debmalya Ray
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
bargcc-0.1.0/MANIFEST.in
ADDED
bargcc-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: bargcc
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: BARG-CC: certified reliability gating and selective adoption for multi-view clustering
|
|
5
|
+
Author-email: Debmalya Ray <debmalya.ray9989@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Repository, https://huggingface.co/spaces/Debmalya/barg-cc-neural-workbench-static/tree/main
|
|
8
|
+
Keywords: multi-view clustering,reliability,masked softmax,certification,neuro-symbolic
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Operating System :: OS Independent
|
|
11
|
+
Classifier: Intended Audience :: Science/Research
|
|
12
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
13
|
+
Requires-Python: >=3.10
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Requires-Dist: numpy>=1.24
|
|
17
|
+
Requires-Dist: scikit-learn>=1.2
|
|
18
|
+
Provides-Extra: torch
|
|
19
|
+
Requires-Dist: torch>=2.1; extra == "torch"
|
|
20
|
+
Provides-Extra: dev
|
|
21
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
22
|
+
Requires-Dist: build>=1; extra == "dev"
|
|
23
|
+
Dynamic: license-file
|
|
24
|
+
|
|
25
|
+
# BARG-CC Python package (`bargcc`)
|
|
26
|
+
|
|
27
|
+
Installable research library built from the BARG-CC IEEE TNNLS architecture, **not** a reproduction of the manuscript's archived neural checkpoints or published experimental results. Main features:
|
|
28
|
+
|
|
29
|
+
- Certified availability-masked softmax (no post-hoc probability flooring)
|
|
30
|
+
- Guaranteed minimum participation share under the manuscript's restricted gate strength
|
|
31
|
+
- Score-weighted block concatenation and transparent geometric controls
|
|
32
|
+
- Fixed-mask / fixed-embedding perturbation and frozen-centroid assignment certificates
|
|
33
|
+
- scikit-learn-compatible block transformer and training-only fitted K-means wrapper
|
|
34
|
+
- Fail-closed selective-adoption decision when **externally justified** simultaneous lower bounds are supplied
|
|
35
|
+
- Optional PyTorch per-view encoder and residual fusion reference scaffold
|
|
36
|
+
- CLI, tests and examples
|
|
37
|
+
|
|
38
|
+
## Install
|
|
39
|
+
|
|
40
|
+
From the unpacked release directory:
|
|
41
|
+
|
|
42
|
+
```powershell
|
|
43
|
+
python -m pip install .
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Or install the prebuilt wheel locally:
|
|
47
|
+
|
|
48
|
+
```powershell
|
|
49
|
+
python -m pip install ./dist/bargcc-0.1.0-py3-none-any.whl
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Optional neural module:
|
|
53
|
+
|
|
54
|
+
```powershell
|
|
55
|
+
python -m pip install '.[torch]'
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**IMPORTANT:** `pip install bargcc` from the public PyPI index will work **only after you publish** this project to PyPI; this release is a local pip-installable wheel and source package. The project name is not claimed to be available on PyPI.
|
|
59
|
+
|
|
60
|
+
## Quickstart
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
import numpy as np
|
|
64
|
+
from bargcc import fuse_blocks, certified_strength, BARGCCKMeans
|
|
65
|
+
|
|
66
|
+
rng=np.random.default_rng(0)
|
|
67
|
+
views=[rng.normal(size=(100,144)),rng.normal(size=(100,128)),rng.normal(size=(100,16))]
|
|
68
|
+
mask=np.ones((100,3),dtype=bool)
|
|
69
|
+
mask[::5,1]=False
|
|
70
|
+
scores=rng.uniform(size=(100,3))
|
|
71
|
+
kappa=certified_strength(0.1,3) # approximately 0.75204
|
|
72
|
+
z,weights,certificate=fuse_blocks(views,mask,scores,kappa=kappa,rho=0.1)
|
|
73
|
+
print(z.shape,certificate.certified,weights[mask].min())
|
|
74
|
+
model=BARGCCKMeans(n_clusters=4,kappa=kappa,rho=0.1,random_state=0)
|
|
75
|
+
model.fit((views,mask,scores))
|
|
76
|
+
print(model.labels_[:5])
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`bargcc certify --rho 0.1 --views 3` prints the floor-constrained strength limit.
|
|
80
|
+
|
|
81
|
+
### NPZ CLI
|
|
82
|
+
|
|
83
|
+
Save `view_0`, `view_1`, ... matrices, `mask` (N by M binary), optional `scores` (N by M in [0,1]) into `inputs.npz` and run:
|
|
84
|
+
|
|
85
|
+
```powershell
|
|
86
|
+
bargcc fuse inputs.npz output.npz --rho 0.1 --kappa 0.75 --dimension-balance
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The output contains `fused`, `weights` and `mask`. **Never pass a real dataset without checking access rights and provenance.**
|
|
90
|
+
|
|
91
|
+
## Reproducibility and scientific scope
|
|
92
|
+
|
|
93
|
+
The certificate assumes a fixed view mask and frozen embeddings. The clustering certificate additionally assumes fixed centroids. If scores are estimated, you need an independently valid score-error bound; quality scores alone are not evidence of semantic clustering utility. The neural module is a reusable reference building block: it omits experiment-specific training loss recipes, quality-proxy fitting, token encoders and checkpoint weights. No FUNSD or other dataset is bundled. Normalization and dimensions must be controlled and fitted on training data only. The `conservative_adopt` function accepts supplied lower confidence bounds but **does not establish their statistical coverage**.
|
|
94
|
+
|
|
95
|
+
No end-to-end benchmarks are claimed for this release. Before journal-level replication, conduct independent benchmarks and matched official-code comparisons.
|
|
96
|
+
|
|
97
|
+
## Release guide
|
|
98
|
+
|
|
99
|
+
See `PUBLISH_PYPI.md` for instructions to publish publicly and enable `pip install bargcc` by name.
|
|
100
|
+
|
|
101
|
+
## License
|
|
102
|
+
|
|
103
|
+
MIT license applies to the *new package code only*. It is not a relicensing of any attached third-party model, original experiment, or dataset.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Publish the `bargcc` package on PyPI (only after author review)
|
|
2
|
+
|
|
3
|
+
1. Verify ownership, package name availability on PyPI, authorship and licensing.
|
|
4
|
+
2. Run automated tests and review the wheel contents. Keep private data, credentials, pretrained checkpoints and license-incompatible source out of the distribution.
|
|
5
|
+
3. Set up PyPI trusted publishing or a scoped PyPI token on your own computer/account. **Never send tokens in chat.**
|
|
6
|
+
4. In a clean Python >=3.10 environment: `python -m pip install build twine`, then `python -m build` and `python -m twine check dist/*`.
|
|
7
|
+
5. Test on TestPyPI first: `python -m twine upload --repository testpypi dist/*` (if configured).
|
|
8
|
+
6. Publish: `python -m twine upload dist/*` (requires your explicit approval and authentication).
|
|
9
|
+
7. Verify index listing and installation `python -m pip install bargcc`.
|
|
10
|
+
|
|
11
|
+
The package has NOT been published to PyPI. The downloadable ZIP includes locally installable distributions.
|
bargcc-0.1.0/README.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# BARG-CC Python package (`bargcc`)
|
|
2
|
+
|
|
3
|
+
Installable research library built from the BARG-CC IEEE TNNLS architecture, **not** a reproduction of the manuscript's archived neural checkpoints or published experimental results. Main features:
|
|
4
|
+
|
|
5
|
+
- Certified availability-masked softmax (no post-hoc probability flooring)
|
|
6
|
+
- Guaranteed minimum participation share under the manuscript's restricted gate strength
|
|
7
|
+
- Score-weighted block concatenation and transparent geometric controls
|
|
8
|
+
- Fixed-mask / fixed-embedding perturbation and frozen-centroid assignment certificates
|
|
9
|
+
- scikit-learn-compatible block transformer and training-only fitted K-means wrapper
|
|
10
|
+
- Fail-closed selective-adoption decision when **externally justified** simultaneous lower bounds are supplied
|
|
11
|
+
- Optional PyTorch per-view encoder and residual fusion reference scaffold
|
|
12
|
+
- CLI, tests and examples
|
|
13
|
+
|
|
14
|
+
## Install
|
|
15
|
+
|
|
16
|
+
From the unpacked release directory:
|
|
17
|
+
|
|
18
|
+
```powershell
|
|
19
|
+
python -m pip install .
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Or install the prebuilt wheel locally:
|
|
23
|
+
|
|
24
|
+
```powershell
|
|
25
|
+
python -m pip install ./dist/bargcc-0.1.0-py3-none-any.whl
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Optional neural module:
|
|
29
|
+
|
|
30
|
+
```powershell
|
|
31
|
+
python -m pip install '.[torch]'
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
**IMPORTANT:** `pip install bargcc` from the public PyPI index will work **only after you publish** this project to PyPI; this release is a local pip-installable wheel and source package. The project name is not claimed to be available on PyPI.
|
|
35
|
+
|
|
36
|
+
## Quickstart
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
import numpy as np
|
|
40
|
+
from bargcc import fuse_blocks, certified_strength, BARGCCKMeans
|
|
41
|
+
|
|
42
|
+
rng=np.random.default_rng(0)
|
|
43
|
+
views=[rng.normal(size=(100,144)),rng.normal(size=(100,128)),rng.normal(size=(100,16))]
|
|
44
|
+
mask=np.ones((100,3),dtype=bool)
|
|
45
|
+
mask[::5,1]=False
|
|
46
|
+
scores=rng.uniform(size=(100,3))
|
|
47
|
+
kappa=certified_strength(0.1,3) # approximately 0.75204
|
|
48
|
+
z,weights,certificate=fuse_blocks(views,mask,scores,kappa=kappa,rho=0.1)
|
|
49
|
+
print(z.shape,certificate.certified,weights[mask].min())
|
|
50
|
+
model=BARGCCKMeans(n_clusters=4,kappa=kappa,rho=0.1,random_state=0)
|
|
51
|
+
model.fit((views,mask,scores))
|
|
52
|
+
print(model.labels_[:5])
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`bargcc certify --rho 0.1 --views 3` prints the floor-constrained strength limit.
|
|
56
|
+
|
|
57
|
+
### NPZ CLI
|
|
58
|
+
|
|
59
|
+
Save `view_0`, `view_1`, ... matrices, `mask` (N by M binary), optional `scores` (N by M in [0,1]) into `inputs.npz` and run:
|
|
60
|
+
|
|
61
|
+
```powershell
|
|
62
|
+
bargcc fuse inputs.npz output.npz --rho 0.1 --kappa 0.75 --dimension-balance
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The output contains `fused`, `weights` and `mask`. **Never pass a real dataset without checking access rights and provenance.**
|
|
66
|
+
|
|
67
|
+
## Reproducibility and scientific scope
|
|
68
|
+
|
|
69
|
+
The certificate assumes a fixed view mask and frozen embeddings. The clustering certificate additionally assumes fixed centroids. If scores are estimated, you need an independently valid score-error bound; quality scores alone are not evidence of semantic clustering utility. The neural module is a reusable reference building block: it omits experiment-specific training loss recipes, quality-proxy fitting, token encoders and checkpoint weights. No FUNSD or other dataset is bundled. Normalization and dimensions must be controlled and fitted on training data only. The `conservative_adopt` function accepts supplied lower confidence bounds but **does not establish their statistical coverage**.
|
|
70
|
+
|
|
71
|
+
No end-to-end benchmarks are claimed for this release. Before journal-level replication, conduct independent benchmarks and matched official-code comparisons.
|
|
72
|
+
|
|
73
|
+
## Release guide
|
|
74
|
+
|
|
75
|
+
See `PUBLISH_PYPI.md` for instructions to publish publicly and enable `pip install bargcc` by name.
|
|
76
|
+
|
|
77
|
+
## License
|
|
78
|
+
|
|
79
|
+
MIT license applies to the *new package code only*. It is not a relicensing of any attached third-party model, original experiment, or dataset.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Run from the extracted package directory in PowerShell.
|
|
2
|
+
# Example: conda activate barg_cc
|
|
3
|
+
$ErrorActionPreference = "Stop"
|
|
4
|
+
python --version
|
|
5
|
+
python -m pip install .
|
|
6
|
+
python -c "import bargcc; print('BARG-CC version', bargcc.__version__)"
|
|
7
|
+
python -m bargcc.cli certify --rho 0.1 --views 3
|
|
8
|
+
python .\examples\quickstart.py
|
|
9
|
+
Write-Host 'BARG-CC local pip installation and smoke test complete.'
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import torch
|
|
2
|
+
from bargcc.neural import NeuralBARGCC
|
|
3
|
+
|
|
4
|
+
model=NeuralBARGCC([144,128,16],embedding_dim=64,hidden_dim=128,kappa=.75,rho=.1,n_clusters=4)
|
|
5
|
+
features=[torch.randn(6,d) for d in (144,128,16)]
|
|
6
|
+
mask=torch.ones(6,3,dtype=torch.bool)
|
|
7
|
+
mask[0,1]=False
|
|
8
|
+
scores=torch.rand(6,3)
|
|
9
|
+
(out,logits),alpha=model(features,mask,scores,return_weights=True)
|
|
10
|
+
print(out.shape, logits.shape, alpha.shape)
|
|
11
|
+
# You must define an actual experimental training loss and frozen evaluation protocol.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import numpy as np
|
|
2
|
+
from bargcc import certified_strength, fuse_blocks, BARGCCKMeans, block_perturbation_bound
|
|
3
|
+
|
|
4
|
+
rng=np.random.default_rng(42)
|
|
5
|
+
views=[rng.normal(size=(30,8)),rng.normal(size=(30,5)),rng.normal(size=(30,4))]
|
|
6
|
+
mask=np.ones((30,3),dtype=bool)
|
|
7
|
+
mask[::4,1]=False
|
|
8
|
+
scores=rng.uniform(size=(30,3))
|
|
9
|
+
rho=.1
|
|
10
|
+
kappa=certified_strength(rho,3)
|
|
11
|
+
Z,alpha,cert=fuse_blocks(views,mask,scores,kappa=kappa,rho=rho,dimension_balance=True)
|
|
12
|
+
print('fused',Z.shape,'minimum observed weight',alpha[mask].min(),'certified',cert.certified)
|
|
13
|
+
model=BARGCCKMeans(n_clusters=3,kappa=kappa,rho=rho,dimension_balance=True,random_state=42)
|
|
14
|
+
model.fit((views[:],mask,scores))
|
|
15
|
+
print('train cluster ids',model.labels_[:10])
|
|
16
|
+
print('example fixed-mask embedding perturbation bound',block_perturbation_bound(1,3,kappa,.05))
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "bargcc"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "BARG-CC: certified reliability gating and selective adoption for multi-view clustering"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [{name = "Debmalya Ray", email = "debmalya.ray9989@gmail.com"}]
|
|
13
|
+
keywords = ["multi-view clustering", "reliability", "masked softmax", "certification", "neuro-symbolic"]
|
|
14
|
+
classifiers = ["Programming Language :: Python :: 3", "Operating System :: OS Independent", "Intended Audience :: Science/Research", "Topic :: Scientific/Engineering :: Artificial Intelligence"]
|
|
15
|
+
dependencies = ["numpy>=1.24", "scikit-learn>=1.2"]
|
|
16
|
+
|
|
17
|
+
[project.optional-dependencies]
|
|
18
|
+
torch = ["torch>=2.1"]
|
|
19
|
+
dev = ["pytest>=7", "build>=1"]
|
|
20
|
+
|
|
21
|
+
[project.scripts]
|
|
22
|
+
bargcc = "bargcc.cli:main"
|
|
23
|
+
|
|
24
|
+
[project.urls]
|
|
25
|
+
Repository = "https://huggingface.co/spaces/Debmalya/barg-cc-neural-workbench-static/tree/main"
|
|
26
|
+
|
|
27
|
+
[tool.setuptools.packages.find]
|
|
28
|
+
where = ["src"]
|
|
29
|
+
|
|
30
|
+
[tool.pytest.ini_options]
|
|
31
|
+
testpaths = ["tests"]
|
bargcc-0.1.0/setup.cfg
ADDED
bargcc-0.1.0/setup.py
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""BARG-CC research API. No empirical performance claims are implied."""
|
|
2
|
+
from .core import (ParticipationCertificate, certified_strength, masked_softmax,
|
|
3
|
+
certified_weights, fuse_blocks, block_perturbation_bound,
|
|
4
|
+
centroid_assignment_certificate, validate_multiview)
|
|
5
|
+
from .estimators import BARGCCTransformer, BARGCCKMeans
|
|
6
|
+
from .selection import SelectionDecision, conservative_adopt, bonferroni_normal_bounds
|
|
7
|
+
__version__ = "0.1.0"
|
|
8
|
+
__all__ = ["ParticipationCertificate", "certified_strength", "masked_softmax",
|
|
9
|
+
"certified_weights", "fuse_blocks", "block_perturbation_bound", "centroid_assignment_certificate",
|
|
10
|
+
"validate_multiview", "BARGCCTransformer", "BARGCCKMeans", "SelectionDecision",
|
|
11
|
+
"conservative_adopt", "bonferroni_normal_bounds"]
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""Simple CLI: validate and fuse NPZ files without accessing network/services."""
|
|
2
|
+
import argparse
|
|
3
|
+
import json
|
|
4
|
+
import sys
|
|
5
|
+
import numpy as np
|
|
6
|
+
from . import __version__
|
|
7
|
+
from .core import fuse_blocks, certified_strength
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def main(argv=None):
|
|
11
|
+
p=argparse.ArgumentParser(prog="bargcc",description="BARG-CC certified multi-view block fusion")
|
|
12
|
+
p.add_argument("--version",action="version",version=__version__)
|
|
13
|
+
sub=p.add_subparsers(dest="cmd",required=True)
|
|
14
|
+
c=sub.add_parser("certify",help="print certified kappa limit")
|
|
15
|
+
c.add_argument("--rho",type=float,required=True)
|
|
16
|
+
c.add_argument("--views",type=int,required=True)
|
|
17
|
+
f=sub.add_parser("fuse",help="fuse an NPZ with keys view_0,...,mask, optionally scores")
|
|
18
|
+
f.add_argument("input",help="input .npz")
|
|
19
|
+
f.add_argument("output",help="output .npz")
|
|
20
|
+
f.add_argument("--kappa",type=float,default=0.0)
|
|
21
|
+
f.add_argument("--rho",type=float)
|
|
22
|
+
f.add_argument("--dimension-balance",action="store_true")
|
|
23
|
+
f.add_argument("--row-normalize",action="store_true")
|
|
24
|
+
args=p.parse_args(argv)
|
|
25
|
+
if args.cmd=="certify":
|
|
26
|
+
print(json.dumps({"rho":args.rho,"max_available":args.views,"kappa_limit":certified_strength(args.rho,args.views)},indent=2))
|
|
27
|
+
elif args.cmd=="fuse":
|
|
28
|
+
with np.load(args.input, allow_pickle=False) as obj:
|
|
29
|
+
mask=obj["mask"]
|
|
30
|
+
keys=[f"view_{i}" for i in range(mask.shape[1])]
|
|
31
|
+
views=[obj[k] for k in keys]
|
|
32
|
+
scores=obj["scores"] if "scores" in obj else None
|
|
33
|
+
fused, alpha, cert=fuse_blocks(views,mask,scores,kappa=args.kappa,rho=args.rho,
|
|
34
|
+
dimension_balance=args.dimension_balance,row_normalize=args.row_normalize)
|
|
35
|
+
np.savez_compressed(args.output,fused=fused,weights=alpha,mask=mask)
|
|
36
|
+
print(json.dumps({"output":args.output,"shape":list(fused.shape),"certified":cert.certified},indent=2))
|
|
37
|
+
|
|
38
|
+
if __name__=="__main__":
|
|
39
|
+
main()
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
"""Manuscript-aligned *fixed-mask, fixed-embedding* BARG-CC primitives.
|
|
2
|
+
|
|
3
|
+
The guarantees do not cover changing masks, retrained encoders, reclustered
|
|
4
|
+
centroids, semantic utility or a score error bound not separately established.
|
|
5
|
+
"""
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
import math
|
|
8
|
+
from typing import Sequence
|
|
9
|
+
import numpy as np
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def _as_mask(mask, n=None, m=None):
|
|
13
|
+
a = np.asarray(mask)
|
|
14
|
+
if a.ndim != 2 or (n is not None and a.shape != (n, m)):
|
|
15
|
+
raise ValueError("availability must have shape (n_samples, n_views)")
|
|
16
|
+
if a.dtype.kind not in "biu" or not np.isin(a, [0, 1]).all():
|
|
17
|
+
raise ValueError("availability must be binary (0/1 or bool)")
|
|
18
|
+
a = a.astype(bool)
|
|
19
|
+
if not a.any(axis=1).all():
|
|
20
|
+
raise ValueError("all-missing rows are not supported; reject or filter explicitly")
|
|
21
|
+
return a
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def validate_multiview(views: Sequence[np.ndarray], availability):
|
|
25
|
+
"""Validate and return (views, binary mask); zero values do NOT mean missing."""
|
|
26
|
+
if not isinstance(views, (list, tuple)) or not views:
|
|
27
|
+
raise ValueError("views must be a nonempty sequence of 2-D arrays")
|
|
28
|
+
arrays = [np.asarray(x, dtype=np.float64) for x in views]
|
|
29
|
+
n = arrays[0].shape[0] if arrays[0].ndim == 2 else -1
|
|
30
|
+
if n < 1 or any(x.ndim != 2 or x.shape[0] != n or x.shape[1] < 1 or not np.isfinite(x).all() for x in arrays):
|
|
31
|
+
raise ValueError("all views must have equal sample counts, positive width and finite values")
|
|
32
|
+
mask = _as_mask(availability, n, len(arrays))
|
|
33
|
+
return arrays, mask
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def certified_strength(rho: float, max_available: int) -> float:
|
|
37
|
+
"""Maximum κ for active-view share >= ρ, for up to max_available views.
|
|
38
|
+
|
|
39
|
+
The maximum is infinite for max_available=1. For M>=2, κρ =
|
|
40
|
+
0.5 * log((1/rho - 1)/(M - 1)).
|
|
41
|
+
"""
|
|
42
|
+
if isinstance(max_available, bool) or not isinstance(max_available, (int, np.integer)) or max_available < 1:
|
|
43
|
+
raise ValueError("max_available must be a positive integer")
|
|
44
|
+
if not np.isfinite(rho) or not (0 < rho <= 1/max_available):
|
|
45
|
+
raise ValueError("require 0 < rho <= 1/max_available")
|
|
46
|
+
if max_available == 1:
|
|
47
|
+
return math.inf
|
|
48
|
+
return max(0.0, 0.5 * math.log((1/rho - 1)/(max_available - 1)))
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
@dataclass(frozen=True)
|
|
52
|
+
class ParticipationCertificate:
|
|
53
|
+
rho: float
|
|
54
|
+
kappa: float
|
|
55
|
+
max_available: int
|
|
56
|
+
kappa_limit: float
|
|
57
|
+
worst_case_lower_share: float
|
|
58
|
+
certified: bool
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def certified_weights(scores, availability, *, kappa: float = 0.0, rho: float | None = None):
|
|
62
|
+
"""Compute stable masked-softmax and certify an optional participation floor.
|
|
63
|
+
|
|
64
|
+
Never floors/renormalizes probabilities after softmax. Scores must be [0,1].
|
|
65
|
+
If rho is provided, a strength outside the sufficient certified region raises.
|
|
66
|
+
"""
|
|
67
|
+
scores = np.asarray(scores, dtype=np.float64)
|
|
68
|
+
mask = _as_mask(availability)
|
|
69
|
+
if scores.shape != mask.shape:
|
|
70
|
+
raise ValueError("scores and mask must have identical (n, m) shapes")
|
|
71
|
+
if not np.isfinite(scores).all() or ((scores < 0) | (scores > 1)).any():
|
|
72
|
+
raise ValueError("reliability scores must be finite and in [0,1]")
|
|
73
|
+
if not np.isfinite(kappa) or kappa < 0:
|
|
74
|
+
raise ValueError("kappa must be finite and nonnegative")
|
|
75
|
+
m = int(mask.sum(axis=1).max())
|
|
76
|
+
if rho is not None:
|
|
77
|
+
limit = certified_strength(float(rho), m)
|
|
78
|
+
if kappa > limit + 1e-12:
|
|
79
|
+
raise ValueError(f"κ={kappa:g} exceeds floor-certified limit κρ={limit:g}")
|
|
80
|
+
else:
|
|
81
|
+
limit = math.inf
|
|
82
|
+
logits = np.where(mask, kappa * (2 * scores - 1), -np.inf)
|
|
83
|
+
centered = logits - np.max(logits, axis=1, keepdims=True)
|
|
84
|
+
exp = np.where(mask, np.exp(centered), 0.0)
|
|
85
|
+
alpha = exp / exp.sum(axis=1, keepdims=True)
|
|
86
|
+
lower = 1.0/(1.0+(m-1)*math.exp(min(2*kappa,700))) if m>1 else 1.0
|
|
87
|
+
certificate = ParticipationCertificate(float(rho) if rho is not None else math.nan,
|
|
88
|
+
float(kappa), m, float(limit), lower, rho is not None and kappa <= limit+1e-12)
|
|
89
|
+
return alpha, certificate
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def masked_softmax(scores, availability, kappa=0.0):
|
|
93
|
+
"""Unrestricted masked-softmax; no participation-floor certificate."""
|
|
94
|
+
return certified_weights(scores, availability, kappa=kappa)[0]
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def fuse_blocks(views, availability, scores=None, *, kappa=0.0, rho=None,
|
|
98
|
+
dimension_balance=False, row_normalize=False):
|
|
99
|
+
"""b_i=[sqrt(M_i * alpha_im) e_im]_m, zeroing unavailable blocks.
|
|
100
|
+
|
|
101
|
+
Optional division by sqrt(d_m) is a simple width control; it is NOT a full
|
|
102
|
+
train-fitted feature scaler. Optional post-concatenation L2 normalization
|
|
103
|
+
alters the scope of fixed-embedding bounds if the original norms vary.
|
|
104
|
+
"""
|
|
105
|
+
arrays, mask = validate_multiview(views, availability)
|
|
106
|
+
if scores is None:
|
|
107
|
+
scores = np.full(mask.shape, .5)
|
|
108
|
+
alpha, cert = certified_weights(scores, mask, kappa=kappa, rho=rho)
|
|
109
|
+
weights = np.sqrt(mask.sum(axis=1)[:,None] * alpha)
|
|
110
|
+
blocks = []
|
|
111
|
+
for j, x in enumerate(arrays):
|
|
112
|
+
scale = math.sqrt(x.shape[1]) if dimension_balance else 1.0
|
|
113
|
+
blocks.append(np.where(mask[:,j,None], x * (weights[:,j,None]/scale), 0.0))
|
|
114
|
+
fused = np.concatenate(blocks, axis=1)
|
|
115
|
+
if row_normalize:
|
|
116
|
+
norms = np.linalg.norm(fused, axis=1, keepdims=True)
|
|
117
|
+
# Zero vectors remain zero: do not silently invent a representation.
|
|
118
|
+
fused = np.divide(fused, norms, out=np.zeros_like(fused), where=norms>0)
|
|
119
|
+
return fused, alpha, cert
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def block_perturbation_bound(max_view_norm, n_available, kappa, score_error):
|
|
123
|
+
"""R sqrt(M) min(κ δ, sqrt(2)), for frozen masks and embeddings."""
|
|
124
|
+
vals = np.asarray([max_view_norm, n_available, kappa, score_error], dtype=float)
|
|
125
|
+
if not np.isfinite(vals).all() or (vals < 0).any() or n_available < 1 or int(n_available) != n_available:
|
|
126
|
+
raise ValueError("nonnegative finite bounds and integer n_available>=1 required")
|
|
127
|
+
return float(max_view_norm * math.sqrt(n_available) * min(kappa*score_error, math.sqrt(2)))
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def centroid_assignment_certificate(embeddings, centroids, error_bounds):
|
|
131
|
+
"""Strict fixed-centroid assignment guarantee: runner-up gap > 2ε.
|
|
132
|
+
|
|
133
|
+
Returns (certified_boolean_array, gap_array, assigned_cluster_indices).
|
|
134
|
+
Ties are not certified. Center fitting or changing the view masks invalidates
|
|
135
|
+
the guarantee.
|
|
136
|
+
"""
|
|
137
|
+
x = np.asarray(embeddings, dtype=float)
|
|
138
|
+
c = np.asarray(centroids, dtype=float)
|
|
139
|
+
if x.ndim != 2 or c.ndim != 2 or c.shape[0] < 2 or x.shape[0] == 0 or x.shape[1] != c.shape[1] or not np.isfinite(x).all() or not np.isfinite(c).all():
|
|
140
|
+
raise ValueError("expected finite (N,D) embeddings and (K,D) centroids, K>=2")
|
|
141
|
+
eps = np.asarray(error_bounds, dtype=float)
|
|
142
|
+
if eps.ndim == 0:
|
|
143
|
+
eps = np.full(x.shape[0], eps.item())
|
|
144
|
+
if eps.shape != (x.shape[0],) or not np.isfinite(eps).all() or (eps < 0).any():
|
|
145
|
+
raise ValueError("error_bounds must be finite nonnegative scalar or length N")
|
|
146
|
+
distances = np.linalg.norm(x[:,None,:]-c[None,:,:], axis=2)
|
|
147
|
+
idx = np.argmin(distances, axis=1)
|
|
148
|
+
top2 = np.partition(distances, 1, axis=1)[:,:2]
|
|
149
|
+
gap = top2[:,1] - top2[:,0]
|
|
150
|
+
return gap > 2*eps, gap, idx
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
"""scikit-learn-style convenience wrappers, not learned reliability estimators."""
|
|
2
|
+
import numpy as np
|
|
3
|
+
from sklearn.base import BaseEstimator, TransformerMixin, ClusterMixin
|
|
4
|
+
from sklearn.cluster import KMeans
|
|
5
|
+
from .core import fuse_blocks
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class BARGCCTransformer(TransformerMixin, BaseEstimator):
|
|
9
|
+
"""Pass X=(views, availability[, scores]); never learns quality scores.
|
|
10
|
+
|
|
11
|
+
Consistent feature transforms/scalers must be fitted upstream on training
|
|
12
|
+
data only. The gate is deterministic for supplied scores and masks.
|
|
13
|
+
"""
|
|
14
|
+
def __init__(self, kappa=0.0, rho=None, dimension_balance=False, row_normalize=False):
|
|
15
|
+
self.kappa = kappa
|
|
16
|
+
self.rho = rho
|
|
17
|
+
self.dimension_balance = dimension_balance
|
|
18
|
+
self.row_normalize = row_normalize
|
|
19
|
+
|
|
20
|
+
def fit(self, X, y=None):
|
|
21
|
+
self.transform(X)
|
|
22
|
+
return self
|
|
23
|
+
|
|
24
|
+
def transform(self, X):
|
|
25
|
+
if not isinstance(X, (list, tuple)) or len(X) not in (2,3):
|
|
26
|
+
raise ValueError("X must be (views, availability[, scores])")
|
|
27
|
+
views, availability = X[:2]
|
|
28
|
+
scores = X[2] if len(X)==3 else None
|
|
29
|
+
return fuse_blocks(views, availability, scores, kappa=self.kappa,
|
|
30
|
+
rho=self.rho, dimension_balance=self.dimension_balance,
|
|
31
|
+
row_normalize=self.row_normalize)[0]
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class BARGCCKMeans(ClusterMixin, BaseEstimator):
|
|
35
|
+
"""Fit K-means on training-only fused blocks, then predict held-out rows."""
|
|
36
|
+
def __init__(self, n_clusters=4, kappa=0.0, rho=None, dimension_balance=False,
|
|
37
|
+
row_normalize=False, random_state=0, n_init=10):
|
|
38
|
+
self.n_clusters=n_clusters
|
|
39
|
+
self.kappa=kappa
|
|
40
|
+
self.rho=rho
|
|
41
|
+
self.dimension_balance=dimension_balance
|
|
42
|
+
self.row_normalize=row_normalize
|
|
43
|
+
self.random_state=random_state
|
|
44
|
+
self.n_init=n_init
|
|
45
|
+
|
|
46
|
+
def _transformer(self):
|
|
47
|
+
return BARGCCTransformer(self.kappa,self.rho,self.dimension_balance,self.row_normalize)
|
|
48
|
+
|
|
49
|
+
def fit(self, X, y=None):
|
|
50
|
+
self.transformer_ = self._transformer()
|
|
51
|
+
z = self.transformer_.fit_transform(X)
|
|
52
|
+
self.model_ = KMeans(n_clusters=self.n_clusters, random_state=self.random_state, n_init=self.n_init)
|
|
53
|
+
self.model_.fit(z)
|
|
54
|
+
self.cluster_centers_ = self.model_.cluster_centers_
|
|
55
|
+
self.labels_ = self.model_.labels_
|
|
56
|
+
return self
|
|
57
|
+
|
|
58
|
+
def predict(self, X):
|
|
59
|
+
from sklearn.utils.validation import check_is_fitted
|
|
60
|
+
check_is_fitted(self, "model_")
|
|
61
|
+
return self.model_.predict(self.transformer_.transform(X))
|
|
62
|
+
|
|
63
|
+
def fit_predict(self, X, y=None):
|
|
64
|
+
return self.fit(X).labels_
|
|
65
|
+
|
|
66
|
+
def transform(self, X):
|
|
67
|
+
from sklearn.utils.validation import check_is_fitted
|
|
68
|
+
check_is_fitted(self, "transformer_")
|
|
69
|
+
return self.transformer_.transform(X)
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
"""Optional torch reference architecture, not an archived-checkpoint reproduction.
|
|
2
|
+
|
|
3
|
+
The neural training recipe and objectives in the paper are not fully specified
|
|
4
|
+
by this standalone model. Custom training losses and the experimental protocol
|
|
5
|
+
must be supplied by researchers; no trained model weights are shipped.
|
|
6
|
+
"""
|
|
7
|
+
try:
|
|
8
|
+
import torch
|
|
9
|
+
from torch import nn
|
|
10
|
+
except ImportError as exc:
|
|
11
|
+
raise ImportError("Neural BARG-CC requires pip install 'bargcc[torch]'") from exc
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class NeuralBARGCC(nn.Module):
|
|
15
|
+
"""Per-view encoders + masked gate + view-aligned residual fusion.
|
|
16
|
+
|
|
17
|
+
This is a reference *building block*, not a claim of exact manuscript
|
|
18
|
+
benchmark replication. Input encoders are MLPs for pre-extracted features.
|
|
19
|
+
mask is Boolean (B,M); quality in [0,1], (B,M).
|
|
20
|
+
Output is (B, embedding_dim), with optional soft cluster logits.
|
|
21
|
+
"""
|
|
22
|
+
def __init__(self, view_dims, embedding_dim=64, hidden_dim=128,
|
|
23
|
+
kappa=0.0, rho=None, residual_gamma=0.5, n_clusters=None):
|
|
24
|
+
super().__init__()
|
|
25
|
+
if not view_dims or min(view_dims) < 1 or embedding_dim<1 or hidden_dim<1:
|
|
26
|
+
raise ValueError("positive nonempty view dimensions required")
|
|
27
|
+
from .core import certified_strength
|
|
28
|
+
self.view_dims = list(view_dims)
|
|
29
|
+
self.kappa = float(kappa)
|
|
30
|
+
self.rho = rho
|
|
31
|
+
self.residual_gamma = float(residual_gamma)
|
|
32
|
+
if not 0<=residual_gamma or not torch.isfinite(torch.tensor(self.kappa)) or self.kappa<0:
|
|
33
|
+
raise ValueError("invalid kappa or residual_gamma")
|
|
34
|
+
if rho is not None and self.kappa > certified_strength(rho,len(view_dims)) + 1e-12:
|
|
35
|
+
raise ValueError("gate strength exceeds participation floor limit")
|
|
36
|
+
self.encoders=nn.ModuleList([
|
|
37
|
+
nn.Sequential(nn.Linear(d,hidden_dim), nn.ReLU(), nn.Linear(hidden_dim,embedding_dim))
|
|
38
|
+
for d in view_dims])
|
|
39
|
+
self.residual=nn.Sequential(nn.Linear(embedding_dim,embedding_dim),nn.Tanh())
|
|
40
|
+
self.projection=nn.Linear(embedding_dim,embedding_dim,bias=False)
|
|
41
|
+
self.head=nn.Linear(embedding_dim,n_clusters) if n_clusters is not None else None
|
|
42
|
+
|
|
43
|
+
def forward(self, views, availability, quality, *, return_weights=False):
|
|
44
|
+
if len(views)!=len(self.view_dims):
|
|
45
|
+
raise ValueError("number of views differs from architecture")
|
|
46
|
+
n=views[0].shape[0]
|
|
47
|
+
device=views[0].device
|
|
48
|
+
if availability.shape!=(n,len(views)) or quality.shape!=(n,len(views)):
|
|
49
|
+
raise ValueError("mask and quality must be (batch,n_views)")
|
|
50
|
+
if not torch.all((availability==0)|(availability==1)):
|
|
51
|
+
raise ValueError("binary availability required")
|
|
52
|
+
mask=availability.to(device=device,dtype=torch.bool)
|
|
53
|
+
if not torch.all(mask.any(dim=1)):
|
|
54
|
+
raise ValueError("all-missing records are rejected")
|
|
55
|
+
q=quality.to(device=device,dtype=views[0].dtype)
|
|
56
|
+
if not bool(torch.isfinite(q).all()) or not bool(((q>=0)&(q<=1)).all()):
|
|
57
|
+
raise ValueError("quality must be finite in [0,1]")
|
|
58
|
+
logits=(self.kappa*(2*q-1)).masked_fill(~mask,torch.finfo(q.dtype).min)
|
|
59
|
+
alpha=torch.softmax(logits,dim=1)*mask
|
|
60
|
+
alpha=alpha/alpha.sum(dim=1,keepdim=True)
|
|
61
|
+
embeddings=[]
|
|
62
|
+
for j,(v, enc) in enumerate(zip(views,self.encoders)):
|
|
63
|
+
if v.shape != (n,self.view_dims[j]):
|
|
64
|
+
raise ValueError("view input shape mismatch")
|
|
65
|
+
embeddings.append(enc(v)*mask[:,j:j+1])
|
|
66
|
+
h=torch.stack(embeddings,dim=1)
|
|
67
|
+
# centered score shifts modulate a view-aligned residual contribution.
|
|
68
|
+
mean=(q*mask).sum(dim=1,keepdim=True)/mask.sum(dim=1,keepdim=True)
|
|
69
|
+
adjusted=h+self.residual_gamma*(q-mean)[:,:,None]*self.residual(h)
|
|
70
|
+
weighted=(alpha[:,:,None]*adjusted).sum(dim=1)
|
|
71
|
+
fused=self.projection(weighted)
|
|
72
|
+
result=(fused,self.head(fused)) if self.head is not None else fused
|
|
73
|
+
return (result,alpha) if return_weights else result
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
"""Fail-closed decision logic. Confidence bounds MUST be justified externally."""
|
|
2
|
+
from dataclasses import dataclass
|
|
3
|
+
import math
|
|
4
|
+
from collections.abc import Mapping
|
|
5
|
+
import numpy as np
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
@dataclass(frozen=True)
|
|
9
|
+
class SelectionDecision:
|
|
10
|
+
selected: str
|
|
11
|
+
adopted: bool
|
|
12
|
+
reason: str
|
|
13
|
+
margins: dict
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def conservative_adopt(reference_lower_bounds: Mapping[str,float],
|
|
17
|
+
uniform_lower_bound: float, *,
|
|
18
|
+
utility_margin: float = 0.0, quality_margin: float = 0.0,
|
|
19
|
+
candidate="gated", fallback="masking") -> SelectionDecision:
|
|
20
|
+
"""Adopt iff ALL externally valid simultaneous lower bounds clear margins.
|
|
21
|
+
|
|
22
|
+
This function does not calculate confidence bounds or claim coverage.
|
|
23
|
+
Inputs must correspond to frozen candidates, matched development groups,
|
|
24
|
+
and a valid simultaneous one-sided procedure, not inspected test scores.
|
|
25
|
+
"""
|
|
26
|
+
if not reference_lower_bounds:
|
|
27
|
+
raise ValueError("at least one reference is required")
|
|
28
|
+
if not all(math.isfinite(x) and x>=0 for x in (utility_margin,quality_margin)):
|
|
29
|
+
raise ValueError("margins must be finite and nonnegative")
|
|
30
|
+
if not isinstance(candidate, str) or not isinstance(fallback,str) or not candidate or not fallback or candidate==fallback:
|
|
31
|
+
raise ValueError("distinct candidate and fallback names required")
|
|
32
|
+
bounds = dict(reference_lower_bounds)
|
|
33
|
+
if not all(isinstance(k,str) and k for k in bounds):
|
|
34
|
+
raise ValueError("reference names must be nonempty strings")
|
|
35
|
+
values = list(bounds.values()) + [uniform_lower_bound]
|
|
36
|
+
# Treat invalid/incomplete evidence as no adoption rather than guessing.
|
|
37
|
+
if any(v is None or not isinstance(v,(int,float,np.floating)) or not np.isfinite(v) for v in values):
|
|
38
|
+
return SelectionDecision(fallback,False,"missing or invalid lower-bound evidence",bounds)
|
|
39
|
+
accepted = (all(v > utility_margin for v in bounds.values()) and uniform_lower_bound > quality_margin)
|
|
40
|
+
reason = "all supplied simultaneous lower bounds clear margins" if accepted else "one or more lower bounds do not clear prespecified margins"
|
|
41
|
+
return SelectionDecision(candidate if accepted else fallback,accepted,reason,bounds)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def bonferroni_normal_bounds(paired_by_reference: Mapping[str,np.ndarray], alpha=0.05):
|
|
45
|
+
"""Descriptive normal-theory simultaneous one-sided LCBs for paired groups.
|
|
46
|
+
|
|
47
|
+
CAUTION: This is NOT a general population-coverage guarantee. Group rows
|
|
48
|
+
must be independent and representative, variance and normal approximation
|
|
49
|
+
justified, and contrasts prespecified. Do not use overlapping resplits or
|
|
50
|
+
pooled OCR tokens as independent groups. For confirmatory use validate
|
|
51
|
+
assumptions, target estimand, and all multiplicity family members first.
|
|
52
|
+
"""
|
|
53
|
+
from statistics import NormalDist
|
|
54
|
+
if not 0 < alpha < 1 or not paired_by_reference:
|
|
55
|
+
raise ValueError("require 0<alpha<1 and at least one comparison")
|
|
56
|
+
result={}
|
|
57
|
+
critical = NormalDist().inv_cdf(1-alpha/len(paired_by_reference))
|
|
58
|
+
for key, x in paired_by_reference.items():
|
|
59
|
+
a=np.asarray(x,dtype=float)
|
|
60
|
+
if a.ndim != 1 or len(a)<3 or not np.isfinite(a).all():
|
|
61
|
+
raise ValueError("each contrast requires >=3 finite group-level differences")
|
|
62
|
+
result[key]=float(a.mean()-critical*a.std(ddof=1)/np.sqrt(len(a)))
|
|
63
|
+
return result
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: bargcc
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: BARG-CC: certified reliability gating and selective adoption for multi-view clustering
|
|
5
|
+
Author-email: Debmalya Ray <debmalya.ray9989@gmail.com>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Repository, https://huggingface.co/spaces/Debmalya/barg-cc-neural-workbench-static/tree/main
|
|
8
|
+
Keywords: multi-view clustering,reliability,masked softmax,certification,neuro-symbolic
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Operating System :: OS Independent
|
|
11
|
+
Classifier: Intended Audience :: Science/Research
|
|
12
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
13
|
+
Requires-Python: >=3.10
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Requires-Dist: numpy>=1.24
|
|
17
|
+
Requires-Dist: scikit-learn>=1.2
|
|
18
|
+
Provides-Extra: torch
|
|
19
|
+
Requires-Dist: torch>=2.1; extra == "torch"
|
|
20
|
+
Provides-Extra: dev
|
|
21
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
22
|
+
Requires-Dist: build>=1; extra == "dev"
|
|
23
|
+
Dynamic: license-file
|
|
24
|
+
|
|
25
|
+
# BARG-CC Python package (`bargcc`)
|
|
26
|
+
|
|
27
|
+
Installable research library built from the BARG-CC IEEE TNNLS architecture, **not** a reproduction of the manuscript's archived neural checkpoints or published experimental results. Main features:
|
|
28
|
+
|
|
29
|
+
- Certified availability-masked softmax (no post-hoc probability flooring)
|
|
30
|
+
- Guaranteed minimum participation share under the manuscript's restricted gate strength
|
|
31
|
+
- Score-weighted block concatenation and transparent geometric controls
|
|
32
|
+
- Fixed-mask / fixed-embedding perturbation and frozen-centroid assignment certificates
|
|
33
|
+
- scikit-learn-compatible block transformer and training-only fitted K-means wrapper
|
|
34
|
+
- Fail-closed selective-adoption decision when **externally justified** simultaneous lower bounds are supplied
|
|
35
|
+
- Optional PyTorch per-view encoder and residual fusion reference scaffold
|
|
36
|
+
- CLI, tests and examples
|
|
37
|
+
|
|
38
|
+
## Install
|
|
39
|
+
|
|
40
|
+
From the unpacked release directory:
|
|
41
|
+
|
|
42
|
+
```powershell
|
|
43
|
+
python -m pip install .
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Or install the prebuilt wheel locally:
|
|
47
|
+
|
|
48
|
+
```powershell
|
|
49
|
+
python -m pip install ./dist/bargcc-0.1.0-py3-none-any.whl
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Optional neural module:
|
|
53
|
+
|
|
54
|
+
```powershell
|
|
55
|
+
python -m pip install '.[torch]'
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**IMPORTANT:** `pip install bargcc` from the public PyPI index will work **only after you publish** this project to PyPI; this release is a local pip-installable wheel and source package. The project name is not claimed to be available on PyPI.
|
|
59
|
+
|
|
60
|
+
## Quickstart
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
import numpy as np
|
|
64
|
+
from bargcc import fuse_blocks, certified_strength, BARGCCKMeans
|
|
65
|
+
|
|
66
|
+
rng=np.random.default_rng(0)
|
|
67
|
+
views=[rng.normal(size=(100,144)),rng.normal(size=(100,128)),rng.normal(size=(100,16))]
|
|
68
|
+
mask=np.ones((100,3),dtype=bool)
|
|
69
|
+
mask[::5,1]=False
|
|
70
|
+
scores=rng.uniform(size=(100,3))
|
|
71
|
+
kappa=certified_strength(0.1,3) # approximately 0.75204
|
|
72
|
+
z,weights,certificate=fuse_blocks(views,mask,scores,kappa=kappa,rho=0.1)
|
|
73
|
+
print(z.shape,certificate.certified,weights[mask].min())
|
|
74
|
+
model=BARGCCKMeans(n_clusters=4,kappa=kappa,rho=0.1,random_state=0)
|
|
75
|
+
model.fit((views,mask,scores))
|
|
76
|
+
print(model.labels_[:5])
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`bargcc certify --rho 0.1 --views 3` prints the floor-constrained strength limit.
|
|
80
|
+
|
|
81
|
+
### NPZ CLI
|
|
82
|
+
|
|
83
|
+
Save `view_0`, `view_1`, ... matrices, `mask` (N by M binary), optional `scores` (N by M in [0,1]) into `inputs.npz` and run:
|
|
84
|
+
|
|
85
|
+
```powershell
|
|
86
|
+
bargcc fuse inputs.npz output.npz --rho 0.1 --kappa 0.75 --dimension-balance
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The output contains `fused`, `weights` and `mask`. **Never pass a real dataset without checking access rights and provenance.**
|
|
90
|
+
|
|
91
|
+
## Reproducibility and scientific scope
|
|
92
|
+
|
|
93
|
+
The certificate assumes a fixed view mask and frozen embeddings. The clustering certificate additionally assumes fixed centroids. If scores are estimated, you need an independently valid score-error bound; quality scores alone are not evidence of semantic clustering utility. The neural module is a reusable reference building block: it omits experiment-specific training loss recipes, quality-proxy fitting, token encoders and checkpoint weights. No FUNSD or other dataset is bundled. Normalization and dimensions must be controlled and fitted on training data only. The `conservative_adopt` function accepts supplied lower confidence bounds but **does not establish their statistical coverage**.
|
|
94
|
+
|
|
95
|
+
No end-to-end benchmarks are claimed for this release. Before journal-level replication, conduct independent benchmarks and matched official-code comparisons.
|
|
96
|
+
|
|
97
|
+
## Release guide
|
|
98
|
+
|
|
99
|
+
See `PUBLISH_PYPI.md` for instructions to publish publicly and enable `pip install bargcc` by name.
|
|
100
|
+
|
|
101
|
+
## License
|
|
102
|
+
|
|
103
|
+
MIT license applies to the *new package code only*. It is not a relicensing of any attached third-party model, original experiment, or dataset.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
ARCHITECTURE_MAPPING.md
|
|
2
|
+
LICENSE
|
|
3
|
+
MANIFEST.in
|
|
4
|
+
PUBLISH_PYPI.md
|
|
5
|
+
README.md
|
|
6
|
+
WINDOWS_INSTALL.ps1
|
|
7
|
+
pyproject.toml
|
|
8
|
+
setup.py
|
|
9
|
+
examples/neural_reference.py
|
|
10
|
+
examples/quickstart.py
|
|
11
|
+
src/bargcc/__init__.py
|
|
12
|
+
src/bargcc/cli.py
|
|
13
|
+
src/bargcc/core.py
|
|
14
|
+
src/bargcc/estimators.py
|
|
15
|
+
src/bargcc/neural.py
|
|
16
|
+
src/bargcc/selection.py
|
|
17
|
+
src/bargcc.egg-info/PKG-INFO
|
|
18
|
+
src/bargcc.egg-info/SOURCES.txt
|
|
19
|
+
src/bargcc.egg-info/dependency_links.txt
|
|
20
|
+
src/bargcc.egg-info/entry_points.txt
|
|
21
|
+
src/bargcc.egg-info/requires.txt
|
|
22
|
+
src/bargcc.egg-info/top_level.txt
|
|
23
|
+
tests/test_core.py
|
|
24
|
+
tests/test_neural.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
bargcc
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import math
|
|
2
|
+
import numpy as np
|
|
3
|
+
import pytest
|
|
4
|
+
from bargcc import (certified_strength,certified_weights,fuse_blocks,
|
|
5
|
+
block_perturbation_bound,centroid_assignment_certificate,
|
|
6
|
+
conservative_adopt,BARGCCKMeans,BARGCCTransformer)
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def fixture():
|
|
10
|
+
views=[np.array([[1.,2.],[3.,4.],[5.,6.]]),np.array([[1.],[5.],[2.]])]
|
|
11
|
+
mask=np.array([[1,1],[1,0],[0,1]])
|
|
12
|
+
score=np.array([[.3,.7],[.9,.8],[.4,.1]])
|
|
13
|
+
return views,mask,score
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def test_strength():
|
|
17
|
+
assert abs(certified_strength(.1,3)-0.5*math.log(9/2))<1e-12
|
|
18
|
+
assert math.isinf(certified_strength(.1,1))
|
|
19
|
+
with pytest.raises(ValueError): certified_strength(.5,3)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def test_masked_gate():
|
|
23
|
+
v,m,s=fixture()
|
|
24
|
+
alpha,c=certified_weights(s,m,kappa=.75,rho=.1)
|
|
25
|
+
assert c.certified
|
|
26
|
+
np.testing.assert_allclose(alpha.sum(1),1)
|
|
27
|
+
assert alpha[1,1]==0 and alpha[2,0]==0
|
|
28
|
+
assert np.all(alpha[m.astype(bool)] >= .1 - 1e-12)
|
|
29
|
+
with pytest.raises(ValueError): certified_weights(s,m,kappa=5,rho=.1)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def test_uniform_masking():
|
|
33
|
+
v,m,s=fixture()
|
|
34
|
+
z,a,_=fuse_blocks(v,m,s,kappa=0)
|
|
35
|
+
np.testing.assert_allclose(a[0],[.5,.5])
|
|
36
|
+
np.testing.assert_allclose(z[0],[1,2,1])
|
|
37
|
+
assert np.all(z[1,-1:]==0) and np.all(z[2,:2]==0)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def test_dimension_balance_and_norm():
|
|
41
|
+
v,m,s=fixture()
|
|
42
|
+
z,a,c=fuse_blocks(v,m,s,kappa=.1,rho=.1,dimension_balance=True,row_normalize=True)
|
|
43
|
+
np.testing.assert_allclose(np.linalg.norm(z,axis=1),1)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def test_reject_all_missing():
|
|
47
|
+
v,m,s=fixture(); m[0]=0
|
|
48
|
+
with pytest.raises(ValueError): fuse_blocks(v,m,s)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def test_reject_bad_scores():
|
|
52
|
+
v,m,s=fixture(); s[0,0]=2
|
|
53
|
+
with pytest.raises(ValueError): fuse_blocks(v,m,s)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def test_bound_and_centroid_certificate():
|
|
57
|
+
assert block_perturbation_bound(2,3,.5,.2)==pytest.approx(2*math.sqrt(3)*.1)
|
|
58
|
+
ok,gap,idx=centroid_assignment_certificate([[.01,0.],[.5,0.]],[[0.,0.],[1.,0.]],[.1,0.])
|
|
59
|
+
assert ok.tolist()==[True,False]
|
|
60
|
+
assert idx[0]==0
|
|
61
|
+
assert gap[1]==0
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def test_bound_numerical_random():
|
|
65
|
+
rng=np.random.default_rng(0)
|
|
66
|
+
for _ in range(50):
|
|
67
|
+
v=[rng.normal(size=(1,6)) for _ in range(3)]
|
|
68
|
+
v=[x / max(1,np.linalg.norm(x)) for x in v]
|
|
69
|
+
mask=np.ones((1,3),bool)
|
|
70
|
+
s=rng.uniform(size=(1,3))
|
|
71
|
+
d=rng.uniform(-.1,.1,size=(1,3))
|
|
72
|
+
s2=np.clip(s+d,0,1)
|
|
73
|
+
kappa=.7
|
|
74
|
+
z1,_,_=fuse_blocks(v,mask,s,kappa=kappa)
|
|
75
|
+
z2,_,_=fuse_blocks(v,mask,s2,kappa=kappa)
|
|
76
|
+
bound=block_perturbation_bound(1,3,kappa,np.abs(s-s2).max())
|
|
77
|
+
assert np.linalg.norm(z1-z2)<=bound+1e-10
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def test_selector_fail_closed():
|
|
81
|
+
assert conservative_adopt({'mask':.05,'other':.04},.01).adopted
|
|
82
|
+
assert not conservative_adopt({'mask':.05,'other':-.01},.01).adopted
|
|
83
|
+
assert not conservative_adopt({'mask':None},.01).adopted
|
|
84
|
+
assert not conservative_adopt({'mask':.05},float('nan')).adopted
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
def test_estimator():
|
|
88
|
+
rng=np.random.default_rng(1)
|
|
89
|
+
views=[rng.normal(size=(20,3)),rng.normal(size=(20,2))]
|
|
90
|
+
mask=np.ones((20,2),bool)
|
|
91
|
+
scores=np.full((20,2),.5)
|
|
92
|
+
X=(views,mask,scores)
|
|
93
|
+
m=BARGCCKMeans(n_clusters=3,rho=.1,kappa=.7,random_state=1).fit(X)
|
|
94
|
+
assert m.predict(X).shape==(20,)
|
|
95
|
+
assert BARGCCTransformer(kappa=.7,rho=.1).fit_transform(X).shape==(20,5)
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import pytest
|
|
2
|
+
|
|
3
|
+
def test_neural_forward():
|
|
4
|
+
torch = pytest.importorskip("torch")
|
|
5
|
+
from bargcc.neural import NeuralBARGCC
|
|
6
|
+
net=NeuralBARGCC([4,3],embedding_dim=8,hidden_dim=12,kappa=.7,rho=.1,n_clusters=3)
|
|
7
|
+
views=[torch.randn(5,4),torch.randn(5,3)]
|
|
8
|
+
mask=torch.ones(5,2,dtype=torch.bool)
|
|
9
|
+
mask[0,1]=0
|
|
10
|
+
quality=torch.rand(5,2)
|
|
11
|
+
(h,logits),a=net(views,mask,quality,return_weights=True)
|
|
12
|
+
assert h.shape==(5,8) and logits.shape==(5,3)
|
|
13
|
+
assert a[0,1]==0
|
|
14
|
+
assert torch.allclose(a.sum(1),torch.ones(5),atol=1e-6)
|
|
15
|
+
(h.sum()+logits.sum()).backward()
|