Merge pull request #78 from ICB-DCM/fixes_documentation

Fixes documentation

@DRAMOptions/DRAMOptions.m

@@ -1,39 +1,25 @@
-% @file DRAMOptions
-% @brief A class for sanity checks of DRAM algorithm (MCMC samling) in PESTO
-
 classdef DRAMOptions < matlab.mixin.SetGet
-   % DRAMOptions provides an option container to pass options as subclass
-   % into the PestoSamplingOptions class.
-   %
+   % DRAMOptions provides an option container to pass options 
+   % into the PestoSamplingOptions class for Delayed Rejection Adaption Metropolis (DRAM).
+   % The DRAM algorithm uses a delayed rejection scheme for better mixing.
+   % 
    % This file is based on AMICI amioptions.m (http://icb-dcm.github.io/AMICI/)
 
    properties      
-      %% Delayed Rejection Adaption Metropolis options
-      % Note: This algorithm uses a delayed rejection scheme for better mixing.
+      % This factor is used for regularization in cases where the single-chain proposal
+      % covariance matrices are ill conditioned. Larger values equal
+      % stronger regularization.
+      regFactor = 1e-6;
 
-      %   --- Delayed Rejection Adaptive Metropolis ---
-      %   opt.DRAM.regFactor          : This factor is used for regularization in
-      %                                 cases where the single-chain proposal
-      %                                 covariance matrices are ill conditioned.
-      %                                 Larger values equal stronger
-      %                                 regularization.
-      %   opt.DRAM.nTry               : The number of tries in the delayed
-      %                                 rejection scheme
-      %   opt.DRAM.verbosityMode      : Defines the level of verbosity 'silent', 'visual',
-      %                                 'debug' or 'text'
-      %   opt.DRAM.adaptionInterval   : Updates the proposal density only every opt.DRAM.adaptionInterval
-      %                                 time
-
-      regFactor         = 1e-6;
-      nTry              = 1;
-      verbosityMode     = 'text';
-      adaptionInterval  = 1;
+      % The number of tries in the delayed rejection scheme
+      nTry = 1;
 
+      % Defines the level of verbosity 'silent', 'visual', 'debug' or 'text'
+      verbosityMode = 'text';
 
+      %  Update the proposal density only every adaptionInterval time
+      adaptionInterval = 1;
 
-   end
-
-   properties (Hidden)
    end
 
    methods
@@ -53,6 +39,9 @@
          %
          %   Note to see the parameters, check the
          %   documentation page for DRAMOptions
+         %
+         % Parameters:
+         % varargin:
 
          % adapted from SolverOptions
 
@@ -150,6 +139,7 @@
       end
 
       function new = copy(this)
+         % Creates a copy of the passed DRAMOptions instance
          new = feval(class(this));
 
          p = properties(this);

@MALAOptions/MALAOptions.m

@@ -1,29 +1,19 @@
-% @file MALAOptions
-% @brief A class for sanity checks of MALA algorithm (MCMC samling) in PESTO
-
 classdef MALAOptions < matlab.mixin.SetGet
    % MALAOptions provides an option container to pass options as subclass
-   % into the PestoSamplingOptions class.
+   % into the PestoSamplingOptions class for the Metropolis Adaptive Langevin Algorithm (MALA).
+   %
+   % Note: This algorithm uses gradients & Hessians either provided
+   % by the user or computed by finite differences.
    %
    % This file is based on AMICI amioptions.m (http://icb-dcm.github.io/AMICI/)
 
    properties      
-      %% Metropolis Adaptive Langevin Algorithm options
-      % Note: This algorithm uses gradients & Hessians either provided
-      % by the user or computed by finite differences.
-
-      % MALA, struct containing the fields
-      %      .regFactor: This factor is used for regularization in
-      %              cases where the proposal covariance matrices are
-      %              ill conditioned. Larger values equal stronger
-      %              regularization.
+      % This factor is used for regularization in cases where the proposal covariance matrices are
+      % ill conditioned. Larger values equal stronger regularization.
       regFactor = 1e-6;
 
-
    end
 
-   properties (Hidden)
-   end
 
    methods
       function obj = MALAOptions(varargin)
@@ -42,7 +32,10 @@
          %
          %   Note to see the parameters, check the
          %   documentation page for MALAOptions
-
+         %
+         % Parameters:
+         % varargin:
+
          % adapted from SolverOptions
 
          if nargin > 0
@@ -139,6 +132,8 @@
       end
 
       function new = copy(this)
+        % Creates a copy of the passed MALAOptions instance
+
          new = feval(class(this));
 
          p = properties(this);

@PHSOptions/PHSOptions.m

@@ -1,42 +1,31 @@
-% @file PHSOptions
-% @brief A class for sanity checks of PHS algorithm (MCMC samling) in PESTO
-
 classdef PHSOptions < matlab.mixin.SetGet
-   % PHSOptions provides an option container to pass options as subclass
-   % into the PestoSamplingOptions class.
+   % PHSOptions provides an option container to set options for Parallel
+   % Hierarchical Sampling (PHS) in PestoSamplingOptions.PHS .
    %
    % This file is based on AMICI amioptions.m (http://icb-dcm.github.io/AMICI/)
 
    properties      
-      %% Parallel Hierarchical Sampling Options
-      % PHS, struct containing the fields
-      %      .nChains: Initial number of temperatures (default 10)
-      %      .alpha: Parameter which controlls the adaption degeneration
-      %              velocity of the single-chain proposals.
-      %              Value between 0 and 1. Default 0.51.
-      %              No adaption (classical Metropolis-Hastings) for 0.
-      %      .memoryLength: The higher the value the more it lowers the
-      %              impact of early adaption steps. Default 1.
-      %      .regFactor: Regularization factor for ill conditioned
-      %              covariance matrices of the adapted proposal density.
-      %              Regularization might happen if the eigenvalues of
-      %              the covariance matrix strongly differ in order of
-      %              magnitude. In this case, the algorithm adds a small
-      %              diag-matrix to the covariance matrix with elements
-      %              regFactor.
-      %      .trainingTime: The number of iterations before the chains
-      %              start to swap. Might get used to ensure a proper local
-      %              adaption of the single chains before exchanging them.
-      nChains                    = 10;
-      alpha                      = 0.51;
-      memoryLength               = 1;
-      regFactor                  = 1e-6;
-      trainingTime               = 1;
+      % Initial number of temperatures
+      nChains = 10;
 
+      % Parameter which controlls the adaption degeneration
+      % velocity of the single-chain proposals.
+      % Value between 0 and 1.
+      % No adaption (classical Metropolis-Hastings) for 0.
+      alpha = 0.51;
+
+      % The higher the value the more it lowers the impact of early adaption steps.
+      memoryLength = 1;
 
-   end
-
-   properties (Hidden)
+      % Regularization factor for ill conditioned covariance matrices of the adapted proposal density.
+      % Regularization might happen if the eigenvalues of the covariance matrix strongly differ in order of
+      % magnitude. In this case, the algorithm adds a small diag-matrix to the covariance matrix with elements
+      % regFactor.
+      regFactor = 1e-6;
+
+      % The number of iterations before the chains start to swap. 
+      % Might get used to ensure a proper local adaption of the single chains before exchanging them.
+      trainingTime = 1;      
    end
 
    methods
@@ -56,7 +45,10 @@
          %
          %   Note to see the parameters, check the
          %   documentation page for PHSOptions
-
+         % 
+         % Parameters:
+         %  varargin:
+         % 
          % adapted from SolverOptions
 
          if nargin > 0
@@ -153,6 +145,7 @@
       end
 
       function new = copy(this)
+        % Creates a copy of the passed PHSOptions instance
          new = feval(class(this));
 
          p = properties(this);

@PTOptions/PTOptions.m

@@ -1,51 +1,41 @@
-% @file PTOptions
-% @brief A class for sanity checks of PT algorithm (MCMC samling) in PESTO
-
 classdef PTOptions < matlab.mixin.SetGet
-   % PTOptions provides an option container to pass options as subclass
-   % into the PestoSamplingOptions class.
+   % PTOptions provides an option container to specify parallel tempering (PT) options 
+   % in PestoSamplingOptions.PT.
    %
    % This file is based on AMICI amioptions.m (http://icb-dcm.github.io/AMICI/)
 
    properties      
-      %% Parallel Tempering Options
+      % Initial number of temperatures
+      nTemps = 10;
 
-      % PT, struct containing the fields
-      %      .nTemps: Initial number of temperatures (default 10)
-      %      .exponentT: The initial temperatures are set by a power law
-      %              to ^opt.exponentT. (default 4)
-      %      .alpha: Parameter which controlls the adaption degeneration
-      %              velocity of the single-chain proposals.
-      %              Value between 0 and 1. Default 0.51.
-      %              No adaption (classical Metropolis-Hastings) for 0.
-      %      .temperatureAlpha: Parameter which controlls the adaption
-      %              degeneration velocity of the temperature adaption.
-      %              Value between 0 and 1. Default 0.51. No effect for
-      %              value = 0.
-      %      .memoryLength: The higher the value the more it lowers the
-      %              impact of early adaption steps. Default 1.
-      %      .regFactor: Regularization factor for ill conditioned
-      %              covariance matrices of the adapted proposal density.
-      %              Regularization might happen if the eigenvalues of
-      %              the covariance matrix strongly differ in order of
-      %              magnitude. In this case, the algorithm adds a small
-      %              diag-matrix to the covariance matrix with elements
-      %              regFactor.
-      %      .temperatureAdaptionScheme: Follows the temperature adaption
-      %              scheme from 'Vousden16' or 'Lacki15'. Can be set to
-      %              'none' for no temperature adaption.
-      nTemps                     = 10;
-      exponentT                  = 4;
-      alpha                      = 0.51;
-      temperatureAlpha           = 0.51;
-      memoryLength               = 1;
-      regFactor                  = 1e-6;
-      temperatureAdaptionScheme  = 'Vousden16';
+      % The initial temperatures are set by a power law to ^opt.exponentT.
+      exponentT = 4;
 
+      % Parameter which controlls the adaption degeneration
+      % velocity of the single-chain proposals.
+      % Value between 0 and 1.
+      % No adaption (classical Metropolis-Hastings) for 0.
+
+      alpha = 0.51;
+
+      % Parameter which controlls the adaption degeneration velocity of
+      % the temperature adaption. Value between 0 and 1. No effect for value = 0.
+      temperatureAlpha = 0.51;
 
-   end
-
-   properties (Hidden)
+      % The higher the value the more it lowers the impact of early adaption steps.
+      memoryLength = 1;
+
+      % Regularization factor for ill conditioned covariance matrices of
+      % the adapted proposal density. Regularization might happen if the
+      % eigenvalues of the covariance matrix strongly differ in order of 
+      % magnitude. In this case, the algorithm adds a small diag-matrix to
+      % the covariance matrix with elements regFactor.
+      regFactor = 1e-6;
+
+      % Follows the temperature adaption scheme from 'Vousden16' or 'Lacki15'. Can be set to
+      % 'none' for no temperature adaption.
+      temperatureAdaptionScheme  = 'Vousden16';
+
    end
 
    methods
@@ -65,6 +55,9 @@
          %
          %   Note to see the parameters, check the
          %   documentation page for PTOptions
+         %
+         % Parameters:
+         %  varargin:
 
          % adapted from SolverOptions
 
@@ -162,6 +155,7 @@
       end
 
       function new = copy(this)
+          % Creates a copy of the passed PTOptions instance
          new = feval(class(this));
 
          p = properties(this);

@PestoOptions/PestoOptions.m

@@ -1,6 +1,3 @@
-% @file PestoOptions
-% @brief A class for checking and holding options for PESTO functions
-
 classdef PestoOptions < matlab.mixin.SetGet
     % PestoOptions provides an option container to pass options to various
     % PESTO functions. Not all options are used by all functions, consult the respective function documentation for details.