Read and write binary file documentation

docs/code/MlNetCookBook.md

@@ -41,6 +41,7 @@ Please feel free to search this page and use any code that suits your needs.
 - [How do I train using cross-validation?](#how-do-i-train-using-cross-validation)
 - [Can I mix and match static and dynamic pipelines?](#can-i-mix-and-match-static-and-dynamic-pipelines)
 - [How can I define my own transformation of data?](#how-can-i-define-my-own-transformation-of-data)
+- [How can I read and write binary data?](#how-can-i-read-and-write-binary-data)
 
 ### General questions about the samples
 
@@ -1022,3 +1023,49 @@ ITransformer loadedModel;
 using (var fs = File.OpenRead(modelPath))
     loadedModel = newContext.Model.Load(fs);
 ```
+
+## How can I read and write binary data?
+Other than using text files, ML.NET will allow you to read and write binary data. This has a few advantages such as not having to specify a schema, can improve reading times, and are generally smaller than text files.
+
+To write binary data you need some data to be able to save. Specifically you need an instance of an `IDavaView`. Below is a code snippet that uses the iris data as an example.
+
+```csharp
+// Data model for the iris data
+public class IrisData
+{
+    public float Label { get; set; }
+    public float SepalLength { get; set; }
+    public float SepalWidth { get; set; }
+    public float PetalLength { get; set; }
+    public float PetalWidth { get; set; }
+}
+
+// An array of iris data points
+var dataArray = new[]
+{
+    new IrisData { Label=1, PetalLength=1, SepalLength=1, PetalWidth=1, SepalWidth=1 },
+    new IrisData { Label=0, PetalLength=2, SepalLength=2, PetalWidth=2, SepalWidth=2 }
+};
+
+// Create the ML.NET context.
+var context = new MLContext();
+
+// Create the data view from an IEnumerable.
+// This method will use the definition of IrisData to understand what columns there are 
+// in the data view. However, the objects in ML.NET are only "promises" of data since 
+// ML.NET operations are lazy. One way to get a look at the data is with Schema Comprehension.
+// Refer to this document for more information - https://github.com/dotnet/machinelearning/blob/master/docs/code/SchemaComprehension.md
+var data = context.Data.LoadFromEnumerable(dataArray);
+
+// Use a FileStream to create a file. Use the stream and the data view in the "SaveAsBinary" method.
+using(var stream = new FileStream("./iris.idv", FileMode.Create))
+{
+    context.Data.SaveAsBinary(data, stream);
+}
+```
+
+To read a binary file, simply use the `context.Data.ReadFromBinary` method and pass in the path of the binary file to read in. Notice that the schema of the data does not need to be defined here.
+
+```csharp
+var data = context.Data.ReadFromBinary("./iris.idv");
+```

docs/samples/Microsoft.ML.Samples/Dynamic/DataOperations/SaveAndReadFromBinary.cs

@@ -0,0 +1,31 @@
+using System.Collections.Generic;
+using System.IO;
+using Microsoft.Data.DataView;
+using Microsoft.ML.SamplesUtils;
+
+namespace Microsoft.ML.Samples.Dynamic.DataOperations
+{
+    public class SaveAndLoadFromBinary
+    {
+        public static void Example()
+        {
+            var mlContext = new MLContext();
+
+            // Get a small dataset as an IEnumerable.
+            IEnumerable<DatasetUtils.SampleTemperatureData> enumerableOfData = DatasetUtils.GetSampleTemperatureData(5);
+
+            // Load dataset into an IDataView. 
+            IDataView data = mlContext.Data.LoadFromEnumerable(enumerableOfData);
+
+            // Creating a FileStream object to create a file and use             
+            // the stream to create a binary file.
+            using (var stream = new FileStream("./sample-temp-data.idv", FileMode.Create))
+            {
+                mlContext.Data.SaveAsBinary(data, stream);
+            }
+
+            // Load a binary file by file path.
+            var binaryData = mlContext.Data.LoadFromBinary("./sample-temp-data.idv");
+        }
+    }
+}

test/Microsoft.ML.Tests/Microsoft.ML.Tests.csproj

@@ -6,6 +6,7 @@
   </PropertyGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\src\Microsoft.Data.DataView\Microsoft.Data.DataView.csproj" />
     <ProjectReference Include="..\..\src\Microsoft.ML.Data\Microsoft.ML.Data.csproj" />
     <ProjectReference Include="..\..\src\Microsoft.ML.Ensemble\Microsoft.ML.Ensemble.csproj" />
     <ProjectReference Include="..\..\src\Microsoft.ML.EntryPoints\Microsoft.ML.EntryPoints.csproj" />
@@ -46,6 +47,7 @@
     <NativeAssemblyReference Condition="'$(OS)' != 'Windows_NT'" Include="tensorflow_framework" />
   </ItemGroup>
   <ItemGroup>
+    <PackageReference Include="Microsoft.Data.DataView" Version="0.10.0" />
     <PackageReference Include="Microsoft.ML.TensorFlow.TestModels" Version="$(MicrosoftMLTensorFlowTestModelsVersion)" />
     <PackageReference Include="Microsoft.ML.Onnx.TestModels" Version="$(MicrosoftMLOnnxTestModelsVersion)" />
   </ItemGroup>

test/Microsoft.ML.Tests/Scenarios/Api/CookbookSamples/CookbookSamplesDynamicApi.cs

@@ -506,6 +506,45 @@ public override Action<InputRow, OutputRow> GetMapping()
             }
         }
 
+        public class IrisData
+        {
+            public float Label { get; set; }
+            public float SepalLength { get; set; }
+            public float SepalWidth { get; set; }
+            public float PetalLength { get; set; }
+            public float PetalWidth { get; set; }
+        }
+
+        [Fact]
+        public void ReadAndWriteBinaryData() =>
+            BinaryData();
+
+        private void BinaryData()
+        {
+            // An array of iris data points
+            var dataArray = new[]
+            {
+                new IrisData { Label=1, PetalLength=1, SepalLength=1, PetalWidth=1, SepalWidth=1 },
+                new IrisData { Label=0, PetalLength=2, SepalLength=2, PetalWidth=2, SepalWidth=2 }
+            };
+
+            // Create the ML.NET context.
+            var context = new MLContext();
+
+            // Create the data view from an IEnumerable.
+            // This method will use the definition of IrisData to understand what columns there are 
+            // in the data view. However, the objects in ML.NET are only "promises" of data since 
+            // ML.NET operations are lazy. One way to get a look at the data is with Schema Comprehension.
+            // Refer to this document for more information - https://github.com/dotnet/machinelearning/blob/master/docs/code/SchemaComprehension.md
+            var data = context.Data.LoadFromEnumerable(dataArray);
+
+            // Use a FileStream to create a file. Use the stream and the data view in the "SaveAsBinary" method.
+            using (var stream = new FileStream("./iris.idv", FileMode.Create))
+            {
+                context.Data.SaveAsBinary(data, stream);
+            }
+        }
+
         private static void RunEndToEnd(MLContext mlContext, IDataView trainData, string modelPath)
         {
             // Construct the learning pipeline. Note that we are now providing a contract name for the custom mapping: