Merge pull request #104 from Genentech/more-docs

Author: avantikalal

src/grelu/data/__init__.py

@@ -0,0 +1,4 @@
+"""
+`gReLU.data` contains modules related to processing and QC of genomic data, and loading
+and augmenting genomic data for training, validation and testing sequence-to-function models.
+"""

src/grelu/data/augment.py

@@ -1,7 +1,16 @@
 """
-Functions to augment data. All functions assume that the input is a numpy array containing an integer
-encoded DNA sequence of shape (L,) or a numpy array containing a label of shape (T, L).
-The augmented output will be in the same format.
+`grelu.data.augment` contains functions to augment genomic sequences or functional genomic data.
+
+All functions assume that the input is either:
+
+(1) a 1-D numpy array containing an integer encoded DNA sequence of shape (length,) or;
+(2) a 2-D numpy array containing a label of shape (tasks, length).
+
+The augmented output must be returned in the same format. All augmentation functions also
+require an index (idx) which is an integer or boolean value.
+
+This module also contains the `Augmenter` class which is responsible for applying multiple
+augmentations to a given DNA sequence or (sequence, label) pair.
 """
 
 import warnings
@@ -12,7 +21,7 @@
 from grelu.sequence.mutate import random_mutate
 from grelu.sequence.utils import reverse_complement
 
-# This is the number of output sequences expected from each type of augmentation
+# This is the number of output sequences expected from a single input sequence using each type of augmentation
 AUGMENTATION_MULTIPLIER_FUNCS = {
     "rc": lambda x: 2**x,
     "max_seq_shift": lambda x: (2 * x) + 1,
@@ -197,7 +206,7 @@ def __call__(
         else:
             raise NotImplementedError
 
-        # Augment the sequence
+        # Apply all sequence augmentation functions here
 
         # Shift sequence
         if self.shift_seq:
@@ -224,7 +233,7 @@ def __call__(
             return seq
 
         else:
-            # Augment the label too
+            # Apply all label augmentation functions here
             if self.shift_label:
                 # Shift label
                 label = shift(label, seq_len=self.label_len, idx=pair_shift_idx)

src/grelu/data/dataset.py

@@ -1,8 +1,13 @@
 """
-Pytorch dataset classes to load sequence data
+`grelu.data.dataset` contains specialized PyTorch Dataset classes to load genomic data.
+All dataset classes must inherit from `torch.utils.Data.Dataset`.
 
-All dataset classes produce either one-hot encoded sequences of shape (4, L)
-or sequence-label pairs of shape (4, L) and (T, L).
+Dataset classes intended for inference produce 2-D tensors of shape (4, length),
+containing one-hot encoded sequences.
+
+Dataset classes intended for training and validation produce (sequence, label)
+pairs, wherein the sequence is a 2-D tensor of shape (4, length) containing a one-hot
+encoded sequence, and the label is a 2-D tensor of shape (tasks, length).
 """
 
 import os

src/grelu/data/preprocess.py

@@ -1,5 +1,8 @@
 """
-Functions to preprocess genomic datasets.
+`grelu.data.preprocess` contains functions to preprocess genomic datasets in standard
+formats, in order to produce data suitable for deep learning. This includes filtering
+and checking data, splitting data into sets for training and validation, and converting
+between data formats.
 """
 
 import os

src/grelu/data/utils.py

@@ -1,5 +1,5 @@
 """
-Dataset-related utility functions.
+`grelu.data.utils` contains Dataset-related utility functions.
 """
 
 from typing import List, Union

src/grelu/design.py

@@ -1,3 +1,8 @@
+"""
+`grelu.design` contains methods to design novel DNA sequences
+using trained sequence-to-function deep learning models.
+"""
+
 from typing import Callable, List, Optional, Union
 
 import numpy as np

src/grelu/interpret/__init__.py

@@ -0,0 +1,3 @@
+"""
+`grelu.interpret` contains modules related to sequence interpretation using trained models.
+"""

src/grelu/interpret/modisco.py

@@ -1,3 +1,9 @@
+"""
+`grelu.interpret.modisco` contains functions that enable the user to run TF-MoDISco
+(Shrikumar et al. 2018) on trained models. Many of the functions here are based on
+https://github.com/jmschrei/tfmodisco-lite.
+"""
+
 import os
 from typing import Callable, List, Optional, Union
 

src/grelu/interpret/motifs.py

@@ -1,5 +1,9 @@
 """
-Functions related to manipulating sequence motifs and scanning DNA sequences with motifs.
+`grelu.interpret.motifs contains functions related to manipulating sequence motifs
+and scanning DNA sequences with motifs. Note that the aim here is not to provide
+a comprehensive suite of functions related to motif analysis, but only the
+functionality necessary for interpreting sequence-to-function deep learning models
+using these motifs.
 """
 
 from typing import Callable, Dict, Generator, List, Optional, Tuple, Union

src/grelu/interpret/score.py

@@ -1,5 +1,9 @@
 """
-Functions related to scoring the importance of individual DNA bases.
+`grelu.interpret.score` contains functions related to scoring the importance of
+individual DNA bases or regions using a trained model.
+
+gReLU uses Captum for several attribution methods, including InputXGradient,
+IntegratedGradients, and Saliency.
 """
 
 import warnings