Added: systemml/site/docs/1.1.0/dml-language-reference.html URL: http://svn.apache.org/viewvc/systemml/site/docs/1.1.0/dml-language-reference.html?rev=1828046&view=auto ============================================================================== --- systemml/site/docs/1.1.0/dml-language-reference.html (added) +++ systemml/site/docs/1.1.0/dml-language-reference.html Fri Mar 30 04:31:05 2018 @@ -0,0 +1,3374 @@ +<!DOCTYPE html> +<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]--> +<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]--> +<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]--> +<!--[if gt IE 8]><!--> <html class="no-js"> <!--<![endif]--> + <head> + <title>Declarative Machine Learning (DML) Language Reference - SystemML 1.1.0</title> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> + + <meta name="description" content="Declarative Machine Learning (DML) Language Reference"> + + <meta name="viewport" content="width=device-width"> + <link rel="stylesheet" href="css/bootstrap.min.css"> + <link rel="stylesheet" href="css/main.css"> + <link rel="stylesheet" href="css/pygments-default.css"> + <link rel="shortcut icon" href="img/favicon.png"> + </head> + <body> + <!--[if lt IE 7]> + <p class="chromeframe">You are using an outdated browser. <a href="http://browsehappy.com/";>Upgrade your browser today</a> or <a href="http://www.google.com/chromeframe/?redirect=true";>install Google Chrome Frame</a> to better experience this site.</p> + <![endif]--> + + <header class="navbar navbar-default navbar-fixed-top" id="topbar"> + <div class="container"> + <div class="navbar-header"> + <div class="navbar-brand brand projectlogo"> + <a href="http://systemml.apache.org/";><img class="logo" src="img/systemml-logo.png" alt="Apache SystemML" title="Apache SystemML"/></a> + </div> + <div class="navbar-brand brand projecttitle"> + <a href="http://systemml.apache.org/";>Apache SystemML<sup id="trademark">â¢</sup></a><br/> + <span class="version">1.1.0</span> + </div> + <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target=".navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + </div> + <nav class="navbar-collapse collapse"> + <ul class="nav navbar-nav navbar-right"> + <li><a href="index.html">Overview</a></li> + <li><a href="https://github.com/apache/systemml";>GitHub</a></li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation<b class="caret"></b></a> + <ul class="dropdown-menu" role="menu"> + <li><b>Running SystemML:</b></li> + <li><a href="https://github.com/apache/systemml";>SystemML GitHub README</a></li> + <li><a href="spark-mlcontext-programming-guide.html">Spark MLContext</a></li> + <li><a href="spark-batch-mode.html">Spark Batch Mode</a> + <li><a href="hadoop-batch-mode.html">Hadoop Batch Mode</a> + <li><a href="standalone-guide.html">Standalone Guide</a></li> + <li><a href="jmlc.html">Java Machine Learning Connector (JMLC)</a> + <li class="divider"></li> + <li><b>Language Guides:</b></li> + <li><a href="dml-language-reference.html">DML Language Reference</a></li> + <li><a href="beginners-guide-to-dml-and-pydml.html">Beginner's Guide to DML and PyDML</a></li> + <li><a href="beginners-guide-python.html">Beginner's Guide for Python Users</a></li> + <li><a href="python-reference.html">Reference Guide for Python Users</a></li> + <li class="divider"></li> + <li><b>ML Algorithms:</b></li> + <li><a href="algorithms-reference.html">Algorithms Reference</a></li> + <li class="divider"></li> + <li><b>Tools:</b></li> + <li><a href="debugger-guide.html">Debugger Guide</a></li> + <li><a href="developer-tools-systemml.html">IDE Guide</a></li> + <li class="divider"></li> + <li><b>Other:</b></li> + <li><a href="contributing-to-systemml.html">Contributing to SystemML</a></li> + <li><a href="engine-dev-guide.html">Engine Developer Guide</a></li> + <li><a href="troubleshooting-guide.html">Troubleshooting Guide</a></li> + <li><a href="release-process.html">Release Process</a></li> + </ul> + </li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">API Docs<b class="caret"></b></a> + <ul class="dropdown-menu" role="menu"> + <li><a href="./api/java/index.html">Java</a></li> + <li><a href="./api/python/index.html">Python</a></li> + </ul> + </li> + + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Issues<b class="caret"></b></a> + <ul class="dropdown-menu" role="menu"> + <li><b>JIRA:</b></li> + <li><a href="https://issues.apache.org/jira/browse/SYSTEMML";>SystemML JIRA</a></li> + + </ul> + </li> + </ul> + </nav> + </div> + </header> + + <div class="container" id="content"> + + <h1 class="title">Declarative Machine Learning (DML) Language Reference</h1> + + + <!-- + +--> + +<h3 id="table-of-contents">Table of Contents</h3> + +<ul> + <li><a href="dml-language-reference.html#introduction">Introduction</a></li> + <li><a href="dml-language-reference.html#variables">Variables</a> + <ul> + <li><a href="dml-language-reference.html#identifier-names">Identifier Names</a></li> + <li><a href="dml-language-reference.html#data-types">Data Types</a></li> + <li><a href="dml-language-reference.html#comments">Comments</a></li> + </ul> + </li> + <li><a href="dml-language-reference.html#expressions">Expressions</a> + <ul> + <li><a href="dml-language-reference.html#operators">Operators</a></li> + <li><a href="dml-language-reference.html#matrix-vector-operations">Matrix-Vector Operations</a></li> + <li><a href="dml-language-reference.html#matrix-indexing">Matrix Indexing</a></li> + </ul> + </li> + <li><a href="dml-language-reference.html#statements">Statements</a> + <ul> + <li><a href="dml-language-reference.html#assignment-statement">Assignment Statement</a></li> + <li><a href="dml-language-reference.html#control-statements">Control Statements</a> + <ul> + <li><a href="dml-language-reference.html#while-statement">While Statement</a></li> + <li><a href="dml-language-reference.html#if-statement">If Statement</a></li> + <li><a href="dml-language-reference.html#for-statement">For Statement</a></li> + <li><a href="dml-language-reference.html#parfor-statement">ParFor Statement</a></li> + </ul> + </li> + <li><a href="dml-language-reference.html#user-defined-function-udf">User-Defined Function (UDF)</a></li> + </ul> + </li> + <li><a href="dml-language-reference.html#variable-scoping">Variable Scoping</a></li> + <li><a href="dml-language-reference.html#command-line-arguments">Command-Line Arguments</a></li> + <li><a href="dml-language-reference.html#built-in-functions">Built-in Functions</a> + <ul> + <li><a href="dml-language-reference.html#matrix-construction-manipulation-and-aggregation-built-in-functions">Matrix Construction, Manipulation, and Aggregation Built-In Functions</a></li> + <li><a href="dml-language-reference.html#matrix-andor-scalar-comparison-built-in-functions">Matrix and/or Scalar Comparison Built-In Functions</a></li> + <li><a href="dml-language-reference.html#casting-built-in-functions">Casting Built-In Functions</a></li> + <li><a href="dml-language-reference.html#statistical-built-in-functions">Statistical Built-In Functions</a></li> + <li><a href="dml-language-reference.html#mathematical-and-trigonometric-built-in-functions">Mathematical and Trigonometric Built-In Functions</a></li> + <li><a href="dml-language-reference.html#linear-algebra-built-in-functions">Linear Algebra Built-In Functions</a></li> + <li><a href="dml-language-reference.html#readwrite-built-in-functions">Read/Write Built-In Functions</a></li> + <li><a href="dml-language-reference.html#data-pre-processing-built-in-functions">Data Pre-Processing Built-In Functions</a></li> + <li><a href="dml-language-reference.html#deep-learning-built-in-functions">Deep Learning Built-In Functions</a></li> + <li><a href="dml-language-reference.html#other-built-in-functions">Other Built-In Functions</a></li> + </ul> + </li> + <li><a href="dml-language-reference.html#frames">Frames</a> + <ul> + <li><a href="dml-language-reference.html#creating-frames">Creating Frames</a></li> + <li><a href="dml-language-reference.html#appending-frames">Appending Frames</a></li> + <li><a href="dml-language-reference.html#indexing-frames">Indexing Frames</a></li> + <li><a href="dml-language-reference.html#casting-frames">Casting Frames</a></li> + <li><a href="dml-language-reference.html#transforming-frames">Transforming Frames</a></li> + </ul> + </li> + <li><a href="dml-language-reference.html#modules">Modules</a></li> + <li><a href="dml-language-reference.html#reserved-keywords">Reserved Keywords</a></li> +</ul> + +<h2 id="introduction">Introduction</h2> + +<p>SystemML compiles scripts written in Declarative Machine Learning (or DML for short) into mixed driver and distributed jobs. DMLâs syntax closely follows R, thereby minimizing the learning curve to use SystemML. Before getting into detail, letâs start with a simple Hello World program in DML. Assuming that Spark is installed on your machine or cluster, place <code>SystemML.jar</code> into your directory. Now, create a text file <code>hello.dml</code> containing following code:</p> + +<pre><code>print("Hello World"); +</code></pre> + +<p>To run this program on your machine, use following command:</p> + +<pre><code>spark-submit SystemML.jar -f hello.dml +</code></pre> + +<p>The option <code>-f</code> in the above command refers to the path to the DML script. A detailed list of the +available options can be found running <code>spark-submit SystemML.jar -help</code>.</p> + +<h2 id="variables">Variables</h2> + +<h3 id="identifier-names">Identifier Names</h3> + +<p>Identifiers are case-sensitive (e.g., <code>var1</code>, <code>Var1</code>, and <code>VAR1</code> are different identifier names), must start with either an upper-case or lower-case letter, and may contain any alphanumeric character including underscore after the first letter. The reserved keywords described later cannot be used as identifier names. Though it is allowed, but not recommended to use built-in functions as an identifier. The only exceptions to this rule are five built-in functions: ‘as.scalar’, ‘as.matrix’, ‘as.double’, ‘as.integer’ and ‘as.logical’.</p> + +<h4 id="examples">Examples</h4> + +<pre><code>A      # valid variable name +_A     # invalid variable name -- starts with underscore +1_A    # invalid variable name -- starts with number +A_1    # valid variable name +min = 10 # valid but deprecated +</code></pre> + +<p>Before, proceeding ahead letâs run the Hello World program using variable:</p> + +<pre><code>helloStr = "Hello World" +print(helloStr) +</code></pre> + +<p>As seen in above example, there is no formal declaration of a variable. A variable is created when first assigned a value, and its type is inferred.</p> + +<h3 id="data-types">Data Types</h3> + +<p>Three data types (frame, matrix and scalar) and four value types (double, integer, string, and boolean) are supported. Matrices are 2-dimensional, and support the double value type (i.e., the cells in a matrix are of type double). The frame data type denotes the tabular data, potentially containing columns of value type numeric, string, and boolean. Frame functions are described in <a href="dml-language-reference.html#frames">Frames</a> and <a href="dml-language-reference.html#data-pre-processing-built-in-functions">Data Pre-Processing Built-In Functions</a>. SystemML supports type polymorphism for both data type (primarily, matrix and scalar types) and value type during evaluation. For example:</p> + +<pre><code># Spoiler alert: matrix() is a built-in function to +# create matrix, which will be discussed later +A = matrix(0, rows=10, cols=10) +B = 10 +C = B + sum(A) +print( "B:" + B + ", C:" + C + ", A[1,1]:" + as.scalar(A[1,1])) +</code></pre> + +<p>In the above script, we create three variables: <code>A</code>, <code>B</code> and <code>C</code> of type <code>matrix</code>, <code>scalar integer</code> and <code>scalar double</code> respectively. Since <code>A</code> is a <code>matrix</code>, it has to be converted to scalar using a built-in function <code>as.scalar</code>. In the above script the operator <code>+</code> used inside <code>print()</code> function, performs string concatenation. Hence, the output of above script is as follows:</p> + +<pre><code>B:10, C:10.0, A[1,1]:0.0 +</code></pre> + +<p>If instead of <code>as.scalar(A[1,1])</code> we would have used <code>A[1,1]</code>, then we will get an compilation error <code>print statement can only print scalars</code>.</p> + +<h3 id="comments">Comments</h3> + +<p>Two forms of commenting are supported: line and block comments. A line comment is indicated using a hash (<code>#</code>), and everything to the right of the hash is commented out. A block comment is indicated using “<code>/*</code>” to start the comment block and “<code>*/</code>” to end it.</p> + +<h4 id="examples-1">Examples</h4> + +<pre><code># this is an example of a line comment +/* this is an example of a +multi-line block comment +*/ +</code></pre> + +<hr /> + +<h2 id="expressions">Expressions</h2> + +<p>Now that we have familiarized ourselves with variables and data type, letâs understand how to use them in expressions.</p> + +<h3 id="operators">Operators</h3> + +<p>SystemML follows same associativity and precedence order as R as described in below table. The dimensions of the input matrices need to match the operator semantics, otherwise an exception will be raised at compile time. When one of the operands is a matrix and the other operand is a scalar value, the operation is performed cell-wise on the matrix using the scalar operand.</p> + +<p><strong>Table 1</strong>: Operators</p> + +<table> + <thead> + <tr> + <th style="text-align: center">Operator</th> + <th>Input</th> + <th>Output</th> + <th>Details</th> + </tr> + </thead> + <tbody> + <tr> + <td style="text-align: center">^</td> + <td>Matrix or Scalar</td> + <td>Matrix or Scalar<sup>1, 2</sup></td> + <td>Exponentiation (right associativity) â Highest precedence</td> + </tr> + <tr> + <td style="text-align: center">- +</td> + <td>Matrix or Scalar</td> + <td>Matrix or Scalar<sup>1</sup></td> + <td>Unary plus, minus</td> + </tr> + <tr> + <td style="text-align: center">%*%</td> + <td>Matrix</td> + <td>Matrix</td> + <td>Matrix multiplication</td> + </tr> + <tr> + <td style="text-align: center">%/% %%</td> + <td>Matrix or Scalar</td> + <td>Matrix or Scalar<sup>1, 2</sup></td> + <td>Integer division and Modulus operator</td> + </tr> + <tr> + <td style="text-align: center">/ *</td> + <td>Matrix or Scalar</td> + <td>Matrix or Scalar<sup>1, 2</sup></td> + <td>Multiplication and Division</td> + </tr> + <tr> + <td style="text-align: center">+ -</td> + <td>Matrix or Scalar</td> + <td>Matrix or Scalar<sup>1, 2</sup></td> + <td>Addition (or string concatenation) and Subtraction</td> + </tr> + <tr> + <td style="text-align: center">< > == != <= >=</td> + <td>Matrix or Scalar (any value type)</td> + <td>Matrix or Scalar<sup>1, 2</sup> (boolean type)</td> + <td>Relational operators</td> + </tr> + <tr> + <td style="text-align: center">& | !</td> + <td>Scalar</td> + <td>Scalar</td> + <td>Boolean operators (Note: operators && and || are not supported)</td> + </tr> + <tr> + <td style="text-align: center">=</td> + <td>-</td> + <td>-</td> + <td>Assignment (Lowest precendence). Note: associativity of assignment “a = b = 3” is not supported</td> + </tr> + </tbody> +</table> + +<p>1 If one of the operands is a matrix, output is matrix; otherwise it is scalar.</p> + +<p>2 Support for Matrix-vector operations</p> + +<h4 id="example">Example</h4> + +<pre><code>A = matrix(1, rows=2,cols=2) +B = matrix(3, rows=2,cols=2) +C = 10 +D = A %*% B + C * 2.1 +print( "D[1,1]:" + as.scalar(D[1,1])) +</code></pre> + +<p>Since matrix multiplication has higher precedence than scalar multiplication, which in turns has higher precedence than addition, the first cell of matrix <code>D</code> is evaluated as <code>((1*3)+(1*3))+(10*2.1) = 27.0</code>.</p> + +<h3 id="matrix-vector-operations">Matrix-Vector Operations</h3> + +<p>Arithmetic and relational operations described in above table support matrix-vector operations. This allows efficient cell-wise operations with either row or a column vector.</p> + +<h4 id="syntax">Syntax</h4> + +<pre><code>Input_Matrix operation Input_Vector +</code></pre> + +<h4 id="example-1">Example</h4> + +<pre><code>M + V or M > V, where M is a matrix and V is either row matrix or a column matrix. +</code></pre> + +<p>Matrix-Vector operation avoids need for creating replicated matrix for certain subset of operations. For example: to compute class conditional probabilities in Naïve-Bayes, without support for matrix-vector operations, one might write below given inefficient script that creates unnecessary and possibly huge replicatedClassSums.</p> + +<pre><code>ones = matrix(1, rows=1, cols=numFeatures) +repClassSums = classSums %*% ones +class_conditionals = (classFeatureCounts + laplace_correction) / repClassSums +</code></pre> + +<p>With support of matrix-vector operations, the above script becomes much more efficient as well as concise:</p> + +<pre><code>class_conditionals = (classFeatureCounts + laplace_correction) / classSums +</code></pre> + +<h3 id="matrix-indexing">Matrix Indexing</h3> + +<p>Each matrix has a specified number of rows and columns. A 1x1 matrix is not equivalent to a scalar double. The first index for both row and columns in a matrix is 1. For example, a matrix with 10 rows and 10 columns would have rows numbered 1 to 10, and columns numbered 1 to 10.</p> + +<p>The elements of the matrix can be accessed by matrix indexing, with both row and column indices required. The indices must either be an expression evaluating to a positive numeric (integer or double) scalar value, or blank. To select the entire row or column of a matrix, leave the appropriate index blank. If a double value is used for indexing, the index value is implicitly cast to an integer with floor (value+eps) in order to account for double inaccuracy (see IEEE754, double precision, eps=pow(2,-53)).</p> + +<h4 id="examples-2">Examples</h4> + +<pre><code>X[1,4] # access cell in row 1, column 4 of matrix X +X[i,j] # access cell in row i, column j of X. +X[1,] # access the 1st row of X +X[,2] # access the 2nd column of X +X[,] # access all rows and columns of X +</code></pre> + +<p>Range indexing is supported to access a contiguous block of rows and columns in the matrix. The grammar for range-based indexing is below. The constraint is that lower-row < upper-row, and lower-column < upper-column.</p> + +<pre><code>[Matrix name][lower-row : upper-row],[lower-column : upper-column] +</code></pre> + +<h4 id="examples-3">Examples</h4> + +<pre><code>X[1:4, 1:4] # access the 4 x 4 submatrix comprising columns 1 â 4 of rows 1 â 4 of X +X[1:4, ] # select the first 4 rows of X +X[1:, ] # incorrect format +</code></pre> + +<hr /> + +<h2 id="statements">Statements</h2> + +<p>A script is a sequence of statements with the default computation semantics being sequential evaluation of the individual statements. The use of a semi-colon at the end of a statement is optional. The types of statements supported are</p> + +<ul> + <li>assignment,</li> + <li>control structures (while, if, for), and</li> + <li>user-defined function declaration.</li> +</ul> + +<h3 id="assignment-statement">Assignment Statement</h3> + +<p>An assignment statement consists of an expression, the result of which is assigned to a variable. The variable gets the appropriate data type (matrix or scalar) and value type (double, int, string, boolean) depending on the type of the variable output by the expression.</p> + +<h4 id="examples-4">Examples</h4> + +<pre><code># max_iteration is of type integer +max_iteration = 3; +# V has data type matrix and value type double. +V = W %*% H; +</code></pre> + +<h3 id="control-statements">Control Statements</h3> + +<h4 id="while-statement">While Statement</h4> + +<p>The syntax for a while statement is as follows:</p> + +<pre><code>while (predicate) { + statement1 + statement2 + ... +} +</code></pre> + +<p>The statements in the while statement body are evaluated repeatedly until the predicate evaluates to TRUE. The while statement body must be surrounded by braces, even if the body only has a single statement. +The predicate in the while statement consist of operations on scalar variables and literals. The body of a while statement may contain any sequence of statements.</p> + +<h5 id="example-2">Example</h5> + +<pre><code>while ((i < 20) & (!converge)) { + H = H * (t(W) %*% V) / (t(W) %*% W %*% H); + W = W * (V %*% t(H)) / (W %*% H %*% t(H)); + i = i + 1; +} +</code></pre> + +<h4 id="if-statement">If Statement</h4> + +<p>The syntax for an if statement is as follows:</p> + +<pre><code>if (predicate1) { + statement1 + statement2 + ... +} [ else if (predicate2) { + statement1 + statement2 + ... +} ] [ else { + statement1 + statement2 + ... +} ] +</code></pre> + +<p>The If statement has three bodies: the <code>if</code> body (evaluated if predicate1 evaluates to TRUE), the optional <code>else if</code> body (evaluated if predicate2 evaluates to TRUE) and the optional <code>else</code> body (evaluated otherwise). There can be multiple <code>else if</code> bodies with different predicates but at most one <code>else</code> body. The bodies may contain any sequence of statements. If only a single statement is enclosed in a body, the braces surrounding the statement can be omitted.</p> + +<h5 id="examples-5">Examples</h5> + +<pre><code># example of if statement +if (i < 20) { + converge = FALSE; +} else { + converge = TRUE; +} +# example of nested control structures +while (!converge) { + H = H * (t(W) %*% V) / (t(W) %*% W %*% H); + W = W * (V %*% t(H)) / (W %*% H %*% t(H)); + i = i + 1; + zerror = sum(z - W %*% H); + if (zerror < maxError) { + converge = TRUE; + } else { + converge = FALSE; + } +} +</code></pre> + +<h4 id="for-statement">For Statement</h4> + +<p>The syntax for a for statement is as follows.</p> + +<pre><code>for (var in <for_predicate> ) { + <statement>* +} +<for_predicate> ::= [lower]:[upper] | seq ([lower], [upper], [increment]) +</code></pre> + +<p>var is an integer scalar variable. lower, upper, and increment are integer expressions.</p> + +<p>Similarly, <code>seq([lower],[upper],[increment])</code> defines a sequence of numbers: {lower, lower + increment, lower + 2(increment), ⦠}. For each element in the sequence, var is assigned the value, and statements in the for loop body are executed.</p> + +<p>The for loop body may contain any sequence of statements. The statements in the for statement body must be surrounded by braces, even if the body only has a single statement.</p> + +<h5 id="example-3">Example</h5> + +<pre><code># example for statement +A = 5; +for (i in 1:20) { + A = A + 1; +} +</code></pre> + +<h4 id="parfor-statement">ParFor Statement</h4> + +<p>The syntax and semantics of a <code>parfor</code> (parallel <code>for</code>) statement are equivalent to a <code>for</code> statement except for the different keyword and a list of optional parameters.</p> + +<pre><code>parfor (var in <for_predicate> <parfor_paramslist> ) { + <statement>* +} + +<parfor_paramslist> ::= <,<parfor_parameter>>* +<parfor_parameter> :: + = check = <dependency_analysis> +|| = par = <degree_of_parallelism> +|| = mode = <execution_mode> +|| = taskpartitioner = <task_partitioning_algorithm> +|| = tasksize = <task_size> +|| = datapartitioner = <data_partitioning_mode> +|| = resultmerge = <result_merge_mode> +|| = opt = <optimization_mode> +|| = log = <log_level> +|| = profile = <monitor> + +<dependency_analysis> 0 1 +<degree_of_parallelism> arbitrary integer number +<execution_mode> LOCAL REMOTE_MR REMOTE_MR_DP REMOTE_SPARK REMOTE_SPARK_DP +<task_partitioning_algorithm> FIXED NAIVE STATIC FACTORING FACTORING_CMIN FACTORING_CMAX +<task_size> arbitrary integer number +<data_partitioning_mode> NONE LOCAL REMOTE_MR REMOTE_SPARK +<result_merge_mode> LOCAL_MEM LOCAL_FILE LOCAL_AUTOMATIC REMOTE_MR REMOTE_SPARK +<optimization_mode> NONE RULEBASED CONSTRAINED HEURISTIC GREEDY FULL_DP +<log_level> ALL TRACE DEBUG INFO WARN ERROR FATAL OFF +<monitor> 0 1 +</code></pre> + +<p>If any of these parameters is not specified, the following respective defaults are used:</p> + +<p><strong>Table 2</strong>: Parfor default parameter values</p> + +<table> + <thead> + <tr> + <th>Parameter Name</th> + <th>Default Value</th> + </tr> + </thead> + <tbody> + <tr> + <td>check</td> + <td>1</td> + </tr> + <tr> + <td>par</td> + <td>[number of virtual processors on master node]</td> + </tr> + <tr> + <td>mode</td> + <td>LOCAL</td> + </tr> + <tr> + <td>taskpartitioner</td> + <td>FIXED</td> + </tr> + <tr> + <td>tasksize</td> + <td>1</td> + </tr> + <tr> + <td>datapartitioner</td> + <td>NONE</td> + </tr> + <tr> + <td>resultmerge</td> + <td>LOCAL_AUTOMATIC</td> + </tr> + <tr> + <td>opt</td> + <td>RULEBASED</td> + </tr> + <tr> + <td>log</td> + <td>INFO</td> + </tr> + <tr> + <td>profile</td> + <td>0</td> + </tr> + </tbody> +</table> + +<p>Of particular note is the <code>check</code> parameter. SystemML’s <code>parfor</code> statement by default (<code>check = 1</code>) performs dependency analysis in an +attempt to guarantee result correctness for parallel execution. For example, the following <code>parfor</code> statement is <strong>incorrect</strong> because +the iterations do not act independently, so they are not parallelizable. The iterations incorrectly try to increment the same <code>sum</code> variable.</p> + +<pre><code>sum = 0 +parfor (i in 1:3) { + sum = sum + i; # not parallelizable - generates error +} +print(sum) +</code></pre> + +<p>SystemML’s <code>parfor</code> dependency analysis can occasionally result in false positives, as in the following example. This example creates a 2x30 +matrix. It then utilizes a <code>parfor</code> loop to write 10 2x3 matrices into the 2x30 matrix. This <code>parfor</code> statement is parallelizable and correct, +but the dependency analysis generates a false positive dependency error for the variable <code>ms</code>.</p> + +<pre><code>ms = matrix(0, rows=2, cols=3*10) +parfor (v in 1:10) { # parallelizable - false positive + mv = matrix(v, rows=2, cols=3) + ms[,(v-1)*3+1:v*3] = mv +} +</code></pre> + +<p>If a false positive arises but you are certain that the <code>parfor</code> is parallelizable, the <code>parfor</code> dependency check can be disabled via +the <code>check = 0</code> option.</p> + +<pre><code>ms = matrix(0, rows=2, cols=3*10) +parfor (v in 1:10, check=0) { # parallelizable + mv = matrix(v, rows=2, cols=3) + ms[,(v-1)*3+1:v*3] = mv +} +</code></pre> + +<p>While developing DML scripts or debugging, it can be useful to <strong>turn off <code>parfor</code> parallelization</strong>. This can be accomplished in the following +three ways:</p> + +<ol> + <li>Replace <code>parfor()</code> with <code>for()</code>. Since <code>parfor</code> is derived from <code>for</code>, you can always use <code>for</code> wherever you can use <code>parfor</code>.</li> + <li><code>parfor(opt = NONE, par = 1, ...)</code>. This disables optimization, uses defaults, and overwrites the specified parameters.</li> + <li><code>parfor(opt = CONSTRAINED, par = 1, ...)</code>. This optimizes using the specified parameters.</li> +</ol> + +<h3 id="user-defined-function-udf">User-Defined Function (UDF)</h3> + +<p>The UDF function declaration statement provides the function signature, which defines the formal parameters used to call the function and return values for the function. The function definition specifies the function implementation, and can either be a sequence of statements or external packages / libraries. If the UDF is implemented in a SystemML script, then UDF declaration and definition occur together.</p> + +<p>The syntax for the UDF function declaration is given as follows. The function definition is stored as a list of statements in the function body. The explanation of the parameters is given below. Any statement can be placed inside a UDF definition except UDF function declaration statements. The variables specified in the return clause will be returned, and no explicit return statement within the function body is required.</p> + +<pre><code>functionName = function([ <DataType>? <ValueType> <var>, ]* ) + return ([ <DataType>? <ValueType> <var>,]*) { + # function body definition in DML + statement1 + statement2 + ... +} +</code></pre> + +<p>The syntax for the UDF function declaration for functions defined in external packages/ ibraries is given as follows. The parameters are explained below. The main difference is that a user must specify the appropriate collection of userParam=value pairs for the given external package. Also, one of the userParam should be âclassnameâ.</p> + +<pre><code>functionName = externalFunction( + [<DataType>? <ValueType> <var>, ]* ) +return ([<DataType>? <ValueType> <var>,]*) +implemented in ([userParam=value]*) +</code></pre> + +<p><strong>Table 3</strong>: Parameters for UDF Function Definition Statements</p> + +<table> + <thead> + <tr> + <th>Parameter Name</th> + <th>Description</th> + <th>Optional</th> + <th>Permissible Values</th> + </tr> + </thead> + <tbody> + <tr> + <td>functionName</td> + <td>Name of the function.</td> + <td>No</td> + <td>Any non-keyword string</td> + </tr> + <tr> + <td>DataType</td> + <td>The data type of the identifier for a formal parameter or return value.</td> + <td>If the value value is scalar or object, then DataType is optional</td> + <td>matrix, scalar, object (capitalization does not matter)</td> + </tr> + <tr> + <td>ValueType</td> + <td>The value type of the identifier for a formal parameter or return value.</td> + <td>No. The value type object can only use used with data type object.</td> + <td>double, integer, string, boolean, object</td> + </tr> + <tr> + <td>Var</td> + <td>The identifier for a formal parameter or return value.</td> + <td>No</td> + <td>Any non-keyword sting</td> + </tr> + <tr> + <td>userParam=value</td> + <td>User-defined parameter to invoke the package.</td> + <td>Yes</td> + <td>Any non-keyword string</td> + </tr> + </tbody> +</table> + +<h4 id="examples-6">Examples</h4> + +<pre><code># example of a UDF defined in DML +mean = function (matrix[double] A) return (double m) { + m = sum(A)/nrow(A) +} + +# example of a UDF defined in DML with multiple return values +minMax = function( matrix[double] M) return (double minVal, double maxVal) { + minVal = min(M); + maxVal = max(M); +} + +# example of an external UDF +time = externalFunction(Integer i) return (Double B) + implemented in (classname="org.apache.sysml.udf.lib.TimeWrapper", exectype="mem"); +t = time(1); +print("Time: " + t); +</code></pre> + +<p>A UDF invocation specifies the function identifier, variable identifiers for calling parameters, and the variables to be populated by the returned values from the function. The syntax for function calls is as follows.</p> + +<pre><code>returnVal = functionName(param1, param2, ...) +[returnVal1, returnVal2, ...] = functionName(param1, param2, ...) +</code></pre> + +<h4 id="examples-7">Examples</h4> + +<pre><code># DML script with a function call +B = matrix(0, rows = 10,cols = 10); +C = matrix(0, rows = 100, cols = 100); +D = addEach(1, C); +index = 0; +while (index < 5) { + [minD, maxD] = minMax(D); + index = index + 1 +} +</code></pre> + +<h2 id="variable-scoping">Variable Scoping</h2> + +<p>DML supports following two types of scoping: + 1. Default: All the variables are bound to global unbounded scope. + 2. Function scope: Only the variables specified in the function declaration can be accessed inside function.</p> + +<p>Note: The command-line parameters are treated as constants which are introduced during parse-time.</p> + +<h3 id="example-of-default-scope">Example of Default Scope</h3> + +<pre><code>if(1!=0) { + A = 1; +} +print("A:" + A); +</code></pre> + +<p>This will result in parser warning, but the program will run to completion. If the expression in the “if” predicate would have evaluated to FALSE, it would have resulted in runtime error. Also, functions need not be defined prior to its call. That is: following code will work without parser warning:</p> + +<pre><code>A = 2; +C = foo(1, A) +print("C:" + C); +foo = function(double A, double B) return (double C) { + C = A + B; +} +</code></pre> + +<h3 id="example-of-function-scope">Example of Function Scope</h3> + +<pre><code>A = 2; +D = 1; +foo = function(double A, double B) return (double C) { + A = 3.0; # value of global A wonât change since it is pass by value + + C = A + B # Note: C = A + D will result in compilation error +} +C = foo(A, 1) +print("C:" + C + " A:" + A); +</code></pre> + +<p>The above code will output: <code>C:4.0 A:2</code></p> + +<h2 id="command-line-arguments">Command-Line Arguments</h2> + +<p>Since most algorithms require arguments to be passed from command line, DML supports command-line arguments. The command line parameters are treated as constants (similar to arguments passed to main function of a java program). The command line parameters can be passed in two ways:</p> + +<ol> + <li> + <p>As named arguments (recommended):</p> + + <p><code>-nvargs param1=7 param2="abc" param3=3.14</code></p> + </li> + <li> + <p>As positional arguments (deprecated):</p> + + <p><code>-args 7 "abc" 3.14</code></p> + </li> +</ol> + +<p>The named arguments can be accessed by adding “\$” before the parameter name, i.e. \$param1. On the other hand, the positional parameter are accessible by adding “\$” before their positions (starting from index 1), i.e. \$1. A string parameter can be passed without quote. For example, <code>param2=abc</code> is valid argument, but it is not recommend.</p> + +<p>Sometimes the user would want to support default values in case user does not explicitly pass the corresponding command line parameter (in below example: <code>$nbrRows</code>). To do so, we use the <code>ifdef</code> function which assigns either command line parameter or the default value to the local parameter.</p> + +<pre><code>local_variable = ifdef(command line variable, default value) +</code></pre> + +<h3 id="example-script-in-file-testdml">Example: Script in file test.dml</h3> + +<pre><code>localVar_nbrRows=ifdef($nbrRows , 10) +M = rand (rows = localVar_nbrRows, cols = $nbrCols) +write (M, $fname, format="csv") +print("Done creating and writing random matrix in " + $fname) +</code></pre> + +<p>In above script, <code>ifdef(\$nbrRows, 10)</code> function is a short-hand for “<code>ifdef(\$nbrRows) then \$nbrRows else 10</code>”.</p> + +<p>Letâs assume that the above script is invoked using following the command line values:</p> + +<pre><code>spark-submit SystemML.jar -f test.dml -nvargs fname=test.mtx nbrRows=5 nbrCols=5 +</code></pre> + +<p>In this case, the script will create a random matrix M with 5 rows and 5 columns and write it to the file “text.mtx” in csv format. After that it will print the message “Done creating and writing random matrix in test.mtx” on the standard output.</p> + +<p>If however, the above script is invoked from the command line using named arguments:</p> + +<pre><code>spark-submit SystemML.jar -f test.dml -nvargs fname=test.mtx nbrCols=5 +</code></pre> + +<p>Then, the script will instead create a random matrix M with 10 rows (i.e. default value provided in the script) and 5 columns.</p> + +<p>It is important to note that the placeholder variables should be treated like constants that are initialized once, either via command line-arguments or via default values at the beginning of the script.</p> + +<p>Each argValue passed from the command-line has a scalar data type, and the value type for argValue is inferred using the following logic:</p> + +<pre><code>if (argValue can be cast as Integer) + Assign argValue integer value type +else if (argValue can be cast as Double) + Assign argValue double value type +else if (argValue can be cast as Boolean) + Assign argValue boolean value type +else + Assign argValue string value type +</code></pre> + +<p>In above example, the placeholder variable <code>\$nbrCols</code> will be treated as integer in the script. If however, the command line arguments were “<code>nbrCols=5.0</code>”, then it would be treated as a double.</p> + +<p>NOTE: argName must be a valid identifier. +NOTE: If argValue contains spaces, it must be enclosed in double-quotes. +NOTE: The values passed from the command-line are passed as literal values which replace the placeholders in the DML script, and are not interpreted as DML.</p> + +<h2 id="built-in-functions">Built-In Functions</h2> + +<p>Built-in functions are categorized in:</p> + +<ul> + <li>Matrix Construction, Manipulation, and Aggregation Built-In Functions</li> + <li>Matrix and/or Scalar Comparison Built-In Functions</li> + <li>Casting Built-In Functions</li> + <li>Statistical Built-In Functions</li> + <li>Mathematical and Trigonometric Built-In Functions</li> + <li>Linear Algebra Built-In Functions</li> + <li>Other Built-In Functions</li> +</ul> + +<p>The tables below list the supported built-in functions. +For example, consider the following expressions:</p> + +<pre><code>s = sum(A); +B = rowSums(A); +C = colSums(A); +D = rowSums(C); +diff = s â as.scalar(D); +</code></pre> + +<p>The builtin function <code>sum</code> operates on a matrix (say A of dimensionality (m x n)) and returns a scalar value corresponding to the sum of all values in the matrix. The built-in functions <code>rowSums</code> and <code>colSums</code>, on the other hand, aggregate values on a per-row and per-column basis respectively. They output matrices of dimensionality (m x 1) and 1xn, respectively. Therefore, B is a m x 1 matrix and C is a 1 x n matrix. Applying <code>rowSums</code> on matrix C, we obtain matrix D as a 1 x 1 matrix. A 1 x 1 matrix is different from a scalar; to treat D as a scalar, an explicit <code>as.scalar</code> operation is invoked in the final statement. The difference between s and <code>as.scalar(D)</code> should be 0.</p> + +<h3 id="matrix-construction-manipulation-and-aggregation-built-in-functions">Matrix Construction, Manipulation, and Aggregation Built-In Functions</h3> + +<p><strong>Table 4</strong>: Matrix Construction, Manipulation, and Aggregation Built-In Functions</p> + +<table> + <thead> + <tr> + <th>Function</th> + <th>Description</th> + <th>Parameters</th> + <th>Example</th> + </tr> + </thead> + <tbody> + <tr> + <td>cbind()</td> + <td>Column-wise matrix concatenation. Concatenates the second matrix as additional columns to the first matrix</td> + <td>Input: (X <matrix>, Y <matrix>) <br />Output: <matrix> <br /> X and Y are matrices, where the number of rows in X and the number of rows in Y are the same.</td> + <td>A = matrix(1, rows=2,cols=3) <br /> B = matrix(2, rows=2,cols=3) <br /> C = cbind(A,B) <br /> print(“Dimensions of C: “ + nrow(C) + “ X “ + ncol(C)) <br /> Output: <br /> Dimensions of C: 2 X 6</td> + </tr> + <tr> + <td>matrix()</td> + <td>Matrix constructor (assigning all the cells to numeric literals).</td> + <td>Input: (<init>, rows=<value>, cols=<value>) <br /> init: numeric literal; <br /> rows/cols: number of rows/cols (expression) <br /> Output: matrix</td> + <td># 10x10 matrix initialized to 0 <br /> A = matrix (0, rows=10, cols=10)</td> + </tr> + <tr> + <td> </td> + <td>Matrix constructor (reshaping an existing matrix).</td> + <td>Input: (<existing matrix>, rows=<value>, cols=<value>, byrow=TRUE) <br /> Output: matrix</td> + <td>A = matrix (0, rows=10, cols=10) <br /> B = matrix (A, rows=100, cols=1)</td> + </tr> + <tr> + <td> </td> + <td>Matrix constructor (initializing using string).</td> + <td>Input: (<initialization string>, rows=<value>, cols=<value>) <br /> Output: matrix</td> + <td>A = matrix(“4 3 2 5 7 8”, rows=3, cols=2) <br /> Creates a matrix: [ [4, 3], [2, 5], [7, 8] ]</td> + </tr> + <tr> + <td>min() <br /> max()</td> + <td>Return the minimum/maximum cell value in matrix</td> + <td>Input: matrix <br /> Output: scalar</td> + <td>min(X) <br /> max(Y)</td> + </tr> + <tr> + <td>min() <br /> max()</td> + <td>Return the minimum/maximum cell values of two matrices, matrix and scalar, or scalar value of two scalars.</td> + <td>Input: matrices or scalars <br /> Output: matrix or scalar</td> + <td>With x,y, z as scalars, and X, Y, Z as matrices: <br /> Z = min (X, Y) <br /> Z = min (X, y) <br /> z = min(x,y)</td> + </tr> + <tr> + <td>nrow(), <br /> ncol(), <br /> length()</td> + <td>Return the number of rows, number of columns, or number of cells in matrix or frame respectively.</td> + <td>Input: matrix or frame <br /> Output: scalar</td> + <td>nrow(X) <br /> ncol(F) <br /> length(X)</td> + </tr> + <tr> + <td>prod()</td> + <td>Return the product of all cells in matrix</td> + <td>Input: matrix <br /> Output: scalarj</td> + <td>prod(X)</td> + </tr> + <tr> + <td>rand()</td> + <td>Generates a random matrix</td> + <td>Input: (rows=<value>, cols=<value>, min=<value>, max=<value>, sparsity=<value>, pdf=<string>, seed=<value>) <br /> rows/cols: Number of rows/cols (expression) <br /> min/max: Min/max value for cells (either constant value, or variable that evaluates to constant value) <br /> sparsity: fraction of non-zero cells (constant value) <br /> pdf: “uniform” (min, max) distribution, or “normal” (0,1) distribution; or “poisson” (lambda=1) distribution. string; default value is “uniform”. Note that, for the Poisson distribution, users can provide the mean/lambda parameter as follows: <br /> rand(rows=1000,cols=1000, pdf=”poisson”, lambda=2.5). <br /> The default value for lambda is 1. <br /> seed: Every invocation of rand() internally generates a random seed with which the cell values are generated. One can optionally provide a seed when repeatability is desired. <br /> Output: matr ix</td> + <td>X = rand(rows=10, cols=20, min=0, max=1, pdf=”uniform”, sparsity=0.2) <br /> The example generates a 10 x 20 matrix, with cell values uniformly chosen at random between 0 and 1, and approximately 20% of cells will have non-zero values.</td> + </tr> + <tr> + <td>rbind()</td> + <td>Row-wise matrix concatenation. Concatenates the second matrix as additional rows to the first matrix</td> + <td>Input: (X <matrix>, Y <matrix>) <br />Output: <matrix> <br /> X and Y are matrices, where the number of columns in X and the number of columns in Y are the same.</td> + <td>A = matrix(1, rows=2,cols=3) <br /> B = matrix(2, rows=2,cols=3) <br /> C = rbind(A,B) <br /> print(“Dimensions of C: “ + nrow(C) + “ X “ + ncol(C)) <br /> Output: <br /> Dimensions of C: 4 X 3</td> + </tr> + <tr> + <td>removeEmpty()</td> + <td>Removes all empty rows or columns from the input matrix target X according to the specified margin. The optional select vector F specifies selected rows or columns; if not provided, the semantics are F=(rowSums(X!=0)>0) and F=(colSums(X!=0)>0) for removeEmpty “rows” and “cols”, respectively. The optional empty.return flag indicates if a row or column of zeros should be returned for empty inputs.</td> + <td>Input : (target= X <matrix>, margin=”…”[, select=F][, empty.return=TRUE]) <br /> Output : <matrix> <br /> Valid values for margin are “rows” or “cols”.</td> + <td>A = removeEmpty(target=X, margin=”rows”, select=F)</td> + </tr> + <tr> + <td>replace()</td> + <td>Creates a copy of input matrix X, where all values that are equal to the scalar pattern s1 are replaced with the scalar replacement s2.</td> + <td>Input : (target= X <matrix>, pattern=<scalar>, replacement=<scalar>) <br /> Output : <matrix> <br /> If s1 is NaN, then all NaN values of X are treated as equal and hence replaced with s2. Positive and negative infinity are treated as different values.</td> + <td>A = replace(target=X, pattern=s1, replacement=s2)</td> + </tr> + <tr> + <td>rev()</td> + <td>Reverses the rows in a matrix</td> + <td>Input : (<matrix>) <br /> Output : <matrix></td> + <td><span style="white-space: nowrap;">A = matrix(“1 2 3 4”, rows=2, cols=2)</span> <br /> <span style="white-space: nowrap;">B = matrix(“1 2 3 4”, rows=4, cols=1)</span> <br /> <span style="white-space: nowrap;">C = matrix(“1 2 3 4”, rows=1, cols=4)</span> <br /> revA = rev(A) <br /> revB = rev(B) <br /> revC = rev(C) <br /> Matrix revA: [[3, 4], [1, 2]]<br /> Matrix revB: [[4], [3], [2], [1]]<br /> Matrix revC: [[1, 2, 3, 4]]<br /></td> + </tr> + <tr> + <td>seq()</td> + <td>Creates a single column vector with values starting from <from>, to <to>, in increments of <increment></td> + <td>Input: (<from>, <to>, <increment>) <br /> Output: <matrix></td> + <td>S = seq (10, 200, 10)</td> + </tr> + <tr> + <td>sum()</td> + <td>Sum of all cells in matrix</td> + <td>Input: matrix <br /> Output: scalar</td> + <td>sum(X)</td> + </tr> + </tbody> +</table> + +<h3 id="matrix-andor-scalar-comparison-built-in-functions">Matrix and/or Scalar Comparison Built-In Functions</h3> + +<p><strong>Table 5</strong>: Matrix and/or Scalar Comparison Built-In Functions</p> + +<table> + <thead> + <tr> + <th>Function</th> + <th>Description</th> + <th>Parameters</th> + <th>Example</th> + </tr> + </thead> + <tbody> + <tr> + <td>pmin() <br /> pmax()</td> + <td>“parallel min/max”.<br /> Return cell-wise minimum/maximum. If the second input is a scalar then it is compared against all cells in the first input.</td> + <td>Input: (<matrix>, <matrix>), or (<matrix>, <scalar>) <br /> Output: matrix</td> + <td>pmin(X,Y) <br /> pmax(X,y)</td> + </tr> + <tr> + <td>rowIndexMax()</td> + <td>Row-wise computation – for each row, find the max value, and return its column index.</td> + <td>Input: (matrix) <br /> Output: (n x 1) matrix</td> + <td>rowIndexMax(X)</td> + </tr> + <tr> + <td>rowIndexMin()</td> + <td>Row-wise computation – for each row, find the minimum value, and return its column index.</td> + <td>Input: (matrix) <br /> Output: (n x 1) matrix</td> + <td>rowIndexMin(X)</td> + </tr> + <tr> + <td>ppred()</td> + <td>“parallel predicate”.<br /> The relational operator specified in the third argument is cell-wise applied to input matrices. If the second argument is a scalar, then it is used against all cells in the first argument. <br /> <strong>NOTE: ppred() has been replaced by the relational operators, so its use is discouraged.</strong></td> + <td>Input: (<matrix>, <matrix>, <string with relational operator>), or <br /> (<matrix>, <scalar>, <string with relational operator>) <br /> Output: matrix</td> + <td>ppred(X,Y,”<”) <br /> ppred(X,y,”<”)</td> + </tr> + </tbody> +</table> + +<h3 id="casting-built-in-functions">Casting Built-In Functions</h3> + +<p><strong>Table 6</strong>: Casting Built-In Functions</p> + +<table> + <thead> + <tr> + <th>Function</th> + <th>Description</th> + <th>Parameters</th> + <th>Example</th> + </tr> + </thead> + <tbody> + <tr> + <td>as.scalar(), <br /> as.matrix()</td> + <td>A 1x1 matrix is cast as scalar (value type preserving), and a scalar is cast as 1x1 matrix with value type double</td> + <td>Input: (<matrix>), or (<scalar>) <br /> Output: <scalar>, or <matrix></td> + <td>as.scalar(X) <br /> as.matrix(x)</td> + </tr> + <tr> + <td>as.double(), <br /> as.integer(), <br /> as.logical()</td> + <td>A variable is cast as the respective value type, data type preserving. as.integer() performs a safe cast. For numerical inputs, as.logical() returns FALSE if the input value is 0 or 0.0, and TRUE otherwise.</td> + <td>Input: (<scalar>) <br /> Output: <scalar></td> + <td>as.double(X) <br /> as.integer(x) <br /> as.logical(y)</td> + </tr> + </tbody> +</table> + +<h3 id="statistical-built-in-functions">Statistical Built-In Functions</h3> + +<p><strong>Table 7</strong>: Statistical Built-In Functions</p> + +<table> + <thead> + <tr> + <th>Function</th> + <th>Description</th> + <th>Parameters</th> + <th>Example</th> + </tr> + </thead> + <tbody> + <tr> + <td>mean() <br /> avg()</td> + <td>Return the mean value of all cells in matrix</td> + <td>Input: matrix <br /> Output: scalar</td> + <td>mean(X)</td> + </tr> + <tr> + <td>var() <br /> sd()</td> + <td>Return the variance/stdDev value of all cells in matrix. Both use unbiased estimators with (n-1) denominator.</td> + <td>Input: matrix <br /> Output: scalar</td> + <td>var(X) <br /> sd(X)</td> + </tr> + <tr> + <td>moment()</td> + <td>Returns the kth central moment of values in a column matrix V, where k = 2, 3, or 4. It can be used to compute statistical measures like Variance, Kurtosis, and Skewness. This function also takes an optional weights parameter W.</td> + <td>Input: (X <(n x 1) matrix>, [W <(n x 1) matrix>),] k <scalar>) <br /> Output: <scalar></td> + <td>A = rand(rows=100000,cols=1, pdf=”normal”) <br /> print(“Variance from our (standard normal) random generator is approximately “ + moment(A,2))</td> + </tr> + <tr> + <td>colSums() <br /> colMeans() <br /> colVars() <br /> colSds() <br /> colMaxs() <br /> colMins()</td> + <td>Column-wise computations – for each column, compute the sum/mean/variance/stdDev/max/min of cell values</td> + <td>Input: matrix <br /> Output: (1 x n) matrix</td> + <td>colSums(X) <br /> colMeans(X) <br /> colVars(X) <br /> colSds(X) <br /> colMaxs(X) <br />colMins(X)</td> + </tr> + <tr> + <td>cov()</td> + <td>Returns the covariance between two 1-dimensional column matrices X and Y. The function takes an optional weights parameter W. All column matrices X, Y, and W (when specified) must have the exact same dimension.</td> + <td>Input: (X <(n x 1) matrix>, Y <(n x 1) matrix> [, W <(n x 1) matrix>)]) <br /> Output: <scalar></td> + <td>cov(X,Y) <br /> cov(X,Y,W)</td> + </tr> + <tr> + <td>table()</td> + <td>Returns the contingency table of two vectors A and B. The resulting table F consists of max(A) rows and max(B) columns. <br /> More precisely, F[i,j] = |{ k | A[k] = i and B[k] = j, 1 ⤠k ⤠n }|, where A and B are two n-dimensional vectors. <br /> This function supports multiple other variants, which can be found below, at the end of this Table 7.</td> + <td>Input: (<(n x 1) matrix>, <(n x 1) matrix>), [<(n x 1) matrix>]) <br /> Output: <matrix></td> + <td>F = table(A, B) <br /> F = table(A, B, C) <br /> And, several other forms (see below Table 7.)</td> + </tr> + <tr> + <td>cdf()<br /> pnorm()<br /> pexp()<br /> pchisq()<br /> pf()<br /> pt()<br /> icdf()<br /> qnorm()<br /> qexp()<br /> qchisq()<br /> qf()<br /> qt()</td> + <td>p=cdf(target=q, …) returns the cumulative probability P[X <= q]. <br /> q=icdf(target=p, …) returns the inverse cumulative probability i.e., it returns q such that the given target p = P[X<=q]. <br /> For more details, please see the section “Probability Distribution Functions” below Table 7.</td> + <td>Input: (target=<scalar>, dist=”…”, …) <br /> Output: <scalar></td> + <td>p = cdf(target=q, dist=”normal”, mean=1.5, sd=2); is same as p=pnorm(target=q, mean=1.5, sd=2); <br /> q=icdf(target=p, dist=”normal”) is same as q=qnorm(target=p, mean=0,sd=1) <br /> More examples can be found in the section “Probability Distribution Functions” below Table 7.</td> + </tr> + <tr> + <td>aggregate()</td> + <td>Splits/groups the values from X according to the corresponding values from G, and then applies the function fn on each group. <br /> The result F is a column matrix, in which each row contains the value computed from a distinct group in G. More specifically, F[k,1] = fn( {X[i,1] | 1<=i<=n and G[i,1] = k} ), where n = nrow(X) = nrow(G). <br /> Note that the distinct values in G are used as row indexes in the result matrix F. Therefore, nrow(F) = max(G). It is thus recommended that the values in G are consecutive and start from 1. <br /> This function supports multiple other variants, which can be found below, at the end of this Table 7.</td> + <td>Input:<br /> (target = X <(n x 1) matrix, or matrix>,<br />    groups = G <(n x 1) matrix>,<br />    fn= “…” <br />    [,weights= W<(n x 1) matrix>] <br />    [,ngroups=N] )<br />Output: F <matrix> <br /> Note: X is a (n x 1) matrix unless ngroups is specified with no weights, in which case X is a regular (n x m) matrix.<br /> The parameter fn takes one of the following functions: “count”, “sum”, “mean”, “variance”, “centralmoment”. In the case of central moment, one must also provide the order of the moment that need to be computed (see example).</td> + <td>F = aggregate(target=X, groups=G, fn= “…” [,weights = W]) <br /> F = aggregate(target=X, groups=G1, fn= “sum”); <br /> F = aggregate(target=Y, groups=G2, fn= “mean”, weights=W); <br /> F = aggregate(target=Z, groups=G3, fn= “centralmoment”, order= “2”); <br /> And, several other forms (see below Table 7.)</td> + </tr> + <tr> + <td>interQuartileMean()</td> + <td>Returns the mean of all x in X such that x>quantile(X, 0.25) and x<=quantile(X, 0.75). X, W are column matrices (vectors) of the same size. W contains the weights for data in X.</td> + <td>Input: (X <(n x 1) matrix> [, W <(n x 1) matrix>)]) <br /> Output: <scalar></td> + <td>interQuartileMean(X) <br /> interQuartileMean(X, W)</td> + </tr> + <tr> + <td>quantile ()</td> + <td>The p-quantile for a random variable X is the value x such that Pr[X<x] <= p and Pr[X<= x] >= p <br /> let n=nrow(X), i=ceiling(p*n), quantile() will return X[i]. p is a scalar (0<p<1) that specifies the quantile to be computed. Optionally, a weight vector may be provided for X.</td> + <td>Input: (X <(n x 1) matrix>, [W <(n x 1) matrix>),] p <scalar>) <br /> Output: <scalar></td> + <td>quantile(X, p) <br /> quantile(X, W, p)</td> + </tr> + <tr> + <td>quantile ()</td> + <td>Returns a column matrix with list of all quantiles requested in P.</td> + <td>Input: (X <(n x 1) matrix>, [W <(n x 1) matrix>),] P <(q x 1) matrix>) <br /> Output: matrix</td> + <td>quantile(X, P) <br /> quantile(X, W, P)</td> + </tr> + <tr> + <td>median()</td> + <td>Computes the median in a given column matrix of values</td> + <td>Input: (X <(n x 1) matrix>, [W <(n x 1) matrix>),]) <br /> Output: <scalar></td> + <td>median(X) <br /> median(X,W)</td> + </tr> + <tr> + <td>rowSums() <br /> rowMeans() <br /> rowVars() <br /> rowSds() <br /> rowMaxs() <br /> rowMins()</td> + <td>Row-wise computations – for each row, compute the sum/mean/variance/stdDev/max/min of cell value</td> + <td>Input: matrix <br /> Output: (n x 1) matrix</td> + <td>rowSums(X) <br /> rowMeans(X) <br /> rowVars(X) <br /> rowSds(X) <br /> rowMaxs(X) <br /> rowMins(X)</td> + </tr> + <tr> + <td>cumsum()</td> + <td>Column prefix-sum (For row-prefix sum, use cumsum(t(X))</td> + <td>Input: matrix <br /> Output: matrix of the same dimensions</td> + <td>A = matrix(“1 2 3 4 5 6”, rows=3, cols=2) <br /> B = cumsum(A) <br /> The output matrix B = [[1, 2], [4, 6], [9, 12]]</td> + </tr> + <tr> + <td>cumprod()</td> + <td>Column prefix-prod (For row-prefix prod, use cumprod(t(X))</td> + <td>Input: matrix <br /> Output: matrix of the same dimensions</td> + <td>A = matrix(“1 2 3 4 5 6”, rows=3, cols=2) <br /> B = cumprod(A) <br /> The output matrix B = [[1, 2], [3, 8], [15, 48]]</td> + </tr> + <tr> + <td>cummin()</td> + <td>Column prefix-min (For row-prefix min, use cummin(t(X))</td> + <td>Input: matrix <br /> Output: matrix of the same dimensions</td> + <td>A = matrix(“3 4 1 6 5 2”, rows=3, cols=2) <br /> B = cummin(A) <br /> The output matrix B = [[3, 4], [1, 4], [1, 2]]</td> + </tr> + <tr> + <td>cummax()</td> + <td>Column prefix-max (For row-prefix min, use cummax(t(X))</td> + <td>Input: matrix <br /> Output: matrix of the same dimensions</td> + <td>A = matrix(“3 4 1 6 5 2”, rows=3, cols=2) <br /> B = cummax(A) <br /> The output matrix B = [[3, 4], [3, 6], [5, 6]]</td> + </tr> + <tr> + <td>sample(range, size, replacement, seed)</td> + <td>Sample returns a column vector of length size, containing uniform random numbers from [1, range]</td> + <td>Input: <br /> range: integer <br /> size: integer <br /> replacement: boolean (Optional, default: FALSE) <br /> seed: integer (Optional) <br /> Output: Matrix dimensions are size x 1</td> + <td>sample(100, 5) <br /> sample(100, 5, TRUE) <br /> sample(100, 120, TRUE) <br /> sample(100, 5, 1234) # 1234 is the seed <br /> sample(100, 5, TRUE, 1234)</td> + </tr> + <tr> + <td>outer(vector1, vector2, “op”)</td> + <td>Applies element wise binary operation “op” (for example: “<”, “==”, “>=”, “<em>”, “min”) on the all combination of vector. <br /> Note: Using “</em>”, we get outer product of two vectors.</td> + <td>Input: vectors of same size d, string <br /> Output: matrix of size d X d</td> + <td>A = matrix(“1 4”, rows = 2, cols = 1) <br /> B = matrix(“3 6”, rows = 1, cols = 2) <br /> C = outer(A, B, “<”) <br /> D = outer(A, B, “*”) <br /> The output matrix C = [[1, 1], [0, 1]] <br /> The output matrix D = [[3, 6], [12, 24]]<br /></td> + </tr> + </tbody> +</table> + +<h4 id="alternative-forms-of-table">Alternative forms of table()</h4> + +<p>The built-in function table() supports different types of input parameters. These variations are described below:</p> + +<ul> + <li>Basic form: <code>F=table(A,B)</code> +As described above in Table 7.</li> + <li>Weighted form: <code>F=table(A,B,W)</code> +Users can provide an optional third parameter C with the same dimensions as of A and B. In this case, the output F[i,j] = âkC[k], where A[k] = i and B[k] = j (1 ⤠k ⤠n).</li> + <li>Scalar form +In basic and weighted forms, both B and W are one dimensional matrices with same number of rows/columns as in A. Instead, one can also pass-in scalar values in the place of B and W. For example, F=table(A,1) is same as the basic form where B is a matrix with all 1âs. Similarly, <code>F=table(A,B,3)</code> is identical to the following two DML statements. <br /> +<code>m3 = matrix(3,rows=nrow(A),cols=1); </code> <br /> +<code>F = table(A,B,m3);</code></li> + <li>Specified Output Size +In the above forms, the dimensions of the matrix produced this function is known only after its execution is complete. Users can precisely control the size of the output matrix via two additional arguments, odim1 and odim2, as shown below: <br /> +<code>F = table(A,B,odim1,odim2);</code> <br /> +The output F will have exactly <code>odim1</code> rows and <code>odim2</code> columns. F may be a truncated or padded (with zeros) version of the output produced by <code>table(A,B)</code> – depending on the values of <code>max(A)</code> and <code>max(B)</code>. For example, if <code>max(A) < odim1</code> then the last (<code>odim1-max(A)</code>) rows will have zeros.</li> +</ul> + +<h4 id="alternative-forms-of-aggregate">Alternative forms of aggregate()</h4> + +<p>The built-in function aggregate() supports different types of input parameters. These variations are described below:</p> + +<ul> + <li>Basic form: <code>F=aggregate(target=X, groups=G, fn="sum")</code> +As described above in Table 7.</li> + <li>Weighted form: <code>F=aggregate(target=X, groups=G, weights=W, fn="sum")</code> +Users can provide an optional parameter W with the same dimensions as of A and B. In this case, fn computes the weighted statistics over values from X, which are grouped by values from G.</li> + <li>Specified Output Size +As noted in Table 7, the number of rows in the output matrix F is equal to the maximum value in the grouping matrix G. Therefore, the dimensions of F are known only after its execution is complete. When needed, users can precisely control the size of the output matrix via an additional argument, <code>ngroups</code>, as shown below: <br /> +<code>F = aggregate(target=X, groups=G, fn="sum", ngroups=10);</code> <br /> +The output F will have exactly 10 rows and 1 column. F may be a truncated or padded (with zeros) version of the output produced by <code>aggregate(target=X, groups=G, fn="sum")</code> â depending on the values of <code>ngroups</code> and <code>max(G)</code>. For example, if <code>max(G) < ngroups</code> then the last (<code>ngroups-max(G)</code>) rows will have zeros.</li> +</ul> + +<h4 id="probability-distribution-functions">Probability Distribution Functions</h4> + +<h5 id="p--cdftargetq-distfn--lowertailtrue"><code>p = cdf(target=q, dist=fn, ..., lower.tail=TRUE)</code></h5> + +<p>This computes the cumulative probability at the given quantile i.e., P[X<=q], where X is random variable whose distribution is specified via string argument fn.</p> + +<ul> + <li><code>target</code>: input quantile at which cumulative probability P[X<=q] is computed, where X is random variable whose distribution is specified via string argument fn. This is a mandatory argument.</li> + <li><code>dist</code>: name of the distribution specified as a string. Valid values are “normal” (for Normal or Gaussian distribution), “f” (for F distribution), “t” (for Student t-distribution), “chisq” (for Chi Squared distribution), and “exp” (for Exponential distribution). This is a mandatory argument.</li> + <li><code>...</code>: parameters of the distribution + <ul> + <li>For <code>dist="normal"</code>, valid parameters are mean and sd that specify the mean and standard deviation of the normal distribution. The default values for mean and sd are 0.0 and 1.0, respectively.</li> + <li>For <code>dist="f"</code>, valid parameters are df1 and df2 that specify two degrees of freedom. Both these parameters are mandatory.</li> + <li>For <code>dist="t"</code>, and dist=”chisq”, valid parameter is df that specifies the degrees of freedom. This parameter is mandatory.</li> + <li>For <code>dist="exp"</code>, valid parameter is rate that specifies the rate at which events occur. Note that the mean of exponential distribution is 1.0/rate. The default value is 1.0.</li> + </ul> + </li> + <li><code>Lower.tail</code>: a Boolean value with default set to TRUE. cdf() computes P[X<=q] when lower.tail=TRUE and it computes P[X>q] when lower.tail=FALSE. In other words, a complement of the cumulative distribution is computed when lower.tail=FALSE.</li> +</ul> + +<h5 id="q--icdftargetp-distfn-"><code>q = icdf(target=p, dist=fn, ...)</code></h5> + +<p>This computes the inverse cumulative probability i.e., it computes a quantile q such that the given probability p = P[X<=q], where X is random variable whose distribution is specified via string argument fn.</p> + +<ul> + <li><code>target</code>: a mandatory argument that specifies the input probability.</li> + <li><code>dist</code>: name of the distribution specified as a string. Same as that in cdf().</li> + <li><code>...</code>: parameters of the distribution. Same as those in cdf().</li> +</ul> + +<p>Alternative to <code>cdf()</code> and <code>icdf()</code>, users can also use distribution-specific functions. The functions <code>pnorm()</code>, <code>pf()</code>, <code>pt()</code>, <code>pchisq()</code>, and <code>pexp()</code> computes the cumulative probabilities for Normal, F, t, Chi Squared, and Exponential distributions, respectively. Appropriate distribution parameters must be provided for each function. Similarly, <code>qnorm()</code>, <code>qf()</code>, <code>qt()</code>, <code>qchisq()</code>, and <code>qexp()</code> compute the inverse cumulative probabilities for Normal, F, t, Chi Squared, and Exponential distributions.</p> + +<p>Following pairs of DML statements are equivalent.</p> + +<p><code>p = cdf(target=q, dist="normal", mean=1.5, sd=2);</code> +is same as +<code>p=pnorm(target=q, mean=1.5, sd=2);</code></p> + +<p><code>p = cdf(target=q, dist="exp", rate=5);</code> +is same as +<code>pexp(target=q,rate=5);</code></p> + +<p><code>p = cdf(target=q, dist="chisq", df=100);</code> +is same as +<code>pchisq(target=q, df=100)</code></p> + +<p><code>p = cdf(target=q, dist="f", df1=100, df2=200);</code> +is same as +<code>pf(target=q, df1=100, df2=200);</code></p> + +<p><code>p = cdf(target=q, dist="t", df=100);</code> +is same as +<code>pt(target=q, df=100)</code></p> + +<p><code>p = cdf(target=q, dist="normal", lower.tail=FALSE);</code> +is same as +<code>p=pnorm(target=q, lower.tail=FALSE);</code> +is same as +<code>p=pnorm(target=q, mean=0, sd=1.0, lower.tail=FALSE);</code> +is same as +<code>p=pnorm(target=q, sd=1.0, lower.tail=FALSE);</code></p> + +<p>Examples of icdf():</p> + +<p><code>q=icdf(target=p, dist="normal");</code> +is same as +<code>q=qnorm(target=p, mean=0,sd=1);</code></p> + +<p><code>q=icdf(target=p, dist="exp");</code> +is same as +<code>q=qexp(target=p, rate=1);</code></p> + +<p><code>q=icdf(target=p, dist="chisq", df=50);</code> +is same as +<code>qchisq(target=p, df=50);</code></p> + +<p><code>q=icdf(target=p, dist="f", df1=50, df2=25);</code> +is same as +<code>qf(target=p, , df1=50, df2=25);</code></p> + +<p><code>q=icdf(target=p, dist="t", df=50);</code> +is same as +<code>qt(target=p, df=50);</code></p> + +<h3 id="mathematical-and-trigonometric-built-in-functions">Mathematical and Trigonometric Built-In Functions</h3> + +<p><strong>Table 8</strong>: Mathematical and Trigonometric Built-In Functions</p> + +<table> + <thead> + <tr> + <th>Function</th> + <th>Description</th> + <th>Parameters</th> + <th>Example</th> + </tr> + </thead> + <tbody> + <tr> + <td>exp(), log(), abs(), sqrt(), round(), floor(), ceil(), ceiling()</td> + <td>Apply mathematical function on input (cell wise if input is matrix)</td> + <td>Input: (<matrix>), or (<scalar>) <br /> Output: <matrix>, or <scalar></td> + <td>sqrt(X) <br /> log(X,y) <br /> round(X) <br /> floor(X) <br /> ceil(X) <br /> ceiling(X)</td> + </tr> + <tr> + <td>sin(), cos(), tan(), sinh(), cosh(), tanh(), asin(), acos(), atan()</td> + <td>Apply trigonometric function on input (cell wise if input is matrix)</td> + <td>Input: (<matrix>), or (<scalar>) <br /> Output: <matrix>, or <scalar></td> + <td>sin(X)</td> + </tr> + <tr> + <td>sign()</td> + <td>Returns a matrix representing the signs of the input matrix elements, where 1 represents positive, 0 represents zero, and -1 represents negative</td> + <td>Input : (A <matrix>) <br /> Output : <matrix></td> + <td><span style="white-space: nowrap;">A = matrix(“-5 0 3 -3”,</span> rows=2, cols=2) <br />signA = sign(A)<br />Matrix signA: [[-1, 0], [1, -1]]</td> + </tr> + </tbody> +</table> + +<h3 id="linear-algebra-built-in-functions">Linear Algebra Built-In Functions</h3> + +<p><strong>Table 9</strong>: Linear Algebra Built-In Functions</p> + +<table> + <thead> + <tr> + <th>Function</th> + <th>Description</th> + <th>Parameters</th> + <th>Example</th> + </tr> + </thead> + <tbody> + <tr> + <td>cholesky()</td> + <td>Computes the Cholesky decomposition of symmetric input matrix A</td> + <td>Input: (A <matrix>) <br /> Output: <matrix></td> + <td><span style="white-space: nowrap;">A = matrix(“4 12 -16 12 37 -43</span> -16 -43 98”, rows=3, cols=3) <br /> B = cholesky(A)<br /> Matrix B: [[2, 0, 0], [6, 1, 0], [-8, 5, 3]]</td> + </tr> + <tr> + <td>diag()</td> + <td>Create diagonal matrix from (n x 1) matrix, or take diagonal from square matrix</td> + <td>Input: (n x 1) matrix, or (n x n) matrix <br /> Output: (n x n) matrix, or (n x 1) matrix</td> + <td>D = diag(matrix(1.0, rows=3, cols=1))<br /> E = diag(matrix(1.0, rows=3, cols=3))</td> + </tr> + <tr> + <td>eigen()</td> + <td>Computes Eigen decomposition of input matrix A. The Eigen decomposition consists of two matrices V and w such that A = V %*% diag(w) %*% t(V). The columns of V are the eigenvectors of the original matrix A. And, the eigen values are given by w. <br /> It is important to note that this function can operate only on small-to-medium sized input matrix that can fit in the main memory. For larger matrices, an out-of-memory exception is raised.</td> + <td>Input : (A <matrix>) <br /> Output : [w <(m x 1) matrix>, V <matrix>] <br /> A is a square symmetric matrix with dimensions (m x m). This function returns two matrices w and V, where w is (m x 1) and V is of size (m x m).</td> + <td>[w, V] = eigen(A)</td> + </tr> + <tr> + <td>lu()</td> + <td>Computes Pivoted LU decomposition of input matrix A. The LU decomposition consists of three matrices P, L, and U such that P %*% A = L %*% U, where P is a permutation matrix that is used to rearrange the rows in A before the decomposition can be computed. L is a lower-triangular matrix whereas U is an upper-triangular matrix. <br /> It is important to note that this function can operate only on small-to-medium sized input matrix that can fit in the main memory. For larger matrices, an out-of-memory exception is raised.</td> + <td>Input : (A <matrix>) <br /> Output : [<matrix>, <matrix>, <matrix>] <br /> A is a square matrix with dimensions m x m. This function returns three matrices P, L, and U, all of which are of size m x m.</td> + <td>[P, L, U] = lu(A)</td> + </tr> + <tr> + <td>qr()</td> + <td>Computes QR decomposition of input matrix A using Householder reflectors. The QR decomposition of A consists of two matrices Q and R such that A = Q%*%R where Q is an orthogonal matrix (i.e., Q%*%t(Q) = t(Q)%*%Q = I, identity matrix) and R is an upper triangular matrix. For efficiency purposes, this function returns the matrix of Householder reflector vectors H instead of Q (which is a large m x m potentially dense matrix). The Q matrix can be explicitly computed from H, if needed. In most applications of QR, one is interested in calculating Q %*% B or t(Q) %*% B â and, both can be computed directly using H instead of explicitly constructing the large Q matrix. <br /> It is important to note that this function can operate only on small-to-medium sized input matrix that can fit in the main memory. For larger matrices, an out-of-memory exception is raised.</td> + <td>Input : (A <matrix>) <br /> Output : [<matrix>, <matrix>] <br /> A is a (m x n) matrix, which can either be a square matrix (m=n) or a rectangular matrix (m != n). This function returns two matrices H and R of size (m x n) i.e., same size as of the input matrix A.</td> + <td>[H, R] = qr(A)</td> + </tr> + <tr> + <td>solve()</td> + <td>Computes the least squares solution for system of linear equations A %*% x = b i.e., it finds x such that ||A%*%x â b|| is minimized. The solution vector x is computed using a QR decomposition of A. <br /> It is important to note that this function can operate only on small-to-medium sized input matrix that can fit in the main memory. For larger matrices, an out-of-memory exception is raised.</td> + <td>Input : (A <(m x n) matrix>, b <(m x 1) matrix>) <br /> Output : <matrix> <br /> A is a matrix of size (m x n) and b is a 1D matrix of size m x 1. This function returns a 1D matrix x of size n x 1.</td> + <td>x = solve(A,b)</td> + </tr> + <tr> + <td>svd()</td> + <td>Singular Value Decomposition of a matrix A (of size m x m), which decomposes into three matrices U, V, and S as A = U %<em>% S %</em>% t(V), where U is an m x m unitary matrix (i.e., orthogonal), V is an n x n unitary matrix (also orthogonal), and S is an m x n matrix with non-negative real numbers on the diagonal.</td> + <td>Input: matrix A <(m x n)> <br /> Output: matrices U <(m x m)>, S <(m x n)>, and V <(n x n)></td> + <td>[U, S, V] = svd(A)</td> + </tr> + <tr> + <td>t()</td> + <td>Transpose matrix</td> + <td>Input: matrix <br /> Output: matrix</td> + <td>t(X)</td> + </tr> + <tr> + <td>trace()</td> + <td>Return the sum of the cells of the main diagonal square matrix</td> + <td>Input: matrix <br /> Output: scalar</td> + <td>trace(X)</td> + </tr> + </tbody> +</table> + +<h3 id="readwrite-built-in-functions">Read/Write Built-In Functions</h3> + +<p>The <code>read</code> and <code>write</code> functions support the reading and writing of matrices and scalars from/to the file system +(local or HDFS). Typically, associated with each data file is a JSON-formatted metadata file (MTD) that stores +metadata information about the content of the data file, such as the number of rows and columns. +For data files written by SystemML, an MTD file will automatically be generated. The name of the +MTD file associated with <code><filename></code> must be <code><filename.mtd></code>. In general, it is highly recommended +that users provide MTD files for their own data as well.</p> + +<p><em>Note: Metadata can also be passed as parameters to <code>read</code> and <code>write</code> function calls.</em></p> + +<h4 id="file-formats-and-mtd-files">File formats and MTD files</h4> + +<p>SystemML supports 4 file formats:</p> + +<ul> + <li>CSV (delimited)</li> + <li>Matrix Market (coordinate)</li> + <li>Text (i,j,v)</li> + <li>Binary</li> +</ul> + +<p>The CSV format is a standard text-based format where columns are separated by delimiter characters, typically commas, and +rows are represented on separate lines.</p> + +<p>SystemML supports the Matrix Market coordinate format, which is a text-based, space-separated format used to +represent sparse matrices. Additional information about the Matrix Market format can be found at +<a href="http://math.nist.gov/MatrixMarket/formats.html#MMformat";>http://math.nist.gov/MatrixMarket/formats.html#MMformat</a>. +SystemML does not currently support the Matrix Market array format for dense matrices. In the Matrix Market +coordinate format, metadata (the number of rows, the number of columns, and the number of non-zero values) are +included in the data file. Rows and columns index from 1. Matrix Market data must be in a single file, whereas the +(i,j,v) text format can span multiple part files on HDFS. Therefore, for scalability reasons, the use of the (i,j,v) text and +binary formats is encouraged when scaling to big data.</p> + +<p>The (i,j,v) format is a text-based sparse format in which the cell values of a matrix are serialized in space-separated triplets +of rowId, columnId, and cellValue, with the rowId and columnId indices being 1-based. This is similar to the Matrix Market +coordinate format, except metadata is stored in a separate file rather than in the data file itself, and the (i,j,v) text format +can span multiple part files.</p> + +<p>The binary format can only be read and written by SystemML.</p> + +<p>Let’s look at a matrix and examples of its data represented in the supported formats with corresponding metadata. In the table below, we have +a matrix consisting of 4 rows and 3 columns.</p> + +<p><strong>Table 10</strong>: Matrix</p> + +<table> + <tr> + <td class="centerboldcell">1.0</td> + <td class="centerboldcell">2.0</td> + <td class="centerboldcell">3.0</td> + </tr> + <tr> + <td class="centerboldcell">0</td> + <td class="centerboldcell">0</td> + <td class="centerboldcell">0</td> + </tr> + <tr> + <td class="centerboldcell">7.0</td> + <td class="centerboldcell">8.0</td> + <td class="centerboldcell">9.0</td> + </tr> + <tr> + <td class="centerboldcell">0</td> + <td class="centerboldcell">0</td> + <td class="centerboldcell">0</td> + </tr> +</table> + +<p>Below, we have examples of this matrix in the CSV, Matrix Market, IJV, and Binary formats, along with corresponding metadata.</p> + +<div class="codetabs2"> + +<div data-lang="CSV"> + <pre><code>1.0,2.0,3.0 +0,0,0 +7.0,8.0,9.0 +0,0,0 +</code></pre> + </div> + +<div data-lang="CSV MTD"> + <pre><code>{ + "data_type": "matrix", + "value_type": "double", + "rows": 4, + "cols": 3, + "nnz": 6, + "format": "csv", + "header": false, + "sep": ",", + "author": "SystemML", + "created": "2017-01-01 00:00:01 PST" +} +</code></pre> + </div> + +<div data-lang="Matrix Market"> + <pre><code>%%MatrixMarket matrix coordinate real general +4 3 6 +1 1 1.0 +1 2 2.0 +1 3 3.0 +3 1 7.0 +3 2 8.0 +3 3 9.0 +</code></pre> + </div> + +<div data-lang="IJV"> + <pre><code>1 1 1.0 +1 2 2.0 +1 3 3.0 +3 1 7.0 +3 2 8.0 +3 3 9.0 +</code></pre> + </div> + +<div data-lang="IJV MTD"> + <pre><code>{ + "data_type": "matrix", + "value_type": "double", + "rows": 4, + "cols": 3, + "nnz": 6, + "format": "text", + "author": "SystemML", + "created": "2017-01-01 00:00:01 PST" +} +</code></pre> + </div> + +<div data-lang="Binary"> + <pre><code>Binary is not a text-based format. +</code></pre> + </div> + +<div data-lang="Binary MTD"> + <pre><code>{ + "data_type": "matrix", + "value_type": "double", + "rows": 4, + "cols": 3, + "rows_in_block": 1000, + "cols_in_block": 1000, + "nnz": 6, + "format": "binary", + "author": "SystemML", + "created": "2017-01-01 00:00:01 PST" +} +</code></pre> + </div> + +</div> + +<p>As another example, here we see the content of the MTD file <code>scalar.mtd</code> associated with a scalar data file <code>scalar</code> +that contains the scalar value 2.0.</p> + +<pre><code>{ + "data_type": "scalar", + "value_type": "double", + "format": "text", + "author": "SystemML", + "created": "2017-01-01 00:00:01 PST" +} +</code></pre> + +<p>Metadata is represented as an MTD file that contains a single JSON object with the attributes described below.</p> + +<p><strong>Table 11</strong>: MTD attributes</p> + +<table> + <thead> + <tr> + <th>Parameter Name</th> + <th>Description</th> + <th>Optional</th> + <th>Permissible values</th> + <th>Data type valid for</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>data_type</code></td> + <td>Indicates the data type of the data</td> + <td>Yes. Default value is <code>matrix</code> if not specified</td> + <td><code>matrix</code>, <code>scalar</code></td> + <td><code>matrix</code>, <code>scalar</code></td> + </tr> + <tr> + <td><code>value_type</code></td> + <td>Indicates the value type of the data</td> + <td>Yes. Default value is <code>double</code> if not specified</td> + <td><code>double</code>, <code>int</code>, <code>string</code>, <code>boolean</code>. Must be <code>double</code> when <code>data_type</code> is <code>matrix</code></td> + <td><code>matrix</code>, <code>scalar</code></td> + </tr> + <tr> + <td><code>rows</code></td> + <td>Number of rows in <code>matrix</code></td> + <td>Yes â only when <code>format</code> is <code>csv</code></td> + <td>any integer > <code>0</code></td> + <td><code>matrix</code></td> + </tr> + <tr> + <td><code>cols</code></td> + <td>Number of columns in <code>matrix</code></td> + <td>Yes â only when <code>format</code> is <code>csv</code></td> + <td>any integer > <code>0</code></td> + <td><code>matrix</code></td> + </tr> + <tr> + <td><code>rows_in_block</code>, <code>cols_in_block</code></td> + <td>Valid only for <code>binary</code> format. Indicates dimensions of blocks</td> + <td>No. Only valid if <code>matrix</code> is in <code>binary</code> format</td> + <td>any integer > <code>0</code></td> + <td><code>matrix</code> in <code>binary</code> format. Valid only when <code>binary</code> format</td> + </tr> + <tr> + <td><code>nnz</code></td> + <td>Number of non-zero values</td> + <td>Yes</td> + <td>any integer > <code>0</code></td> + <td><code>matrix</code></td> + </tr> + <tr> + <td><code>format</code></td> + <td>Data file format</td> + <td>Yes. Default value is <code>text</code></td> + <td><code>csv</code>, <code>mm</code>, <code>text</code>, <code>binary</code></td> + <td><code>matrix</code>, <code>scalar</code>. Formats <code>csv</code> and <code>mm</code> are applicable only to matrices</td> + </tr> + <tr> + <td><code>description</code></td> + <td>Description of the data</td> + <td>Yes</td> + <td>Any valid JSON string or object</td> + <td><code>matrix</code>, <code>scalar</code></td> + </tr> + <tr> + <td><code>author</code></td> + <td>User that created the metadata file, defaults to <code>SystemML</code></td> + <td>N/A</td> + <td>N/A</td> + <td>N/A</td> + </tr> + <tr> + <td><code>created</code></td> + <td>Date/time when metadata file was written</td> + <td>N/A</td> + <td>N/A</td> + <td>N/A</td> + </tr> + </tbody> +</table> + +<p>In addition, when reading or writing CSV files, the metadata may contain one or more of the following five attributes. +Note that this metadata can be specified as parameters to the <code>read</code> and <code>write</code> function calls.</p> + +<p><strong>Table 12</strong>: Additional MTD attributes when reading/writing CSV files</p> + +<table> + <thead> + <tr> + <th>Parameter Name</th> + <th>Description</th> + <th>Optional</th> + <th>Permissible values</th> + <th>Data type valid for</th> + </tr> + </thead> + <tbody> + <tr> + <td><code>header</code></td> + <td>Specifies whether the data file has a header. If the header exists, it must be the first line in the file.</td> + <td>Yes, default value is <code>false</code>.</td> + <td><code>true</code>/<code>false</code> (<code>TRUE</code>/<code>FALSE</code> in DML)</td> + <td><code>matrix</code></td> + </tr> + <tr> + <td><code>sep</code></td> + <td>Specifies the separator (delimiter) used in the data file. Note that using a delimiter composed of just numeric values or a period (decimal point) can be ambiguous and may lead to unexpected results.</td> + <td>Yes, default value is “<code>,</code>” (comma)</td> + <td>string</td> + <td><code>matrix</code></td> + </tr> + <tr> + <td><code>fill</code></td> + <td>Only valid when reading CSV files. It specifies whether or not to fill the empty fields in the input file. Empty fields are denoted by consecutive separators (delimiters). If <code>fill</code> is <code>true</code> then every empty field is filled with the value specified by the “default” attribute. An exception is raised if <code>fill</code> is <code>false</code> and the input file has one or more empty fields.</td> + <td>Yes, default is <code>true</code>.</td> + <td><code>true</code>/<code>false</code> (<code>TRUE</code>/<code>FALSE</code> in DML)</td> + <td><code>matrix</code></td> + </tr> + <tr> + <td><code>default</code></td> + <td>Only valid when reading CSV files and <code>fill</code> is <code>true</code>. It specifies the special value with which all empty values are filled while reading the input matrix.</td> + <td>Yes, default value is <code>0</code></td> + <td>any double</td> + <td><code>matrix</code></td> + </tr> + <tr> + <td><code>sparse</code></td> + <td>Only valid when writing CSV files. It specifies whether or not to explicitly output zero (<code>0</code>) values. Zero values are written out only when <code>sparse=FALSE</code>.</td> + <td>Yes, default value is <code>FALSE</code>.</td> + <td><code>TRUE</code>/<code>FALSE</code> in DML</td>
[... 1667 lines stripped ...]
