Improves documentation

Author: Lucas-Mc

wfdb/io/record.py

@@ -1500,20 +1500,28 @@ def edf2mit(record_name, pn_dir=None, delete_file=True, record_only=False):
 
 def wav2mit(record_name, pn_dir=None, delete_file=True, record_only=False):
     """
-    Convert WAV formatted files to MIT format. See here for more details about
-    the formatting of a WAV file: http://soundfile.sapp.org/doc/WaveFormat/.
+    Convert .wav (format 16, multiplexed signals, with embedded header
+    information) formatted files to MIT format. See here for more details about
+    the formatting of a .wav file: http://soundfile.sapp.org/doc/WaveFormat/.
+
+    This process may not work with some .wav files that are encoded using
+    variants of the original .wav format that are not WFDB-compatible. In
+    principle, this program should be able to recognize such files by their
+    format codes, and it will produce an error message in such cases. If
+    the format code is incorrect, however, `wav2mit` may not recognize that
+    an error has occurred.
 
     Parameters
     ----------
     record_name : str
-        The name of the input WAV record to be read.
+        The name of the input .wav record to be read.
     pn_dir : str, optional
         Option used to stream data from Physionet. The Physionet
         database directory from which to find the required record files.
         eg. For record '100' in 'http://physionet.org/content/mitdb'
         pn_dir='mitdb'.
     delete_file : bool, optional
-        Whether to delete the saved WAV file (False) or not (True)
+        Whether to delete the saved .wav file (False) or not (True)
         after being imported.
     record_only : bool, optional
         Whether to only return the record information (True) or not (False).
@@ -1527,6 +1535,44 @@ def wav2mit(record_name, pn_dir=None, delete_file=True, record_only=False):
         corresponding .dat and .hea files. This record file will not match the
         `rdrecord` output since it will only give us the digital signal for now.
 
+    Notes
+    -----
+    Files that can be processed successfully using `wav2mit` always have exactly
+    three chunks (a header chunk, a format chunk, and a data chunk).  In .wav
+    files, binary data are always written in little-endian format (least
+    significant byte first). The format of `wav2mit`'s input files is as follows:
+
+    [Header chunk]
+    Bytes  0 -  3: "RIFF" [4 ASCII characters]
+    Bytes  4 -  7: L-8 (number of bytes to follow in the file, excluding bytes 0-7)
+    Bytes  8 - 11: "WAVE" [4 ASCII characters]
+
+    [Format chunk]
+    Bytes 12 - 15: "fmt " [4 ASCII characters, note trailing space]
+    Bytes 16 - 19: 16 (format chunk length in bytes, excluding bytes 12-19)
+    Bytes 20 - 35: format specification, consisting of:
+    Bytes 20 - 21: 1 (format tag, indicating no compression is used)
+    Bytes 22 - 23: number of signals (1 - 65535)
+    Bytes 24 - 27: sampling frequency in Hz (per signal)
+                   Note that the sampling frequency in a .wav file must be an
+                   integer multiple of 1 Hz, a restriction that is not imposed
+                   by MIT (WFDB) format.
+    Bytes 28 - 31: bytes per second (sampling frequency * frame size in bytes)
+    Bytes 32 - 33: frame size in bytes
+    Bytes 34 - 35: bits per sample (ADC resolution in bits)
+                   Note that the actual ADC resolution (e.g., 12) is written in
+                   this field, although each output sample is right-padded to fill
+                   a full (16-bit) word. (.wav format allows for 8, 16, 24, and
+                   32 bits per sample)
+
+    [Data chunk]
+    Bytes 36 - 39: "data" [4 ASCII characters]
+    Bytes 40 - 43: L-44 (number of bytes to follow in the data chunk)
+    Bytes 44 - L-1: sample data, consisting of:
+    Bytes 44 - 45: sample 0, channel 0
+    Bytes 46 - 47: sample 0, channel 1
+    ... etc. (same order as in a multiplexed WFDB signal file)
+
     Examples
     --------
     >>> wav_record = wfdb.wav2mit('sample-data/SC4001E0-PSG.wav', record_only=True)