From 87f1eefcf982f6242834ce90cc46dc7f343abee6 Mon Sep 17 00:00:00 2001 From: Christoph Ruegg Date: Wed, 23 Jul 2014 13:13:10 +0200 Subject: [PATCH] Data: docs --- docs/content/CSV.fsx | 17 +++--- docs/content/MatlabFiles.fsx | 90 ++++++++++++++++++++++++++++ docs/content/MatrixMarket.fsx | 62 +++++++++++++++++++ docs/tools/templates/template.cshtml | 6 +- 4 files changed, 165 insertions(+), 10 deletions(-) create mode 100644 docs/content/MatlabFiles.fsx create mode 100644 docs/content/MatrixMarket.fsx diff --git a/docs/content/CSV.fsx b/docs/content/CSV.fsx index f8bcb746..c379b2ad 100644 --- a/docs/content/CSV.fsx +++ b/docs/content/CSV.fsx @@ -32,11 +32,12 @@ Reading a matrix from a delimited file -------------------------------------- The `DelimitedReader` class provides static functions to read a matrix from a file or string in delimited form. +It can read from: -* **Read**: read from a TextReader. If you have your delimited data already in memory in a string, +* **TextReader**: If you have your delimited data already in memory in a string, you can use this method using a StringReader. -* **ReadStream**: read directly from a stream, e.g. a MemoryStream, FileStream or NetworkStream. -* **ReadFile**: read from a file, specified by the file system path. +* **Stream**: read directly from a stream, e.g. a MemoryStream, FileStream or NetworkStream. +* **File Path (string)**: read from a file, specified by the file system path. All these functions expect the data type of the matrix to be generated as generic type argument. Only Double, Single, Complex and Complex32 are supported. @@ -44,6 +45,8 @@ Only Double, Single, Complex and Complex32 are supported. Example: [lang=csharp] + using MathNet.Numerics.Data.Text; + Matrix matrix = DelimitedReader.Read("data.csv", false, ",", true); Unfortunately the lack of standard means that the parsing logic needs to be parametrized accordingly. @@ -64,7 +67,7 @@ but for simplicity the Read functions expects those parameters explicitly as opt Writing a matrix to a delimited file ------------------------------------ -The dual to the delimiter above is the `DelimitedWriter` class that can serialize a matrix +The dual to the reader above is the `DelimitedWriter` class that can serialize a matrix to a delimited text file, stream or TextWriter. The static Write functions accept the following optional arguments to control the output format: @@ -82,7 +85,7 @@ The static Write functions accept the following optional arguments to control th Example: [lang=csharp] - DelimitedWriter.WriteFile(matrix, "data.csv", ","); + DelimitedWriter.Write("data.csv", matrix, ","); Alternatives @@ -91,7 +94,7 @@ Alternatives The data extension packages also offer other ways to serialize a matrix to a binary stream or file. Among others: -* NIST MatrixMarket text files -* MATLAB mat files +* [NIST MatrixMarket text files](MatrixMarket.html) +* [MATLAB Level-5 Mat files](MatlabFiles.html) *) diff --git a/docs/content/MatlabFiles.fsx b/docs/content/MatlabFiles.fsx new file mode 100644 index 00000000..225bf2a5 --- /dev/null +++ b/docs/content/MatlabFiles.fsx @@ -0,0 +1,90 @@ +(*** hide ***) +#I "../../out/lib/net40" +#r "MathNet.Numerics.dll" +#r "MathNet.Numerics.FSharp.dll" + +(** +MATLAB Level-5 Mat Files +======================== + +Level-5 MATLAB Mat files are popular as binary file container for storing one or more matrices. +Math.NET Numerics provides basic support for such Mat files with the **MathNet.Numerics.Data.Matlab** package, +which is available on NuGet as separate package and not included in the basic distribution. + + +Reading matrices from a MATLAB file +----------------------------------- + +The `MatlabReader` class provides static functions to list all matrices stored in a MAT file or stream, +and to read them individually as Math.NET matrices: + + [lang=csharp] + using MathNet.Numerics.LinearAlgebra; + using MathNet.Numerics.Data.Matlab; + + // read the first matrix as double + Matrix m = MatlabReader.Read("collection.mat"); + + // read a specific matrix named "vd": + Matrix m = MatlabReader.Read("collection.mat", "vd"); + + // we can also choose to convert to a different type: + Matrix m = MatlabReader.Read("collection.mat"); + + // read all matrices of a file by name into a dictionary + Dictionary> ms = + MatlabReader.ReadAll("collection.mat"); + + // read the matrices named "Ad" and "vd" into a dictionary + var ms = MatlabReader.ReadAll("collection.mat", "vd", "Ad"); + +Alternatively the reader can list all matrices of a file into named data elements, +which can then be read into matrices individually. This is useful e.g. if we need to +read some of the matrices to a different type: + + [lang=csharp] + List ms = MatlabReader.List("collection.mat"); + Matrix Ad = MatlabReader.Unpack(ms.Find(m => m.Name == "Ad")); + Matrix vd = MatlabReader.Unpack(ms.Find(m => m.Name == "vd")); + + +Writing matrices to a MATLAB file +--------------------------------- + +The dual to the reader above is the `MatlabWriter` class that can serialize matrices +to a MATLAB file or stream. Like the reader, the writer can use `MatlabMatrix` data elements +to compose packed matrices into a file. Each matrix has a name which must not contain spaces. + + [lang=csharp] + var matrices = new List(); + m.Add(MatlabWriter.Pack(myFirstMatrix, "m1"); + m.Add(MatlabWriter.Pack(mySecondMatrix, "m2"); + MatlabWrier.Store("file.mat", matrices); + +But there are also direct routines if only a single matrix or matrices of all the same data type +are to be stored in a file: + + [lang=csharp] + // write a single matrix "myMatrix" and name it "m1". + MatlabWriter.Write("file.mat", myMatrix, "m1"); + + // write multiple matrices, from a list of matrices and a list of their names: + MatlabWriter.Write("file.mat", new[] { m1, m2 }, new[] { "m1", "m2" }); + + // write a dictionary of matrices: + var dict = new Dictionary>(); + dict.Add("m1", m1); + dict.Add("m2", m2); + MatlabWriter.Write("file.mat", dict); + + +Alternatives +------------ + +The data extension packages also offer other ways to serialize a matrix to a text file. +Among others: + +* [Delimited Text Files (CSV & TSV)](CSV.html) +* [NIST MatrixMarket text files](MatrixMarket.html) + +*) diff --git a/docs/content/MatrixMarket.fsx b/docs/content/MatrixMarket.fsx new file mode 100644 index 00000000..730202ea --- /dev/null +++ b/docs/content/MatrixMarket.fsx @@ -0,0 +1,62 @@ +(*** hide ***) +#I "../../out/lib/net40" +#r "MathNet.Numerics.dll" +#r "MathNet.Numerics.FSharp.dll" + +(** +NIST MatrixMarket Text Files +============================ + +MatrixMarket is both a [vast repository of test data](http://math.nist.gov/MatrixMarket/) +and a text-based [exchange file format](http://math.nist.gov/MatrixMarket/formats.html) provided by NIST. +Being text-based makes it convenient to deal with and program against, and also works well with versioning +tools like [Git](http://www.git-scm.com/). But other than [CSV](CSV.html) it can also store sparse matrices in a compact way. + +Math.NET Numerics provides basic support for MatrixMarket files with the **MathNet.Numerics.Data.Text** package, +which is available on NuGet as separate package and not included in the basic distribution. + + +Reading a matrix from a MatrixMarket file +----------------------------------------- + +The `MatrixMarketReader` class provides static functions to read a matrix or a vector from a file or string. +It can read from: + +* **TextReader**: If you have your delimited data already in memory in a string, + you can use this method using a StringReader. +* **Stream**: read directly from a stream, e.g. a MemoryStream, FileStream or NetworkStream. +* **File Path (string)**: read from a file, specified by the file system path. Optionally GZip compressed. + +All these functions expect the data type of the matrix to be generated as generic type argument. +Only Double, Single, Complex and Complex32 are supported. + +Example: + + [lang=csharp] + using MathNet.Numerics.Data.Text; + + Matrix matrix = MatrixMarketReader.ReadMatrix("fidap007.mtx"); + + +Writing a matrix to a MatrixMarket file +--------------------------------------- + +The dual to the reader above is the `MatrixMarketWriter` class that can serialize a matrix or vector +to a MatrixMarket text file, stream or TextWriter. + +Example: + + [lang=csharp] + MatrixMarketWriter.WriteMatrix("matrix.mtx", m); + + +Alternatives +------------ + +The data extension packages also offer other ways to serialize a matrix to a binary stream or file. +Among others: + +* [Delimited Text Files (CSV & TSV)](CSV.html) +* [MATLAB Level-5 Mat files](MatlabFiles.html) + +*) diff --git a/docs/tools/templates/template.cshtml b/docs/tools/templates/template.cshtml index 6143a13b..98d9c1ce 100644 --- a/docs/tools/templates/template.cshtml +++ b/docs/tools/templates/template.cshtml @@ -86,7 +86,7 @@
  • Linear Least Squares
  • Nonlinear Optimization
  • Distance Metrics
    • - +
  • Curve Fitting
  • Regression
  • Interpolation
    • @@ -97,11 +97,11 @@
  • Working Together
  • Delimited Text Files (CSV)
    • -
  • NIST MatrixMarket
    • +
  • NIST MatrixMarket
    • +
  • MATLAB
  • FsLab & Deedle
  • Microsoft Excel
  • numl.net machine learning
    • -
  • MATLAB
  • R-project