bargcc 0.1.0__py3-none-any.whl
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/__init__.py +11 -0
- bargcc/cli.py +39 -0
- bargcc/core.py +150 -0
- bargcc/estimators.py +69 -0
- bargcc/neural.py +73 -0
- bargcc/selection.py +63 -0
- bargcc-0.1.0.dist-info/METADATA +103 -0
- bargcc-0.1.0.dist-info/RECORD +12 -0
- bargcc-0.1.0.dist-info/WHEEL +5 -0
- bargcc-0.1.0.dist-info/entry_points.txt +2 -0
- bargcc-0.1.0.dist-info/licenses/LICENSE +21 -0
- bargcc-0.1.0.dist-info/top_level.txt +1 -0
bargcc/__init__.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"]
|
bargcc/cli.py
ADDED
|
@@ -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()
|
bargcc/core.py
ADDED
|
@@ -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
|
bargcc/estimators.py
ADDED
|
@@ -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)
|
bargcc/neural.py
ADDED
|
@@ -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
|
bargcc/selection.py
ADDED
|
@@ -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,12 @@
|
|
|
1
|
+
bargcc/__init__.py,sha256=RATQTvUYCpVHU0sqHg-vR_b2yOKDwjqO7_8j0rXqeWs,746
|
|
2
|
+
bargcc/cli.py,sha256=83k7Qld_7hGliXVZoFrqt7oB9snqAldC3GWPetyZW5g,1916
|
|
3
|
+
bargcc/core.py,sha256=oweFTu4Wvs3uLnRDKtyQIkbi8Ixdb4oIaVXsmQ3tjzs,7097
|
|
4
|
+
bargcc/estimators.py,sha256=GEKgCM7iQeSGxbsNrwhjgMHknSJkVoTqHncVbRmRXf8,2768
|
|
5
|
+
bargcc/neural.py,sha256=pzO5rjmwmx7dNSViB7DLeJSRHlLbeBwqu-PR_FHd6cc,3971
|
|
6
|
+
bargcc/selection.py,sha256=fLGnxds1-bAMZ_A5qOCQhThvzU9meN6U5wBesyC__sc,3352
|
|
7
|
+
bargcc-0.1.0.dist-info/licenses/LICENSE,sha256=eaI_ILlA6fcl_eljRwiCgHJ2Ag5AGXn2GuhZwqwXQjg,1069
|
|
8
|
+
bargcc-0.1.0.dist-info/METADATA,sha256=Yfia83yUA-fFZvcxE4yg4JcDc4E1DtF6Nk-t-10zB3A,4717
|
|
9
|
+
bargcc-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
10
|
+
bargcc-0.1.0.dist-info/entry_points.txt,sha256=SsDsru5zvX-WqPBnhZtC8O64aX8ByfJr-6n2tKGhspw,43
|
|
11
|
+
bargcc-0.1.0.dist-info/top_level.txt,sha256=eFSmRl47iF4VCEsoKIuJqm720_eJuGMZl2ziufZwUXQ,7
|
|
12
|
+
bargcc-0.1.0.dist-info/RECORD,,
|
|
@@ -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.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
bargcc
|