## The module "multi2colblocks" of the Mastrave modelling library

**Daniele de Rigo**

#### Copyright and license notice of the function multi2colblocks

Copyright © 2009,2010,2011 Daniele de Rigo

The file multi2colblocks.m is part of Mastrave.

Mastrave is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Mastrave is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Mastrave. If not, see http://www.gnu.org/licenses/.

#### Function declaration

[col_blocks,n_dims,n_points] = ... multi2colblocks(values,dims= [] ,points= [] ,in_orientation= 'columns' ,out_orientation= 'columns' )

#### Description

Utility for extracting from a given dataset ` values ` (a matrix or
multi-dimensional array) a sequence of subsets.

`is intended to be a collection of N multidimensional points (or layers). If`

**values**`has the default value, each column of`

**in_orientations**`is intended to contain N values corresponding to a given coordinate of N points (or layers). From`

**values**`, a sequence of blocks of coordinates - by default a sequence of sub-sets of columns - is to be aggregated in`

**values**`. Each block is composed by the N points (or by the number of points indicated by`

**col_blocks**`) whose non-selected coordinates are replaced with zeros. In case`

**points**`were a multidimensional array, the position of each coordinate dimension is equivalent to the position of the corresponding column in the matrix returned by multi2mat(`

**values**`,`

**values**`).`

**in_orientation**

#### Input arguments

valuesNumeric vector, matrix or multidimensional-array. It is intended to be a collection of N multidimensional points (or layers): if::numeric::has the default value, each column ofin_orientationsis intended to contain N values corresponding to a given coordinate of N points (or layers). Fromvalues, a sequence of blocks of coordinates ─ by default a sequence of sub-sets of columns ─ is to be aggregated invalues. Each block is composed by the N points (or by the number of points indicated bycol_blocks) whose non-selected coordinates are replaced with zeros.pointsdimsCell-array of dimension sets (or just a single dimension set) the i-th of them lists which of the n dimensions of::cellindex::(e.g. which of its n columns, ifvalueshas the default value) need to be preserved in the i-th block to be returned withinin_orientation. In casecol_blockswere a multidimensional array, the position of each coordinate dimension is equivalent to the position of the corresponding column in the matrix returned by multi2mat(values,values). ifin_orientationis an empty matrix [], all dimensions will be separately included, so that [] is considered equivalent { 1, 2, ... , n }. If omitted, the default value is an empty matrix: [].dimspointsCell-array of indexes to the points of::cellindex-1|numel::(e.g. its rows, ifvalueshas the default value) to which each block element belongs. The i-th array of indexes of the cell-arrayin_orientationrefers to the points ofpointsto be included within the i-th block ofvalues. The dimensions of these points which are listed in the i-th array ofcol_blockswill be included in the i-th block ofdims. The values of the omitted dimensions of the points will be replaced with zeros. If a vector of non-negative numbers is passed instead of a cell-array, the i-th element of it is expected to indicate the number of points ofcol_blocks(starting from the first point) to be included in the i-th block ofvalues. ifcol_blocksis an empty matrix [], all points will be included. If omitted, the default value is an empty matrix: [].pointsin_orientationDimension along which to split::scalar_index|string::into blocks (default: 'columns'). Eachvaluescolumn corresponds to a coordinate along the specified dimension ofcolbloks. In case a string is passed, valid options are: option │ meaning ───────────────┼───────────────────────────────────── 'columns' │ Splitvaluesdimensions by │ considering them column-wise (each │ dimension corresponds to a column). │ Equivalent to 1. (Default value). ───────────────┼───────────────────────────────────── 'rows' │ Splitvaluesdimensions by │ considering them row-wise (each │ dimension corresponds to a row). │ Equivalent to 2.valuesout_orientationDimension along which the blocks of::scalar_index|string::are to be packed in the sparse matrixvalues(default: 'columns'). In case a string is passed, valid options are: option │ meaning ───────────────┼───────────────────────────────────── 'columns' │ Packcol_blocksblocks so that each │ dimension corresponds to a column │ (column-wise). │ Equivalent to 1. (Default value). ───────────────┼───────────────────────────────────── 'rows' │ Packvaluesblocks so that each │ dimension corresponds to a row │ (row-wise). │ Equivalent to 2.values

#### Example of usage

See also: multi2mat, mat2multi, cell2sparse, mdeal Keywords: multidimensional-array, smart reshape, column-wise, row-wise Version: 0.7.2

#### Support

The Mastrave modelling library is committed to provide reusable and general - but also robust and scalable - modules for research modellers dealing with computational science. You can help the Mastrave project by providing feedbacks on unexpected behaviours of this module. Despite all efforts, all of us - either developers or users - (should) know that errors are unavoidable. However, the free software paradigm successfully highlights that scientific knowledge freedom also implies an impressive opportunity for collectively evolve the tools and ideas upon which our daily work is based. Reporting a problem that you found using Mastrave may help the developer team to find a possible bug. Please, be aware that Mastrave is entirely based on voluntary efforts: in order for your help to be as effective as possible, please read carefully the section on reporting problems. Thank you for your collaboration.