Examples and FAQ
This section contains examples that demonstrate the Matrix program, along with a link to frequently asked questions.
Example 1: Generate zonal data
This sample program generates a zonal data file from input files. The resulting zonal file will contain combined data from the input zonal data and a summary of trips to the zones that are in the central business district.
RUN PGM=MATRIX mati[1]=tripfile.mat zdati[1]=socoecon.dat,z=#1, pop=#2, area=#3, income=#4, hh1=#5, hh2=#6, hh3=#7 zdati[2]=employ.dat, z=#1, gov=#2, retail=#3, other=#4 ARRAY pop=10, area=10 totemp=10, tothh=10 ; this is a 10 zone problem area[i]=zi.1.area totemp[i]=zi.2.gov + zi.2.retail + zi.2.other tothh[i]=zi.1.hh1 + zi.1.hh2 + zi.1.hh3 jloop include=1-5,38,56-100,145-150 ;cbd zones cbdtrips[j] = cbdtrips[j] + mi.1.tottrips[j] endjloop if (i==zones) ; at last zone jloop ; write a file of zonal records print file=newzdat.zda form=6 list=j(3) pop[j] area[j] totemp[j] tothh[j] cbdtrips[j] endjloop endif ENDRUN
This example program get I-J values for records with trip tours on them. The MATRIX program processes the tours.dat file. For each leg of the tour, it looks up highway or transit time based on the major mode for that journey. Mode 1 corresponds to highway, transit otherwise.
The program will read each input record from the RECI file and do calculations as specified. The MatVal function is used to randomly access any i-j value from any input matrix.
The format is: MatVal( filenumber, tablenumber, i, j, failvalue)
The failvalue is returned if lookup fails (invalid filenumber, tablenumber, i, or j). This script has been tested for validity, but has not been thoroughly tested for logical content.
RUN PGM=MATRIX mati=hwytime.mat,trntime.mat reci=tours.dat, org=23, dst=26 ; there are 80 fields on the record, can be referenced by reci.nfield[#]. ; Field 23 can also be referenced as ri.org, and field 26 as ri.dst ; setup array to store time values with max of 8 legs on each tour array hwyt=8 trnt=8 set val=0, vars=hwyt trnt ; initialize output variables ; trips from org to dst from=ri.org leg=1 loop stops=32,42,5 ; flds 32,37,42 if (reci.nfield[stops] > 0) ; if main mode org-dst is hwy if (reci.nfield[76] = 1) ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,reci.nfield[stops],0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,reci.nfield[stops],0) endif leg=leg+1 from=reci.nfield[stops] endif endloop ; from last stop to dst if (reci.nfield[76] = 1) ; if main mode org-dst is hwy ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,ri.dst,0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,ri.dst,0) endif ; trips from dst to org from=ri.dst leg=5 loop stops=47,57,5 if (reci.nfield[stops] > 0) if (reci.nfield[77] = 1) ; if main mode dst-org is hwy ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,reci.nfield[stops],0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,reci.nfield[stops],0) endif leg=leg+1 from=reci.nfield[stops] endif endloop ; from last stop to org if (reci.nfield[77] = 1) ; if main mode dst-org is hwy ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,ri.org,0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,ri.org,0) endif ; write out I/P record(RECI) and append highway and transit time values print file=tourtime.dat, form=5 list=reci, hwyt[1],hwyt[2],hwyt[3],hwyt[4],hwyt[5],hwyt[6],hwyt[7],hwyt[8], trnt[1],trnt[2],trnt[3],trnt[4],trnt[5],trnt[6],trnt[7],trnt[8] ; compute totals of highway and transit time arrays hwyt_tot=arraysum(hwyt) trnt_tot=arraysum(trnt) ENDRUN
Example 3: RECI/RECO processing
This is an example of using RECI/RECO to process DBF data files.
RUN PGM=MATRIX This is an example of using RECI/RECO to process DBF data files. FILEI RECI = ZONES_2002.DBF FILEO RECO[1] = ZONES_2002_NEW.DBF, FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), EXCLUDERECI=HOUSEHOLDS FILEO RECO[2] = ZONES_2010.DBF, FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), POP_2010(8.0), HH_2010(8.0), HHsiz_2010(4.2), Pden_2010(4.2), EXCLUDERECI=HOUSEHOLDS FILEO RECO[3] = ZONES_2020.DBF, FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), POP_2010(8.0), HH_2010(8.0), HHsiz_2010(4.2), Pden_2010(6.2), POP_2020(8.0), HH_2020(8.0), HHsiz_2020(4.2), Pden_2020(6.2), EXCLUDERECI=HOUSEHOLDS ; compute regional base year statistics TotalHH=TotalHH+RECI.NFIELD[5] TotalPop=TotalPop+RECI.NFIELD[6] avgHHsize=TotalPop/TotalHH ; print regional base year statistics if (I=0) ; check for end of file PRINT LIST='Total Households = ',TotalHH PRINT LIST='Total Population = ',TotalPop PRINT LIST='Average Household size = ',avgHHsize endif ; rename RECI field RO.HH_2002=ri.HOUSEHOLDS ; calculate zonal average household size for base year RO.HHsiz_2002=ri.POP_2002/HH_2002 ; calculate zonal population density per/acre for base year RO.Pden_2002=ri.POP_2002/(ri.AREA/43560) ; factor base year data for 2010 RO.HH_2010=HH_2002*1.2 RO.POP_2010=RECI.NFIELD[6]*1.4 RO.HHsiz_2010=POP_2010/HH_2010 RO.Pden_2010=POP_2010/(ri.AREA/43560) ; factor base year data for 2020 RO.HH_2020=HH_2002*1.5 RO.POP_2020=RECI.NFIELD[6]*1.8 RO.HHsiz_2020=POP_2020/HH_2020 RO.Pden_2020=POP_2020/(ri.AREA/43560) ; write data to defined output files WRITE RECO=1,2,3 ENDRUN
This example uses the CHOICE command in MATRIX to estimate a singly-constrained gravity model, constrained on production trip ends.
RUN PGM=MATRIX FILEO MATO[1] = "C:\CUBETOWN\MODEL\MODELS\SINGLEPRODDIST.MAT" MO=1 NAME=HBW FILEI ZDATI[1] = "{SCENARIO_DIR}\TRIPENDS.DBF" FILEI MATI[1] = "{SCENARIO_DIR}\CURRENTCOSTS.MAT" ;The general approach for a singly constrained in Voyager is to use the ;MATRIX program and the CHOICE command to implement a destination choice ;model. ;If you require a gamma curve deterrence function rather than the negative exponential,you need to specify the appropriate calculations yourself. ;This example gives a "destination choice" model constrained on production trip ends. CHOICE ALTERNATIVES=all1, DEMAND=ZI.1.P1, COSTS=mi.1.1, ODEMAND=1, STARTMW=99, DESTSPLIT = TOTAL 0.2 all1 ;To apply singly constrained on attractions; ;- transpose the cost matrix, saving it to output file ;- run MATRIX, reading the transposed costs, reversing your use of the ; production and attraction data (i.e., TOTAL=ZI.1.A[1] etc) ; to implement a destination choice, with attraction totals as the single constraint. ;- transpose the resulting matrix to correct orientation. ENDRUN
Example 5: DBI processing using JOINTODBI
This example uses DBI processing to combine two fields from different tables into a new table, using the JOINTTODBI functionality. The inputs and output are stored in an MDB file.
RUN PGM=MATRIX FILEO RECO[1] = "DBI_Examples.mdb\AlfaBeta2", FIELDS=ZONE_ ALFA BETA FILEI DBI[2] = "DBI_Examples.mdb\BETA", SORT=ZONE_ JOINTODBI=1 JOINTOFIELDS=ZONE_ FILEI DBI[1] = "DBI_Examples.mdb\ALFA" ZONES=1 LOOP k=1,DBI.1.NUMRECORDS x=DBIReadRecord(1,k) RO.ZONE_=DI.1.ZONE_ RO.ALFA=DI.1.ALFA RO.BETA=DI.2.BETA WRITE RECO=1 ENDLOOP ENDRUN
Example 6: DBI processing using AUTOARRAY
This example performs the same function as Example 5: DBI processing using JOINTODBI. This time, the AUTOARRAY functionality accomplishes the task.
RUN PGM=MATRIX FILEO RECO[1] = "DBI_Examples.mdb\AlfaBeta3", FIELDS = ZONE_ ALFA(10.4) BETA(10.4) FILEI DBI[2] = "DBI_Examples.mdb\BETA", AUTOARRAY=BETA FILEI DBI[1] = "DBI_Examples.mdb\ALFA", AUTOARRAY=ALFA ZONES = 1 LOOP L3=1,DBI.1.NUMRECORDS,1 RO.ZONE_ = L3 RO.ALFA = DBA.1.ALFA[L3] RO.BETA = DBA.2.BETA[L3] WRITE RECO = 1 ENDLOOP ENDRUN
Example 7: Simple logit model using XCHOICE
This model uses XCHOICE to implement a simple logit model, where demand is allocated between car and bus trips.
RUN PGM=MATRIX MSG='Absolute XChoice' FILEI MATI[1] = ".\Inputs\COSTCAR.MAT" FILEI MATI[2] = ".\Inputs\COSTPTBUS.MAT" FILEI MATI[3] = ".\Inputs\ALLDEMAND.MAT" FILEO MATO[1] = ".\ABSOLUTE_OD.MAT", MO=15-16 MW[1] = MI.3.1 MW[3] = MI.1.1 MW[4] = MI.2.1 ; Absolute logit model XCHOICE, ; List choices ALTERNATIVES = car, bus, ; Input total demand DEMANDMW = 1, ; Input costs COSTSMW = 3, 4, ; Forecast demand ODEMANDMW = 15,16, ; Model structure SPLIT = TOTAL 0.02 car bus, ; Forecast composite cost SPLITCOMP = 19, ; Working matrices STARTMW = 30 ENDRUN
Example 8: Cost-based nested logit model using XCHOICE
This example employs XCHOICE to implement a hierarchical logit choice model. The top-level options are car and public transportation, with bus and rail as options within public transport.
RUN PGM=MATRIX MSG='Cost Based Nested XChoice' FILEI MATI[4] = ".\Inputs\AllDemand.mat" FILEI MATI[3] = ".\Inputs\CostPTrail.mat" FILEI MATI[1] = ".\Inputs\COSTCAR.MAT" FILEI MATI[2] = ".\Inputs\COSTPTBUS.MAT" FILEO MATO[1] = ".\Nested_OD.MAT", MO=14-16 MW[1] = MI.4.1 MW[4] = MI.1.1 MW[5] = MI.2.1 MW[6] = MI.3.1 ; Absolute hierarchical logit model ; Specify scale parameters lambda = 0.02 mu = 0.03 XCHOICE, ; List choices ALTERNATIVES = car bus rail, ; Input demand DEMAND = 1, ; Input costs COSTSMW = 4, 5, 6, ; Forecast demand ODEMANDMW = 14,15,16, ; Model Structure ; Top level nest SPLIT = TOTAL lambda car pt, ; Forecast composite cost top level SPLITCOMP = 19, ; PT nest SPLIT = PT mu bus rail, ; Forecast composite cost PT level SPLITCOMP = 20, ; Working matrices STARTMW =70 ENDRUN
Please see FAQ - Matrix & Distribution in Frequently Asked Questions.