Skip to content

Add release notes for ML.NET 0.2 #301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
glebuk merged 3 commits into from
Jun 5, 2018
Merged

Add release notes for ML.NET 0.2 #301

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4f241e9
Add release notes for ML.NET 0.2
Jun 5, 2018
87b20ce
Adding release note about TextLoader changes and additional issue/PR …
Jun 5, 2018
f026db2
Addressing comments: fixing typos, changing formatting, and adding re…
Jun 5, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions docs/release-notes/0.2/release-0.2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# ML.NET 0.2 Release Notes

We would like to thank the community for the engagement so far and helping us shape ML.NET.

Today we are releasing ML.NET 0.2. This release focuses on addressing questions/issues, adding clustering to the list of supported machine learning tasks, enabling using data from memory to train models, easier model validation, and more.

### Installation

Supported platforms: Windows, MacOS, Linux (see [supported OS versions of .NET Core 2.0](https://github.com/dotnet/core/blob/master/release-notes/2.0/2.0-supported-os.md) for more detail)

@TomFinley TomFinley Jun 5, 2018

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not an appropriate use of parentheses, but rather, let's use two separate sentences.

@GalOshri GalOshri Jun 5, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed.

@TomFinley TomFinley Jun 5, 2018

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Supported platforms: Windows, MacOS, Linux [](start = 0, length = 42)

I am somewhat hostile to the idea of using language in this fashion, especially when there is so little cost to actually using proper grammatic sentences. So instead of "Supported platforms: Windows, MacOS, Linux" we may use "Supported platforms are Windows, MacOS, and Linux." You could even use the active voice we support as opposed to "supported" for bonus points.

@GalOshri GalOshri Jun 5, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed.


You can install ML.NET NuGet from the CLI using:
```
dotnet add package Microsoft.ML
```

From package manager:
```
Install-Package Microsoft.ML
```

### Release Notes

Below are some of the highlights from this release.

#### New machine learning tasks: clustering

@TomFinley TomFinley Jun 5, 2018

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This formatting scheme does not correspond to the formatting used for 0.1 release notes. There was a ### level 3 release notes header in those, but followed by a list style structure. I actually preferred that structure to this structure, where we are using, seemingly, level four headers to refer to individual points which, as near as I can tell, correspond to individual sentences.

@GalOshri GalOshri Jun 5, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed to the previous format.

Clustering is an unsupervised learning task that groups sets of items based on their features. It identifies which items are more similar to each other than other items. This might be useful in scenarios such as organizing news articles into groups based on their topics, segmenting users based on their shopping habits, and grouping viewers based on their taste in movies.

@TomFinley TomFinley Jun 5, 2018

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clustering is an unsupervised learning task [](start = 0, length = 43)

Opinions may differ, but I really do not feel like defining terms like "clustering" or "cross validation" in release notes is appropriate. Verbose release notes are IMHO tedious. :P Links to Wikipedia, fantastic, but otherwise I'd refrain from defining it beyond that link. If someone doesn't know what clustering or cross-validation are, they aren't going to be enlightened by this brief description.

@GalOshri GalOshri Jun 5, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A brief description might help give a sense of what the term means and whether it would be interesting to learn more by clicking the link. Perhaps we can adjust this once the release notes start to feel too verbose?


ML.NET 0.2 exposes `KMeansPlusPlusClusterer` which implments K-Means++ clustering. [This test](https://github.com/dotnet/machinelearning/blob/78810563616f3fcb0b63eb8a50b8b2e62d9d65fc/test/Microsoft.ML.Tests/Scenarios/ClusteringTests.cs) shows how to use it (from [#222](https://github.com/dotnet/machinelearning/pull/222)).

@TomFinley TomFinley Jun 5, 2018

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

implments [](start = 51, length = 9)

implements, not implments.

@GalOshri GalOshri Jun 5, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for catching this. Addressed.

@TomFinley TomFinley Jun 5, 2018

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#222 [](start = 264, length = 4)

I am curious. Comments of course, do this automatically. So I can just mention #222 and this link will work. Does the same apply to checked in artifacts? That is, if you just said #222, with no syntax, would it just work? I honestly don't know but it may be worthwhile to think about.

@TomFinley TomFinley Jun 5, 2018 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

K-Means++ clustering [](start = 61, length = 20)

K-means is a well understood algorithm. The initialization peculiar to K-means++, however, is not. Please link to the relevant publications. (Take care to use links accessible to people without Microsoft's access to various "paid" published paper services and whatnot, if possible. This can be somewhat hard to detect within Microsoft so use something outside corpnet to check that people outside can read as well.)

@GalOshri GalOshri Jun 5, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added links from here.


#### Train using data objects in addition to loading data from a file: `CollectionDataSource`

ML.NET 0.1 enabled loading data from a delimited text file. `CollectionDataSource` in ML.NET 0.2 adds the ability to use a collection of objects as the input to a `LearningPipeline`. See sample usage [here](https://github.com/dotnet/machinelearning/blob/78810563616f3fcb0b63eb8a50b8b2e62d9d65fc/test/Microsoft.ML.Tests/CollectionDataSourceTests.cs#L133) (from [#106](https://github.com/dotnet/machinelearning/pull/106)).

#### Easier model validation with cross-validation and train-test

[Cross-validation](https://en.wikipedia.org/wiki/Cross-validation_(statistics)) is an approach to validating how well your model statistically performs. It does not require a separate test dataset, but rather uses your training data to test your model (it partitions the data so different data is used for training and testing, and it does this multiple times). [Here](https://github.com/dotnet/machinelearning/blob/78810563616f3fcb0b63eb8a50b8b2e62d9d65fc/test/Microsoft.ML.Tests/Scenarios/SentimentPredictionTests.cs#L51) is an example for doing cross-validation (from [#212](https://github.com/dotnet/machinelearning/pull/212)).

@TomFinley TomFinley Jun 5, 2018

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we please wordwrap these things? One of the nice things about Markdown is that it is simultaneously both interpretable both as a "rendered" document, plus as its actual raw form... hence the deliberate choice of the name "Markdown" as opposed to "Markup." Whenever we don't properly wordwrap these things, that compromises that crucial advantage it has.

There is some language I wrote earlier in some other contexts, about writing documentation. You may find it useful, or not.

One of the things I would suggest is installing text wrapping. At the time of
writing Visual Studio Code does not have hard wrapping installed by default,
but there is a nice extension called rewrap.

Hit Control-p, then type the command ext install rewrap. You will be able
to install rewrap from here. Once you do, you can change its settings: in
particular I would change its wrapping column to 78, in order to reflect our
guidelines. This is controlled through the setting
"rewrap.wrappingColumn": 78.

Visual Studio Code uses a JSON format configuration file (somewhat
akin to, say, Sublime Text and some other editors), and you can configure the
behavior of plugin architecture here as well. So if you go to the menu "File,"
then "Preferences," then "Settings," you will your user configuration. If
you've never provided settings, your user settings will be empty, looking
something like this:

// Place your settings in this file to overwrite the default settings
{
}

Once you change it, it will look something like this.

// Place your settings in this file to overwrite the default settings
{
    "rewrap.wrappingColumn": 78
}

Thenceforth, whenever you want to wrap a paragraph, Alt-Q will do so.

@GalOshri GalOshri Jun 5, 2018

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed.


Train-test is a shortcut to testing your model on a separate dataset. See example usage [here](https://github.com/dotnet/machinelearning/blob/78810563616f3fcb0b63eb8a50b8b2e62d9d65fc/test/Microsoft.ML.Tests/Scenarios/SentimentPredictionTests.cs#L36).

Note that the `LearningPipeline` is prepared the same way in both cases.

#### Speed improvement for predictions

By not creating a parallel cursor for dataviews that only have one element, we get a significant speed-up for predictions (see [#179](https://github.com/dotnet/machinelearning/issues/179) for a few measurements).

#### Updated `TextLoader` API

The `TextLoader` API is now code generated and was updated to take explicit declarations for the columns in the data, which is required in some scenarios. See [#142](https://github.com/dotnet/machinelearning/pull/142).

#### Added daily NuGet builds of the project

Daily NuGet builds of ML.NET are now available [here](https://dotnet.myget.org/feed/dotnet-core/package/nuget/Microsoft.ML).

#### Additional issues closed in this milestone

[Here](https://github.com/dotnet/machinelearning/milestone/1?closed=1) is the list of issues closed as part of this milestone.

### Acknowledgements

Shoutout to tincann, rantri, yamachu, pkulikov, Sorrien, v-tsymbalistyi, Ky7m, forki, jessebenson, mfaticaearnin, and the ML.NET team for their contributions as part of this release!