Merge pull request #87 from yingtluo/master

Documenting code

code/stat159lambda/classification/design_matrix.py

@@ -6,13 +6,48 @@
 
 
 class DesignMatrix:
+	"""
+	DesignMatrix class in which each instance represents a design matrix. Each
+	design matrix has the following attributes:
+	(1) X : data array, adjusted for offset
+	(2) y : array of the scenes, adjusted for offest
+
+	Parameters
+	----------
+	data_file : string
+	"""
     def __init__(self, data_file):
         self.X = np.load(data_file).T[NUM_OFFSET_VOLUMES:, :]
         ss = ssm.SceneSlicer()
         self.y = np.array(ss.get_scene_slices()[0][NUM_OFFSET_VOLUMES:])
 
     def get_design_matrix(self, volume_indices, voxels_indices):
+    	"""
+    	Given the indices for the desired volume and voxels, returns the
+    	corresponding design matrix
+
+    	Parameters
+    	----------
+    	volume_indices : array
+    	voxels_indices : array
+
+    	Returns
+    	-------
+    	matrix : array
+    	"""
         return self.X[volume_indices, :][:, voxels_indices]
 
     def get_labels(self, volume_indices):
+    	"""
+    	Given the indices for the desired volumes, returns the corresponding
+    	labels from those scenes
+
+    	Parameters
+    	----------
+    	volume_indices : array
+
+    	Returns
+    	-------
+    	indices : array
+    	"""
         return self.y[volume_indices]

code/stat159lambda/classification/partition_volumes.py

@@ -6,6 +6,19 @@
 TRAINING_PERCENT = .80
 
 def partition_volumes():
+	"""
+	Partitions the volumes from the SceneSlicer object randomly to generate
+	training and testing data
+
+	Parameters
+	----------
+	None
+
+	Returns
+	-------
+	train_indices : array
+	test_indices : array
+	"""
 	volume_indices = np.array(range(NUM_VOLUMES - NUM_OFFSET_VOLUMES))
 	clean_slice_mask = ss.SceneSlicer().get_clean_slice_mask()
 	volume_indices = volume_indices[clean_slice_mask]
@@ -17,17 +30,51 @@ def partition_volumes():
 
 
 def save_train_test_indices(train_indices, test_indices):
+	"""
+	Saves the given train and test indices into designated .npy files
+
+	Parameters
+	----------
+	train_indices : array
+	test_indices : array
+
+	Returns
+	-------
+	None
+	"""
 	np.save('train_indices', train_indices)
 	np.save('test_indices', test_indices)
 
 
 def get_train_indices():
+	"""
+	Retrieves the train indices from their saved file and loads that data
+
+	Parameters
+	----------
+	None
+
+	Returns
+	-------
+	train_indices : array
+	"""
 	if not os.path.exists('train_indices.npy'):
 		save_train_test_indices(*partition_volumes())
 	return np.load('train_indices.npy')
 
 
 def get_test_indices():
+	"""
+	Retrieves the test indices from their saved file and loads that data
+
+	Parameters
+	----------
+	None
+
+	Returns
+	-------
+	test_indices : array
+	"""
 	if not os.path.exists('test_indices.npy'):
 		save_train_test_indices(*partition_volumes())
 	return np.load('test_indices.npy')

code/stat159lambda/preprocess/preprocess.py

@@ -16,6 +16,19 @@
 
 
 def concatenate_runs(subj_num):
+    """
+    Concatenates data from all runs for a particular subject and saves that
+    data into a designated file. If file already exists, uses that cached file
+    instead.
+
+    Parameters
+    ----------
+    subj_num : int 
+
+    Returns
+    -------
+    None
+    """
     npy_file_name = dp.get_concatenated_path(subj_num)
     if not exists(npy_file_name) or not USE_CACHED_DATA:
         run_data = []
@@ -36,6 +49,20 @@ def concatenate_runs(subj_num):
 
 
 def reshape_smoothed_to_2d(subj_num, fwhm_mm):
+    """
+    Reshapes the original 4-D array data into a 2-D array of a given subject
+    and full width half maximum smoothed version and saves that into a
+    designated file. If file already exists, uses that cached file instead.
+
+    Parameters
+    ----------
+    subj_num : int
+    fwhm_mm : int
+
+    Returns
+    -------
+    None
+    """
     smoothed_path = dp.get_smoothed_path(subj_num, fwhm_mm)
     smoothed_path_2d = smoothed_path.replace('.npy', '_2d.npy')
     if not exists(smoothed_path_2d) or not USE_CACHED_DATA:
@@ -53,6 +80,18 @@ def reshape_smoothed_to_2d(subj_num, fwhm_mm):
 
 
 def get_affine():
+    """
+    Retrieves the absolute path to the affine.npy file and loads the data from
+    that file
+
+    Parameters
+    ----------
+    None
+
+    Returns
+    -------
+    affine_data : array
+    """
     affine_path = '{0}/data/affine.npy'.format(REPO_HOME_PATH)
     if not exists(affine_path):
         subj_num, run_num = 1, 1
@@ -64,6 +103,21 @@ def get_affine():
 
 
 def gaussian_smooth_subj(subj_num, fwhm_mm):
+    """
+    Retrieves the absolute path to the smoothed data for a particular subject
+    and full width half maximum smoothed version. Loads the data and saves it
+    in the retrieved path. If file already exists, then uses cached version
+    instead.
+
+    Parameters
+    ----------
+    subj_num : int
+    fwhm_mm : int
+
+    Returns 
+    -------
+    None
+    """
     smoothed_data_path = dp.get_smoothed_path(subj_num, fwhm_mm)
     if not exists(smoothed_data_path) or not USE_CACHED_DATA:
         data = np.load(dp.get_concatenated_path(subj_num)).astype(np.float32)
@@ -76,20 +130,65 @@ def gaussian_smooth_subj(subj_num, fwhm_mm):
 
 
 def apply_gaussian_smooth(data_4d, fwhm_mm):
+    """
+    Applies a Gaussian filter to the 4-D data
+
+    Parameters
+    ----------
+    data_4d : 4-D array
+    fwhm_mm : int
+
+    Returns
+    -------
+    gaussian_data : array
+    """
     sigma = np.hstack((convert_fwhm_mm_to_sd_voxel(fwhm_mm), 0))
     return filters.gaussian_filter(data_4d, sigma)
 
 
 def convert_fwhm_to_sigma(fwhm):
+    """
+    Converts the full width half maximum smoothed version to standard deviation
+
+    Parameters
+    ----------
+    fwhm : int
+
+    Returns
+    -------
+    sigma : float
+    """
     return fwhm / (2 * np.sqrt(2 * np.log(2)))
 
 
 def get_voxel_lengths(affine):
+    """
+    Computes vector norms along the 0th axis
+
+    Parameters
+    ----------
+    affine : array
+
+    Returns
+    -------
+    norms : array
+    """
     affine = affine[:3, :3]
     return np.linalg.norm(affine, axis=0)
 
 
 def convert_fwhm_mm_to_sd_voxel(fwhm):
+    """
+    Converts the full width half maximum measurement to standard deviation
+
+    Parameters
+    ----------
+    fwhm : int
+
+    Returns
+    -------
+    sd_voxel : float
+    """
     return convert_fwhm_to_sigma(fwhm) / get_voxel_lengths(get_affine())