Time series samples and documentation alignment #2900

sfilipi · 2019-03-09T07:00:31Z

All overloads have method and parameter documentation according to XML template table below.
The returned estimator and its class hierarchy have documentation according to template table below.
The corresponding options class and its class hierarchy have documentation
All overloaded versions have samples
Sample names are <API_method>.cs or <API_method>WithOptions.cs.
Sample path mirrors the MLContext path. (e.g. MLContext.Transforms.Categorical.OneHotEncoding goes to Dynamic/Transforms/Categorical/OneHotEncoding.cs
Sample is included in the API xml documentation.

sfilipi · 2019-03-09T07:02:47Z

....Samples/Dynamic/Transforms/TimeSeries/DetectIndependentIdenticallyDistributedChangePoint.cs

@@ -111,7 +111,7 @@ public static void IidChangePointDetectorPrediction()
            string inputColumnName = nameof(IidChangePointData.Value);

            // Time Series model.
-            ITransformer model = ml.Transforms.IidChangePointEstimator(outputColumnName, inputColumnName, 95, Size / 4).Fit(dataView);
+            ITransformer model = ml.Transforms.DetectIndependentIdenticallyDistributedChangePoint(outputColumnName, inputColumnName, 95, Size / 4).Fit(dataView);


@CESARDELATORRE, @eerhardt, @TomFinley @shauheen how do you feel about those API names?

I would rather leave it to DetectIIDChangePoint, but abbreviations have been deemed cryptic. #Resolved

I would stick with IID, it is fairly well known abreviation. #Resolved

We have Lda, Pca, and so on. I feel Iid is not much worse than them. #Resolved

thanks for the input.

In reply to: 265343959 [](ancestors = 265343959)

codecov · 2019-03-09T07:46:34Z

Codecov Report

❗ No coverage uploaded for pull request base (master@9f87099). Click here to learn what that means.
The diff coverage is 100%.

@@            Coverage Diff            @@
##             master    #2900   +/-   ##
=========================================
  Coverage          ?   72.25%           
=========================================
  Files             ?      796           
  Lines             ?   142304           
  Branches          ?    16049           
=========================================
  Hits              ?   102828           
  Misses            ?    35099           
  Partials          ?     4377

Flag	Coverage Δ
#Debug	`72.25% <100%> (?)`
#production	`67.99% <100%> (?)`
#test	`88.4% <100%> (?)`

Impacted Files	Coverage Δ
.../Microsoft.ML.TimeSeries/IidChangePointDetector.cs	`69.82% <ø> (ø)`
.../Microsoft.ML.TimeSeries/SsaChangePointDetector.cs	`77.51% <ø> (ø)`
src/Microsoft.ML.TimeSeries/SsaSpikeDetector.cs	`82.9% <ø> (ø)`
src/Microsoft.ML.TimeSeries/IidSpikeDetector.cs	`72.54% <ø> (ø)`
src/Microsoft.ML.TimeSeries/ExtensionsCatalog.cs	`93.33% <ø> (ø)`
...osoft.ML.TimeSeries.Tests/TimeSeriesStaticTests.cs	`98.56% <100%> (ø)`
...osoft.ML.TimeSeries.StaticPipe/TimeSeriesStatic.cs	`100% <100%> (ø)`

ganik · 2019-03-11T23:12:13Z

src/Microsoft.ML.TimeSeries/ExtensionsCatalog.cs

            int confidence, int changeHistoryLength, MartingaleType martingale = MartingaleType.Power, double eps = 0.1)
            => new IidChangePointEstimator(CatalogUtils.GetEnvironment(catalog), outputColumnName, confidence, changeHistoryLength, inputColumnName, martingale, eps);

        /// <summary>
-        /// Create a new instance of <see cref="IidSpikeEstimator"/>
+        /// Create a new instance of <see cref="IidSpikeEstimator"/> that detects a spike in an indiependent identically distributed time series.


indiependent [](start = 96, length = 12)

typo #Resolved

ganik · 2019-03-11T23:12:26Z

src/Microsoft.ML.TimeSeries/ExtensionsCatalog.cs

@@ -10,7 +10,8 @@ namespace Microsoft.ML
    public static class TimeSeriesCatalog
    {
        /// <summary>
-        /// Create a new instance of <see cref="IidChangePointEstimator"/>
+        /// Create a new instance of <see cref="IidChangePointEstimator"/> that detects a change of in a indiependent identically distributed time series.


indiependent [](start = 105, length = 12)

same typo #Resolved

ganik · 2019-03-11T23:13:56Z

src/Microsoft.ML.TimeSeries/IidChangePointDetector.cs

@@ -192,16 +192,9 @@ private static IRowMapper Create(IHostEnvironment env, ModelLoadContext ctx, Dat
    }

    /// <summary>
-    /// Estimator for <see cref="IidChangePointDetector"/>
+    /// The <see cref="IEstimator{ITransformer}"/> for detecting a signal change on an Independent Identically Distributed time series.


IEstimator{ITransformer} [](start = 23, length = 24)

Why this changed? #Closed

We're standardizing the documentation across types, and i added a bit more info too.

In reply to: 264467232 [](ancestors = 264467232)

ganik

sfilipi · 2019-03-13T05:13:26Z

@shmoradims, @rogancarr @zeahmed when you get a chance. #Resolved

shmoradims · 2019-03-13T17:54:47Z

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/DetectIidChangePoint.cs

@@ -30,7 +30,7 @@ public IidChangePointData(float value)

        // This example creates a time series (list of Data with the i-th element corresponding to the i-th time slot). 
        // IidChangePointDetector is applied then to identify points where data distribution changed.


IidChangePointDetector [](start = 11, length = 22)

let's not put class names in the comments. This has already changed and is incorrect now. we can't catch these. #Closed

shmoradims · 2019-03-13T17:58:10Z

    public static void IidChangePointDetectorPrediction()

Is this another sample? Why do we have two samples in one file? #Resolved

Refers to: docs/samples/Microsoft.ML.Samples/Dynamic/IidChangePointDetectorTransform.cs:91 in e2487bf. [](commit_id = e2487bf, deletion_comment = False)

shmoradims · 2019-03-13T18:03:45Z

    public static void SsaChangePointDetectorPrediction()

ditto #Resolved

Refers to: docs/samples/Microsoft.ML.Samples/Dynamic/SsaChangePointDetectorTransform.cs:95 in e2487bf. [](commit_id = e2487bf, deletion_comment = False)

shmoradims · 2019-03-13T18:04:59Z

        // Setup IidSpikeDetector arguments

please remove all these class names. they're stale and compiler can't help us keeping it up-to-date. #Resolved

Refers to: docs/samples/Microsoft.ML.Samples/Dynamic/SsaSpikeDetectorTransform.cs:53 in e2487bf. [](commit_id = e2487bf, deletion_comment = False)

shmoradims · 2019-03-13T18:08:03Z

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/SsaDetectSpike.cs

@@ -55,7 +55,7 @@ public static void SsaSpikeDetectorTransform()
            var outputColumnName = nameof(SsaSpikePrediction.Prediction);

            // The transformed data.
-            var transformedData = ml.Transforms.SsaSpikeEstimator(outputColumnName, inputColumnName, 95, 8, TrainingSize, SeasonalitySize + 1).Fit(dataView).Transform(dataView);
+            var transformedData = ml.Transforms.SsaDetectSpike(outputColumnName, inputColumnName, 95, 8, TrainingSize, SeasonalitySize + 1).Fit(dataView).Transform(dataView);


SsaDetectSpike [](start = 48, length = 14)

Why not DetectSsaSpike instead? I think IID and SSA should be added to the name in the same way. right now we have DetectIidSpike and SsaDetectSpike. #Closed

i thought of that, but that doesn't make complete sense to me.

IID is the type of distribution.
SSA is a method.

Detect Independent Identically Distributed Spike/Change makes sense.

and

Singular Spectrum Analysis Detect Spike/Change makes sense but not Detect Singular Spectrum Analysis Spike

In reply to: 265263423 [](ancestors = 265263423)

Just a random idea and not a required change. How about DetectSpikeBySsa?

In reply to: 265345768 [](ancestors = 265345768,265263423)

I like that better, actually.

In reply to: 265386353 [](ancestors = 265386353,265345768,265263423)

shmoradims · 2019-03-13T18:10:22Z

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/SsaDetectChangePoint.cs

@@ -48,7 +54,7 @@ public static void SsaChangePointDetectorTransform()
            var outputColumnName = nameof(ChangePointPrediction.Prediction);

            // The transformed data.
-            var transformedData = ml.Transforms.SsaChangePointEstimator(outputColumnName, inputColumnName, 95, 8, TrainingSize, SeasonalitySize + 1).Fit(dataView).Transform(dataView);
+            var transformedData = ml.Transforms.SsaDetectChangePoint(outputColumnName, inputColumnName, 95, 8, TrainingSize, SeasonalitySize + 1).Fit(dataView).Transform(dataView);


SsaDetectChangePoint [](start = 48, length = 20)

ditto: DetectSsaChangePoint #Closed

shmoradims · 2019-03-13T18:12:59Z

src/Microsoft.ML.TimeSeries/ExtensionsCatalog.cs

@@ -10,7 +10,8 @@ namespace Microsoft.ML
    public static class TimeSeriesCatalog
    {
        /// <summary>
-        /// Create a new instance of <see cref="IidChangePointEstimator"/>
+        /// Create a new instance of <see cref="IidChangePointEstimator"/> that detects a change of in a independent identically distributed time series.


[](start = 140, length = 1)

add acronym (IID) here so that people know what IID is. #Closed

shmoradims · 2019-03-13T18:14:22Z

src/Microsoft.ML.TimeSeries/ExtensionsCatalog.cs

             int confidence, int pvalueHistoryLength, AnomalySide side = AnomalySide.TwoSided)
            => new IidSpikeEstimator(CatalogUtils.GetEnvironment(catalog), outputColumnName, confidence, pvalueHistoryLength, inputColumnName, side);

        /// <summary>
-        /// Create a new instance of <see cref="SsaChangePointEstimator"/>
+        /// Create a new instance of <see cref="SsaChangePointEstimator"/> for detecting a change in a time series signal using Singular Spectrum Analysis.


. [](start = 154, length = 1)

ditto: add (SSA) #Closed

shmoradims · 2019-03-13T18:27:13Z

src/Microsoft.ML.TimeSeries/SsaSpikeDetector.cs

@@ -26,8 +26,7 @@
 namespace Microsoft.ML.Transforms.TimeSeries
 {


please also clean up the xml for the 4 estimator classes: SsaSpikeEstimator, etc. Their xml shouldn't have any samples and just cref to extension method APIs for usage, plus include algorithm details, in this case link to SSA paper or IID wikipage. #Closed

wschin · 2019-03-14T00:47:52Z

    public static void IidSpikeDetectorPrediction()

Another example? Maybe create another Example() which will call these two existing functions? #Resolved

Refers to: docs/samples/Microsoft.ML.Samples/Dynamic/IidSpikeDetectorTransform.cs:79 in e2487bf. [](commit_id = e2487bf, deletion_comment = False)

wschin · 2019-03-14T00:48:16Z

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/SsaDetectChangePoint.cs

+        {
+            [VectorType(4)]
+            public double[] Prediction { get; set; }
+        }


I like it. #Resolved

wschin · 2019-03-14T00:55:45Z

    public static Vector<double> SsaSpikeDetect(

SsaDetectSpike or DetectSpikeBySsa? Please also double-check if static APIs' names are aligned with their dynamic ones. #Resolved

Refers to: src/Microsoft.ML.TimeSeries.StaticPipe/TimeSeriesStatic.cs:300 in e2487bf. [](commit_id = e2487bf, deletion_comment = False)

wschin

This is a conditional approval. It's valid only if (1) there is only one Example() per sample file (2) equivalent dynamic and static APIs have the same name.

sfilipi · 2019-03-14T17:04:48Z

    public static void IidSpikeDetectorPrediction()

I removed it. The code is in the history of the file, and should get moved to the machinelearning-samples repository

In reply to: 472661246 [](ancestors = 472661246)

Refers to: docs/samples/Microsoft.ML.Samples/Dynamic/IidSpikeDetectorTransform.cs:79 in e2487bf. [](commit_id = e2487bf, deletion_comment = False)

shmoradims · 2019-03-14T17:23:37Z

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/SsaDetectChangePoint.cs

+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public static class SsaDetectChangePoint


SsaDetectChangePoint [](start = 24, length = 20)

please rename these to match the new API name #Resolved

shmoradims · 2019-03-14T17:27:47Z

docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/SsaDetectSpike.cs

+
+namespace Microsoft.ML.Samples.Dynamic
+{
+    public static class SsaDetectSpike


SsaDetectSpike [](start = 24, length = 14)

ditto: rename to DetectSpikeBySsa. Make sure to update the filename inside xml CDATA. #Resolved

shmoradims · 2019-03-14T17:28:32Z

src/Microsoft.ML.TimeSeries/ExtensionsCatalog.cs

+        /// <example>
+        /// <format type="text/markdown">
+        /// <![CDATA[
+        /// [!code-csharp[SsaChangePointEstimator](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/SsaDetectChangePoint.cs)]


SsaDetectChangePoint [](start = 133, length = 20)

update #Closed

shmoradims · 2019-03-14T17:28:46Z

src/Microsoft.ML.TimeSeries/ExtensionsCatalog.cs

+        /// <example>
+        /// <format type="text/markdown">
+        /// <![CDATA[
+        /// [!code-csharp[SingularSpectrumAnalysisDetectSpike](~/../docs/samples/docs/samples/Microsoft.ML.Samples/Dynamic/Transforms/TimeSeries/SsaDetectSpike.cs)]


SsaDetectSpike [](start = 145, length = 14)

update #Closed

shmoradims · 2019-03-14T17:30:18Z

src/Microsoft.ML.TimeSeries/SsaChangePointDetector.cs

@@ -202,16 +201,8 @@ private static IRowMapper Create(IHostEnvironment env, ModelLoadContext ctx, Dat
    }

    /// <summary>
-    /// Estimator for <see cref="SsaChangePointDetector"/>
+    /// The <see cref="IEstimator{ITransformer}"/> for detecting a signal change through <a href="http://arxiv.org/pdf/1206.6910.pdf">Singular Spectrum Analysis (SSA).</a> of time series.


. [](start = 166, length = 1)

extra dot #Closed

shmoradims

sfilipi requested review from codemzs, ganik, shmoradims, CESARDELATORRE and zeahmed March 9, 2019 07:00

sfilipi commented Mar 9, 2019

View reviewed changes

ganik reviewed Mar 11, 2019

View reviewed changes

ganik approved these changes Mar 11, 2019

View reviewed changes

sfilipi requested a review from rogancarr March 13, 2019 05:11

sfilipi self-assigned this Mar 13, 2019

sfilipi added this to the 0319 milestone Mar 13, 2019

shmoradims reviewed Mar 13, 2019

View reviewed changes

wschin reviewed Mar 14, 2019

View reviewed changes

wschin approved these changes Mar 14, 2019

View reviewed changes

shmoradims reviewed Mar 14, 2019

View reviewed changes

shmoradims approved these changes Mar 14, 2019

View reviewed changes

sfilipi added 6 commits March 14, 2019 11:29

Time series samples and documentation alignment

83e02ce

adjusting the name to IID

59d2092

keeping the acronym in the name, but not in documentation

ac638e6

fixing typo

003e3fa

Addressing PR comments

1de5220

PR comments.

632876f

sfilipi force-pushed the timeseriesDocs branch from c6988dc to 632876f Compare March 14, 2019 18:32

sfilipi merged commit da655b8 into dotnet:master Mar 14, 2019

sfilipi deleted the timeseriesDocs branch March 14, 2019 19:43

This was referenced Apr 5, 2019

Time Series samples for stateful prediction engine. #3213

Merged

Samples for time series prediction engine and general clean up of all time series samples #3277

Closed

ghost locked as resolved and limited conversation to collaborators Mar 23, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Time series samples and documentation alignment #2900

Time series samples and documentation alignment #2900

sfilipi commented Mar 9, 2019

sfilipi Mar 9, 2019 •

edited

Loading

shauheen Mar 13, 2019 •

edited by sfilipi

Loading

wschin Mar 14, 2019 •

edited by sfilipi

Loading

sfilipi Mar 14, 2019

codecov bot commented Mar 9, 2019 •

edited

Loading

ganik Mar 11, 2019 •

edited by sfilipi

Loading

ganik Mar 11, 2019 •

edited by sfilipi

Loading

ganik Mar 11, 2019 •

edited by shmoradims

Loading

sfilipi Mar 12, 2019

ganik left a comment

sfilipi commented Mar 13, 2019 •

edited

Loading

shmoradims Mar 13, 2019 •

edited

Loading

shmoradims commented Mar 13, 2019 •

edited by sfilipi

Loading

shmoradims commented Mar 13, 2019 •

edited by sfilipi

Loading

shmoradims commented Mar 13, 2019 •

edited by sfilipi

Loading

shmoradims Mar 13, 2019 •

edited

Loading

sfilipi Mar 13, 2019

wschin Mar 14, 2019

sfilipi Mar 14, 2019

shmoradims Mar 13, 2019 •

edited

Loading

shmoradims Mar 13, 2019 •

edited

Loading

shmoradims Mar 13, 2019 •

edited

Loading

shmoradims Mar 13, 2019 •

edited

Loading

wschin commented Mar 14, 2019 •

edited by sfilipi

Loading

wschin Mar 14, 2019 •

edited by sfilipi

Loading

wschin commented Mar 14, 2019 •

edited by sfilipi

Loading

wschin left a comment

sfilipi commented Mar 14, 2019

shmoradims Mar 14, 2019 •

edited by sfilipi

Loading

shmoradims Mar 14, 2019 •

edited by sfilipi

Loading

shmoradims Mar 14, 2019 •

edited

Loading

shmoradims Mar 14, 2019 •

edited

Loading

shmoradims Mar 14, 2019 •

edited

Loading

shmoradims left a comment

		@@ -30,7 +30,7 @@ public IidChangePointData(float value)

		// This example creates a time series (list of Data with the i-th element corresponding to the i-th time slot).
		// IidChangePointDetector is applied then to identify points where data distribution changed.

		@@ -26,8 +26,7 @@
		namespace Microsoft.ML.Transforms.TimeSeries
		{

Time series samples and documentation alignment #2900

Time series samples and documentation alignment #2900

Conversation

sfilipi commented Mar 9, 2019

sfilipi Mar 9, 2019 • edited Loading

Choose a reason for hiding this comment

shauheen Mar 13, 2019 • edited by sfilipi Loading

Choose a reason for hiding this comment

wschin Mar 14, 2019 • edited by sfilipi Loading

Choose a reason for hiding this comment

sfilipi Mar 14, 2019

Choose a reason for hiding this comment

codecov bot commented Mar 9, 2019 • edited Loading

Codecov Report

ganik Mar 11, 2019 • edited by sfilipi Loading

Choose a reason for hiding this comment

ganik Mar 11, 2019 • edited by sfilipi Loading

Choose a reason for hiding this comment

ganik Mar 11, 2019 • edited by shmoradims Loading

Choose a reason for hiding this comment

sfilipi Mar 12, 2019

Choose a reason for hiding this comment

ganik left a comment

Choose a reason for hiding this comment

sfilipi commented Mar 13, 2019 • edited Loading

shmoradims Mar 13, 2019 • edited Loading

Choose a reason for hiding this comment

shmoradims commented Mar 13, 2019 • edited by sfilipi Loading

shmoradims commented Mar 13, 2019 • edited by sfilipi Loading

shmoradims commented Mar 13, 2019 • edited by sfilipi Loading

shmoradims Mar 13, 2019 • edited Loading

Choose a reason for hiding this comment

sfilipi Mar 13, 2019

Choose a reason for hiding this comment

wschin Mar 14, 2019

Choose a reason for hiding this comment

sfilipi Mar 14, 2019

Choose a reason for hiding this comment

shmoradims Mar 13, 2019 • edited Loading

Choose a reason for hiding this comment

shmoradims Mar 13, 2019 • edited Loading

Choose a reason for hiding this comment

shmoradims Mar 13, 2019 • edited Loading

Choose a reason for hiding this comment

shmoradims Mar 13, 2019 • edited Loading

Choose a reason for hiding this comment

wschin commented Mar 14, 2019 • edited by sfilipi Loading

wschin Mar 14, 2019 • edited by sfilipi Loading

Choose a reason for hiding this comment

wschin commented Mar 14, 2019 • edited by sfilipi Loading

wschin left a comment

Choose a reason for hiding this comment

sfilipi commented Mar 14, 2019

shmoradims Mar 14, 2019 • edited by sfilipi Loading

Choose a reason for hiding this comment

shmoradims Mar 14, 2019 • edited by sfilipi Loading

Choose a reason for hiding this comment

shmoradims Mar 14, 2019 • edited Loading

Choose a reason for hiding this comment

shmoradims Mar 14, 2019 • edited Loading

Choose a reason for hiding this comment

shmoradims Mar 14, 2019 • edited Loading

Choose a reason for hiding this comment

shmoradims left a comment

Choose a reason for hiding this comment

sfilipi Mar 9, 2019 •

edited

Loading

shauheen Mar 13, 2019 •

edited by sfilipi

Loading

wschin Mar 14, 2019 •

edited by sfilipi

Loading

codecov bot commented Mar 9, 2019 •

edited

Loading

ganik Mar 11, 2019 •

edited by sfilipi

Loading

ganik Mar 11, 2019 •

edited by sfilipi

Loading

ganik Mar 11, 2019 •

edited by shmoradims

Loading

sfilipi commented Mar 13, 2019 •

edited

Loading

shmoradims Mar 13, 2019 •

edited

Loading

shmoradims commented Mar 13, 2019 •

edited by sfilipi

Loading

shmoradims commented Mar 13, 2019 •

edited by sfilipi

Loading

shmoradims commented Mar 13, 2019 •

edited by sfilipi

Loading

shmoradims Mar 13, 2019 •

edited

Loading

shmoradims Mar 13, 2019 •

edited

Loading

shmoradims Mar 13, 2019 •

edited

Loading

shmoradims Mar 13, 2019 •

edited

Loading

shmoradims Mar 13, 2019 •

edited

Loading

wschin commented Mar 14, 2019 •

edited by sfilipi

Loading

wschin Mar 14, 2019 •

edited by sfilipi

Loading

wschin commented Mar 14, 2019 •

edited by sfilipi

Loading

shmoradims Mar 14, 2019 •

edited by sfilipi

Loading

shmoradims Mar 14, 2019 •

edited by sfilipi

Loading

shmoradims Mar 14, 2019 •

edited

Loading

shmoradims Mar 14, 2019 •

edited

Loading

shmoradims Mar 14, 2019 •

edited

Loading