Skip to content

Commit 41d59a1

Browse files
eerhardteerhardt
authored
Merge pull request dotnet#479 from shauheen/v0.3
Cherrypick to update release for V0.3
2 parents 9cecb72 + ad681e4 commit 41d59a1

File tree

56 files changed

+8938
-5546
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+8938
-5546
lines changed

‎Directory.Build.targets

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,33 @@
55
Text="The tools directory [$(ToolsDir)] does not exist. Please run build in the root of the repo to ensure the tools are installed before attempting to build an individual project." />
66
</Target>
77

8+
<Target Name="CopyNativeAssemblies"
9+
BeforeTargets="PrepareForRun">
10+
11+
<PropertyGroup>
12+
<LibPrefix Condition="'$(OS)' != 'Windows_NT'">lib</LibPrefix>
13+
<LibExtension Condition="'$(OS)' == 'Windows_NT'">.dll</LibExtension>
14+
<LibExtension Condition="'$(OS)' != 'Windows_NT'">.so</LibExtension>
15+
<LibExtension Condition="$([MSBuild]::IsOSPlatform('osx'))">.dylib</LibExtension>
16+
</PropertyGroup>
17+
18+
<ItemGroup>
19+
<NativeAssemblyReference>
20+
<FullAssemblyPath>$(NativeOutputPath)$(LibPrefix)%(NativeAssemblyReference.Identity)$(LibExtension)</FullAssemblyPath>
21+
</NativeAssemblyReference>
22+
</ItemGroup>
23+
24+
<Copy SourceFiles = "@(NativeAssemblyReference->'%(FullAssemblyPath)')"
25+
DestinationFolder="$(OutputPath)"
26+
OverwriteReadOnlyFiles="$(OverwriteReadOnlyFiles)"
27+
Retries="$(CopyRetryCount)"
28+
RetryDelayMilliseconds="$(CopyRetryDelayMilliseconds)"
29+
UseHardlinksIfPossible="$(CreateHardLinksForPublishFilesIfPossible)"
30+
UseSymboliclinksIfPossible="$(CreateSymbolicLinksForPublishFilesIfPossible)">
31+
<Output TaskParameter="DestinationFiles" ItemName="FileWrites"/>
32+
</Copy>
33+
34+
</Target>
35+
836
<Import Project="$(ToolsDir)/versioning.targets" Condition="Exists('$(ToolsDir)/versioning.targets')" />
937
</Project>

‎docs/release-notes/0.3/release-0.3.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# ML.NET 0.3 Release Notes
2+
3+
Today we are releasing ML.NET 0.3. This release focuses on adding components
4+
to ML.NET from the internal codebase (such as Factorization Machines,
5+
LightGBM, Ensembles, and LightLDA), enabling export to the ONNX model format,
6+
and bug fixes.
7+
8+
### Installation
9+
10+
ML.NET supports Windows, MacOS, and Linux. See [supported OS versions of .NET
11+
Core
12+
2.0](https://github.com/dotnet/core/blob/master/release-notes/2.0/2.0-supported-os.md)
13+
for more details.
14+
15+
You can install ML.NET NuGet from the CLI using:
16+
```
17+
dotnet add package Microsoft.ML
18+
```
19+
20+
From package manager:
21+
```
22+
Install-Package Microsoft.ML
23+
```
24+
25+
### Release Notes
26+
27+
Below are some of the highlights from this release.
28+
29+
* Added Field-Aware Factorization Machines (FFM) as a learner for binary
30+
classification (#383)
31+
32+
* FFM is useful for various large sparse datasets, especially in areas
33+
such as recommendations and click prediction. It has been used to win
34+
various click prediction competitions such as the [Criteo Display
35+
Advertising Challenge on
36+
Kaggle](https://www.kaggle.com/c/criteo-display-ad-challenge). You can
37+
learn more about the winning solution
38+
[here](https://www.csie.ntu.edu.tw/~r01922136/kaggle-2014-criteo.pdf).
39+
* FFM is a streaming learner so it does not require the entire dataset to
40+
fit in memory.
41+
* You can learn more about FFM
42+
[here](http://www.csie.ntu.edu.tw/~cjlin/papers/ffm.pdf) and some of the
43+
speedup approaches that are used in ML.NET
44+
[here](https://github.com/wschin/fast-ffm/blob/master/fast-ffm.pdf).
45+
46+
* Added [LightGBM](https://github.com/Microsoft/LightGBM) as a learner for
47+
binary classification, multiclass classification, and regression (#392)
48+
49+
* LightGBM is a tree based gradient boosting machine. It is under the
50+
umbrella of the [DMTK](http://github.com/microsoft/dmtk) project at
51+
Microsoft.
52+
* The LightGBM repository shows various [comparison
53+
experiments](https://github.com/Microsoft/LightGBM/blob/6488f319f243f7ff679a8e388a33e758c5802303/docs/Experiments.rst#comparison-experiment)
54+
that show good accuracy and speed, so it is a great learner to try out.
55+
It has also been used in winning solutions in various [ML
56+
challenges](https://github.com/Microsoft/LightGBM/blob/a6e878e2fc6e7f545921cbe337cc511fbd1f500d/examples/README.md).
57+
* This addition wraps LightGBM and exposes it in ML.NET.
58+
* Note that LightGBM can also be used for ranking, but the ranking
59+
evaluator is not yet exposed in ML.NET.
60+
61+
* Added Ensemble learners for binary classification, multiclass
62+
classification, and regression (#379)
63+
64+
* [Ensemble learners](https://en.wikipedia.org/wiki/Ensemble_learning)
65+
enable using multiple learners in one model. As an example, the Ensemble
66+
learner could train both `FastTree` and `AveragedPerceptron` and average
67+
their predictions to get the final prediction.
68+
* Combining multiple models of similar statistical performance may lead to
69+
better performance than each model separately.
70+
71+
* Added LightLDA transform for topic modeling (#377)
72+
73+
* LightLDA is an implementation of [Latent Dirichlet
74+
Allocation](https://en.wikipedia.org/wiki/Latent_Dirichlet_allocation)
75+
which infers topical structure from text data.
76+
* The implementation of LightLDA in ML.NET is based on [this
77+
paper](https://arxiv.org/abs/1412.1576). There is a distributed
78+
implementation of LightLDA
79+
[here](https://github.com/Microsoft/lightlda).
80+
81+
* Added One-Versus-All (OVA) learner for multiclass classification (#363)
82+
83+
* [OVA](https://en.wikipedia.org/wiki/Multiclass_classification#One-vs.-rest)
84+
(sometimes known as One-Versus-Rest) is an approach to using binary
85+
classifiers in multiclass classification problems.
86+
* While some binary classification learners in ML.NET natively support
87+
multiclass classification (e.g. Logistic Regression), there are others
88+
that do not (e.g. Averaged Perceptron). OVA enables using the latter
89+
group for multiclass classification as well.
90+
91+
* Enabled export of ML.NET models to the [ONNX](https://onnx.ai/) format
92+
(#248)
93+
94+
* ONNX is a common format for representing deep learning models (also
95+
supporting certain other types of models) which enables developers to
96+
move models between different ML toolkits.
97+
* ONNX models can be used in [Windows
98+
ML](https://docs.microsoft.com/en-us/windows/uwp/machine-learning/overview)
99+
which enables evaluating models on Windows 10 devices and taking
100+
advantage of capabilities like hardware acceleration.
101+
* Currently, only a subset of ML.NET components can be used in a model
102+
that is converted to ONNX.
103+
104+
Additional issues closed in this milestone can be found
105+
[here](https://github.com/dotnet/machinelearning/milestone/2?closed=1).
106+
107+
### Acknowledgements
108+
109+
Shoutout to [pkulikov](https://github.com/pkulikov),
110+
[veikkoeeva](https://github.com/veikkoeeva),
111+
[ross-p-smith](https://github.com/ross-p-smith),
112+
[jwood803](https://github.com/jwood803),
113+
[Nepomuceno](https://github.com/Nepomuceno), and the ML.NET team for their
114+
contributions as part of this release!

‎src/Microsoft.ML.Console/Console.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,4 @@ public static class Console
88
{
99
public static int Main(string[] args) => Maml.Main(args);
1010
}
11-
}
11+
}

‎src/Microsoft.ML.Console/Microsoft.ML.Console.csproj

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,34 @@
33
<PropertyGroup>
44
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
55
<DefineConstants>CORECLR</DefineConstants>
6-
<TargetFramework>netcoreapp2.0</TargetFramework>
7-
<OutputType>Exe</OutputType>
8-
<AssemblyName>MML</AssemblyName>
9-
<StartupObject>Microsoft.ML.Runtime.Tools.Console.Console</StartupObject>
6+
<TargetFramework>netcoreapp2.0</TargetFramework>
7+
<OutputType>Exe</OutputType>
8+
<AssemblyName>MML</AssemblyName>
9+
<StartupObject>Microsoft.ML.Runtime.Tools.Console.Console</StartupObject>
1010
</PropertyGroup>
1111

1212
<ItemGroup>
1313
<ProjectReference Include="..\Microsoft.ML.Core\Microsoft.ML.Core.csproj" />
14+
<ProjectReference Include="..\Microsoft.ML.CpuMath\Microsoft.ML.CpuMath.csproj" />
1415
<ProjectReference Include="..\Microsoft.ML.Data\Microsoft.ML.Data.csproj" />
16+
<ProjectReference Include="..\Microsoft.ML.Ensemble\Microsoft.ML.Ensemble.csproj" />
17+
<ProjectReference Include="..\Microsoft.ML.FastTree\Microsoft.ML.FastTree.csproj" />
18+
<ProjectReference Include="..\Microsoft.ML.InternalStreams\Microsoft.ML.InternalStreams.csproj" />
19+
<ProjectReference Include="..\Microsoft.ML.KMeansClustering\Microsoft.ML.KMeansClustering.csproj" />
20+
<ProjectReference Include="..\Microsoft.ML.LightGBM\Microsoft.ML.LightGBM.csproj" />
1521
<ProjectReference Include="..\Microsoft.ML.Maml\Microsoft.ML.Maml.csproj" />
22+
<ProjectReference Include="..\Microsoft.ML.PCA\Microsoft.ML.PCA.csproj" />
1623
<ProjectReference Include="..\Microsoft.ML.PipelineInference\Microsoft.ML.PipelineInference.csproj" />
17-
</ItemGroup>
24+
<ProjectReference Include="..\Microsoft.ML.ResultProcessor\Microsoft.ML.ResultProcessor.csproj" />
25+
<ProjectReference Include="..\Microsoft.ML.StandardLearners\Microsoft.ML.StandardLearners.csproj" />
26+
<ProjectReference Include="..\Microsoft.ML.Sweeper\Microsoft.ML.Sweeper.csproj" />
27+
<ProjectReference Include="..\Microsoft.ML.Transforms\Microsoft.ML.Transforms.csproj" />
28+
<ProjectReference Include="..\Microsoft.ML.UniversalModelFormat\Microsoft.ML.UniversalModelFormat.csproj" />
1829

30+
<NativeAssemblyReference Include="FastTreeNative" />
31+
<NativeAssemblyReference Include="CpuMathNative" />
32+
<NativeAssemblyReference Include="FactorizationMachineNative" />
33+
<NativeAssemblyReference Include="LdaNative" />
34+
</ItemGroup>
35+
1936
</Project>

‎src/Microsoft.ML.Core/EntryPoints/ModuleArgs.cs

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -527,6 +527,11 @@ public sealed class EntryPointAttribute : Attribute
527527
/// Short name of the Entry Point
528528
/// </summary>
529529
public string ShortName { get; set; }
530+
531+
/// <summary>
532+
/// Remarks on the Entry Point, for more extensive XML documentation on the C#API
533+
/// </summary>
534+
public string Remarks { get; set; }
530535
}
531536

532537
/// <summary>

‎src/Microsoft.ML.Core/EntryPoints/ModuleCatalog.cs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ public sealed class EntryPointInfo
4444
public readonly string Description;
4545
public readonly string ShortName;
4646
public readonly string FriendlyName;
47+
public readonly string Remarks;
4748
public readonly MethodInfo Method;
4849
public readonly Type InputType;
4950
public readonly Type OutputType;
@@ -63,6 +64,7 @@ internal EntryPointInfo(IExceptionContext ectx, MethodInfo method,
6364
Method = method;
6465
ShortName = attribute.ShortName;
6566
FriendlyName = attribute.UserName;
67+
Remarks = attribute.Remarks;
6668
ObsoleteAttribute = obsoleteAttribute;
6769

6870
// There are supposed to be 2 parameters, env and input for non-macro nodes.

‎src/Microsoft.ML.Data/Evaluators/EvaluatorUtils.cs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -653,10 +653,10 @@ public static void ReconcileKeyValuesWithNoNames(IHostEnvironment env, IDataView
653653
ValueMapper<uint, uint> mapper =
654654
(ref uint src, ref uint dst) =>
655655
{
656-
if (src == 0 || src > keyCount)
656+
if (src > keyCount)
657657
dst = 0;
658658
else
659-
dst = src + 1;
659+
dst = src;
660660
};
661661
views[i] = LambdaColumnMapper.Create(env, "ReconcileKeyValues", views[i], columnName, columnName,
662662
views[i].Schema.GetColumnType(index), keyType, mapper);
@@ -866,7 +866,7 @@ private static IDataView AppendPerInstanceDataViews(IHostEnvironment env, string
866866
}
867867
else if (dvNumber == 0 && dv.Schema.HasKeyNames(i, type.KeyCount))
868868
firstDvKeyWithNamesColumns.Add(name);
869-
else if (type.KeyCount > 0 && name != labelColName)
869+
else if (type.KeyCount > 0 && name != labelColName && !dv.Schema.HasKeyNames(i, type.KeyCount))
870870
{
871871
// For any other key column (such as GroupId) we do not reconcile the key values, we only convert to U4.
872872
if (!firstDvKeyNoNamesColumns.ContainsKey(name))
@@ -901,7 +901,7 @@ private static IDataView AppendPerInstanceDataViews(IHostEnvironment env, string
901901
Func<IDataView, int, IDataView> keyToValue =
902902
(idv, i) =>
903903
{
904-
foreach (var keyCol in firstDvVectorKeyColumns.Prepend(labelColName))
904+
foreach (var keyCol in firstDvVectorKeyColumns.Concat(firstDvKeyWithNamesColumns).Prepend(labelColName))
905905
{
906906
if (keyCol == labelColName && labelColKeyValuesType == null)
907907
continue;

‎src/Microsoft.ML.FastTree/FastTree.cs

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,31 @@ public abstract class FastTreeTrainerBase<TArgs, TPredictor> :
8282

8383
protected string InnerArgs => CmdParser.GetSettings(Host, Args, new TArgs());
8484

85+
internal const string Remarks = @"<remarks>
86+
<para>FastTrees is an efficient implementation of the <a href='https://arxiv.org/abs/1505.01866'>MART</a> gradient boosting algorithm.
87+
Gradient boosting is a machine learning technique for regression problems.
88+
It builds each regression tree in a step-wise fashion, using a predefined loss function to measure the error for each step and corrects for it in the next.
89+
So this prediction model is actually an ensemble of weaker prediction models. In regression problems, boosting builds a series of of such trees in a step-wise fashion and then selects the optimal tree using an arbitrary differentiable loss function.
90+
</para>
91+
<para>
92+
MART learns an ensemble of regression trees, which is a decision tree with scalar values in its leaves.
93+
A decision (or regression) tree is a binary tree-like flow chart, where at each interior node one decides which of the two child nodes to continue to based on one of the feature values from the input.
94+
At each leaf node, a value is returned. In the interior nodes, the decision is based on the test 'x <= v' where x is the value of the feature in the input sample and v is one of the possible values of this feature.
95+
The functions that can be produced by a regression tree are all the piece-wise constant functions.
96+
</para>
97+
<para>
98+
The ensemble of trees is produced by computing, in each step, a regression tree that approximates the gradient of the loss function, and adding it to the previous tree with coefficients that minimize the loss of the new tree.
99+
The output of the ensemble produced by MART on a given instance is the sum of the tree outputs.
100+
</para>
101+
<list type='bullet'>
102+
<item>In case of a binary classification problem, the output is converted to a probability by using some form of calibration.</item>
103+
<item>In case of a regression problem, the output is the predicted value of the function.</item>
104+
<item>In case of a ranking problem, the instances are ordered by the output value of the ensemble.</item>
105+
</list>
106+
<a href='https://en.wikipedia.org/wiki/Gradient_boosting#Gradient_tree_boosting'>Wikipedia: Gradient boosting (Gradient tree boosting)</a>.
107+
<a href='http://projecteuclid.org/DPubS?service=UI&version=1.0&verb=Display&handle=euclid.aos/1013203451'>Greedy function approximation: A gradient boosting machine.</a>.
108+
</remarks>";
109+
85110
public override bool NeedNormalization => false;
86111

87112
public override bool WantCaching => false;

‎src/Microsoft.ML.FastTree/FastTreeClassification.cs

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -338,7 +338,11 @@ public void AdjustTreeOutputs(IChannel ch, RegressionTree tree,
338338

339339
public static partial class FastTree
340340
{
341-
[TlcModule.EntryPoint(Name = "Trainers.FastTreeBinaryClassifier", Desc = FastTreeBinaryClassificationTrainer.Summary, UserName = FastTreeBinaryClassificationTrainer.UserNameValue, ShortName = FastTreeBinaryClassificationTrainer.ShortName)]
341+
[TlcModule.EntryPoint(Name = "Trainers.FastTreeBinaryClassifier",
342+
Desc = FastTreeBinaryClassificationTrainer.Summary,
343+
Remarks = FastTreeBinaryClassificationTrainer.Remarks,
344+
UserName = FastTreeBinaryClassificationTrainer.UserNameValue,
345+
ShortName = FastTreeBinaryClassificationTrainer.ShortName)]
342346
public static CommonOutputs.BinaryClassificationOutput TrainBinary(IHostEnvironment env, FastTreeBinaryClassificationTrainer.Arguments input)
343347
{
344348
Contracts.CheckValue(env, nameof(env));

‎src/Microsoft.ML.FastTree/FastTreeRanking.cs

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1096,7 +1096,11 @@ public static FastTreeRankingPredictor Create(IHostEnvironment env, ModelLoadCon
10961096

10971097
public static partial class FastTree
10981098
{
1099-
[TlcModule.EntryPoint(Name = "Trainers.FastTreeRanker", Desc = FastTreeRankingTrainer.Summary, UserName = FastTreeRankingTrainer.UserNameValue, ShortName = FastTreeRankingTrainer.ShortName)]
1099+
[TlcModule.EntryPoint(Name = "Trainers.FastTreeRanker",
1100+
Desc = FastTreeRankingTrainer.Summary,
1101+
Remarks = FastTreeRankingTrainer.Remarks,
1102+
UserName = FastTreeRankingTrainer.UserNameValue,
1103+
ShortName = FastTreeRankingTrainer.ShortName)]
11001104
public static CommonOutputs.RankingOutput TrainRanking(IHostEnvironment env, FastTreeRankingTrainer.Arguments input)
11011105
{
11021106
Contracts.CheckValue(env, nameof(env));

‎src/Microsoft.ML.FastTree/FastTreeRegression.cs

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -448,7 +448,11 @@ public static FastTreeRegressionPredictor Create(IHostEnvironment env, ModelLoad
448448

449449
public static partial class FastTree
450450
{
451-
[TlcModule.EntryPoint(Name = "Trainers.FastTreeRegressor", Desc = FastTreeRegressionTrainer.Summary, UserName = FastTreeRegressionTrainer.UserNameValue, ShortName = FastTreeRegressionTrainer.ShortName)]
451+
[TlcModule.EntryPoint(Name = "Trainers.FastTreeRegressor",
452+
Desc = FastTreeRegressionTrainer.Summary,
453+
Remarks = FastTreeRegressionTrainer.Remarks,
454+
UserName = FastTreeRegressionTrainer.UserNameValue,
455+
ShortName = FastTreeRegressionTrainer.ShortName)]
452456
public static CommonOutputs.RegressionOutput TrainRegression(IHostEnvironment env, FastTreeRegressionTrainer.Arguments input)
453457
{
454458
Contracts.CheckValue(env, nameof(env));

‎src/Microsoft.ML.FastTree/FastTreeTweedie.cs

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,11 @@ public sealed partial class FastTreeTweedieTrainer : BoostingFastTreeTrainerBase
3636
{
3737
public const string LoadNameValue = "FastTreeTweedieRegression";
3838
public const string UserNameValue = "FastTree (Boosted Trees) Tweedie Regression";
39-
public const string Summary = "Trains gradient boosted decision trees to fit target values using a Tweedie loss function. This learner " +
40-
"is a generalization of Poisson, compound Poisson, and gamma regression.";
39+
public const string Summary = "Trains gradient boosted decision trees to fit target values using a Tweedie loss function. This learner is a generalization of Poisson, compound Poisson, and gamma regression.";
40+
new public const string Remarks = @"<remarks>
41+
<a href='https://en.wikipedia.org/wiki/Gradient_boosting#Gradient_tree_boosting'>Wikipedia: Gradient boosting (Gradient tree boosting)</a>
42+
<a href='http://projecteuclid.org/DPubS?service=UI&version=1.0&verb=Display&handle=euclid.aos/1013203451'>Greedy function approximation: A gradient boosting machine</a>
43+
</remarks>";
4144

4245
public const string ShortName = "fttweedie";
4346

@@ -460,7 +463,10 @@ protected override void Map(ref VBuffer<float> src, ref float dst)
460463

461464
public static partial class FastTree
462465
{
463-
[TlcModule.EntryPoint(Name = "Trainers.FastTreeTweedieRegressor", Desc = FastTreeTweedieTrainer.Summary, UserName = FastTreeTweedieTrainer.UserNameValue, ShortName = FastTreeTweedieTrainer.ShortName)]
466+
[TlcModule.EntryPoint(Name = "Trainers.FastTreeTweedieRegressor",
467+
Desc = FastTreeTweedieTrainer.Summary,
468+
UserName = FastTreeTweedieTrainer.UserNameValue,
469+
ShortName = FastTreeTweedieTrainer.ShortName)]
464470
public static CommonOutputs.RegressionOutput TrainTweedieRegression(IHostEnvironment env, FastTreeTweedieTrainer.Arguments input)
465471
{
466472
Contracts.CheckValue(env, nameof(env));

0 commit comments

Comments
 (0)