si4onnx package

Submodules

si4onnx.data module

class si4onnx.data.SyntheticDataset(n_samples, shape, loc=0, scale=1, local_signal=0, local_size=None, seed=0)

Bases: Dataset

A PyTorch Dataset for generating synthetic data with iid Gaussian noise and local signals.

This dataset generates samples containing Gaussian noise with optional local signals added at random positions.

The dataset generates three components for each sample:

Data: Tensor containing Gaussian noise with optional local signals
Mask: Binary tensor indicating the position of local signals
Label: Binary value indicating presence of local signal

data

Array containing the generated synthetic data.

Type:: numpy.ndarray

masks

Array containing the masks for local signals.

Type:: numpy.ndarray

labels

Array containing the binary labels.

Type:: numpy.ndarray

Examples

>>> dataset = SyntheticDataset(
...     n_samples=1000,
...     shape=(32, 32),
...     loc=0,
...     scale=1,
...     local_signal=2.0
... )
>>> data, mask, label = dataset[0]
>>> print(data.shape, mask.shape, label.shape)
torch.Size([32, 32]) torch.Size([32, 32]) torch.Size([])

si4onnx.data.generate_iid_data(n_samples, shape, loc=0, scale=1, local_signal=0, local_size=None, seed=0)

Generate synthetic data with iid Gaussian noise and local signals.

Parameters:

n_samples (int) – The number of samples.
shape (tuple) – The shape of the data (channels, height, width).
loc (float, optional) – The mean of the Gaussian noise. Default is 0.0.
scale (float, optional) – The standard deviation of the Gaussian noise. Default is 1.0.
local_signal (float, optional) – The strength of the local signal to add. Default is 0.0.
local_size (int or None, optional) – The size of the local signal region. If None, uses min(height, width) // 3.
seed (int, optional) – The seed for reproducibility. Default is 0.

Returns:

np.ndarray – The generated data of shape (size, channels, height, width).
np.ndarray – Binary masks indicating signal locations of shape (size, channels, height, width).
np.ndarray – Binary labels indicating presence of signal of shape (size,).

si4onnx.hypothesis module

class si4onnx.hypothesis.BackMeanDiff(threshold: float, i_idx: int = 0, o_idx: int = 0, post_process: Operator | list[Operator] = [], use_norm: bool = False, **kwargs)

Bases: PresetHypothesis

Hypothesis for the mean difference between the ROI and the background region in the input data.

Examples

>>> import onnx
>>> from si4onnx.hypothesis import BackMeanDiff
>>> from si4onnx.operators import InputDiff, Abs
>>> from si4onnx.utils import load
>>> model = onnx.("model.onnx")
>>> si_model = si4onnx.load(
...     model=onnx.load("model.onnx"),
...     hypothesis=BackMeanDiff(
...         threshold=0.5,
...         post_process=[InputDiff(), Abs()]
...     )
... )
... print(si_model.inference(input_image, var=1.0).p_value)

algorithm(si_model: NN, a: Tensor, b: Tensor, z: Tensor) → tuple[Tensor, list]

Parameters:

si_model (NN) – The model for the selective inference.
a (torch.Tensor) – The input tensor a.
b (torch.Tensor) – The input tensor b.
z (float) – The test statistic z.

Returns:

roi_vector (torch.Tensor) – The flattened roi.
[l, u] (list(float)) – The over-conditioning interval that contains z.

Parameters:

si_model (NN) – The model for the selective inference.
X (torch.Tensor | list[torch.Tensor] | tuple[torch.Tensor]) – The input data.
var (float | torch.Tensor | np.ndarray) – The variance of the noise.
mask (torch.Tensor | n.ndarray | None, optional) – A mask that specifies the regions that are not selected as ROI and oter region, that is to say, a mask specify regions that will not be used for the test statistic. Defaults to None.

model_selector(roi_vector: Tensor) → bool

Parameters:: roi_vector (torch.Tensor) – should be a tensor of int
Returns:: True if the input roi_vector is the same as the roi_vector in the construct_hypothesis method
Return type:: bool

class si4onnx.hypothesis.Hypothesis

Bases: ABC

abstract algorithm(a, b, z, **kwargs)

abstract construct_hypothesis(X, si_model, *kwargs)

abstract model_selector(roi_vector, **kwargs)

class si4onnx.hypothesis.NeighborMeanDiff(threshold: float, neighborhood_range: int = 1, i_idx: int = 0, o_idx: int = 0, post_process: Module | list[Module] = [], use_norm: bool = False, **kwargs)

Bases: PresetHypothesis

Hypothesis for the mean difference between the ROI and the neighborhood region in the input data.

Examples

>>> import onnx
>>> from si4onnx.hypothesis import NeigborMeanDiff
>>> from si4onnx.operators import InputDiff, Abs
>>> from si4onnx.utils import load
>>> model = onnx.load("model.onnx")
>>> si_model = si4onnx.load(
...     model=onnx.load("model.onnx"),
...     hypothesis=NeigborMeanDiff(
...         threshold=0.5,
...         post_process=[InputDiff(), Abs()]
...     )
... )
... print(si_model.inference(input_image, var=1.0).p_value)

algorithm(si_model: NN, a: Tensor, b: Tensor, z: Tensor) → tuple[Tensor, list]

Parameters:

si_model (NN) – The model for the selective inference.
a (torch.Tensor) – The input tensor a.
b (torch.Tensor) – The input tensor b.
z (float) – The test statistic z.

Returns:

roi_vector (torch.Tensor) – The flattened roi.
[l, u] (list(float)) – The over-conditioning interval that contains z.

Parameters:

si_model (NN) – The model for the selective inference.
X (torch.Tensor | list[torch.Tensor] | tuple[torch.Tensor]) – The input data.
var (float | torch.Tensor | np.ndarray) – The variance of the noise.
mask (torch.Tensor | n.ndarray | None, optional) – A mask that specifies the regions that are not selected as ROI and oter region, that is to say, a mask specify regions that will not be used for the test statistic. Defaults to None.

model_selector(roi_vector: Tensor) → bool

Parameters:: roi_vector (torch.Tensor) – should be a tensor of int
Returns:: True if the input roi_vector is the same as the roi_vector in the construct_hypothesis method
Return type:: bool

exception si4onnx.hypothesis.NoHypothesisError

Bases: Exception

If the hypothesis is not obtained from observartion, please raise this error

class si4onnx.hypothesis.PresetHypothesis(threshold: float, i_idx: int = 0, o_idx: int = 0, post_process: Operator | list[Operator] = [], use_norm: bool = False, **kwargs): Bases: Hypothesis

class si4onnx.hypothesis.ReferenceMeanDiff(threshold: float, i_idx: int = 0, o_idx: int = 0, post_process: Module | list[Module] = [], use_norm: bool = False, **kwargs)

Bases: PresetHypothesis

Hypothesis for the mean difference between the ROI and the neighborhood region in the input data.

Examples

>>> import onnx
>>> from si4onnx.hypothesis import ReferenceMeanDiff
>>> from si4onnx.operators import InputDiff, Abs
>>> from si4onnx.utils import load
>>> model = onnx.load("model.onnx")
>>> si_model = si4onnx.load(
...     model=onnx.load("model.onnx"),
...     hypothesis=ReferenceMeanDiff(
...         threshold=0.5,
...         post_process=[InputDiff(), Abs()]
...     )
... )
... print(si_model.inference(input=(input_image, reference_image), var=1.0).p_value)

algorithm(si_model: NN, a: Tensor, b: Tensor, z: Tensor) → tuple[Tensor, list]

Parameters:

si_model (NN) – The model for the selective inference.
a (torch.Tensor) – The input tensor a.
b (torch.Tensor) – The input tensor b.
z (float) – The test statistic z.

Returns:

roi_vector (torch.Tensor) – The flattened roi.
[l, u] (list(float)) – The over-conditioning interval that contains z.

construct_hypothesis(si_model: NN, X: tuple, var: float | Tensor | ndarray, mask: Tensor | None = None)

Parameters:

si_model (NN) – The model for the selective inference.
X (tuple) – The tuple of the input data and the reference data. (input_data, reference_data)
var (float | torch.Tensor | n.ndarray) – The variance of the noise.
mask (torch.Tensor | n.ndarray | None, optional) – A mask that specifies the regions that are not selected as ROI and oter region, that is to say, a mask specify regions that will not be used for the test statistic. Defaults to None.

model_selector(roi_vector)

Parameters:: roi_vector (torch.Tensor) – should be a tensor of int
Returns:: True if the input roi_vector is the same as the roi_vector in the construct_hypothesis method
Return type:: bool

si4onnx.hypothesis.check_use_sigmoid(si_model, selected_node_name)

Parameters:

si_model (si4onnx.nn.NN) – The model for the selective inference.
selected_node_name (str) – The name of the selected node.

Returns:

True if the selected node is a Sigmoid.

Return type:

bool

si4onnx.layers module

class si4onnx.layers.Add(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.AveragePool(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.BatchNormalization(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.Concat(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.Constant(inputs, node)

Bases: Layer

forward()

forward_si()

class si4onnx.layers.ConstantOfShape(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.Conv(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.ConvTranspose(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.Div(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.Equal(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.Exp(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.EyeLike(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.Flatten(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.Gemm(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.GlobalAveragePool(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.Greater(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.Layer(inputs, node, **kwargs)

Bases: ABC

abstract forward()

abstract forward_si()

class si4onnx.layers.LeakyRelu(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.MatMul(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.MaxPool(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.Mul(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.RandomNormalLike(inputs, node)

Bases: Layer

forward(x, rng, mean=None, scale=None)

forward_si(output_x, z)

class si4onnx.layers.Reciprocal(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.ReduceSum(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.Relu(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.Reshape(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.Resize(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.Shape(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.Sigmoid(inputs, node)

Bases: Layer

Sigmoid activation function can be used only in the intermediate layers that are not subject to the test or the final layer of the input subject to the test.

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.Slice(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.Split(inputs, node, node_output)

Bases: Layer

forward() → tuple[Tensor]

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.Squeeze(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.Sub(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

class si4onnx.layers.Transpose(inputs, node)

Bases: Layer

forward(x)

forward_si(a, b, l, u, z)

class si4onnx.layers.Unsqueeze(inputs, node, node_output)

Bases: Layer

forward()

forward_si(node, node_output, node_output_si, z)

si4onnx.nn module

class si4onnx.nn.NN(model: ModelProto, seed: int | None = None, memoization: bool = True)

Bases: Module

Deep learning model class for Selective Inference.

forward(input)

Forward pass of the model.

Parameters:: input (torch.Tensor | list[torch.Tensor])
Returns:: output
Return type:: torch.Tensor | list[torch.Tensor]

forward_si(input, a, b, l, u, z)

Forward pass with computing the trancated interval of the output.

Parameters:

input (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list in the deep learning model
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)

Returns:

x (torch.Tensor | list[torch.Tensor]) – output tensor or tensor list in the deep learning model
a (torch.Tensor | list[torch.Tensor]) – output a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – output b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

si4onnx.operators module

class si4onnx.operators.Abs(*args, **kwargs)

Bases: Operator

forward(x)

forward_si(x, a, b, l, u, z)

Compute the interval.

Parameters:

x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)

Returns:

output_x (torch.Tensor | list[torch.Tensor]) – output tensor or tensor list
output_a (torch.Tensor | list[torch.Tensor]) – output a tensor or tensor list
output_b (torch.Tensor | list[torch.Tensor]) – output b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

class si4onnx.operators.AverageFilter(kernel_size: int = 3)

Bases: Operator

forward(x)

forward_si(x, a, b, l, u, z)

Parameters:

x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)

Returns:

output_x (torch.Tensor | list[torch.Tensor]) – output tensor or tensor list
output_a (torch.Tensor | list[torch.Tensor]) – output a tensor or tensor list
output_b (torch.Tensor | list[torch.Tensor]) – output b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

class si4onnx.operators.GaussianFilter(kernel_size: int = 3, sigma: float = 1.0)

Bases: Operator

forward(x)

Compute the convolution of the input tensor with a Gaussian kernel.

Parameters:: x (torch.Tensor) – input tensor
Returns:: output – output tensor
Return type:: torch.Tensor

forward_si(x, a, b, l, u, z)

Parameters:

x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)

Returns:

output_x (torch.Tensor | list[torch.Tensor]) – output tensor or tensor list
output_a (torch.Tensor | list[torch.Tensor]) – output a tensor or tensor list
output_b (torch.Tensor | list[torch.Tensor]) – output b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

class si4onnx.operators.InputDiff(*args, **kwargs)

Bases: Operator

forward(x, input_x)

forward_si(x, a, b, l, u, z, input_x, input_a, input_b)

Compute (x - input_x), (a - input_a), (b - input_b)

Parameters:

x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)
Input_x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
Input_a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
Input_b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list

Returns:

output_x (torch.Tensor | list[torch.Tensor]) – output tensor or tensor list
output_a (torch.Tensor | list[torch.Tensor]) – output a tensor or tensor list
output_b (torch.Tensor | list[torch.Tensor]) – output b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

class si4onnx.operators.Neg(*args, **kwargs)

Bases: Operator

forward(x)

forward_si(x, a, b, l, u, z)

Parameters:

x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)

Returns:

torch.Tensor | list[torch.Tensor] – -x tensor or tensor list
torch.Tensor | list[torch.Tensor] – -a tensor or tensor list
torch.Tensor | list[torch.Tensor] – -b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

class si4onnx.operators.Operator(*args, **kwargs)

Bases: ABC

abstract forward(x, **kwargs)

abstract forward_si(x, a, b, l, u, z, **kwargs)

si4onnx.si module

class si4onnx.si.InferenceResult(stat: float, p_value: float, inf_p: float, sup_p: float, searched_intervals: list[list[float]], truncated_intervals: list[list[float]], search_count: int, detect_count: int, null_rv: rv_continuous, alternative: Literal['two-sided', 'less', 'greater'], output: ndarray, score_map: ndarray, roi: ndarray, non_roi: ndarray | None = None)

Bases: SelectiveInferenceResult

A class extending SelectiveInferenceResult with ROI and output information.

For the attributes inherited from SelectiveInferenceResult, please see its documentation.

output

Output of the inference process.

Type:: np.ndarray

score_map

Score map obtained from the inference process.

Type:: np.ndarray

roi

Region of interest for the inference.

Type:: np.ndarray

non_roi

Region outside of the ROI.

Type:: np.ndarray | None

non_roi: ndarray | None = None: Region outside of the ROI.

output: ndarray: Output of the inference process.

roi: ndarray: Region of interest for the inference.

score_map: ndarray: Score map obtained from the inference process.

class si4onnx.si.PresetSelectiveInferenceModel(model: ModelProto, hypothesis: PresetHypothesis, seed: int | None = None, memoization: bool = True, **kwargs)

Bases: SelectiveInferenceModel

algorithm(a, b, z, **kwargs)

Parameters:

a (torch.Tensor) – A vector of nuisance parameter
b (torch.Tensor) – A vector of the direction of test statistic
z (float) – A test statistic

Returns:

First Elements is outputs obtained in the value of z. Second Element is a obtained truncated interval

Return type:

tuple[object, tuple[float,float]]

Abstruct method for construct hypothesis from the observed output of NN.

Parameters:

input (torch.Tensor | np.ndarray | list | tuple) – Input of NN
var (int | float | np.ndarray | torch.Tensor) – Covariance matrix of input Treated as the diagonal of the covariance matrix, representing independent variances for each dimension.

Raises:

NoHypothesisError – If the hypothesis is not obtained from observartion, please raise this error

Inference process for Selective Inference

Parameters:

input (torch.Tensor | np.ndarray | list[torch.Tensor | np.ndarray] | tuple[torch.Tensor | np.ndarray, ...]) – Input of NN
var (float | np.ndarray | torch.Tensor) – Covariance matrix of the noise of input.
mask (torch.Tensor | np.ndarray | None, optional) – The mask can be used to specify the region that may be used for the hypothesis test. The mask to apply the logical AND operator to the roi and non_roi. Defaults to None.
**kwargs – Arbitrary keyword arguments.
inference_mode (Literal["parametric", "exhaustive", "over_conditioning"], optional) – Must be one of ‘parametric’, ‘exhaustive’,or ‘over_conditioning’. Defaults to ‘parametric’.
max_iter (int, optional) – Maximum number of iterations. Defaults to 100_000.
n_jobs (int, optional) – Number of jobs to run in parallel. Defaults to 1.
step (float, optional) – Step size for the search strategy. Defaults to 1e-6.
significance_level (float, optional) – Significance level only for the termination criterion ‘decision’. Defaults to 0.05.
precision (float, optional) – Precision only for the termination criterion ‘precision’. Defaults to 0.001.

Returns:

The result of the inference.

Return type:

InferenceResult

model_selector(roi, **kwargs)

Abstruct method for compare whether same model are obtained from output and observed output(self.output)

Parameters:: roi_vector (Any) – roi obtained from the output of NN
Returns:: If same models are obtained from output and observed output(self.output), Return value should be true. If not, return value should be false.
Return type:: bool

class si4onnx.si.SelectiveInferenceModel

Bases: ABC

abstract algorithm(a: Tensor, b: Tensor, z: float, **kwargs) → tuple[object, tuple[float, float]]

Parameters:

a (torch.Tensor) – A vector of nuisance parameter
b (torch.Tensor) – A vector of the direction of test statistic
z (float) – A test statistic

Returns:

First Elements is outputs obtained in the value of z. Second Element is a obtained truncated interval

Return type:

tuple[object, tuple[float,float]]

Abstruct method for construct hypothesis from the observed output of NN.

Parameters:

input (torch.Tensor | np.ndarray | list | tuple) – Input of NN
var (int | float | np.ndarray | torch.Tensor) – Covariance matrix of input Treated as the diagonal of the covariance matrix, representing independent variances for each dimension.

Raises:

NoHypothesisError – If the hypothesis is not obtained from observartion, please raise this error

forward(input: Tensor | ndarray) → Tensor

inference(input: Tensor | ndarray, var: float | ndarray | Tensor, **kwargs) → SelectiveInferenceResult

Parameters:

input (torch.Tensor | np.ndarray | list[torch.Tensor | np.ndarray] | tuple[torch.Tensor | np.ndarray, ...]) – Input of NN
var (float | np.ndarray | torch.Tensor) – Covariance matrix of the noise of input.
**kwargs (Any)

Abstruct method for compare whether same model are obtained from output and observed output(self.output)

Parameters:: roi_vector (Any) – roi obtained from the output of NN
Returns:: If same models are obtained from output and observed output(self.output), Return value should be true. If not, return value should be false.
Return type:: bool

si4onnx.si.load(model: ModelProto, hypothesis: PresetHypothesis, seed: float | None = None, memoization: bool = True) → PresetSelectiveInferenceModel

Load onnx model and hypothesis setting to SelectiveInferenceModel

Parameters:

model (onnx.ModelProto) – The onnx model instance.
hypothesis (PresetHypothesis) – The hypothesis setting. You can choose an instance of the class “PresetHypothesis” for preset hypothesis setting.
seed (float, optional) – The seed of random number generator. If the onnx model contains RandomNormalLike layers, the seed is used to generate the same random numbers. Default to None.
memoization (bool, optional) – Whether to use memoization. If True, the memoization is enabled

Returns:

si_model – The Selective Inference model

Return type:

PresetSelectiveInferenceModel

Raises:

ValueError – If hypothesis is not an instance of PresetHypothesis

si4onnx.utils module

si4onnx.utils.thresholding(threshold: Tensor, x: Tensor, a: Tensor, b: Tensor, l: Tensor, u: Tensor, z: Tensor, use_sigmoid: bool = False, use_norm: bool = False)

Threshold the input tensor x with the given threshold (thr) and return the indices greater than thr.

Parameters:

threshold (torch.Tensor) – threshold tensor
x (torch.Tensor) – input tensor
a (torch.Tensor) – a tensor
b (torch.Tensor) – b tensor
use_sigmoid (bool, optional) – Whether to use sigmoid or not in the output layer. Defaults to False
use_norm (bool, optional) – Whether to apply min-max normalization. Defaults to False

Returns:

torch.Tensor – threshold index, which is greater than the threshold The shape of the tensor is flattened.
float – lower bound of the truncated interval
float – upper bound of the truncated interval

Convert input to numpy array if it’s a PyTorch tensor.

Parameters:: input (np.ndarray | torch.Tensor | List[np.ndarray | torch.Tensor] | Tuple[np.ndarray | torch.Tensor, ...]) – Input data (numpy array or torch tensor)
Returns:: Numpy array of the input data
Return type:: numpy.ndarray or None

si4onnx.utils.to_torch_tensor(input: Tensor | ndarray)

Convert input to PyTorch tensor if it’s a numpy array.

Parameters:: input (np.ndarray | torch.Tensor) – Input data (numpy array or torch tensor)
Returns:: torch.Tensor of type double
Return type:: torch.Tensor

Module contents

class si4onnx.Abs(*args, **kwargs)

Bases: Operator

forward(x)

forward_si(x, a, b, l, u, z)

Compute the interval.

Parameters:

x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)

Returns:

output_x (torch.Tensor | list[torch.Tensor]) – output tensor or tensor list
output_a (torch.Tensor | list[torch.Tensor]) – output a tensor or tensor list
output_b (torch.Tensor | list[torch.Tensor]) – output b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

class si4onnx.AverageFilter(kernel_size: int = 3)

Bases: Operator

forward(x)

forward_si(x, a, b, l, u, z)

Parameters:

x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)

Returns:

output_x (torch.Tensor | list[torch.Tensor]) – output tensor or tensor list
output_a (torch.Tensor | list[torch.Tensor]) – output a tensor or tensor list
output_b (torch.Tensor | list[torch.Tensor]) – output b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

class si4onnx.BackMeanDiff(threshold: float, i_idx: int = 0, o_idx: int = 0, post_process: Operator | list[Operator] = [], use_norm: bool = False, **kwargs)

Bases: PresetHypothesis

Hypothesis for the mean difference between the ROI and the background region in the input data.

Examples

>>> import onnx
>>> from si4onnx.hypothesis import BackMeanDiff
>>> from si4onnx.operators import InputDiff, Abs
>>> from si4onnx.utils import load
>>> model = onnx.("model.onnx")
>>> si_model = si4onnx.load(
...     model=onnx.load("model.onnx"),
...     hypothesis=BackMeanDiff(
...         threshold=0.5,
...         post_process=[InputDiff(), Abs()]
...     )
... )
... print(si_model.inference(input_image, var=1.0).p_value)

algorithm(si_model: NN, a: Tensor, b: Tensor, z: Tensor) → tuple[Tensor, list]

Parameters:

si_model (NN) – The model for the selective inference.
a (torch.Tensor) – The input tensor a.
b (torch.Tensor) – The input tensor b.
z (float) – The test statistic z.

Returns:

roi_vector (torch.Tensor) – The flattened roi.
[l, u] (list(float)) – The over-conditioning interval that contains z.

Parameters:

si_model (NN) – The model for the selective inference.
X (torch.Tensor | list[torch.Tensor] | tuple[torch.Tensor]) – The input data.
var (float | torch.Tensor | np.ndarray) – The variance of the noise.
mask (torch.Tensor | n.ndarray | None, optional) – A mask that specifies the regions that are not selected as ROI and oter region, that is to say, a mask specify regions that will not be used for the test statistic. Defaults to None.

model_selector(roi_vector: Tensor) → bool

Parameters:: roi_vector (torch.Tensor) – should be a tensor of int
Returns:: True if the input roi_vector is the same as the roi_vector in the construct_hypothesis method
Return type:: bool

class si4onnx.GaussianFilter(kernel_size: int = 3, sigma: float = 1.0)

Bases: Operator

forward(x)

Compute the convolution of the input tensor with a Gaussian kernel.

Parameters:: x (torch.Tensor) – input tensor
Returns:: output – output tensor
Return type:: torch.Tensor

forward_si(x, a, b, l, u, z)

Parameters:

x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)

Returns:

output_x (torch.Tensor | list[torch.Tensor]) – output tensor or tensor list
output_a (torch.Tensor | list[torch.Tensor]) – output a tensor or tensor list
output_b (torch.Tensor | list[torch.Tensor]) – output b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

class si4onnx.Hypothesis

Bases: ABC

abstract algorithm(a, b, z, **kwargs)

abstract construct_hypothesis(X, si_model, *kwargs)

abstract model_selector(roi_vector, **kwargs)

class si4onnx.InputDiff(*args, **kwargs)

Bases: Operator

forward(x, input_x)

forward_si(x, a, b, l, u, z, input_x, input_a, input_b)

Compute (x - input_x), (a - input_a), (b - input_b)

Parameters:

x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)
Input_x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
Input_a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
Input_b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list

Returns:

output_x (torch.Tensor | list[torch.Tensor]) – output tensor or tensor list
output_a (torch.Tensor | list[torch.Tensor]) – output a tensor or tensor list
output_b (torch.Tensor | list[torch.Tensor]) – output b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

class si4onnx.NN(model: ModelProto, seed: int | None = None, memoization: bool = True)

Bases: Module

Deep learning model class for Selective Inference.

forward(input)

Forward pass of the model.

Parameters:: input (torch.Tensor | list[torch.Tensor])
Returns:: output
Return type:: torch.Tensor | list[torch.Tensor]

forward_si(input, a, b, l, u, z)

Forward pass with computing the trancated interval of the output.

Parameters:

input (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list in the deep learning model
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)

Returns:

x (torch.Tensor | list[torch.Tensor]) – output tensor or tensor list in the deep learning model
a (torch.Tensor | list[torch.Tensor]) – output a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – output b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

class si4onnx.Neg(*args, **kwargs)

Bases: Operator

forward(x)

forward_si(x, a, b, l, u, z)

Parameters:

x (torch.Tensor | list[torch.Tensor]) – input tensor or tensor list
a (torch.Tensor | list[torch.Tensor]) – a tensor or tensor list
b (torch.Tensor | list[torch.Tensor]) – b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – l tensor or tensor list
u (torch.Tensor | list[torch.Tensor]) – u tensor or tensor list
z (float)

Returns:

torch.Tensor | list[torch.Tensor] – -x tensor or tensor list
torch.Tensor | list[torch.Tensor] – -a tensor or tensor list
torch.Tensor | list[torch.Tensor] – -b tensor or tensor list
l (torch.Tensor | list[torch.Tensor]) – lower bound of the truncated interval
u (torch.Tensor | list[torch.Tensor]) – upper bound of the truncated interval

class si4onnx.NeighborMeanDiff(threshold: float, neighborhood_range: int = 1, i_idx: int = 0, o_idx: int = 0, post_process: Module | list[Module] = [], use_norm: bool = False, **kwargs)

Bases: PresetHypothesis

Hypothesis for the mean difference between the ROI and the neighborhood region in the input data.

Examples

>>> import onnx
>>> from si4onnx.hypothesis import NeigborMeanDiff
>>> from si4onnx.operators import InputDiff, Abs
>>> from si4onnx.utils import load
>>> model = onnx.load("model.onnx")
>>> si_model = si4onnx.load(
...     model=onnx.load("model.onnx"),
...     hypothesis=NeigborMeanDiff(
...         threshold=0.5,
...         post_process=[InputDiff(), Abs()]
...     )
... )
... print(si_model.inference(input_image, var=1.0).p_value)

algorithm(si_model: NN, a: Tensor, b: Tensor, z: Tensor) → tuple[Tensor, list]

Parameters:

si_model (NN) – The model for the selective inference.
a (torch.Tensor) – The input tensor a.
b (torch.Tensor) – The input tensor b.
z (float) – The test statistic z.

Returns:

roi_vector (torch.Tensor) – The flattened roi.
[l, u] (list(float)) – The over-conditioning interval that contains z.

Parameters:

si_model (NN) – The model for the selective inference.
X (torch.Tensor | list[torch.Tensor] | tuple[torch.Tensor]) – The input data.
var (float | torch.Tensor | np.ndarray) – The variance of the noise.
mask (torch.Tensor | n.ndarray | None, optional) – A mask that specifies the regions that are not selected as ROI and oter region, that is to say, a mask specify regions that will not be used for the test statistic. Defaults to None.

model_selector(roi_vector: Tensor) → bool

Parameters:: roi_vector (torch.Tensor) – should be a tensor of int
Returns:: True if the input roi_vector is the same as the roi_vector in the construct_hypothesis method
Return type:: bool

class si4onnx.Operator(*args, **kwargs)

Bases: ABC

abstract forward(x, **kwargs)

abstract forward_si(x, a, b, l, u, z, **kwargs)

class si4onnx.ReferenceMeanDiff(threshold: float, i_idx: int = 0, o_idx: int = 0, post_process: Module | list[Module] = [], use_norm: bool = False, **kwargs)

Bases: PresetHypothesis

Hypothesis for the mean difference between the ROI and the neighborhood region in the input data.

Examples

>>> import onnx
>>> from si4onnx.hypothesis import ReferenceMeanDiff
>>> from si4onnx.operators import InputDiff, Abs
>>> from si4onnx.utils import load
>>> model = onnx.load("model.onnx")
>>> si_model = si4onnx.load(
...     model=onnx.load("model.onnx"),
...     hypothesis=ReferenceMeanDiff(
...         threshold=0.5,
...         post_process=[InputDiff(), Abs()]
...     )
... )
... print(si_model.inference(input=(input_image, reference_image), var=1.0).p_value)

algorithm(si_model: NN, a: Tensor, b: Tensor, z: Tensor) → tuple[Tensor, list]

Parameters:

si_model (NN) – The model for the selective inference.
a (torch.Tensor) – The input tensor a.
b (torch.Tensor) – The input tensor b.
z (float) – The test statistic z.

Returns:

roi_vector (torch.Tensor) – The flattened roi.
[l, u] (list(float)) – The over-conditioning interval that contains z.

construct_hypothesis(si_model: NN, X: tuple, var: float | Tensor | ndarray, mask: Tensor | None = None)

Parameters:

si_model (NN) – The model for the selective inference.
X (tuple) – The tuple of the input data and the reference data. (input_data, reference_data)
var (float | torch.Tensor | n.ndarray) – The variance of the noise.
mask (torch.Tensor | n.ndarray | None, optional) – A mask that specifies the regions that are not selected as ROI and oter region, that is to say, a mask specify regions that will not be used for the test statistic. Defaults to None.

model_selector(roi_vector)

Parameters:: roi_vector (torch.Tensor) – should be a tensor of int
Returns:: True if the input roi_vector is the same as the roi_vector in the construct_hypothesis method
Return type:: bool

class si4onnx.SelectiveInferenceModel

Bases: ABC

abstract algorithm(a: Tensor, b: Tensor, z: float, **kwargs) → tuple[object, tuple[float, float]]

Parameters:

a (torch.Tensor) – A vector of nuisance parameter
b (torch.Tensor) – A vector of the direction of test statistic
z (float) – A test statistic

Returns:

First Elements is outputs obtained in the value of z. Second Element is a obtained truncated interval

Return type:

tuple[object, tuple[float,float]]

Abstruct method for construct hypothesis from the observed output of NN.

Parameters:

input (torch.Tensor | np.ndarray | list | tuple) – Input of NN
var (int | float | np.ndarray | torch.Tensor) – Covariance matrix of input Treated as the diagonal of the covariance matrix, representing independent variances for each dimension.

Raises:

NoHypothesisError – If the hypothesis is not obtained from observartion, please raise this error

forward(input: Tensor | ndarray) → Tensor

inference(input: Tensor | ndarray, var: float | ndarray | Tensor, **kwargs) → SelectiveInferenceResult

Parameters:

input (torch.Tensor | np.ndarray | list[torch.Tensor | np.ndarray] | tuple[torch.Tensor | np.ndarray, ...]) – Input of NN
var (float | np.ndarray | torch.Tensor) – Covariance matrix of the noise of input.
**kwargs (Any)

Abstruct method for compare whether same model are obtained from output and observed output(self.output)

Parameters:: roi_vector (Any) – roi obtained from the output of NN
Returns:: If same models are obtained from output and observed output(self.output), Return value should be true. If not, return value should be false.
Return type:: bool

class si4onnx.SyntheticDataset(n_samples, shape, loc=0, scale=1, local_signal=0, local_size=None, seed=0)

Bases: Dataset

A PyTorch Dataset for generating synthetic data with iid Gaussian noise and local signals.

This dataset generates samples containing Gaussian noise with optional local signals added at random positions.

The dataset generates three components for each sample:

Data: Tensor containing Gaussian noise with optional local signals
Mask: Binary tensor indicating the position of local signals
Label: Binary value indicating presence of local signal

data

Array containing the generated synthetic data.

Type:: numpy.ndarray

masks

Array containing the masks for local signals.

Type:: numpy.ndarray

labels

Array containing the binary labels.

Type:: numpy.ndarray

Examples

>>> dataset = SyntheticDataset(
...     n_samples=1000,
...     shape=(32, 32),
...     loc=0,
...     scale=1,
...     local_signal=2.0
... )
>>> data, mask, label = dataset[0]
>>> print(data.shape, mask.shape, label.shape)
torch.Size([32, 32]) torch.Size([32, 32]) torch.Size([])

si4onnx.load(model: ModelProto, hypothesis: PresetHypothesis, seed: float | None = None, memoization: bool = True) → PresetSelectiveInferenceModel

Load onnx model and hypothesis setting to SelectiveInferenceModel

Parameters:

model (onnx.ModelProto) – The onnx model instance.
hypothesis (PresetHypothesis) – The hypothesis setting. You can choose an instance of the class “PresetHypothesis” for preset hypothesis setting.
seed (float, optional) – The seed of random number generator. If the onnx model contains RandomNormalLike layers, the seed is used to generate the same random numbers. Default to None.
memoization (bool, optional) – Whether to use memoization. If True, the memoization is enabled

Returns:

si_model – The Selective Inference model

Return type:

PresetSelectiveInferenceModel

Raises:

ValueError – If hypothesis is not an instance of PresetHypothesis

si4onnx.thresholding(threshold: Tensor, x: Tensor, a: Tensor, b: Tensor, l: Tensor, u: Tensor, z: Tensor, use_sigmoid: bool = False, use_norm: bool = False)

Threshold the input tensor x with the given threshold (thr) and return the indices greater than thr.

Parameters:

threshold (torch.Tensor) – threshold tensor
x (torch.Tensor) – input tensor
a (torch.Tensor) – a tensor
b (torch.Tensor) – b tensor
use_sigmoid (bool, optional) – Whether to use sigmoid or not in the output layer. Defaults to False
use_norm (bool, optional) – Whether to apply min-max normalization. Defaults to False

Returns:

torch.Tensor – threshold index, which is greater than the threshold The shape of the tensor is flattened.
float – lower bound of the truncated interval
float – upper bound of the truncated interval