Docs: update morphology file format in docs (#517)

Author: bgmeulem

data_base/IO/LoaderDumper/dask_to_categorized_msgpack.py

@@ -12,19 +12,19 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-r"""Save and load dask dataframes to msgpack with categorical columns.
+"""Save and load dask dataframes to msgpack with categorical columns.
 
 This dumper is designed for dataframes with the following properties:
 
 - The index is str
 - The columns have a lot of repetitive values, so they can be grouped.
  
-If the number of partitions is very large (:math:`\textgreater 10000`), it will repartition the 
+If the number of partitions is very large (:math:`\\gt 10000`), it will repartition the 
 dataframe to 5000 partitions. 
 Loading such a dataframe is normaly possible within 1 second.
 
-Before saving, all str-columns will be converted to ``pd.Categorical``s
-In each respective partition, if the part of unique values in the respective column is :math:`\leq 20%`. The original datatype
+Before saving, all str-columns will be converted to ``pd.Categorical``
+In each respective partition, if the part of unique values in the respective column is :math:`\\leq 20\\%`. The original datatype
 will be restored if the dataframe is loaded. 
 This therefore only serves as optimization to increase loading speed and reduce network traffic for suitable dataframes. 
 Suitable dataframes are for example the :ref:`syn_activation_format` dataframe.

docs/file_formats.rst

@@ -21,7 +21,7 @@ File & data formats
 .syn
 ****
 ISF custom file format to store synapse locations onto a morphology.
-Only valid with an associated morphology :ref:`hoc_file_format` file.
+Only valid with an associated morphology :ref:`morphology_file_format` file.
 
 For each synapse, it provides the synapse type and location onto the morphology.
 Each row index corresponds to its synapse ID, providing a link to a corresponding :ref:`con_file_format` file.
@@ -50,9 +50,9 @@ Example::
 .con
 ****
 ISF custom file format to store connectivity data. 
-To be used in conjunction with an associated :ref:`syn_file_format` file and morphology :ref:`hoc_file_format` file.
+To be used in conjunction with an associated :ref:`syn_file_format` file and morphology :ref:`morphology_file_format` file.
 It numbers each synapse, and links it to its associated presynaptic cell type and ID.
-While a :ref:`syn_file_format` file and :ref:`hoc_file_format` file provide the anatomical realization of a morphology embedding into a network,
+While a :ref:`syn_file_format` file and :ref:`morphology_file_format` file provide the anatomical realization of a morphology embedding into a network,
 the addition of a :ref:`con_file_format` file makes possible to construct a functional realization, as it allows linking the synapses to
 presynaptic cells of a dense connectome model, which in turn allows to assign cell type specific activation patterns 
 to each synapse. ISF's workflow is designed to create these files in tandem, so they always co-exist.
@@ -91,7 +91,7 @@ Cell parameters
 ===============
 
 :ref:`param_file_format` file to store biophysical parameters of a cell.
-Includes a reference to a :ref:`hoc_file_format` morphology file, 
+Includes a reference to a :ref:`morphology_file_format` morphology file, 
 biophysical properties of the cell per morphological structure (e.g. soma, dendrite, axon initial segment ...),
 and basic simulation parameters. Morphology structure labels should match those inferred from the morphology file.
 
@@ -181,7 +181,7 @@ Network parameters
 ==================
 The :ref:`param_file_format` format is used to store network parameters, 
 describing the presynaptic cells and their synaptic activations.
-Only valid with an associated :ref:`hoc_file_format` morphology file, :ref:`syn_file_format` file, and :ref:`con_file_format` file.
+Only valid with an associated :ref:`morphology_file_format` morphology file, :ref:`syn_file_format` file, and :ref:`con_file_format` file.
 
 For each presynaptic cell type in the network, this following information is provided:
 

simrun/modular_reduced_model_inference/strategy.py

@@ -440,26 +440,26 @@ def visualize(self, optimizer_output, normalize=True):
 
 
 class RaisedCosineBasis(object):
-    r"""Set of raised cosine basis functions to use as a kernel for weighing synaptic activation patterns.
+    """Set of raised cosine basis functions to use as a kernel for weighing synaptic activation patterns.
     
     A raised cosine is defined as:
     
     .. math::
     
-        f_i(x) = \\frac{1}{2} cos(a \cdot log(\\tau + c) - \phi_i) + \\frac{1}{2}
+        f_i(x) = \\frac{1}{2} cos(a \\cdot log(\\tau + c) - \\phi_i) + \\frac{1}{2}
         
     where :math:`\\tau` is the input dimension (space or time e.g.), :math:`a` is the steepness, :math:`c` is the offset, and :math:`\phi` is the phase.
-    These basis functions can be superimposed using learnable weights :math:`x_i` to form a single filter :math:`\mathbf{w}(\\tau)` over the domain :math:`\\tau`:
+    These basis functions can be superimposed using learnable weights :math:`x_i` to form a single filter :math:`\\mathbf{w}(\\tau)` over the domain :math:`\\tau`:
     
     .. math::
     
-        \mathbf{w}(\\tau) = \sum_{i} x_i \cdot f_i(\\tau)
+        \mathbf{w}(\\tau) = \\sum_{i} x_i \\cdot f_i(\\tau)
         
     And this filter can then be used to weigh the input data :math:`\mathbf{D}`:
     
     .. math::
     
-        WI(t) = \int_{t-width}^{t}  \mathbf{w}(\\tau) \cdot \mathbf{D}(\\tau)
+        WI(t) = \\int_{t-width}^{t}  \\mathbf{w}(\\tau) \\cdot \\mathbf{D}(\\tau)
         
     Note:
         The notation here heavily implies that the cosine functions are defined over the time domain.
@@ -503,10 +503,10 @@ def __init__(
 
 
     def compute(self, width=80):
-        r"""Compute the vector of raised cosine basis functions :math:`\mathbf{f}`.
+        """Compute the vector of raised cosine basis functions :math:`\\mathbf{f}`.
         
-        Each element :math:`f_i` in the vector :math:`\mathbf{f}` is a raised cosine basis function 
-        with a different :math:`\phi_i`. The domain of each :math:`f_i` is :math:`[0, width]`.
+        Each element :math:`f_i` in the vector :math:`\\mathbf{f}` is a raised cosine basis function 
+        with a different :math:`\\phi_i`. The domain of each :math:`f_i` is :math:`[0, width]`.
         
         Args:
             width (int): The width of the basis functions.
@@ -531,25 +531,25 @@ def compute(self, width=80):
 
 
     def get(self):
-        r"""Get the basis functions :math:`\mathbf{f}`.
+        """Get the basis functions :math:`\\mathbf{f}`.
         
         Returns:
             list: The list of basis functions."""
         return self.basis
 
 
     def get_superposition(self, x):
-        r"""Get the weighed sum :math:`\mathbf{w}(\\tau)` of the basis functions :math:`f`.
+        """Get the weighed sum :math:`\\mathbf{w}(\\tau)` of the basis functions :math:`f`.
         
         The superposition of all basis functions, weighed by the input weights,
         is a single filter of length :param:`width` that can be used to weigh the input data: synapse activations.
         
         .. math::
     
-            \mathbf{w}(\\tau) = \sum_{i} x_i\ f_i(\\tau) = \mathbf{x} \cdot \mathbf{f}(\\tau)
+            \\mathbf{w}(\\tau) = \\sum_{i} x_i\\ f_i(\\tau) = \\mathbf{x} \\cdot \\mathbf{f}(\\tau)
         
         Args:
-            x (array): The (learnable) input weights :math:`\mathbf{x}`
+            x (array): The (learnable) input weights :math:`\\mathbf{x}`
         
         Returns:
             array: The weighed sum of the basis functions.
@@ -558,7 +558,7 @@ def get_superposition(self, x):
 
 
     def visualize(self, ax=None, plot_kwargs=None):
-        r"""Visualize the basis functions :math:`\mathbf{f}`.
+        """Visualize the basis functions :math:`\\mathbf{f}`.
         
         Args:
             ax (plt.axis): The axis to plot on. Default is ``None``.
@@ -576,7 +576,7 @@ def visualize(self, ax=None, plot_kwargs=None):
 
 
     def visualize_w(self, x, ax=None, plot_kwargs=None):    
-        r"""Visualize the superposition :math:`\mathbf{w}(\tau)` of the basis functions :math:`\mathbf{f}`.
+        """Visualize the superposition :math:`\\mathbf{w}(\\tau)` of the basis functions :math:`\\mathbf{f}`.
         
         Args:
             x (array): The (learnable) input weights for the basis functions.
@@ -637,7 +637,7 @@ def _setup(self):
         self._get_score = partial(self._get_score_static, self.RaisedCosineBasis_postspike, self.ISI)
 
     def _get_x0(self):
-        r"""Get an initial guess for the learnable weights of the basis functions :math:`\mathbf{x}`.
+        """Get an initial guess for the learnable weights of the basis functions :math:`\\mathbf{x}`.
         
         These weights are optimized by the solver.
         
@@ -679,7 +679,7 @@ def normalize_x(self, x):
 
 
 class Strategy_spatiotemporalRaisedCosine(_Strategy):
-    r'''Spatiotemporal raised cosine strategy.
+    '''Spatiotemporal raised cosine strategy.
     
     Uses the :class:``RaisedCosineBasis`` to create a set of basis functions.
     
@@ -691,27 +691,27 @@ class Strategy_spatiotemporalRaisedCosine(_Strategy):
         - ``ISI``: The inter-spike intervals.
 
     Attributes:
-        RaisedCosineBasis_spatial (RaisedCosineBasis): The spatial basis functions :math:`\mathbf{g}(z)`.
-        RaisedCosineBasis_temporal (RaisedCosineBasis): The temporal basis functions :math:`\mathbf{f}(t)`.
+        RaisedCosineBasis_spatial (RaisedCosineBasis): The spatial basis functions :math:`\\mathbf{g}(z)`.
+        RaisedCosineBasis_temporal (RaisedCosineBasis): The temporal basis functions :math:`\\mathbf{f}(t)`.
         base_vectors_arrays_dict (dict): 
-            The basis vectors for each group. basis vectors are of shape (:math:`N_{trials}`, :math:`N_\tau`, :math:`N_z`)
+            The basis vectors for each group. basis vectors are of shape (:math:`N_{trials}`, :math:`N_\\tau`, :math:`N_z`)
             These basis vectors are used for the optimizer, and are already multiplied with the data.
             Do not confuse them with the basis vectors of :param:`RaisedCosineBasis_spatial` and :param:`RaisedCosineBasis_temporal`,
             as the latter are not multiplied with the synapse activaiton data.
         groups (list): The list of groups. Usually simply ``['EXC', 'INH']``.
         len_z (int): The length of the spatial domain i.e. the amount of spatial basis vectors.
         len_t (int): The length of the temporal domain i.e. the amount of temporal basis vectors.
         len_trials (int): The number of trials.
-        convert_x (callable): The conversion function to convert the 1D learnable weight vector :math:`\mathbf{x}` into a structured dictionary.
+        convert_x (callable): The conversion function to convert the 1D learnable weight vector :math:`\\mathbf{x}` into a structured dictionary.
         _get_score (callable): The cost function to provide to the optimizer.
     '''
 
     def __init__(self, name, RaisedCosineBasis_spatial, RaisedCosineBasis_temporal):
-        r"""
+        """
         Args:
             name (str): The name of the strategy.
-            RaisedCosineBasis_spatial (RaisedCosineBasis): The spatial basis functions :math:`\mathbf{g}(z)`.
-            RaisedCosineBasis_temporal (RaisedCosineBasis): The temporal basis :math:`\mathbf{f}(t)`.
+            RaisedCosineBasis_spatial (RaisedCosineBasis): The spatial basis functions :math:`\\mathbf{g}(z)`.
+            RaisedCosineBasis_temporal (RaisedCosineBasis): The temporal basis :math:`\\mathbf{f}(t)`.
         """
         super(Strategy_spatiotemporalRaisedCosine, self).__init__(name)
         self.RaisedCosineBasis_spatial = RaisedCosineBasis_spatial
@@ -728,33 +728,33 @@ def _setup(self):
         self._get_score = partial(self._get_score_static, self.convert_x, self.base_vectors_arrays_dict)
 
     def compute_basis(self):
-        r'''Compute the basis vectors for the dataset.
+        '''Compute the basis vectors for the dataset.
         
-        These basis vectors are defined as :math:`\mathbf{f}(t) \cdot \mathbf{g}(z) \cdot \mathbf{D}`.
+        These basis vectors are defined as :math:`\\mathbf{f}(t) \\cdot \\mathbf{g}(z) \\cdot \\mathbf{D}`.
         When these basis vectors are weighed, they form the argument of the integral over the domain.
         Once integrated over the domain, they yield the weighted net input.
         
         .. math::
 
-            WNI(t) = \int_{t-width}^{t} \int_z \mathbf{w}_{\\tau}(\\tau) \cdot \mathbf{w}_{z}(z) \cdot \mathbf{D} = \int_{t-width}^{t} \int_z \mathbf{x} \cdot \mathbf{y} \cdot \mathbf{f}(t) \cdot \mathbf{g}(z) \cdot \mathbf{D}
+            WNI(t) = \\int_{t-width}^{t} \\int_z \\mathbf{w}_{\\tau}(\\tau) \\cdot \\mathbf{w}_{z}(z) \\cdot \\mathbf{D} = \\int_{t-width}^{t} \\int_z \\mathbf{x} \\cdot \\mathbf{y} \\cdot \\mathbf{f}(t) \\cdot \\mathbf{g}(z) \\cdot \\mathbf{D}
         
         Attention:
             These are not the same basis vectors as in :class:`RaisedCosineBasis`.
-            These basis vectors are already multiplied with the data :math:`\mathbf{D}`.
+            These basis vectors are already multiplied with the data :math:`\\mathbf{D}`.
             Since dot product is commutative, the order of this multiplication does not matter for calculating
             the weighted net input, but these intermediate basis vectors are different.
             
         Returns:
-            dict: A dictionary of basis vectors for each group. basis vectors are of shape :math:`(n_trials, dim(\mathbf{f}(\\tau)), dim(\mathbf{g}(z)))`.
+            dict: A dictionary of basis vectors for each group. basis vectors are of shape :math:`(n\\_trials, dim(\\mathbf{f}(\\tau)), dim(\\mathbf{g}(z)))`.
         '''
 
         def _compute_base_vector_array(spatiotemp_SA):
-            r"""
+            """
             Args:
-                spatiotemp_SA (array): The spatiotemporal synaptic activation patterns of shape :math:`(n_trials, dim(\mathbf{f}(\\tau)), dim(\mathbf{g}(z)))`.
+                spatiotemp_SA (array): The spatiotemporal synaptic activation patterns of shape :math:`(n_trials, dim(\\mathbf{f}(\\tau)), dim(\\mathbf{g}(z)))`.
                 
             Returns:
-                array: The basis vector array of shape :math:`(n_trials, dim(\mathbf{f}(\\tau)), dim(\mathbf{g}(z)))`.
+                array: The basis vector array of shape :math:`(n\\_trials, dim(\\mathbf{f}(\\tau)), dim(\\mathbf{g}(z)))`.
             """
             _, time_domain, space_domain = spatiotemp_SA.shape
             self.RaisedCosineBasis_spatial.compute(space_domain)
@@ -776,7 +776,7 @@ def _compute_base_vector_array(spatiotemp_SA):
         self.base_vectors_arrays_dict = base_vectors_arrays_dict
 
     def _get_x0(self):
-        r"""Get an initial guess for the learnable weights  :math:`\mathbf{x}` and :math:`\mathbf{y}` of the basis functions :math:`\mathbf{f}(\tau)` and :math:`\mathbf{g}(z)`.
+        """Get an initial guess for the learnable weights  :math:`\\mathbf{x}` and :math:`\\mathbf{y}` of the basis functions :math:`\\mathbf{f}(\\tau)` and :math:`\\mathbf{g}(z)`.
         
         Returns:
             np.array: An array of random values in the range :math:`[-1, 1)`, with the same length as the basis parameters.
@@ -785,7 +785,7 @@ def _get_x0(self):
 
     @staticmethod
     def _convert_x_static(groups, len_z, x):
-        r"""Convert the input array :math:`\mathbf{x}` into a dictionary of basis vectors.
+        """Convert the input array :math:`\\mathbf{x}` into a dictionary of basis vectors.
         
         Useful for passing the learnable weights to the optimizer as a one-dimensional array,
         but keeping track of the basis vectors for each group and dimension.
@@ -827,21 +827,21 @@ def _convert_x_static(groups, len_z, x):
 
     @staticmethod
     def _get_score_static(convert_x, base_vectors_arrays_dict, x):
-        r"""Calculate the weighted net input :math:`WNI(t)` for the given weights :math:`\mathbf{x}`.
+        """Calculate the weighted net input :math:`WNI(t)` for the given weights :math:`\\mathbf{x}`.
         
         This is the method that calculates the cost function for the optimizer.
         It is assigned to :func:`~simrun.modular_reduced_model_inference.Strategy_spatiotemporalRaisedCosine._get_score` during
         the setup of the strategy.
         
-        This method left-multiplies the basis vectors :math:`\mathbf{f}(\tau) \cdot \mathbf{g}(z) \cdot \mathbf{D}` 
-        with the learnable weights :math:`\mathbf{x}` and :math:`\mathbf{y}`.
+        This method left-multiplies the basis vectors :math:`\\mathbf{f}(\\tau) \\cdot \\mathbf{g}(z) \\cdot \\mathbf{D}` 
+        with the learnable weights :math:`\\mathbf{x}` and :math:`\\mathbf{y}`.
         It then integrates the results for each group to get the weighted net input :math:`WNI(t)`.
         
         Args:
             convert_x (callable): The conversion function from the learnable weights to the basis vectors.
             base_vectors_arrays_dict (dict): The dictionary of basis vectors for each group.
             x (array): 
-                The learnable weights :math:`\mathbf{x}` and :math:`\mathbf{y}` as a single array.
+                The learnable weights :math:`\\mathbf{x}` and :math:`\\mathbf{y}` as a single array.
                 These are converted to spatial and temporal weights per group with :param:`convert_x`.
             
         Attention:
@@ -862,18 +862,18 @@ def _get_score_static(convert_x, base_vectors_arrays_dict, x):
         return wni  # shape: (n_trials,)
 
     def normalize(self, x, flipkey=None):
-        r'''Normalize the kernel basis functions such that sum of all absolute values of all kernels is 1.
+        '''Normalize the kernel basis functions such that sum of all absolute values of all kernels is 1.
         
         Attention:
             These are the same basis functions as in :class:`RaisedCosineBasis`.
             These are thus not multiplied with the synapse activation data, as is the case with :func:`compute_basis`
             
         Args:
-            x (array): The learnable weights :math:`\mathbf{x}` and :math:`\mathbf{y}` as a 1D array.
+            x (array): The learnable weights :math:`\\mathbf{x}` and :math:`\\mathbf{y}` as a 1D array.
                 These are converted to spatial and temporal weights per group with :param:`convert_x`.
             
         Returns:
-            array: The normalized learnable weights :math:`\mathbf{x}`.
+            array: The normalized learnable weights :math:`\\mathbf{x}`.
         '''
         x = self.convert_x(x)
         #temporal