Semantic array programming: abstract, portable and scalable data-transformation modelling for the community of computational scientists.
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
Copyright and license notice of the function create_contiguous_intervals
Copyright © 2007,2008,2009,2010,2011,2012 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.