updating docs

docs/changes.rst

@@ -3,6 +3,10 @@
 Changelog
 ---------
 
+v1.2.0
+~~~~~~
+- Added a random_state parameter to Scaper, which allows all runs to be perfectly reproducible given the same audio and the same random seed.
+
 v1.1.0
 ~~~~~~
 - Added functionality which modifies a source_time distribution tuple according to the duration of the source and the duration of the event.

docs/conf.py

@@ -40,7 +40,7 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
-    'numpydoc',
+    'sphinx.ext.napoleon',
     'sphinx_issues'
 ]
 

docs/examples.rst

@@ -12,6 +12,11 @@ Example: synthesizing 1000 soundscapes in one go
     # OUTPUT FOLDER
     outfolder = 'audio/soundscapes/'
 
+    # SEED INITIAL RANDOM STATE (OPTIONAL)
+    np.random.seed(0)  
+    
+    
+
     # SCAPER SETTINGS
     fg_folder = 'audio/soundbank/foreground/'
     bg_folder = 'audio/soundbank/background/'
@@ -53,9 +58,22 @@ Example: synthesizing 1000 soundscapes in one go
     for n in range(n_soundscapes):
 
         print('Generating soundscape: {:d}/{:d}'.format(n+1, n_soundscapes))
+        # generate a random seed for this Scaper object
+        # because of the earlier seed these will always be the same and are given to the
+        # Scaper object for reproducible results.
+
+        seed = np.random.randint(0, 100000)
+
+        ## alternate ways to define random state:
+        #     seed = np.random.RandomState(0)
+        #
+        # or don't define any random state. runs will be random and not reproducible in 
+        # this case. you can use np.random.get_state() to reproduce the run after the fact
+        # if needed:
+        #     seed = None
 
         # create a scaper
-        sc = scaper.Scaper(duration, fg_folder, bg_folder)
+        sc = scaper.Scaper(duration, fg_folder, bg_folder, random_state=seed)
         sc.protected_labels = []
         sc.ref_db = ref_db
 

docs/tutorial.rst

@@ -100,6 +100,31 @@ when we add foreground events, we'll have to specify an ``snr``
 be louder (or softer) with respect to the background level specified by
 ``sc.ref_db``.
 
+Seeding the Scaper generator for reproducibility
+------------------------------------------------
+
+A further argument can be specified to the ``Scaper`` object:
+
+- The random state: this can be either a numpy.random.RandomState object or an integer.
+  In the latter case, a random state will be constructed. The random state is what will 
+  be used for drawing from any distributions. If the audio kept in all of the folders is
+  exactly the same and the random state is fixed between runs, the same dataset will be 
+  generated both times.
+
+This can be specified like so (e.g. for a random seed of 0):
+
+.. code-block:: python
+
+    import scaper
+    import os
+    soundscape_duration = 10.0
+    seed = 0 
+    foreground_folder = os.path.expanduser('~/audio/foreground/')
+    background_folder = os.path.expanduser('~/audio/background/')
+    sc = scaper.Scaper(soundscape_duration, foreground_folder, background_folder, 
+                       random_state=seed)
+    sc.ref_db = -20
+
 Adding a background and foreground sound events
 -----------------------------------------------
 

scaper/core.py

@@ -828,52 +828,24 @@ class Scaper(object):
         Path to foreground folder.
     bg_path : str
         Path to background folder.
-    protected_labels : list
+    protected_labels : list 
         Provide a list of protected foreground labels. When a foreground
         label is in the protected list it means that when a sound event
         matching the label gets added to a soundscape instantiation the
         duration of the source audio file cannot be altered, and the
         duration value that was provided in the specification will be
-        ignored.
-
-        Adding labels to the protected list is useful for sound events
+        ignored. Adding labels to the protected list is useful for sound events
         whose semantic validity would be lost if the sound were trimmed
         before the sound event ends, for example an animal vocalization
         such as a dog bark.
-
+    random_state : int, RandomState instance or None, optional (default=None)
+        If int, random_state is the seed used by the random number 
+        generator; If RandomState instance, random_state is the random number 
+        generator; If None, the random number generator is the RandomState 
+        instance used by np.random.
     '''
 
     def __init__(self, duration, fg_path, bg_path, protected_labels=[], random_state=None):
-        '''
-        Create a Scaper object.
-
-        Parameters
-        ----------
-        duration : float
-            Duration of the soundscape, in seconds.
-        fg_path : str
-            Path to foreground folder.
-        bg_path : str
-            Path to background folder.
-        protected_labels : list
-            Provide a list of protected foreground labels. When a foreground
-            label is in the protected list it means that when a sound event
-            matching the label gets added to a soundscape instantiation the
-            duration of the source audio file cannot be altered, and the
-            duration value that was provided in the specification will be
-            ignored.
-
-            Adding labels to the protected list is useful for sound events
-            whose semantic validity would be lost if the sound were trimmed
-            before the sound event ends, for example an animal vocalization
-            such as a dog bark.
-        random_state : int, RandomState instance or None, optional (default=None)
-            If int, random_state is the seed used by the random number 
-            generator; If RandomState instance, random_state is the random number 
-            generator; If None, the random number generator is the RandomState 
-            instance used by np.random.
-
-        '''
         # Duration must be a positive real number
         if np.isrealobj(duration) and duration > 0:
             self.duration = duration

scaper/version.py

@@ -2,5 +2,5 @@
 # -*- coding: utf-8 -*-
 """Version info"""
 
-short_version = '1.1'
-version = '1.1.0'
+short_version = '1.2'
+version = '1.2.0'

setup.py

@@ -42,10 +42,9 @@
     ],
     extras_require={
         'docs': [
-                'sphinx==1.2.3',  # autodoc was broken in 1.3.1
-                'sphinxcontrib-napoleon',
+                'sphinx',  # autodoc was broken in 1.3.1
                 'sphinx_rtd_theme',
-                'numpydoc',
+                'sphinx_issues',
             ],
         'tests': ['backports.tempfile', 'pysoundfile']
     }