Cli doc on selective ISM and better errors

Author: evancofer

docs/source/overview/cli.md

@@ -303,13 +303,15 @@ You may find that there are more output files than you expect in `output_dir` at
 - **Warnings:** Selene may detect that the `ref` base(s) in a variant do not match with the bases specified in the reference sequence FASTA at the `(chrom, pos)`. In this case, Selene will use the `ref` base(s) specified in the VCF file in place of those in the reference genome and output predictions accordingly. These predictions will be distinguished by the row label column `ref_match` value `False`. You may review these variants and determine whether you still want to use those predictions/scores. If you find that most of the variants have `ref_match = False`, it may be that you have specified the wrong reference genome version---please check this before proceeding.  
 
 ### _In silico_ mutagenesis
-An example configuration for _in silico_ mutagenesis when using a single sequence as input:
+An example configuration for _in silico_ mutagenesis of the whole sequence (i.e. rather than a subsequence), when using a single sequence as input:
 ```YAML
 in_silico_mutagenesis: {
     input_sequence: ATCGATAAAATTCTGGAG...,
     save_data: [predictions, diffs],
     output_path_prefix: /path/to/output/dir/filename_prefix,
-    mutate_n_bases: 1
+    mutate_n_bases: 1,
+    start_position: 0,
+    end_position: None
 }
 ```
 
@@ -318,15 +320,19 @@ in_silico_mutagenesis: {
 - `save_data`: A list of the data files to output. Must input 1 or more of the following options: `[abs_diffs, diffs, logits, predictions]`. (Note that the raw prediction values will not be outputted by default---you must specify `predictions` in the list if you want them.)
 - `output_path_prefix`: Optional, default is "ism". The path to which the data files are written. We have specified that it should be a filename _prefix_ because we will append additional information depending on what files you would like to output (e.g. `fileprefix_logits.tsv`) If directories in the path do not yet exist, they will automatically be created. 
 - `mutate_n_bases`: Optional, default is 1. The number of bases to mutate at any time. Standard _in silico_ mutagenesis only mutates a single base at a time, so we encourage users to start by leaving this value at 1. Double/triple mutations will be more difficult to interpret and are something we may work on in the future. 
+- `start_position`: Optional, default is 0. The starting position of the subsequence that should be mutated. This value should be nonnegative, and less than `end_position`. Also, the value of `end_position - start_position` should be at least `mutate_n_bases`.
+- `end_position`: Optional, default is `None`. If left as `None`, Selene will use the `sequence_length` parameter from `analyze_sequences`. This is the ending position of the subsequence that should be mutated. This value should be nonnegative, and greater than `start_position`. The value of `end_position -  start_position` should be at least `mutate_n_bases`.
 
-An example configuration for _in silico_ mutagenesis when using a FASTA file as input:
+An example configuration for _in silico_ mutagenesis of the center 100 bases of a 1000 base sequence read from a FASTA file input:
 ```YAML
 in_silico_mutagenesis: {
-    input_path: /path/to/sequences1.fa, 
+    input_path: /path/to/sequences1.fa,
     save_data: [logits],
     output_dir: /path/to/output/predictions/dir,
     mutate_n_bases: 1,
-    use_sequence_name: True
+    use_sequence_name: True,
+    start_position: 450,
+    end_position: 550
 }
 ```
 
@@ -338,6 +344,8 @@ in_silico_mutagenesis: {
 - `use_sequence_name`: Optional, default is `True`.
   - If `use_sequence_name`, output files are prefixed by the sequence name/description corresponding to each sequence in the FASTA file. Spaces in the description are replaced with underscores '_'.
   - If not `use_sequence_name`, output files are prefixed with the index `i` corresponding to the `i`th sequence in the FASTA file.
+- `start_position`: Optional, default is 0. The starting position of the subsequence that should be mutated. This value should be nonnegative, and less than `end_position`. The value of `end_position - start_position` should be at least `mutate_n_bases`.
+- `end_position`: Optional, default is `None`. If left as `None`, Selene will use the `sequence_length` parameter passed to `analyze_sequences`. This is the ending position of the subsequence that should be mutated. This value should be nonnegative, and greater than `start_position`. The value of `end_position -  start_position` should be at least `mutate_n_bases`.
 
 ## Sampler configurations
 Data sampling is used during model training and evaluation. You must specify the sampler in the configuration YAML file alongside the other operation-specific configurations (i.e. `train_model` or `evaluate_model`). 

selene_sdk/predict/_in_silico_mutagenesis.py

@@ -66,17 +66,27 @@ def in_silico_mutagenesis_sequences(sequence,
     if end_position is None:
         end_position = len(sequence)
     if start_position >= end_position:
-        raise ValueError("Starting positions must be less than the ending positions.")
+        raise ValueError(("Starting positions must be less than the ending "
+                          "positions. Found a starting position of {0} with "
+                          "an ending position of {1}.").format(start_position,
+                                                               end_position))
     if start_position < 0:
         raise ValueError("Negative starting positions are not supported.")
     if end_position < 0:
         raise ValueError("Negative ending positions are not supported.")
     if start_position >= len(sequence):
-        raise ValueError("Starting positions must be less than the sequence length.")
+        raise ValueError(("Starting positions must be less than the sequence length."
+                          " Found a starting position of {0} with a sequence length "
+                          "of {1}.").format(start_position, len(sequence)))
     if end_position > len(sequence):
-        raise ValueError("Ending positions must be less than or equal to the sequence length.")
+        raise ValueError(("Ending positions must be less than or equal to the sequence "
+                          "length. Found an ending position of {0} with a sequence "
+                          "length of {1}.").format(end_position, len(sequence)))
     if (end_position - start_position) < mutate_n_bases:
-        raise ValueError("Fewer bases exist in the substring specified by the starting and ending positions than need to be mutated.")
+        raise ValueError(("Fewer bases exist in the substring specified by the starting "
+                          "and ending positions than need to be mutated. There are only "
+                          "{0} currently, but {1} bases must be mutated at a "
+                          "time").format(end_position - start_position, mutate_n_bases))
 
     sequence_alts = []
     for index, ref in enumerate(sequence):

selene_sdk/predict/model_predict.py

@@ -710,18 +710,27 @@ def in_silico_mutagenesis(self,
         if end_position is None:
             end_position = self.sequence_length
         if start_position >= end_position:
-            raise ValueError("Starting positions must be less than the ending positions.")
+            raise ValueError(("Starting positions must be less than the ending "
+                              "positions. Found a starting position of {0} with "
+                              "an ending position of {1}.").format(start_position,
+                                                                   end_position))
         if start_position < 0:
             raise ValueError("Negative starting positions are not supported.")
         if end_position < 0:
             raise ValueError("Negative ending positions are not supported.")
         if start_position >= self.sequence_length:
-            raise ValueError("Starting positions must be less than the sequence length.")
+            raise ValueError(("Starting positions must be less than the sequence length."
+                              " Found a starting position of {0} with a sequence length "
+                              "of {1}.").format(start_position, self.sequence_length))
         if end_position > self.sequence_length:
-            raise ValueError("Ending positions must be less than or equal to the sequence length.")
+            raise ValueError(("Ending positions must be less than or equal to the sequence "
+                              "length. Found an ending position of {0} with a sequence "
+                              "length of {1}.").format(end_position, self.sequence_length))
         if (end_position - start_position) < mutate_n_bases:
-            raise ValueError("Fewer bases exist in the substring specified by the starting and ending positions than need to be mutated.")
-
+            raise ValueError(("Fewer bases exist in the substring specified by the starting "
+                              "and ending positions than need to be mutated. There are only "
+                              "{0} currently, but {1} bases must be mutated at a "
+                              "time").format(end_position - start_position, mutate_n_bases))
 
         path_dirs, _ = os.path.split(output_path_prefix)
         if path_dirs:
@@ -856,19 +865,27 @@ def in_silico_mutagenesis_from_file(self,
         if end_position is None:
             end_position = self.sequence_length
         if start_position >= end_position:
-            raise ValueError("Starting positions must be less than the ending positions.")
+            raise ValueError(("Starting positions must be less than the ending "
+                              "positions. Found a starting position of {0} with "
+                              "an ending position of {1}.").format(start_position,
+                                                                   end_position))
         if start_position < 0:
             raise ValueError("Negative starting positions are not supported.")
         if end_position < 0:
             raise ValueError("Negative ending positions are not supported.")
         if start_position >= self.sequence_length:
-            raise ValueError("Starting positions must be less than the sequence length.")
+            raise ValueError(("Starting positions must be less than the sequence length."
+                              " Found a starting position of {0} with a sequence length "
+                              "of {1}.").format(start_position, self.sequence_length))
         if end_position > self.sequence_length:
-            raise ValueError("Ending positions must be less than or equal to the sequence length.")
+            raise ValueError(("Ending positions must be less than or equal to the sequence "
+                              "length. Found an ending position of {0} with a sequence "
+                              "length of {1}.").format(end_position, self.sequence_length))
         if (end_position - start_position) < mutate_n_bases:
-            raise ValueError("Fewer bases exist in the substring specified by the starting and ending positions than need to be mutated.")
-
-
+            raise ValueError(("Fewer bases exist in the substring specified by the starting "
+                              "and ending positions than need to be mutated. There are only "
+                              "{0} currently, but {1} bases must be mutated at a "
+                              "time").format(end_position - start_position, mutate_n_bases))
 
         os.makedirs(output_dir, exist_ok=True)