update XML comments for feature extractor options

ar1st0crat · Oct 6, 2021 · 8d79e2c · 8d79e2c
1 parent 16d54cc
commit 8d79e2c
Show file tree

Hide file tree

Showing 13 changed files with 292 additions and 5 deletions.
diff --git a/NWaves/FeatureExtractors/Options/AmsOptions.cs b/NWaves/FeatureExtractors/Options/AmsOptions.cs
@@ -3,6 +3,25 @@
 
 namespace NWaves.FeatureExtractors.Options
 {
+    /// <summary>
+    /// Defines properties for configuring <see cref="AmsExtractor"/>. 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>FrameDuration = 0.025</item>
+    ///     <item>HopDuration = 0.01</item>
+    ///     <item>Window = WindowType.Rectangular</item>
+    ///     <item>ModulationFftSize = 64</item>
+    ///     <item>ModulationHopSize = 4</item>
+    /// </list>
+    /// </para>
+    /// </summary>
     [DataContract]
     public class AmsOptions : FeatureExtractorOptions
     {

diff --git a/NWaves/FeatureExtractors/Options/ChromaOptions.cs b/NWaves/FeatureExtractors/Options/ChromaOptions.cs
@@ -4,6 +4,34 @@
 
 namespace NWaves.FeatureExtractors.Options
 {
+    /// <summary>
+    /// Defines properties for configuring <see cref="ChromaExtractor"/>. 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// Specific contracts are:
+    /// <list type="bullet">
+    ///     <item>Number of chroma coefficients must be positive</item>
+    ///     <item>Norm must be positive</item>
+    ///     <item>Octave width must be positive</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>FrameDuration = 0.025</item>
+    ///     <item>HopDuration = 0.01</item>
+    ///     <item>FeatureCount = 12</item>
+    ///     <item>Window = WindowType.Hann</item>
+    ///     <item>OctaveWidth = 2</item>
+    ///     <item>CenterOctave = 5.0</item>
+    ///     <item>Norm = 2</item>
+    ///     <item>BaseC = true</item>
+    /// </list>
+    /// </para>
+    /// </summary>
     [DataContract]
     public class ChromaOptions : FeatureExtractorOptions
     {

diff --git a/NWaves/FeatureExtractors/Options/FeatureExtractorOptions.cs b/NWaves/FeatureExtractors/Options/FeatureExtractorOptions.cs
@@ -5,7 +5,21 @@
 namespace NWaves.FeatureExtractors.Options
 {
     /// <summary>
-    /// Defines basic properties for configuring feature extractors.
+    /// Defines basic properties for configuring feature extractors. 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>FrameDuration = 0.025</item>
+    ///     <item>HopDuration = 0.01</item>
+    ///     <item>Window = WindowType.Rectangular</item>
+    /// </list>
+    /// </para>
     /// </summary>
     [DataContract]
     public class FeatureExtractorOptions

diff --git a/NWaves/FeatureExtractors/Options/FilterbankOptions.cs b/NWaves/FeatureExtractors/Options/FilterbankOptions.cs
@@ -4,6 +4,33 @@
 
 namespace NWaves.FeatureExtractors.Options
 {
+    /// <summary>
+    /// Defines properties for configuring filterbank-based extractors (including MFCC, PLP, etc.). 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// Specific contracts are:
+    /// <list type="bullet">
+    ///     <item>Filter bank size must be positive number or the entire filter bank must be specified (not null)</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>FrameDuration = 0.025</item>
+    ///     <item>HopDuration = 0.01</item>
+    ///     <item>Window = WindowType.Hamming</item>
+    ///     <item>FilterbankSize = 12 (acts as FeatureCount)</item>
+    ///     <item>LowFrequency = 0</item>
+    ///     <item>HighFrequency = 0 (i.e. it will be auto-computed as SamplingRate/2)</item>
+    ///     <item>NonLinearity = NonLineriatyType.None</item>
+    ///     <item>SpectrumType = SpectrumType.Power</item>
+    ///     <item>LogFloor = 1.4e-45 (float epsilon)</item>
+    /// </list>
+    /// </para>
+    /// </summary>
     [DataContract]
     public class FilterbankOptions : FeatureExtractorOptions
     {

diff --git a/NWaves/FeatureExtractors/Options/LpcOptions.cs b/NWaves/FeatureExtractors/Options/LpcOptions.cs
@@ -3,13 +3,35 @@
 
 namespace NWaves.FeatureExtractors.Options
 {
+    /// <summary>
+    /// Defines properties for configuring <see cref="LpcExtractor"/>. 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// Specific contracts are:
+    /// <list type="bullet">
+    ///     <item>LPC order must be positive mumber</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>FrameDuration = 0.025</item>
+    ///     <item>HopDuration = 0.01</item>
+    ///     <item>FeatureCount = LPC order + 1 (auto-computed)</item>
+    ///     <item>Window = WindowType.Rectangular</item>
+    /// </list>
+    /// </para>
+    /// </summary>
     [DataContract]
     public class LpcOptions : FeatureExtractorOptions
     {
         /// <summary>
         /// Gets or sets order of LPC. 
         /// This property is required. It has priority over FeatureCount. 
-        /// FeatureCount will be autocomputed as LpcOrder + 1.
+        /// FeatureCount will be autocomputed by <see cref="LpcExtractor"/> as LpcOrder+1.
         /// </summary>
         [DataMember]
         public int LpcOrder { get; set; }

diff --git a/NWaves/FeatureExtractors/Options/LpccOptions.cs b/NWaves/FeatureExtractors/Options/LpccOptions.cs
@@ -3,6 +3,29 @@
 
 namespace NWaves.FeatureExtractors.Options
 {
+    /// <summary>
+    /// Defines properties for configuring <see cref="LpccExtractor"/>. 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// Specific contracts are:
+    /// <list type="bullet">
+    ///     <item>FeatureCount must be positive mumber</item>
+    ///     <item>LPC order must be positive mumber (usually, FeatureCount-1)</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>FrameDuration = 0.025</item>
+    ///     <item>HopDuration = 0.01</item>
+    ///     <item>Window = WindowType.Rectangular</item>
+    ///     <item>LifterSize = 22</item>
+    /// </list>
+    /// </para>
+    /// </summary>
     [DataContract]
     public class LpccOptions : LpcOptions
     {

diff --git a/NWaves/FeatureExtractors/Options/MfccOptions.cs b/NWaves/FeatureExtractors/Options/MfccOptions.cs
@@ -4,6 +4,39 @@
 
 namespace NWaves.FeatureExtractors.Options
 {
+    /// <summary>
+    /// Defines properties for configuring <see cref="MfccExtractor"/>. 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// Specific contracts are:
+    /// <list type="bullet">
+    ///     <item>FeatureCount must be positive mumber</item>
+    ///     <item>DCT type must have one of these values: "1", "2", "3", "4", "1N", "2N", "3N", "4N"</item>
+    ///     <item>Filter bank size must be positive number or the entire filter bank must be specified (not null)</item>
+    ///     <item>FeatureCount must not exceed filterbank size</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>FrameDuration = 0.025</item>
+    ///     <item>HopDuration = 0.01</item>
+    ///     <item>Window = WindowType.Hamming</item>
+    ///     <item>FilterbankSize = 24</item>
+    ///     <item>LowFrequency = 0</item>
+    ///     <item>HighFrequency = 0 (i.e. it will be auto-computed as SamplingRate/2)</item>
+    ///     <item>DctType = "2N"</item>
+    ///     <item>NonLinearity = NonLineriatyType.Log10</item>
+    ///     <item>SpectrumType = SpectrumType.Power</item>
+    ///     <item>LifterSize = 0 (no liftering)</item>
+    ///     <item>LogFloor = 1.4e-45 (float epsilon)</item>
+    ///     <item>LogEnergyFloor = 1.4e-45 (float epsilon)</item>
+    /// </list>
+    /// </para>
+    /// </summary>
     [DataContract]
     public class MfccOptions : FilterbankOptions
     {

diff --git a/NWaves/FeatureExtractors/Options/MultiFeatureOptions.cs b/NWaves/FeatureExtractors/Options/MultiFeatureOptions.cs
@@ -3,6 +3,24 @@
 
 namespace NWaves.FeatureExtractors.Options
 {
+    /// <summary>
+    /// Defines properties for configuring multi-feature extractors. 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>FrameDuration = 0.025</item>
+    ///     <item>HopDuration = 0.01</item>
+    ///     <item>Window = WindowType.Rectangular</item>
+    ///     <item>FeatureList = "all"</item>
+    /// </list>
+    /// </para>
+    /// </summary>
     [DataContract]
     public class MultiFeatureOptions : FeatureExtractorOptions
     {

diff --git a/NWaves/FeatureExtractors/Options/PitchOptions.cs b/NWaves/FeatureExtractors/Options/PitchOptions.cs
@@ -3,6 +3,26 @@
 
 namespace NWaves.FeatureExtractors.Options
 {
+    /// <summary>
+    /// Defines properties for configuring <see cref="PitchExtractor"/>. 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// Specific contracts are:
+    /// <list type="bullet">
+    ///     <item>HighFrequency must be greater than LowFrequency</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>LowFrequency = 80 (Hz)</item>
+    ///     <item>HighFrequency = 400 (Hz)</item>
+    /// </list>
+    /// </para>
+    /// </summary>
     [DataContract]
     public class PitchOptions : FeatureExtractorOptions
     {

diff --git a/NWaves/FeatureExtractors/Options/PlpOptions.cs b/NWaves/FeatureExtractors/Options/PlpOptions.cs
@@ -4,6 +4,38 @@
 
 namespace NWaves.FeatureExtractors.Options
 {
+    /// <summary>
+    /// Defines properties for configuring <see cref="PlpExtractor"/>. 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// Specific contracts are:
+    /// <list type="bullet">
+    ///     <item>FeatureCount must be positive mumber</item>
+    ///     <item>Filter bank size must be positive number or the entire filter bank must be specified (not null)</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>FrameDuration = 0.025</item>
+    ///     <item>HopDuration = 0.01</item>
+    ///     <item>Window = WindowType.Hamming</item>
+    ///     <item>FilterbankSize = 24</item>
+    ///     <item>LowFrequency = 0</item>
+    ///     <item>HighFrequency = 0 (i.e. it will be auto-computed as SamplingRate/2)</item>
+    ///     <item>LpcOrder = 0 (i.e. it will be autocomputed as FeatureCount-1)</item>
+    ///     <item>NonLinearity = NonLineriatyType.Log10</item>
+    ///     <item>SpectrumType = SpectrumType.Power</item>
+    ///     <item>LifterSize = 0 (no liftering)</item>
+    ///     <item>Rasta = 0 (no RASTA-filtering)</item>
+    ///     <item>LogFloor = 1.4e-45 (float epsilon)</item>
+    ///     <item>LogEnergyFloor = 1.4e-45 (float epsilon)</item>
+    /// </list>
+    /// </para>
+    /// </summary>
     [DataContract]
     public class PlpOptions : FilterbankOptions
     {

diff --git a/NWaves/FeatureExtractors/Options/PnccOptions.cs b/NWaves/FeatureExtractors/Options/PnccOptions.cs
@@ -4,6 +4,36 @@
 
 namespace NWaves.FeatureExtractors.Options
 {
+    /// <summary>
+    /// Defines properties for configuring <see cref="PnccExtractor"/>. 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// Specific contracts are:
+    /// <list type="bullet">
+    ///     <item>FeatureCount must be positive mumber</item>
+    ///     <item>Filter bank size must be positive number or the entire filter bank must be specified (not null)</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>FrameDuration = 0.025</item>
+    ///     <item>HopDuration = 0.01</item>
+    ///     <item>Window = WindowType.Hamming</item>
+    ///     <item>FilterbankSize = 40</item>
+    ///     <item>LowFrequency = 100</item>
+    ///     <item>HighFrequency = 6800</item>
+    ///     <item>Power = 15</item>
+    ///     <item>SpectrumType = SpectrumType.Power</item>
+    ///     <item>LifterSize = 0 (no liftering)</item>
+    ///     <item>LogFloor = 1.4e-45 (float epsilon)</item>
+    ///     <item>LogEnergyFloor = 1.4e-45 (float epsilon)</item>
+    /// </list>
+    /// </para>
+    /// </summary>
     [DataContract]
     public class PnccOptions : FilterbankOptions
     {

diff --git a/NWaves/FeatureExtractors/Options/WaveletOptions.cs b/NWaves/FeatureExtractors/Options/WaveletOptions.cs
@@ -2,6 +2,24 @@
 
 namespace NWaves.FeatureExtractors.Options
 {
+    /// <summary>
+    /// Defines properties for configuring <see cref="WaveletExtractor"/>. 
+    /// General contracts are:
+    /// <list type="bullet">
+    ///     <item>Sampling rate must be positive number</item>
+    ///     <item>Frame duration must be positive number</item>
+    ///     <item>Hop duration must be positive number</item>
+    /// </list>
+    /// <para>
+    /// Default values:
+    /// <list type="bullet">
+    ///     <item>FrameDuration = 0.025</item>
+    ///     <item>HopDuration = 0.01</item>
+    ///     <item>Window = WindowType.Rectangular</item>
+    ///     <item>WaveletName = "haar"</item>
+    /// </list>
+    /// </para>
+    /// </summary>
     [DataContract]
     public class WaveletOptions : FeatureExtractorOptions
     {