Merge pull request #713 from mcveanlab/undocument-genetic-map

Remove genetic_map from public API.

docs/api.rst

@@ -29,9 +29,6 @@ accessed through the main entry point, :func:`.get_species`.
 .. autoclass:: stdpopsim.Contig()
     :members:
 
-.. autoclass:: stdpopsim.GeneticMap()
-    :members:
-
 .. autoclass:: stdpopsim.Citation()
     :members:
 

stdpopsim/genetic_maps.py

@@ -14,10 +14,13 @@ class GeneticMap:
     Class representing a genetic map for a species. Provides functionality for
     downloading and cacheing recombination maps from a remote URL.
 
-    .. todo: Document the attributes in this class
+    .. note: This interface is internal, preliminary and should not be used by
+        external code.
 
     :ivar url: The URL where the packed and compressed genetic map can be obtained.
     :vartype url: str
+    :ivar file_pattern: The pattern used to map individual chromosome id strings
+        to files.
     """
 
     def __init__(
@@ -37,7 +40,7 @@ def __init__(
         self.long_description = long_description
         self.url = url
         self.sha256 = sha256
-        self._file_pattern = file_pattern
+        self.file_pattern = file_pattern
         self.description = description
         self.citations = citations
 
@@ -52,24 +55,11 @@ def __init__(
     def map_cache_dir(self):
         """
         The path to the directory in which the files for this map are stored.
-        Names for individual chromosome files within this directory can be obtained
-        using :attr:`file_pattern`.
 
         :type: pathlib.Path
         """
         return self._cache.cache_path
 
-    @property
-    def file_pattern(self):
-        """
-        The pattern used to map individual chromosome id strings to files. To obtain
-        the file names, you can use Python's :meth:`str.format` method, for example
-        ``my_map.file_pattern.format(id=my_chromosome_id_string)``.
-
-        :type: str
-        """
-        return self._file_pattern
-
     def __str__(self):
         s = "GeneticMap:\n"
         s += "\tspecies   = {}\n".format(self.species.name)

stdpopsim/species.py

@@ -310,16 +310,16 @@ def add_genetic_map(self, genetic_map):
         self.genetic_maps.append(genetic_map)
 
     def get_genetic_map(self, id):
-        """
-        Returns a genetic map (AKA. recombination map) with the specified ``id``.
-
-        :param str id: The string identifier for the genetic map.
-            A complete list of IDs for each species can be found in the
-            "Genetic Maps" subsection for the species in the :ref:`sec_catalog`.
-        :rtype: :class:`GeneticMap`
-        :return: A :class:`GeneticMap` that defines the frequency of
-            recombinations across the genome.
-        """
+        # NOTE: Undocumenting this method as the GeneticMap API isn't part of the
+        # supported public interface.
+        #
+        # Returns a genetic map (AKA. recombination map) with the specified ``id``.
+        # :param str id: The string identifier for the genetic map.
+        #     A complete list of IDs for each species can be found in the
+        #     "Genetic Maps" subsection for the species in the :ref:`sec_catalog`.
+        # :rtype: :class:`GeneticMap`
+        # :return: A :class:`GeneticMap` that defines the frequency of
+        #     recombinations across the genome.
         for gm in self.genetic_maps:
             if gm.id == id:
                 return gm