pyprobound.cooperativity.Cooperativity
- class Cooperativity(spacing, mode_a, mode_b, train_hill=False, train_posbias=False, bias_mode='strand', bias_bin=1, length_specific_bias=True, normalize=False)
Bases:
BindingExperiment-specific dimer cooperativity modeling with position bias.
\[\log \frac{\omega_{a:b}(x^a, x^b)}{ K^{rel}_{\text{D}, a} (S_{i, x^a}) K^{rel}_{\text{D}, b} (S_{i, x^b}) }\]- log_hill
The Hill coeffient in log space.
- Type:
Tensor
- log_posbias
The bias \(\omega_{a:b}(x^a_m, x^b_n)\) at each relative offset \(n-m\) for each strand.
- Type:
list[Tensor]
- __init__(spacing, mode_a, mode_b, train_hill=False, train_posbias=False, bias_mode='strand', bias_bin=1, length_specific_bias=True, normalize=False)
Initializes the experiment-specific dimer cooperativity.
- Parameters:
spacing (
Spacing) – The experiment-independent specification of the dimer.mode_a (
Mode) – The first binding mode contributing to the dimer.mode_b (
Mode) – The second binding mode contributing to the dimer.train_hill (
bool) – Whether to train a Hill coefficient for the dimer.train_posbias (
bool) – Whether to train posbias parameter \(\omega_{a:b}(x^a, x^b)\) for each pair of windows \((x^a_m, x^b_n)\).bias_mode (
Literal['strand','same','reverse']) – Whether to train a separate bias for each strand, use the same bias across both strands, or a reversed bias for the opposite strand.bias_bin (
int) – Applies constraint \(\omega_{a:b}( x^a_{i\times\text{bias_bin}}, x^b_{j\times\text{bias_bin}} ) =\) \(\cdots = \omega_{a:b}( x^a_{(i+1)\times\text{bias_bin}-1}, x^b_{(j+1)\times\text{bias_bin}-1} )\).length_specific_bias (
bool) – Whether to train a separate bias parameter for each input length.normalize (
bool) – Whether to mean-center log_posbias over all windows.
Methods
cache(fun)Decorator for a function to cache its output.
Checks that input lengths of Binding components are consistent.
Iterator of child components.
expected_log_score()Calculates the expected log score.
Uninformative prior of input, used for calculating expectations.
forward(seqs)Calculates the log score of each sequence.
freeze()Turns off gradient calculation for all parameters.
The flattened cooperativity \(\omega_{a:b}(x^a, x^b)\).
The cooperativity position bias \(\omega_{a:b}(x^a, x^b)\).
The cooperativity position bias \(\omega_{a:b}(x^a, x^b)\).
key()The specification of a Binding component.
The maximum number of bytes needed to encode a sequence.
optim_procedure([ancestry, current_order])The sequential optimization procedure for all Binding components.
reload(checkpoint)Loads the model from a checkpoint file.
reload_from_state_dict(state_dict)Loads the model from a state dict.
save(checkpoint[, flank_lengths])Saves the model to a file with "state_dict" and "metadata" fields.
score_windows(seqs)Calculates the log score of each window before summing over them.
unfreeze([parameter])Turns on gradient calculation for the specified parameter.
Attributes
Applies the constraint \(\omega_{a:b}( x^a_{i\times\text{bias_bin}}, x^b_{j\times\text{bias_bin}} ) =\) \(\cdots = \omega_{a:b}( x^a_{(i+1)\times\text{bias_bin}-1}, x^b_{(j+1)\times\text{bias_bin}-1} )\).
Whether to train a separate bias for each strand, use the same bias across both strands, or a reversed bias for the opposite strand.
Whether to train a separate bias parameter for each input length.
The number of output channels of the component modes.
alias of
Literal['all', 'hill', 'posbias']Non-Inherited Members
- unfreezable
alias of
Literal[‘all’, ‘hill’, ‘posbias’]
- property n_strands: Literal[1, 2]
The number of output channels of the component modes.
- property bias_mode: Literal['strand', 'same', 'reverse']
Whether to train a separate bias for each strand, use the same bias across both strands, or a reversed bias for the opposite strand.
- property bias_bin: int
Applies the constraint \(\omega_{a:b}( x^a_{i\times\text{bias_bin}}, x^b_{j\times\text{bias_bin}} ) =\) \(\cdots = \omega_{a:b}( x^a_{(i+1)\times\text{bias_bin}-1}, x^b_{(j+1)\times\text{bias_bin}-1} )\).
- property length_specific_bias: bool
Whether to train a separate bias parameter for each input length.
- key()
The specification of a Binding component.
All Binding components with the same specification will be optimized together in the sequential optimization procedure.
- Return type:
tuple[Spec]
- max_embedding_size()
The maximum number of bytes needed to encode a sequence.
Used for splitting calculations to avoid GPU limits on tensor sizes.
- Return type:
int
- check_length_consistency()
Checks that input lengths of Binding components are consistent.
- Raises:
RuntimeError – There is an input mismatch between components.
- Return type:
None
- unfreeze(parameter='all')
Turns on gradient calculation for the specified parameter.
- Parameters:
parameter (unfreezable) – Parameter to be unfrozen, defaults to all parameters.
- Return type:
None
- optim_procedure(ancestry=None, current_order=None)
The sequential optimization procedure for all Binding components.
The optimization procedure is generated recursively through iteration over the child components of each module. All Binding components with the same specification returned from key() are trained jointly.
- Parameters:
ancestry (
tuple[Component,...] |None) – The parent components from the root for which the procedure is being generated to the current component.current_order (
dict[tuple[Spec,...],BindingOptim] |None) – Mapping of Binding component specifications to the sequential optimization procedure for those Binding components.
- Return type:
dict[tuple[Spec,...],BindingOptim]- Returns:
The current_order updated with the optimization of the current component’s children.
- get_log_spacing()
The flattened cooperativity \(\omega_{a:b}(x^a, x^b)\).
- Return type:
Tensor- Returns:
A tensor with the flattened representation of the cooperativity of each pair of windows \((x^a_m, x^b_n)\), of shape \((\text{n_strands}_a,\text{n_strands}_b, \text{out_length}_a+\text{out_length}_b-1)\).
- get_log_spacing_diagonals()
The cooperativity position bias \(\omega_{a:b}(x^a, x^b)\).
- Return type:
list[Tensor]- Returns:
A list of tensors with the bias of each pair of windows \((x^a_m, x^b_n)\) at each relative offset \(n-m\), each of shape \((\text{input_lengths}_a,\text{input_lengths}_b, \text{n_strands}_a,\text{n_strands}_b,\text{diagonal_length})\).)`.
- get_log_spacing_matrix()
The cooperativity position bias \(\omega_{a:b}(x^a, x^b)\).
- Return type:
Tensor- Returns:
A tensor with the bias of each pair of windows \((x^a_m, x^b_n)\) of shape \((\text{input_lengths}_a,\text{input_lengths}_b, \text{n_strands}_a,\text{n_strands}_b, \text{out_length}_a,\text{out_length}_b)\).)`.
- expected_sequence()
Uninformative prior of input, used for calculating expectations.
- Return type:
Tensor
- score_windows(seqs)
Calculates the log score of each window before summing over them.
\[\log \frac{\omega_{a:b}(x^a, x^b)}{ K^{rel}_{\text{D}, a} (S_{i, x^a}) K^{rel}_{\text{D}, b} (S_{i, x^b}) }\]- Parameters:
seqs (
Tensor) – A sequence tensor of shape \((\text{minibatch},\text{length})\) or \((\text{minibatch},\text{in_channels},\text{in_length})\).- Return type:
Tensor- Returns:
A tensor with the score of each window of shape \((\text{minibatch},\text{n_strands}_a,\text{n_strands}_b, \text{out_length}_a,\text{out_length}_b)\).
- forward(seqs)
Calculates the log score of each sequence.
\[\log \frac{1}{ K^{rel}_{\text{D}, a} (S_i) K^{rel}_{\text{D}, b} (S_i) } = \log \sum_{x^a, x^b} \frac{\omega_{a:b}(x^a, x^b)}{ K^{rel}_{\text{D}, a} (S_{i, x^a}) K^{rel}_{\text{D}, b} (S_{i, x^b}) }\]- Parameters:
seqs (
Tensor) – A sequence tensor of shape \((\text{minibatch},\text{length})\) or \((\text{minibatch},\text{in_channels},\text{length})\).- Return type:
Tensor- Returns:
The log score tensor of shape \((\text{minibatch},)\).