From ffc993d0b948e1b438931d42ba12a95c57501f7e Mon Sep 17 00:00:00 2001 From: Sakari Malkki Date: Tue, 17 Dec 2024 11:12:40 +0200 Subject: [PATCH] Updates readme with better explanations for computations --- docs/README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 67 insertions(+), 8 deletions(-) diff --git a/docs/README.md b/docs/README.md index d36d9dc..43b9b12 100644 --- a/docs/README.md +++ b/docs/README.md @@ -264,6 +264,25 @@ The database needs to contain alias files for each language used in the database ```Matrix``` class has a set of extension methods for performing basic computations for the datapoints. +Values of dimensions can be summed or multiplied together to new values. If the original matrix has the following structure: + +|| col-0 || col0-1 || col0-2 || +||-----------|-----------|-----------|-----------|-----------|-----------| +|| col1-0 | col1-1| col1-0 | col1-1| col1-0 | col1-1 | +|row0-0| 0 | 1 | 2 | 3 | 4 | 5 | +|row0-1| 6 | 7 | 8 | 9 | 10 | 11 | +|row0-2| 12 | 13 | 14 | 15 | 16 | 17 | + +If we sum the row0 dimension's values 1 and 2 together to form a new value "rowSum", the resulting matrix will look like this: + +|| col-0 || col0-1 || col0-2 || +||-----------|-----------|-----------|-----------|-----------|-----------| +|| col1-0 | col1-1| col1-0 | col1-1| col1-0 | col1-1 | +|row0-0| 0 | 1 | 2 | 3 | 4 | 5 | +|row0-1| 6 | 7 | 8 | 9 | 10 | 11 | +|row0-2| 12 | 13 | 14 | 15 | 16 | 17 | +|rowSum | 18 | 20 | 22 | 24 | 26 | 28 | + #### Sum ```SumToNewValue()``` computes sums of datapoints defined by a subset of values from a given dimension. The method takes a new dimension value as a parameter that will define the resulting values. @@ -271,15 +290,20 @@ The method also has an asyncronous variant ```SumToNewValueAsync()```. ##### Example ```csharp - DimensionValue newDimensionValue = new("sumValueCode", new("en", "Sum value")); // New single language dimension value - Matrix output = matrix.SumToNewValue(newDimensionValue, matrix.Metadata.Dimensions[0]); // Sums up all values in the first dimension and creates a new dimension value for the result + DimensionValue newDimensionValue = new("sumValueCode", new("en", "Sum value")); + Matrix output = matrix.SumToNewValue(newDimensionValue, matrix.Metadata.Dimensions[0]); ``` ```AddConstantToSubset()``` adds a constant to a subset of datapoints. Also has an asynchronous variant ```AddConstantToSubsetAsync()```. ##### Example ```csharp - Matrix output = matrix.AddConstantToSubset(matrix.Metadata.Dimensions[0], 5); // Adds 5 to all values in the first dimension + IMatrixMap map = new MatrixMap([ + new DimensionMap("var0", ["var0_val0"]), + new DimensionMap("var1", ["var1_val1", "var1_val2"]), + ]); + + Matrix output = matrix.AddConstantToSubset(map, 5); ``` #### Multiplication @@ -289,15 +313,20 @@ The method also has an asyncronous variant ```MultiplyToNewValueAsync()`` ##### Example ```csharp - DimensionValue newDimensionValue = new("productValueCode", new("en", "Product value")); // New single language dimension value - Matrix output = matrix.MultiplyToNewValue(newDimensionValue, matrix.Metadata.Dimensions[0]); // Calculates the product of all values in the first dimension and creates a new dimension value for the result + DimensionValue newDimensionValue = new("productValueCode", new("en", "Product value")); + Matrix output = matrix.MultiplyToNewValue(newDimensionValue, matrix.Metadata.Dimensions[0]); ``` ```MultiplySubsetByConstant()``` Multiply a subset of datapoints by a constant. Also has an asynchronous variant ```MultiplySubsetByConstantAsync()```. ##### Example ```csharp - Matrix output = matrix.MultiplySubsetByConstant(matrix.Metadata.Dimensions[0], 5); // Multiplies all values in the first dimension by 5 + IMatrixMap map = new MatrixMap([ + new DimensionMap("var0", ["var0_val0"]), + new DimensionMap("var1", ["var1_val1", "var1_val2"]), + ]); + + Matrix output = matrix.MultiplySubsetByConstant(map, 5); ``` @@ -305,16 +334,46 @@ The method also has an asyncronous variant ```MultiplyToNewValueAsync()`` ```DivideSubsetBySelectedValue()``` divides a subset of datapoints defined by values from one dimension with datapoints defined by a value from the same dimension. Also has an asyncronous variant ```DivideSubsetBySelectedValueAsync()``` +If the original matrix has the following structure: + +|| col-0 || col0-1 || col0-2 || +||-----------|-----------|-----------|-----------|-----------|-----------| +|| col1-0 | col1-1| col1-0 | col1-1| col1-0 | col1-1 | +|row0-0| 0 | 1 | 2 | 3 | 4 | 5 | +|row0-1| 6 | 7 | 8 | 9 | 10 | 11 | +|row0-2| 12 | 13 | 14 | 15 | 16 | 17 | +|rowSum | 18 | 20 | 22 | 24 | 26 | 28 | + +And we divide row dimension values row0-1 and row0-2 by rowSum the resulting matrix will look like this: + +|| col-0 || col0-1 || col0-2 || +||-----------|-----------|-----------|-----------|-----------|-----------| +|| col1-0 | col1-1| col1-0 | col1-1| col1-0 | col1-1 | +|row0-0| 0 | 1 | 2 | 3 | 4 | 5 | +|row0-1| 0.33 | 0.35 | 0.36 | 0.38 | 0.39 | 0.41 | +|row0-2| 0.67 | 0.65 | 0.64 | 0.63 | 0.61 | 0.59 | +|rowSum | 18 | 20 | 22 | 24 | 26 | 28 | + ##### Example ```csharp - Matrix output = matrix.DivideSubsetBySelectedValue(matrix.Metadata.Dimensions[0], matrix.Metadata.Dimensions[1].Values[0].Code); // Divides all values in the first dimension by the first value in the second dimension + IMatrixMap map = new MatrixMap([ + new DimensionMap("var0", ["var0_val0"]), + new DimensionMap("var1", ["var1_val1", "var1_val2"]), + ]); + + Matrix output = matrix.DivideSubsetBySelectedValue(matrix.Metadata.Dimensions[0], matrix.Metadata.Dimensions[1].Values[0].Code); ``` ```DivideSubsetByConstant()``` Divide a subset of datapoints by a constant. Also has an asynchronous variant ```DivideSubsetByConstantAsync()```. ##### Example ```csharp - Matrix output = matrix.DivideSubsetByConstant(matrix.Metadata.Dimensions[0], 2); // Divides all values in the first dimension by 2 + IMatrixMap map = new MatrixMap([ + new DimensionMap("var0", ["var0_val0"]), + new DimensionMap("var1", ["var1_val1", "var1_val2"]), + ]); + + Matrix output = matrix.DivideSubsetByConstant(map, 2); ```