Made in-script documentation more readable

audio.py

@@ -33,14 +33,18 @@ _SCALING_FACTORS = pd.Series(
 def midi_to_notes(midi_file: str) -> pd.DataFrame:
   """
   Convert midi file to "song map" (dataframe where each note is broken
-  into its components)
+  into its components).
 
-  Parameters:
-  midi_file (str): Path to the midi file.
+  Parameters
+  ----------
+  
+  midi_file : str
+      Path to the midi file.
 
-  Returns:
-  pd.Dataframe: 3xN matrix where each column is a note, composed of
-  pitch, duration and step.
+  Returns
+  -------
+  song_map : pd.Dataframe
+      3xN matrix where each column is a note, composed of pitch, duration and step.
   """
     
   pm = pretty_midi.PrettyMIDI(midi_file)
@@ -64,7 +68,8 @@ def midi_to_notes(midi_file: str) -> pd.DataFrame:
   # Put notes in a dataframe
   notes_df = pd.DataFrame({name: np.array(value) for name, value in notes.items()})
   notes_df = notes_df[:_CAP] # Cap the song to match the model's architecture
-  return notes_df / _SCALING_FACTORS # Scale
+  song_map = notes_df / _SCALING_FACTORS # Scale
+  return song_map
 
 
 def display_audio(pm: pretty_midi.PrettyMIDI, seconds=-1) -> display.Audio:
@@ -72,13 +77,19 @@ def display_audio(pm: pretty_midi.PrettyMIDI, seconds=-1) -> display.Audio:
   Display a song in PrettyMIDI format as a display.Audio object.
   This method specially comes in useful in a jupyter notebook.
 
-  Parameters:
-  pm (str): PrettyMidi object containing a song.
-  seconds (int): Time fraction of the song to be displayed. When
-                 set to -1, the full length is taken.
-
-  Returns:
-  display.Audio: Song as an object allowing for display.
+  Parameters
+  ----------
+  
+  pm : str
+      PrettyMidi object containing a song.
+  seconds : int
+      Time fraction of the song to be displayed.
+      Default ``-1``, for which the full length is taken.
+
+  Returns
+  -------
+  display_obj : display.Audio
+      Song as an object allowing for display.
   """
     
   waveform = pm.fluidsynth(fs=_SAMPLING_RATE)
@@ -88,7 +99,9 @@ def display_audio(pm: pretty_midi.PrettyMIDI, seconds=-1) -> display.Audio:
   else:
       waveform_short = waveform[:seconds*_SAMPLING_RATE]
   
-  return display.Audio(waveform_short, rate=_SAMPLING_RATE)
+  display_obj = display.Audio(waveform_short, rate=_SAMPLING_RATE)
+    
+  return display_obj
     
 
 def map_to_wav(song_map: pd.DataFrame, out_file: str, velocity: int=50) -> pretty_midi.PrettyMIDI:
@@ -96,14 +109,22 @@ def map_to_wav(song_map: pd.DataFrame, out_file: str, velocity: int=50) -> prett
   Convert "song map" to midi file (reverse process with respect to 
   midi_to_notes) and (optionally) save it, generating a PrettyMidi object in the process.
 
-  Parameters:
-  song_map (pd.DataFrame): 3xN matrix where each column is a note, composed of
-  pitch, duration and step.
-  out_file (str): Path or file to write .mid file to. If None, no saving is done.
-  velocity: Note loudness, i. e. the hardness a piano key is struck with.
-
-  Returns:
-  pretty_midi.PrettyMIDI: PrettyMIDI object containing the song's representation.
+  Parameters
+  ----------
+  
+  song_map : pd.DataFrame
+      3xN matrix where each column is a note, composed of pitch, duration and step.
+  out_file : str
+      Path or file to write .mid file to. If None, no saving is done.
+  velocity : int
+      Note loudness, i. e. the hardness a piano key is struck with.
+      Default ``50``.
+
+  Returns
+  -------
+  
+  pm : pretty_midi.PrettyMIDI
+      PrettyMIDI object containing the song's representation.
   """
 
   # Get song map as dataframe
@@ -151,20 +172,31 @@ def generate_and_display(model: VAE,
   """
   Generate a song, (optionally) save it and display it.
 
-  Parameters:
-  model (VAE): Instance of VAE to generate the song with.
-  out_file (str): Path or file to write .mid file to. If None, no saving is done.
-  z_sample (tf.Tensor): Song encoding used to generate a song. If None, perform
-                        generate an unconditioned piece.
-  velocity: Note loudness, i. e. the hardness a piano key is struck with.
-  seconds (int): Time fraction of the song to be displayed. When
-                 set to -1, the full length is taken.
-
-  Returns:
-  display.Audio: Song as an object allowing for display.
+  Parameters
+  ----------
+  model : VAE
+      Instance of VAE to generate the song with.
+  out_file : str
+      Path or file to write .mid file to.
+      Default ``None``, for which no saving is done.
+  z_sample : tf.Tensor 
+      Song encoding used to generate a song.
+      Default ``None``, for which an unconditioned piece is generated.
+  velocity : int
+      Note loudness, i. e. the hardness a piano key is struck with.
+      Default ``50``.
+  seconds : int
+      Time fraction of the song to be displayed.
+      Default ``-1``, for which the full length is taken.
+
+  Returns
+  -------
+  display_obj : display.Audio
+      Song as an object allowing for display.
   """
     
   song_map = model.generate(z_sample)
   wav = map_to_wav(song_map, out_file, velocity)
-
-  return display_audio(wav, seconds)
+  display_obj = display_audio(wav, seconds)
+                             
+  return display_obj