BINN

This is the API reference for the BINN-package. For usage examples, see Examples. Note that the API is still stabilizing and will undergo changes.

BINN

Bases: LightningModule

Implements a Biologically Informed Neural Network (BINN). The BINN is implemented using the Lightning-framework. If you are unfamiliar with PyTorch, we suggest visiting their website: https://pytorch.org/

Parameters:

Name	Type	Description	Default
pathways	Network	A Network object that defines the network topology.	required
activation	str	Activation function to use. Defaults to "tanh".	'tanh'
weight	Tensor	Weights for loss function. Defaults to torch.Tensor([1, 1]).	tensor([1, 1])
learning_rate	float	Learning rate for optimizer. Defaults to 1e-4.	0.0001
n_layers	int	Number of layers in the network. Defaults to 4.	4
scheduler	str	Learning rate scheduler to use. Defaults to "plateau".	'plateau'
optimizer	str	Optimizer to use. Defaults to "adam".	'adam'
validate	bool	Whether to use validation data during training. Defaults to False.	False
n_outputs	int	Number of output nodes. Defaults to 2.	2
dropout	float	Dropout probability. Defaults to 0.	0
residual	bool	Whether to use residual connections. Defaults to False.	False

Attributes:

Name	Type	Description
residual	bool	Whether to use residual connections.
pathways	Network	A Network object that defines the network topology.
n_layers	int	Number of layers in the network.
layer_names	List[str]	List of layer names.
features	Index	A pandas Index object containing the input features.
layers	Module	The layers of the BINN.
loss	Module	The loss function used during training.
learning_rate	float	Learning rate for optimizer.
scheduler	str	Learning rate scheduler used.
optimizer	str	Optimizer used.
validate	bool	Whether to use validation data during training.

Source code in binn/binn.py

class BINN(pl.LightningModule):
    """
    Implements a Biologically Informed Neural Network (BINN). The BINN
    is implemented using the Lightning-framework.
    If you are unfamiliar with PyTorch, we suggest visiting
    their website: https://pytorch.org/


    Args:
        pathways (Network): A Network object that defines the network topology.
        activation (str, optional): Activation function to use. Defaults to "tanh".
        weight (torch.Tensor, optional): Weights for loss function. Defaults to torch.Tensor([1, 1]).
        learning_rate (float, optional): Learning rate for optimizer. Defaults to 1e-4.
        n_layers (int, optional): Number of layers in the network. Defaults to 4.
        scheduler (str, optional): Learning rate scheduler to use. Defaults to "plateau".
        optimizer (str, optional): Optimizer to use. Defaults to "adam".
        validate (bool, optional): Whether to use validation data during training. Defaults to False.
        n_outputs (int, optional): Number of output nodes. Defaults to 2.
        dropout (float, optional): Dropout probability. Defaults to 0.
        residual (bool, optional): Whether to use residual connections. Defaults to False.

    Attributes:
        residual (bool): Whether to use residual connections.
        pathways (Network): A Network object that defines the network topology.
        n_layers (int): Number of layers in the network.
        layer_names (List[str]): List of layer names.
        features (Index): A pandas Index object containing the input features.
        layers (nn.Module): The layers of the BINN.
        loss (nn.Module): The loss function used during training.
        learning_rate (float): Learning rate for optimizer.
        scheduler (str): Learning rate scheduler used.
        optimizer (str): Optimizer used.
        validate (bool): Whether to use validation data during training.
    """

    def __init__(
        self,
        network: Network = None,
        connectivity_matrices: list = None,
        activation: str = "tanh",
        weight: torch.tensor = torch.tensor([1, 1]),
        learning_rate: float = 1e-4,
        n_layers: int = 4,
        scheduler: str = "plateau",
        optimizer: str = "adam",
        validate: bool = False,
        n_outputs: int = 2,
        dropout: float = 0,
        residual: bool = False,
        device: str = "cpu",
    ):
        super().__init__()
        self.to(device)
        self.residual = residual
        if not connectivity_matrices:
            self.network = network
            self.connectivity_matrices = self.network.get_connectivity_matrices(
                n_layers
            )
        else:
            self.connectivity_matrices = connectivity_matrices
        self.n_layers = n_layers

        layer_sizes = []
        self.layer_names = []

        matrix = self.connectivity_matrices[0]
        i, _ = matrix.shape
        layer_sizes.append(i)
        self.layer_names.append(matrix.index.tolist())
        self.features = matrix.index
        self.trainable_params = matrix.to_numpy().sum() + len(matrix.index)
        for matrix in self.connectivity_matrices[1:]:
            self.trainable_params += matrix.to_numpy().sum() + len(matrix.index)
            i, _ = matrix.shape
            layer_sizes.append(i)
            self.layer_names.append(matrix.index.tolist())

        if self.residual:
            self.layers = _generate_residual(
                layer_sizes,
                connectivity_matrices=self.connectivity_matrices,
                activation=activation,
                bias=True,
                n_outputs=n_outputs,
            )
        else:
            self.layers = _generate_sequential(
                layer_sizes,
                connectivity_matrices=self.connectivity_matrices,
                activation=activation,
                bias=True,
                n_outputs=n_outputs,
                dropout=dropout,
            )
        self.apply(_init_weights)
        self.weight = weight
        self.loss = nn.CrossEntropyLoss()
        self.learning_rate = learning_rate
        self.scheduler = scheduler
        self.optimizer = optimizer
        self.validate = validate
        self.save_hyperparameters()
        print("\nBINN is on the device:", self.device, end="\n")

    def forward(self, x: torch.tensor) -> torch.tensor:
        """
        Performs a forward pass through the BINN.

        Args:
            x (torch.Tensor): The input tensor to the BINN.

        Returns:
            torch.Tensor: The output tensor of the BINN.
        """
        if self.residual:
            return self._forward_residual(x)
        else:
            return self.layers(x)

    def training_step(self, batch, _):
        """
        Performs a single training step for the BINN.

        Args:
            batch: The batch of data to use for the training step.
            _: Not used.

        Returns:
            torch.Tensor: The loss tensor for the training step.
        """
        x, y = batch
        x = x.to(self.device)
        y = y.to(self.device)
        y_hat = self(x).to(self.device)
        loss = self.loss(y_hat, y)
        prediction = torch.argmax(y_hat, dim=1)
        accuracy = self.calculate_accuracy(y, prediction)
        self.log("train_loss", loss, prog_bar=True, on_step=False, on_epoch=True)
        self.log("train_acc", accuracy, prog_bar=True, on_step=False, on_epoch=True)
        return loss

    def validation_step(self, batch, _):
        """
        Implements a single validation step for the BINN.

        Args:
            batch: A tuple containing the input and output data for the current batch.
            _: The batch index, which is not used.
        """

        x, y = batch
        y_hat = self(x)
        loss = self.loss(y_hat, y)
        prediction = torch.argmax(y_hat, dim=1)
        accuracy = self.calculate_accuracy(y, prediction)
        self.log("val_loss", loss, prog_bar=True, on_step=False, on_epoch=True)
        self.log("val_acc", accuracy, prog_bar=True, on_step=False, on_epoch=True)
        return {"val_loss": loss, "val_acc": accuracy}

    def test_step(self, batch, _):
        """
        Implements a single testing step for the BINN.

        Args:
            batch: A tuple containing the input and output data for the current batch.
            _: The batch index, which is not used.
        """
        x, y = batch
        y_hat = self(x)
        loss = self.loss(y_hat, y)
        prediction = torch.argmax(y_hat, dim=1)
        accuracy = self.calculate_accuracy(y, prediction)
        self.log("test_loss", loss, prog_bar=True, on_step=False, on_epoch=True)
        self.log("test_acc", accuracy, prog_bar=True, on_step=False, on_epoch=True)

    def configure_optimizers(self):
        """
        Configures the optimizer and learning rate scheduler for training the BINN.

        Returns:
            A list of optimizers and a list of learning rate schedulers.
        """
        if self.validate:
            monitor = "val_loss"
        else:
            monitor = "train_loss"

        if isinstance(self.optimizer, str):
            if self.optimizer == "adam":
                optimizer = torch.optim.Adam(
                    self.parameters(), lr=self.learning_rate, weight_decay=1e-3
                )
                self.optimizer = optimizer
        else:
            optimizer = self.optimizer

        if self.scheduler == "plateau":
            scheduler = {
                "scheduler": torch.optim.lr_scheduler.ReduceLROnPlateau(
                    optimizer, patience=5, threshold=0.01, mode="min", verbose=True
                ),
                "interval": "epoch",
                "monitor": monitor,
            }
        elif self.scheduler == "step":
            scheduler = {
                "scheduler": torch.optim.lr_scheduler.StepLR(
                    optimizer, step_size=25, gamma=0.1, verbose=True
                )
            }

        return [optimizer], [scheduler]

    def calculate_accuracy(self, y, prediction) -> float:
        return torch.sum(y == prediction).item() / float(len(y))

    def get_connectivity_matrices(self) -> list:
        """
        Returns the connectivity matrices underlying the BINN.

        Returns:
            The connectivity matrices as a list of Pandas DataFrames.
        """
        return self.connectivity_matrices

    def reset_params(self):
        """
        Resets the trainable parameters of the BINN.
        """
        self.apply(_reset_params)

    def init_weights(self):
        """
        Initializes the trainable parameters of the BINN.
        """
        self.apply(_init_weights)

    def _forward_residual(self, x: torch.tensor):
        x_final = torch.tensor([0, 0], device=self.device)
        residual_counter: int = 0
        for name, layer in self.layers.named_children():
            if name.startswith("Residual"):
                if "out" in name:
                    x_temp = layer(x)
                if _is_activation(layer):
                    x_temp = layer(x_temp)
                    x_final = x_temp + x_final
                    residual_counter = residual_counter + 1
            else:
                x = layer(x)
        x_final = x_final / residual_counter
        return x_final

configure_optimizers()

Configures the optimizer and learning rate scheduler for training the BINN.

Returns:

Type	Description
	A list of optimizers and a list of learning rate schedulers.

Source code in binn/binn.py

def configure_optimizers(self):
    """
    Configures the optimizer and learning rate scheduler for training the BINN.

    Returns:
        A list of optimizers and a list of learning rate schedulers.
    """
    if self.validate:
        monitor = "val_loss"
    else:
        monitor = "train_loss"

    if isinstance(self.optimizer, str):
        if self.optimizer == "adam":
            optimizer = torch.optim.Adam(
                self.parameters(), lr=self.learning_rate, weight_decay=1e-3
            )
            self.optimizer = optimizer
    else:
        optimizer = self.optimizer

    if self.scheduler == "plateau":
        scheduler = {
            "scheduler": torch.optim.lr_scheduler.ReduceLROnPlateau(
                optimizer, patience=5, threshold=0.01, mode="min", verbose=True
            ),
            "interval": "epoch",
            "monitor": monitor,
        }
    elif self.scheduler == "step":
        scheduler = {
            "scheduler": torch.optim.lr_scheduler.StepLR(
                optimizer, step_size=25, gamma=0.1, verbose=True
            )
        }

    return [optimizer], [scheduler]

forward(x)

Performs a forward pass through the BINN.

Parameters:

Name	Type	Description	Default
x	Tensor	The input tensor to the BINN.	required

Returns:

Type	Description
tensor	torch.Tensor: The output tensor of the BINN.

Source code in binn/binn.py

def forward(self, x: torch.tensor) -> torch.tensor:
    """
    Performs a forward pass through the BINN.

    Args:
        x (torch.Tensor): The input tensor to the BINN.

    Returns:
        torch.Tensor: The output tensor of the BINN.
    """
    if self.residual:
        return self._forward_residual(x)
    else:
        return self.layers(x)

get_connectivity_matrices()

Returns the connectivity matrices underlying the BINN.

Returns:

Type	Description
list	The connectivity matrices as a list of Pandas DataFrames.

Source code in binn/binn.py

def get_connectivity_matrices(self) -> list:
    """
    Returns the connectivity matrices underlying the BINN.

    Returns:
        The connectivity matrices as a list of Pandas DataFrames.
    """
    return self.connectivity_matrices

init_weights()

Initializes the trainable parameters of the BINN.

Source code in binn/binn.py

def init_weights(self):
    """
    Initializes the trainable parameters of the BINN.
    """
    self.apply(_init_weights)

reset_params()

Resets the trainable parameters of the BINN.

Source code in binn/binn.py

def reset_params(self):
    """
    Resets the trainable parameters of the BINN.
    """
    self.apply(_reset_params)

test_step(batch, _)

Implements a single testing step for the BINN.

Parameters:

Name	Type	Description	Default
batch		A tuple containing the input and output data for the current batch.	required
_		The batch index, which is not used.	required

Source code in binn/binn.py

def test_step(self, batch, _):
    """
    Implements a single testing step for the BINN.

    Args:
        batch: A tuple containing the input and output data for the current batch.
        _: The batch index, which is not used.
    """
    x, y = batch
    y_hat = self(x)
    loss = self.loss(y_hat, y)
    prediction = torch.argmax(y_hat, dim=1)
    accuracy = self.calculate_accuracy(y, prediction)
    self.log("test_loss", loss, prog_bar=True, on_step=False, on_epoch=True)
    self.log("test_acc", accuracy, prog_bar=True, on_step=False, on_epoch=True)

training_step(batch, _)

Performs a single training step for the BINN.

Parameters:

Name	Type	Description	Default
batch		The batch of data to use for the training step.	required
_		Not used.	required

Returns:

Type	Description
	torch.Tensor: The loss tensor for the training step.

Source code in binn/binn.py

def training_step(self, batch, _):
    """
    Performs a single training step for the BINN.

    Args:
        batch: The batch of data to use for the training step.
        _: Not used.

    Returns:
        torch.Tensor: The loss tensor for the training step.
    """
    x, y = batch
    x = x.to(self.device)
    y = y.to(self.device)
    y_hat = self(x).to(self.device)
    loss = self.loss(y_hat, y)
    prediction = torch.argmax(y_hat, dim=1)
    accuracy = self.calculate_accuracy(y, prediction)
    self.log("train_loss", loss, prog_bar=True, on_step=False, on_epoch=True)
    self.log("train_acc", accuracy, prog_bar=True, on_step=False, on_epoch=True)
    return loss

validation_step(batch, _)

Implements a single validation step for the BINN.

Parameters:

Name	Type	Description	Default
batch		A tuple containing the input and output data for the current batch.	required
_		The batch index, which is not used.	required

Source code in binn/binn.py

def validation_step(self, batch, _):
    """
    Implements a single validation step for the BINN.

    Args:
        batch: A tuple containing the input and output data for the current batch.
        _: The batch index, which is not used.
    """

    x, y = batch
    y_hat = self(x)
    loss = self.loss(y_hat, y)
    prediction = torch.argmax(y_hat, dim=1)
    accuracy = self.calculate_accuracy(y, prediction)
    self.log("val_loss", loss, prog_bar=True, on_step=False, on_epoch=True)
    self.log("val_acc", accuracy, prog_bar=True, on_step=False, on_epoch=True)
    return {"val_loss": loss, "val_acc": accuracy}