This "How-to" post provides an example of CUBE Voyager script to obtain frequency tables from matrix values. The example referenced in this post is the below:
communities.bentley.com/.../ex_5F00_Frequency_5F00_Calc.zip
1. Using FREQUENCY Control Statement
To obtain the frequency of occurrence of the values of work matrices with CUBE Voyager scripting is possible by using the FREQUENCY control statement in a matrix program. Details on the usage of this keyword are provided in the CUBE Voyager Reference Guide (9 Matrix Program > Control statements > FREQUENCY):
FREQUENCY: Matrix Control Statement that stratifies one matrix's values based upon the values of another. The following keywords are those used in the example provided in this post (please check the Reference Guide for other keywords):
| Keyword | Description |
| RANGE | Set of two, or three, numbers that establishes the valid values for stratification. The numbers are separated by a dash. The first number (RANGE[1]) is the lowest value for which there is to be a stratification. The second number (RANGE[2]) is the highest value for stratification. The third, optional, number (RANGE[3]) is an increment for stratification. If there is no increment, the default will be 1. During accumulation, if the value from BASEMW is less than RANGE[1], or higher than RANGE[2], the value from VALUEMW is accumulated into an out-of-range bucket. |
| BASEMW | Work matrix number ( MW[ ] ) whose values will be used for the stratification (e.g., the time matrix for a trip length distribution). |
| VALUEMW | Work matrix number ( MW[ ] ) whose values will be accumulated according to the values of BASEMW (e.g., the trip matrix for a trip length distribution). |
Example Ex1 "Using FREQUENCY with one accumulation matrix"
In the provided example named Ex1, the following script is used to derive the frequency report in the output main print file.
mw[1]=mi.1.1
mw[2]=mi.2.1
FREQUENCY BASEMW=2 VALUEMW=1 RANGE=-800-800-10
Work matrix 1 is considered the matrix storing the values to be accumulated in the different classes (input matrix 1.1). The work matrix 2 instead is considered the "bin" matrix whose values will be used for the stratification.
The range is given by the following values:
- -800 is the lowest value for stratification (note: this is negative in this example), referring to work matrix 2 bins
- 800 is the highest value for stratification (note: positive in this example), again referring to work matrix 2 bins
- 10 is the step size, representing the increment for the stratification
Considering the following:
- The actual minimum value in the bin work matrix 2 is -686.4 (I=225, J=2605)...
- ...but the minimum bin value where some non-null values are observed in the accumulation work matrix 1 is -618 (I=2454, J=580).
- The maximum bin value in the same matrix is 718.8 (I=1484, J=147), for this cell, non-null values are observed in the accumulation work matrix 1 as well.
It can be observed (in the main print file) that the frequency distribution report starts reporting (accumulating) from -620, as below:
BASEMW=2 VALUEMW=1 RANGE=-800,800,10
MW[2] Accum
>= - < Obs Sum Pct Pct
-------------------------------------------
-620 - -610 2 0.02 0.0 0.0 |
-610 - -600 1 0.01 0.0 0.0 |
-600 - -590 -- -- -- 0.0 |
(...)
and accumulates till the maximum value as below:
(...)
710 - 720 1 1.01 0.0 100.0 |
720 - 730 -- -- -- 100.0 |
730 - 740 -- -- -- 100.0 |
740 - 750 -- -- -- 100.0 |
750 - 760 -- -- -- 100.0 |
760 - 770 -- -- -- 100.0 |
770 - 780 -- -- -- 100.0 |
780 - 790 -- -- -- 100.0 |
790 - 800 -- -- -- 100.0 |
800+ -- -- -- 100.0 |
-------------------------------------------
Total Obs = 1,529,904
Total Sum = 412,838.5
Mean = -2.74
@I=J = 12,350.22
Example Ex2 "Using FREQUENCY with two accumulation matrices"
In this case, the used script is the below, where the same stratification matrix is used, but an additional accumulation matrix is accumulated.
mw[1]=mi.1.1 ;accumulated 1
mw[2]=mi.2.1 ;bins
mw[3]=mi.3.1 ;accumulated 2
FREQUENCY BASEMW=2 VALUEMW=1 RANGE=-800-800-10
FREQUENCY BASEMW=2 VALUEMW=3 RANGE=-800-800-10
Two separate frequency reports are provided in the main print file this time.
2. Using Voyager Scripting
Example Ex3 "Using Script with one accumulation matrix"
A different approach is used in the third example, with an explicit script outputting the table below:
(...)
This contain a separate accumulation and reporting of customized values, in this case null values and intrazonals (I=J). The script contains the following blocks:
- User definition of min value, max value and interval, similarly to the RANGE used in the previous examples
- User definition of the accumulation and stratification work matrices
- Declaration of two arrays (_frequ and _value) to store and accumulate frequency and values by category index
- JLOOP-ENDJLOOP block for the indexing of segments and accumulation of values (note: condition for treatment of negative values is needed)
- Final loop at the end of the accumulation process to output the values in the RECO table
Example Ex4 "Using Script with two accumulation matrices"
The last example is a generalization of example Ex3, considering more than one accumulation matrix, in particular, two in this case.
(...)