Merge pull request #37 from apriha/develop

v0.6.1

.travis.yml

@@ -33,7 +33,7 @@ script:
   - |
     if [[ $DOWNLOADS_ENABLED == "false" ]]; then
       # use cached resources on Amazon S3
-      aws s3 cp s3://lineage-resources/resources.tar.gz resources.tar.gz
+      aws s3 cp s3://snps-resources/resources.tar.gz resources.tar.gz
       if [[ -f resources.tar.gz ]]; then
         tar -xzf resources.tar.gz
         rm resources.tar.gz

CONTRIBUTING.rst

@@ -17,7 +17,8 @@ Documentation improvements
 --------------------------
 
 ``snps`` could always use more documentation, whether as part of the official ``snps``
-docs, in docstrings, or even on the web in blog posts, articles, and such.
+docs, in docstrings, or even on the web in blog posts, articles, and such. See below for
+info on how to generate documentation.
 
 Feature requests and feedback
 -----------------------------
@@ -54,13 +55,17 @@ To set up ``snps`` for local development:
 
     pipenv run pytest --cov=snps tests
 
-6. Commit your changes and push your branch to GitHub::
+6. Check code formatting::
+
+    black --check --diff .
+
+7. Commit your changes and push your branch to GitHub::
 
     git add .
     git commit -m "Your detailed description of your changes."
     git push origin name-of-your-bugfix-or-feature
 
-7. Submit a pull request through the GitHub website.
+8. Submit a pull request through the GitHub website.
 
 Pull request guidelines
 ```````````````````````
@@ -73,3 +78,12 @@ For merging, you should:
 1. Ensure tests pass.
 2. Update documentation when there's new API, functionality, etc.
 3. Add yourself to ``CONTRIBUTORS.rst``.
+
+Documentation
+-------------
+After the development environment has been setup, documentation can be generated via the
+following command::
+
+    sphinx-build -T -E -D language=en docs docs/_build
+
+Then, the documentation can be viewed by opening ``docs/_build/index.html`` in a browser.

README.rst

@@ -51,7 +51,7 @@ First, let's setup logging to get some helpful output:
 
 >>> import logging, sys
 >>> logger = logging.getLogger()
->>> logger.setLevel(logging.DEBUG)
+>>> logger.setLevel(logging.INFO)
 >>> logger.addHandler(logging.StreamHandler(sys.stdout))
 
 Now we're ready to download some example data from `openSNP <https://opensnp.org>`_:

src/snps/__init__.py

@@ -629,7 +629,7 @@ def remap_snps(self, target_assembly, complement_bases=True):
         snps = self.snps
 
         if snps.empty:
-            logger.debug("No SNPs to remap")
+            logger.warning("No SNPs to remap")
             return chromosomes_remapped, chromosomes_not_remapped
         else:
             chromosomes = snps["chrom"].unique()
@@ -638,7 +638,7 @@ def remap_snps(self, target_assembly, complement_bases=True):
         valid_assemblies = ["NCBI36", "GRCh37", "GRCh38", 36, 37, 38]
 
         if target_assembly not in valid_assemblies:
-            logger.debug("Invalid target assembly")
+            logger.warning("Invalid target assembly")
             return chromosomes_remapped, chromosomes_not_remapped
 
         if isinstance(target_assembly, int):
@@ -677,7 +677,7 @@ def remap_snps(self, target_assembly, complement_bases=True):
                     }
                 )
             else:
-                logger.debug(
+                logger.warning(
                     "Chromosome {} not remapped; "
                     "removing chromosome from SNPs for consistency".format(chrom)
                 )
@@ -734,11 +734,11 @@ def _remapper(self, task):
             mapped_region = mapping["mapped"]["seq_region_name"]
 
             if orig_region != mapped_region:
-                logger.debug("discrepant chroms")
+                logger.warning("discrepant chroms")
                 continue
 
             if orig_range_len != mapped_range_len:
-                logger.debug(
+                logger.warning(
                     "discrepant coords"
                 )  # observed when mapping NCBI36 -> GRCh38
                 continue
@@ -922,7 +922,7 @@ def _load_snps_helper(
         discrepant_genotypes_threshold,
         save_output,
     ):
-        logger.debug("Loading " + os.path.relpath(file))
+        logger.info("Loading {}".format(os.path.relpath(file)))
         discrepant_positions, discrepant_genotypes = self._add_snps(
             SNPs(file),
             discrepant_snp_positions_threshold,
@@ -937,7 +937,7 @@ def _load_snps_helper(
             discrepant_genotypes, sort=True
         )
 
-    def save_snps(self, filename="", vcf=False):
+    def save_snps(self, filename="", vcf=False, atomic=True, **kwargs):
         """ Save SNPs to file.
 
         Parameters
@@ -946,6 +946,10 @@ def save_snps(self, filename="", vcf=False):
             filename for file to save
         vcf : bool
             flag to save file as VCF
+        atomic : bool
+            atomically write output to a file on local filesystem
+        **kwargs
+            additional parameters to `pandas.DataFrame.to_csv`
 
         Returns
         -------
@@ -964,7 +968,7 @@ def save_snps(self, filename="", vcf=False):
                 ext = ".csv"
 
             filename = "{}{}{}".format(prefix, self.assembly, ext)
-        return super().save_snps(filename=filename, vcf=vcf)
+        return super().save_snps(filename=filename, vcf=vcf, atomic=atomic, **kwargs)
 
     def save_discrepant_positions(self, filename=""):
         """ Save SNPs with discrepant positions to file.
@@ -1068,12 +1072,12 @@ def _add_snps(
         source = [s.strip() for s in snps._source.split(",")]
 
         if not snps._build_detected:
-            logger.debug("build not detected, assuming build {}".format(snps._build))
+            logger.warning("build not detected, assuming build {}".format(snps._build))
 
         if not self._build:
             self._build = build
         elif self._build != build:
-            logger.debug(
+            logger.warning(
                 "build / assembly mismatch between current build of SNPs and SNPs being loaded"
             )
 
@@ -1097,7 +1101,7 @@ def _add_snps(
                 prefix = "{}_".format(clean_str(self._name))
 
             if 0 < len(discrepant_positions) < discrepant_snp_positions_threshold:
-                logger.debug(
+                logger.warning(
                     "{} SNP positions were discrepant; keeping original positions".format(
                         str(len(discrepant_positions))
                     )
@@ -1113,7 +1117,7 @@ def _add_snps(
                         ),
                     )
             elif len(discrepant_positions) >= discrepant_snp_positions_threshold:
-                logger.debug(
+                logger.warning(
                     "too many SNPs differ in position; ensure same genome build is being used"
                 )
                 return discrepant_positions, discrepant_genotypes
@@ -1162,7 +1166,7 @@ def _add_snps(
             ]
 
             if 0 < len(discrepant_genotypes) < discrepant_genotypes_threshold:
-                logger.debug(
+                logger.warning(
                     "{} SNP genotypes were discrepant; marking those as null".format(
                         str(len(discrepant_genotypes))
                     )
@@ -1178,7 +1182,7 @@ def _add_snps(
                         ),
                     )
             elif len(discrepant_genotypes) >= discrepant_genotypes_threshold:
-                logger.debug(
+                logger.warning(
                     "too many SNPs differ in their genotype; ensure file is for same "
                     "individual"
                 )

src/snps/io.py

@@ -732,7 +732,7 @@ def _parse_vcf(self, buffer, rsids):
 
                 # snps does not yet support multi-sample vcf.
                 if len(line_split) > 10:
-                    logger.debug("Multiple samples detected in the vcf file")
+                    logger.info("Multiple samples detected in the vcf file")
 
                 ref = line_split[3]
                 alt = line_split[4]

src/snps/resources.py

@@ -135,7 +135,7 @@ def get_reference_sequences(
         valid_assemblies = ["NCBI36", "GRCh37", "GRCh38"]
 
         if assembly not in valid_assemblies:
-            logger.debug("Invalid assembly")
+            logger.warning("Invalid assembly")
             return {}
 
         if not self._reference_chroms_available(assembly, chroms):
@@ -476,7 +476,7 @@ def _get_path_assembly_mapping_data(
         if not os.path.exists(destination) or not self._all_chroms_in_tar(
             chroms, destination
         ):
-            logger.debug("Downloading {}".format(os.path.relpath(destination)))
+            logger.info("Downloading {}".format(os.path.relpath(destination)))
 
             try:
                 self._download_assembly_mapping_data(
@@ -642,7 +642,7 @@ def _print_download_msg(path):
         path : str
             path to file being downloaded
         """
-        logger.debug("Downloading " + os.path.relpath(path))
+        logger.info("Downloading {}".format(os.path.relpath(path)))
 
 
 class ReferenceSequence:

src/snps/utils.py

@@ -163,7 +163,7 @@ def save_df_as_csv(
                 destination = filename
             else:
                 destination = os.path.join(path, filename)
-                logger.debug("Saving " + os.path.relpath(destination))
+                logger.info("Saving {}".format(os.path.relpath(destination)))
 
             if prepend_info:
                 s = (
@@ -200,7 +200,7 @@ def save_df_as_csv(
             logger.warning(err)
             return ""
     else:
-        logger.debug("no data to save...")
+        logger.warning("no data to save...")
         return ""