de Rigo, D. (2012). Partitioning a range from a set of values: the module "create_contiguous_intervals" of the Mastrave modelling library. In: Semantic Array Programming with Mastrave - Introduction to Semantic Computational Modelling. http://mastrave.org/doc/mtv_m/create_contiguous_intervals

## Partitioning a range from a set of values: the module "create_contiguous_intervals" of the Mastrave modelling library

Daniele de Rigo

The file create_contiguous_intervals.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

[intervals, bound_idx] = create_contiguous_intervals( boundary_set      ,
range        = [] )



#### Description

Given a vector of numbers boundary_set (and optionally the range to be covered by the union of the intervals to be created), this module returns a two-column matrix of contiguous intervals . If range is omitted or empty, it is intended to be an interval composed by the minimum and the maximum value of boundary_set . The returned intervals matrix may be described as composed by two column vectors a and b which represent the intervals' endpoints:

[a, b] = mdeal( intervals )

The i-th intervals row defines the i-th interval whose endpoints are respectively a (i) and b (i) . The first column vector a and the second one b will satisfy the following conditions:

all( a < b )
all( a == sort(a) )
all( b == sort(b) )
all( b(1:end-1) == a(2:end) )
a(1) == range(1)
b(end) == range(2)
intervals == [ a b ]

The aforementioned conditions refer to the case in which the input argument range is passed as numeric interval. The range argument also accepts non-numeric values. If range is the label '[)' (or '[['), boundary_set is constrained to be sort( a ) whilst the last element of b is set to exceed the maximum value of a by the average a difference:

b( end ) = max( a ) + mean( diff( a ) )

If range is the label '(]' (or ']]'), boundary_set is constrained to be sort( b ) whilst the first element of a is set to be the minimum value of b minus the average b difference:

a( 1 ) = min( b ) - mean( diff( b ) )

If range is the label '[]' the behavior is the same as when range is the empty vector [].

The function optionally returns the position matrix bound_idx of each element of boundary_set in the matrix intervals (if not belonging to boundary_set , range elements will be reported in the bound_idx matrix as NaN). If range limits exclude some elements of boundary_set , they will not be used to create intervals .

#### Input arguments


boundary_set           ::real::
vector or matrix of real numbers defining the
lower and upper boundary of each contiguous
interval to be created.  The upper boundary of the
n-th interval will be by definition the lower
boundary of the (n+1)-th interval.

range                  ::interval|(numeric,empty)|string::
2-columns vector of real numbers defining the
extreme values of the intervals to be created,
i.e. the lower boundary of the firts interval and
the upper boundary of the last interval.
If omitted or empty, default value is:
[ min( boundary_set (:)) max( boundary_set (:)) ]
If  range  is a string label, valid labels are:

range │ meaning
───────┼───────────────────────────────────────────
'[)'  │ Force the first column of  intervals
'[['  │ to be   sort(  boundary_set  )   and the
│ last value of the second column to
│ exceed   max(  boundary_set  )   by
│ the mean of the first column differences.
───────┼───────────────────────────────────────────
'(]'  │ Force the second column of  intervals
']]'  │ to be   sort(  boundary_set  )   and the
│ first value of the first column to be
│ min(  boundary_set  )  minus the mean of
│ the second column differences.
───────┼───────────────────────────────────────────
'[]'  │ Same as if  range  value were the empty
│ vector [].



#### Example of usage


% Basic usage
bset            = [20 10 50 30 40]
[ ints , bidx ] = create_contiguous_intervals( bset )

% Passing a numeric interval as  range  value
[ ints , bidx ] = create_contiguous_intervals( bset , [ 20  50 ] )
[ ints , bidx ] = create_contiguous_intervals( bset , [ 40  12 ] )
[ ints , bidx ] = create_contiguous_intervals( bset , [-inf 41 ] )
[ ints , bidx ] = create_contiguous_intervals( bset , [ 4   inf] )
% Borderline case: scalar or empty  boundary_set
[ ints , bidx ] = create_contiguous_intervals( [20] , [ 4   inf] )
[ ints , bidx ] = create_contiguous_intervals( []   , [ 4   inf] )

% Passing a label as  range  value
[ ints , bidx ] = create_contiguous_intervals( bset , '[)' )
[ ints , bidx ] = create_contiguous_intervals( bset , '(]' )
% Borderline case: scalar or empty  boundary_set
[ ints , bidx ] = create_contiguous_intervals( [20] , '[)' )
[ ints , bidx ] = create_contiguous_intervals( [20] , '(]' )
[ ints , bidx ] = create_contiguous_intervals( []   , '[)' )
[ ints , bidx ] = create_contiguous_intervals( []   , '(]' )


See also:
find_disjoint_intervals

Keywords:
intervals, ordering

version: 0.2.7

#### 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.

Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016 Daniele de Rigo