update docs of loss and network

update docs of loss and network

Author: taigw

docs/source/pymic.loss.cls.rst

@@ -4,34 +4,10 @@ pymic.loss.cls package
 Submodules
 ----------
 
-pymic.loss.cls.ce module
+pymic.loss.cls.basic module
 ------------------------
 
-.. automodule:: pymic.loss.cls.ce
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pymic.loss.cls.l1 module
-------------------------
-
-.. automodule:: pymic.loss.cls.l1
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pymic.loss.cls.mse module
--------------------------
-
-.. automodule:: pymic.loss.cls.mse
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pymic.loss.cls.nll module
--------------------------
-
-.. automodule:: pymic.loss.cls.nll
+.. automodule:: pymic.loss.cls.basic
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/pymic.loss.seg.rst

@@ -4,6 +4,14 @@ pymic.loss.seg package
 Submodules
 ----------
 
+pymic.loss.seg.abstract module
+------------------------
+
+.. automodule:: pymic.loss.seg.abstract
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   
 pymic.loss.seg.ce module
 ------------------------
 

docs/source/usage.fsl.rst

@@ -209,7 +209,7 @@ hyper-parameters. For example, the following is a configuration for using ``2DUN
    bilinear      = False
    deep_supervise= False
 
-The ``SegNetDict`` in :mod:`pymic.net.neg_dict_seg` lists all the built-in network 
+The ``SegNetDict`` in :mod:`pymic.net.net_dict_seg` lists all the built-in network 
 structures currently implemented in PyMIC. 
 
 You can also define your own networks. To integrate your customized 

pymic/io/image_read_write.py

@@ -10,15 +10,12 @@ def load_nifty_volume_as_4d_array(filename):
     """
     Read a nifty image and return a dictionay storing data array, origin, 
     spacing and direction.\n
-    output['data_array'] 4d array with shape [C, D, H, W];\n
-    output['spacing']    a list of spacing in z, y, x axis;\n
-    output['direction']  a 3x3 matrix for direction.
+    output['data_array'] 4D array with shape [C, D, H, W];\n
+    output['spacing']    A list of spacing in z, y, x axis;\n
+    output['direction']  A 3x3 matrix for direction.
 
-    Args:
-        filename (str): the input file name
-    
-    Returns:
-        dict: a dictionay storing data array, origin, spacing and direction.
+    :param filename: (str) The input file name
+    :return: A dictionay storing data array, origin, spacing and direction.
     """
     img_obj    = sitk.ReadImage(filename)
     data_array = sitk.GetArrayFromImage(img_obj)
@@ -43,15 +40,12 @@ def load_rgb_image_as_3d_array(filename):
     """
     Read an RGB image and return a dictionay storing data array, origin, 
     spacing and direction. \n
-    output['data_array'] 3d array with shape [D, H, W]; \n
+    output['data_array'] 3D array with shape [D, H, W]; \n
     output['spacing']    a list of spacing in z, y, x axis;  \n
     output['direction']  a 3x3 matrix for direction.
 
-    Args:
-        filename (str): the input file name
-    
-    Returns:
-        dict: a dictionay storing data array, origin, spacing and direction.
+    :param filename: (str) The input file name
+    :return: A dictionay storing data array, origin, spacing and direction.
     """
     image = np.asarray(Image.open(filename))
     image_shape = image.shape
@@ -74,14 +68,11 @@ def load_rgb_image_as_3d_array(filename):
 
 def load_image_as_nd_array(image_name):
     """
-    load an image and return a 4D array with shape [C, D, H, W], 
+    Load an image and return a 4D array with shape [C, D, H, W], 
     or 3D array with shape [C, H, W].
 
-    Args:
-        image_name (str): the image name.
-
-    Returns:
-        dict: a dictionay storing data array, origin, spacing and direction.
+    :param filename: (str) The input file name
+    :return: A dictionay storing data array, origin, spacing and direction.
     """
     if (image_name.endswith(".nii.gz") or image_name.endswith(".nii") or
         image_name.endswith(".mha")):
@@ -97,10 +88,9 @@ def save_array_as_nifty_volume(data, image_name, reference_name = None):
     """
     Save a numpy array as nifty image
 
-    Args:
-        data (numpy.ndarray): a numpy array with shape [Depth, Height, Width].\n
-        image_name (str): the ouput file name.\n
-        reference_name (str): file name of the reference image of which 
+    :param data:  (numpy.ndarray) A numpy array with shape [Depth, Height, Width].
+    :param image_name:  (str) The ouput file name.
+    :param reference_name:  (str) File name of the reference image of which 
         meta information is used.
     """
     img = sitk.GetImageFromArray(data)
@@ -114,12 +104,11 @@ def save_array_as_nifty_volume(data, image_name, reference_name = None):
 
 def save_array_as_rgb_image(data, image_name):
     """
-    Save a numpy array as rgb image
+    Save a numpy array as rgb image.
 
-    Args:
-        data (numpy.ndarray): a numpy array with shape [3, H, W] or
-        [H, W, 3] or [H, W]. \n
-        image_name (str): the output file name.
+    :param data:  (numpy.ndarray) A numpy array with shape [3, H, W] or
+        [H, W, 3] or [H, W]. 
+    :param image_name:  (str) The output file name.
     """
     data_dim = len(data.shape)
     if(data_dim == 3):
@@ -133,10 +122,9 @@ def save_nd_array_as_image(data, image_name, reference_name = None):
     """
     Save a 3D or 2D numpy array as medical image or RGB image
     
-    Args:
-        data (numpy.ndarray): a numpy array with shape [D, H, W] or [C, H, W]. \n
-        image_name (str): the output file name. \n 
-        reference_name (str): file name of the reference image of which 
+    :param data:  (numpy.ndarray) A numpy array with shape [3, H, W] or
+        [H, W, 3] or [H, W]. 
+    :param reference_name: (str) File name of the reference image of which 
         meta information is used.
     """
     data_dim = len(data.shape)
@@ -158,16 +146,14 @@ def rotate_nifty_volume_to_LPS(filename_or_image_dict, origin = None, direction
     '''
     Rotate the axis of a 3D volume to LPS
 
-    Args:
-        filename_or_image_dict (str): filename of the nifty file (str) or image dictionary 
+    :param filename_or_image_dict: (str) Filename of the nifty file (str) or image dictionary 
         returned by load_nifty_volume_as_4d_array. If supplied with the former, 
         the flipped image data will be saved to override the original file. 
         If supplied with the later, only flipped image data will be returned.\n
-        origin (list or tuple): the origin of the image.\n
-        direction (list or tuple): the direction of the image.
+    :param origin: (list/tuple) The origin of the image.
+    :param direction: (list or tuple) The direction of the image.
 
-    Returns:
-        dict: a dictionary for image data and meta info, with ``data_array``,
+    :return: A dictionary for image data and meta info, with ``data_array``,
         ``origin``, ``direction`` and ``spacing``.
     '''
 

pymic/io/nifty_dataset.py

@@ -15,13 +15,12 @@ class NiftyDataset(Dataset):
     dimention order [C, D, H, W] for 3D images, and 3D tensors 
     with dimention order [C, H, W] for 2D images.
 
-    Args:
-        root_dir (str): Directory with all the images. \n
-        csv_file (str): Path to the csv file with image names. \n
-        modal_num (int): Number of modalities. \n
-        with_label (bool): Load the data with segmentation ground truth or not. \n
-        with_weight(bool): Load pixel-wise weight map or not. \n
-        transform (list): list of transform to be applied on a sample.
+    :param root_dir: (str) Directory with all the images. 
+    :param csv_file: (str) Path to the csv file with image names.
+    :param modal_num: (int) Number of modalities. 
+    :param with_label: (bool) Load the data with segmentation ground truth or not.
+    :param transform:  (list) List of transforms to be applied on a sample.
+        The built-in transforms can listed in :mod:`pymic.transform.trans_dict`.
     """
     def __init__(self, root_dir, csv_file, modal_num = 1, 
             with_label = False, transform=None):
@@ -93,13 +92,13 @@ class ClassificationDataset(NiftyDataset):
     dimention order [C, D, H, W] for 3D images, and 3D tensors 
     with dimention order [C, H, W] for 2D images.
 
-    Args:
-        root_dir (str): Directory with all the images. \n
-        csv_file (str): Path to the csv file with image names. \n
-        modal_num (int): Number of modalities. \n
-        class_num (int): class number of the classificaiton task. \n
-        with_label (bool): Load the data with segmentation ground truth or not. \n
-        transform (list): list of transform to be applied on a sample.
+    :param root_dir: (str) Directory with all the images. 
+    :param csv_file: (str) Path to the csv file with image names.
+    :param modal_num: (int) Number of modalities. 
+    :param class_num: (int) Class number of the classificaiton task.
+    :param with_label: (bool) Load the data with segmentation ground truth or not.
+    :param transform:  (list) List of transforms to be applied on a sample.
+        The built-in transforms can listed in :mod:`pymic.transform.trans_dict`.
     """
     def __init__(self, root_dir, csv_file, modal_num = 1, class_num = 2, 
             with_label = False, transform=None):

pymic/loss/cls/basic.py

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+from __future__ import print_function, division
+
+import torch
+import torch.nn as nn
+
+class AbstractClassificationLoss(nn.Module):
+    """
+    Abstract Classification Loss.
+    """
+    def __init__(self, params = None):
+        super(AbstractClassificationLoss, self).__init__()
+    
+    def forward(self, loss_input_dict):
+        """
+        The arguments should be written in the `loss_input_dict` dictionary, and it has the
+        following fields. 
+        
+        :param prediction: A prediction with shape of [N, C] where C is the class number.
+        :param ground_truth: The corresponding ground truth, with shape of [N, 1].
+
+        Note that `prediction` is the digit output of a network, before using softmax.
+        """
+        pass
+
+class CrossEntropyLoss(AbstractClassificationLoss):
+    """
+    Standard Softmax-based  CE loss.
+    """
+    def __init__(self, params = None):
+        super(CrossEntropyLoss, self).__init__(params)
+        self.ce_loss = nn.CrossEntropyLoss()
+    
+    def forward(self, loss_input_dict):
+        predict = loss_input_dict['prediction']
+        labels  = loss_input_dict['ground_truth']
+        loss = self.ce_loss(predict, labels)
+        return loss
+
+class SigmoidCELoss(AbstractClassificationLoss):
+    """
+    Sigmoid-based CE loss.
+    """
+    def __init__(self, params = None):
+        super(SigmoidCELoss, self).__init__(params)
+    
+    def forward(self, loss_input_dict):
+        predict = loss_input_dict['prediction']
+        labels  = loss_input_dict['ground_truth']
+        predict = nn.Sigmoid()(predict) * 0.999 + 5e-4
+        loss = - labels * torch.log(predict) - (1 - labels) * torch.log( 1 - predict)
+        loss = loss.mean()
+        return loss
+
+class L1Loss(AbstractClassificationLoss):
+    """
+    L1 (MAE) loss for classification
+    """
+    def __init__(self, params = None):
+        super(L1Loss, self).__init__(params)
+        self.l1_loss = nn.L1Loss()
+    
+    def forward(self, loss_input_dict):
+        predict = loss_input_dict['prediction']
+        labels  = loss_input_dict['ground_truth'][:, None] # reshape to N, 1
+        softmax = nn.Softmax(dim = 1)
+        predict = softmax(predict)
+        num_class  = list(predict.size())[1]
+        data_type = 'float' if(predict.dtype is torch.float32) else 'double'
+        soft_y = get_soft_label(labels, num_class, data_type)
+        loss = self.l1_loss(predict, soft_y)
+        return loss
+
+class MSELoss(AbstractClassificationLoss):
+    """
+    Mean Square Error loss for classification.
+    """
+    def __init__(self, params = None):
+        super(MSELoss, self).__init__(params)
+        self.mse_loss = nn.MSELoss()
+    
+    def forward(self, loss_input_dict):
+        predict = loss_input_dict['prediction']
+        labels  = loss_input_dict['ground_truth'][:, None] # reshape to N, 1
+        softmax = nn.Softmax(dim = 1)
+        predict = softmax(predict)
+        num_class  = list(predict.size())[1]
+        data_type = 'float' if(predict.dtype is torch.float32) else 'double'
+        soft_y = get_soft_label(labels, num_class, data_type)
+        loss = self.mse_loss(predict, soft_y)
+        return loss
+
+class NLLLoss(AbstractClassificationLoss):
+    """
+    The negative log likelihood loss for classification.
+    """
+    def __init__(self, params = None):
+        super(NLLLoss, self).__init__(params)
+        self.nll_loss = nn.NLLLoss()
+    
+    def forward(self, loss_input_dict):
+        predict = loss_input_dict['prediction']
+        labels  = loss_input_dict['ground_truth']
+        logsoft = nn.LogSoftmax(dim = 1)
+        predict = logsoft(predict)
+        loss = self.nll_loss(predict, labels)
+        return loss