poplar.nn.networks
==================

.. py:module:: poplar.nn.networks

.. autoapi-nested-parse::

   Network classes defined and constructed for use within `poplar`.

   ..
       !! processed by numpydoc !!


Classes
-------

.. autoapisummary::

   poplar.nn.networks.LinearModel


Functions
---------

.. autoapisummary::

   poplar.nn.networks.load_model


Module Contents
---------------

.. py:class:: LinearModel(in_features: int, out_features: int, neurons: list, activation: Any, name='model', device='cpu', rescaler=None, out_activation=None, initialisation=None, dropout=0.0, batch_norm=False)

   Bases: :py:obj:`torch.nn.Module`


   
   LinearModel class implementing a standard multi-layer perceptron with some convenience features for function approximation use. 

   This is a subclass of `torch.nn.Module`.

   :Parameters:

       **in_features** : int
           Number of features for the input layer of the model.

       **out_features** : int
           Number of features for the output layer of the model.

       **neurons** : list
           A list containing the number of neurons in each layer of the model (excluding input/output).

       **activation** : Any
           The activation function to be used for each hidden layer.

       **name** : str, optional
           A name for the model, used for file naming. Defaults to "model".

       **device** : str, optional
           pytorch device to initialise the model to, by default "cpu"

       **rescaler** : _type_, optional
           An object for rescaling inputs/outputs. by default `IdentityRescaler` (see `mlsel.nn.rescaling.py` for examples)

       **out_activation** : _type_, optional
           Activation function for the output layer, by default None

       **initialisation** : _type_, optional
           Function for setting the initial weights of all neurons, by default uses xavier_uniform rescaling

       **dropout** : float, optional
           Sets the dropout probability for all layers, by default 0 (no dropout).

       **batch_norm** : bool, optional
           If True, enables batch normalisation between layers, by default False














   ..
       !! processed by numpydoc !!

   .. py:method:: forward(x: torch.Tensor)

      
      Computes the output for a set of inputs, and removes extra dimensions in the output.


      :Parameters:

          **x** : torch.Tensor
              The input tensor to the model.



      :Returns:

          torch.Tensor
              The resulting output tensor, with no dimensions of size 1.











      ..
          !! processed by numpydoc !!


   .. py:method:: save(outdir: str)

      
      Saves the model to a pickle file for reloading later.


      :Parameters:

          **outdir** : str
              Output file directory in which to place the model directory.














      ..
          !! processed by numpydoc !!


   .. py:method:: run_on_dataset(inputs: torch.Tensor, n_batches=1, luminosity_distances=None, runtime=False)

      
      Run this model on a set of inputs, applying all necessary rescalings and transformations.

      If the output is distance-normalised, luminosity distances can also be provided to convert these into unnormalised values.

      :Parameters:

          **inputs** : torch.Tensor
              Input tensor to run through the model.

          **n_batches** : int, optional
              Number of batches to process the input data in, by default 1 (the entire dataset)

          **luminosity_distances** : torch.Tensor, optional
              Set of luminosity distance values to multiply the output data by, by default None

          **runtime** : bool, optional
              If True, returns timing statistics. By default False



      :Returns:

          output: torch.Tensor
              The output of the model after reversing the input scalings.

          timings: list (only returned if runtime is True)
              The time taken for the network [in total, per_datapoint].











      ..
          !! processed by numpydoc !!


   .. py:method:: test_threshold_accuracy(xdata: torch.Tensor, ydata: torch.Tensor, threshold: float, confusion_matrix=False, **run_kwargs)

      
      Test the performance of the linear model when operating as a classifier (i.e. with respect to a given threshold).
      Reports either a fractional accuracy or a confusion matrix decomposing this accuracy into its constituent parts.

      Only supported for `out_features == 1`.

      :Parameters:

          **xdata** : torch.Tensor
              Set of input (target) data to be processed by the network.

          **ydata** : torch.Tensor
              Set of true values to compare the network output with.

          **threshold** : float
              A threshold value with which to compare the accuracy of each network when operating as a classifier (i.e. 0: below threshold, 1: above threshold)

          **confusion_matrix** : bool, optional
              If True, outputs the result in confusion matrix format. By default False

          **\*\*kwargs**
              Keyword arguments passed to run_on_dataset.



      :Returns:

          accuracy: double
              Accuracy of the network, normalised to [0,1].

          confmat: torch.Tensor (only returned if confusion_matrix is True)
              Confusion matrix of the network output over the two classes (below threshold, above threshold).











      ..
          !! processed by numpydoc !!


   .. py:method:: set_device(device)

      
      Sets the device of both the model and its rescaler.


      :Parameters:

          **device** : str
              Device to move the model and rescaler to.














      ..
          !! processed by numpydoc !!


.. py:function:: load_model(path: str, device='cpu') -> LinearModel

   
   Load an existing `LinearModel` from file.


   :Parameters:

       **path** : str
           Path to `.pkl` file to be loaded.

       **device** : str, optional
           The PyTorch device to load the model to, by default "cpu"



   :Returns:

       LinearModel
           Loaded LinearModel.











   ..
       !! processed by numpydoc !!