whatIf? Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Working with Maps ======

Mapping allows you to pass the elements from one variable into the elemants of another variable based on defined map structure. Here we will outline the instances that mapping is used.

===== Map Tool =====

The map tool is the main way to map the elements in one variable according to a map into the elements in another variable. There are three main types of maps that the map tool uses: full matrix, dimension and index. Examples and uses of these mapping types are explored below

==== Full Matrix Mapping ====

The full matrix map is used to map a complete set of elements to another set of the elements and is commonly used to aggregate elements into classes and transfer data from one set of elements to another set of elements.

=== Aggregation into classes ===

This is a common use of the map tool. Using the example below the map tool is used to aggregate populations by age into several status classes based on the data in the image below. \\
{{:howtos:toolcoding:mapdata.gif|}}

The supporting tool script code for building the informants and importing data from the data source can be found [[howtos:toolcoding:mapEx1|here]].

The first step is to create the map indicating how the elements relate to each other. For this example ages 0 to 1 are classified as new, ages 2 to 4 are classified as young and ages 5 to 6 are classified as old.

<code>

local vaToac[ageClass,vehicleAge] = create (; dim=ageClass, dim=vehicleAge, format=mapping, \
	0 -> new, \
	1 -> new, \
	2 -> young, \
	3 -> young, \
	4 -> young, \
	5 -> old, \
	6 -> old)

table (vaToac[ageClass,vehicleAge])

</code>

By using the table tool you can see the matrix that has been constructed in the vaToac[ageClass,vehicleAge] variable and how one element is mapped to the other (by default Table hides all zero values). \\

{{:howtos:toolcoding:vatoac.gif|}}

<code>

local vehicleClass[vType,ac] = map (vehicles[vType,va], vaToac[ageClass,vehicleAge])

table (vehicleClass[vType,ac])

</code>

As you can see in the following table every point for ages 0 to 1 is aggregated and classified as "new", while ages 2 to 4 aggregated and classified as "young" and ages 5 to 6 are aggregated and classified as "old"

{{:howtos:toolcoding:mapresults.gif|}}


=== Element mapping ===

One reason for creating a map is because the element names in the source data do not match the elements in your model. This map can be as simple as passing the source data from [[using_maps#one element to another element|one element to another]], passing data from one element to many elements in the model on a [[using_maps#one element to many elements|one-to-one basis]] or passing data from one source element to many elements in the model [[using_maps#one element to many elements using splits|based on specified splits]].

All of the following element mapping examples refer to the data found in the image below. \\

{{:howtos:toolcoding:mapdata2.gif|}}

The supporting tool script code for building the informants and importing data from the data source can be found [[howtos:toolcoding:mapEx2#source data from one element to another|here]].

== one element to another element ==

Mapping source data from one element to another is useful when the element names in your database do not match the element names in your model.

The first step is to create the map indicating how the elements relate to each other. For this example naphtha is mapped to Gasoline, diesel is mapped to Diesel and fuel oil is mapped to IFO.

<code>

local fTypeDBTofTypeM[fTypeM,fTypeDB] = create (; dim=fuelType_model, dim=fuelType_DB, format=mapping, \
	"naphtha" -> "Gasoline", \
	"diesel" -> "Diesel", \
	"fuel oil" -> "IFO")

table (fTypeDBTofTypeM[fTypeM,fTypeDB])

</code>

By using the table tool you can see the map that has been constructed in the fTypeDBTofTypeM[fTypeM,fTypeDB] variable and how one element is mapped to the other (by default Table hides all zero values). \\

{{:howtos:toolcoding:ftypedbtoftypem.gif|}}

<code>

local fuelEm_model[fTypeM,em] = map (fuelEm_DB[fTypeDB,em], fTypeDBTofTypeM[fTypeM,fTypeDB])

table (fuelEm_model[fTypeM,em])

</code>

The table below displays the results of the map tool, see how the row names now correspond to the elements in the fuelType_model dimension.

{{:howtos:toolcoding:mapresults2a.gif|}}

== one element to many elements ==

This is useful when the granularity of your elements is finer than the elements provided in your source data.  For example your source data contains emissions data for fuel oil however your model captures the various grades of fuel oil as seen below.

The supporting tool script code for building the informants and importing data from the data source can be found [[howtos:toolcoding:mapEx2#source data from one element to many elements in the model with and without splits|here]].

As in the previous example the first step is to create the map indicating how the elements relate to each other. For this example naphtha is mapped to Gasoline, diesel is mapped to Diesel and fuel oil is mapped to both IFO and HFO.

<code>

local fTypeDBTofTypeM[fTypeM,fTypeDB] = create (; dim=fuelType_model, dim=fuelType_DB, format=mapping, \
	"naphtha" -> "Gasoline", \
	"diesel" -> "Diesel", \
	"fuel oil" -> "IFO, HFO")

table (fTypeDBTofTypeM[fTypeM,fTypeDB])

</code>

By using the table tool you can see the matrix that has been constructed in the fTypeDBTofTypeM[fTypeM,fTypeDB] variable and how one element is mapped to the other (by default Table hides all zero values).

{{:howtos:toolcoding:ftypedbtoftypem2.gif|image}}

<code>

local fuelEm_model[fTypeM,em] = map (fuelEm_DB[fTypeDB,em], fTypeDBTofTypeM[fTypeM,fTypeDB])

table (fuelEm_model[fTypeM,em])

</code>

The table below displays the results of the map tool, see how the row names now correspond to the elements in the fuelType_model dimension and how the values have been duplicated for both IFO and HFO.

{{:howtos:toolcoding:mapresults2b.gif|image}}

== one element to many elements using splits ==

The above exmaple simply copied the data for fuel oil in the database to both the IFO and HFO elements in the model. However there may be times that you want the data to be split in some way between the elements. Unfortunately fractions can not be specified when using the "goes into" or "->" parameter. Therefore you must use the following method to specify how the data is split between two or more elements. 

The supporting tool script code for building the informants and importing data from the data source can be found [[howtos:toolcoding:mapEx2#sourcedatafromoneelementtomanyelementsinthemodelwithandwithoutsplits|here]].

As in the previous example the first step is to create the map indicating how the elements relate to each other. This map is created differently than the previous examples. In this case you need to manually populated that map by using the method outlined below.

<code>

local fTypeDBTofTypeM[fTypeM,fTypeDB] = create (; dim=fuelType_model, dim=fuelType_DB, \
	data="1 0 0 0 1 0 0 0 0.5 0 0 0.5")

table (fTypeDBTofTypeM[fTypeM,fTypeDB])

</code>

By using the table tool you can see the map that you have manually constructed in the fTypeDBTofTypeM[fTypeM,fTypeDB] variable and how this relates the syntax found in the code above. (by default Table hides all zero values).

{{:howtos:toolcoding:ftypedbtoftypem3.gif|image}}

<code>

local fuelEm_model[fTypeM,em] = map (fuelEm_DB[fTypeDB,em], fTypeDBTofTypeM[fTypeM,fTypeDB])

table (fuelEm_model[fTypeM,em])

</code>

The table below displays the results of the map tool, see how the row names now correspond to the elements in the fuelType_model dimension and how the values have been multiplied by 0.5 for both IFO and HFO.

{{:howtos:toolcoding:mapresults2c.gif|image}}

==== Dimension Mapping ====

The dimension map is a quick map that is used to map a set of elements to another set of the elements. However for a dimension map to work the element names in both informants need to be spelled exactly the same. This method is useful for mapping data from a set of elements to a subset of those elements as seen in the example below. \\

{{:howtos:toolcoding:mapdata3.gif|}}

The supporting tool script code for building the informants and importing data from the data source in the table above can be found [[howtos:toolcoding:mapEx3|here]].

Unlike the full matrix method, dimension mapping does not require the creation of a map template because the mapping is based on element names. Using the display tool below we can what elements are in appType and waterApp informants to ensure that dimension mapping is possible.

<code>

display (appType[], waterApp[])

</code>

{{:howtos:toolcoding:apptypedisplay.gif|}} {{:howtos:toolcoding:waterappdisplay.gif|}}

We can see that both informant contain the elements dishWasher and waterHeater so we can proceed with the dimension mapping of these elements as follows.

<code>

local waterAppliances[wApp,t] = map (appliance[aType,t]; appType->waterApp)

table (waterAppliances[wApp,t])

</code>

The table below displays the results of the map tool, see how the variable waterApplicanes[wApp,t] now contains data for only the dishWasher and waterHeater elements

{{:howtos:toolcoding:mapresults3.gif|image}}

==== Index Mapping ====

Index mapping allows you to map the right-most dimension of a variable onto the new dimension. This is the most difficult method to use because you need to know the position in the array or index number of the element(s) you are interested in mapping as well as the order of your informants.

This example demonstrates how you can take a subsection of elements from the data in the table below and map them into the complete set using both the one to one and many to one mapping parameters.

{{:howtos:toolcoding:mapdata4.gif|}}

The supporting tool script code for building the informants and importing data from the data source can be found [[howtos:toolcoding:mapEx4|here]].

As in the full matrix method we need to first create a map indicating how the elements relate to each other. The data parameter in the create tool indicates the position in the array or the index number that we will be mapping to. Also notice that the map tool requires you to specify the new dimension

<code>

local mapPriaire[pp] = create (; dim=prairieProv, dataType=integer, data="4 5 6")

regions_a[t,r] = map ( prairieData[t,pp], mapPriaire[pp]; mapping=oneToOne, newDim=region)

table (regions_a[t,r])

</code>

As you can see in the following table data for Alberta, British Columbia and Saskatchewan has been individually mapped into the variable regions_a[t,r].

{{:howtos:toolcoding:mapresults4a.gif|image}}

As with the one to one mapping the map indicating how the elements related to each other needs to be created. However notice how the index numbers are all pointing to the same position in the array.

<code>

local mapAtlantic[ap] = create (; dim=atlanticProv, dataType=integer, data="1 1 1 1")

regions_b[t,r] = map ( atlanticData[t,ap], mapAtlantic[ap]; mapping=manyToOne, newDim=region)

table (regions_b[t,r])

</code>

In contrast to the one to one example all of the values for the Atlantic provinces have been aggregated and mapped into the Atlantic element in the regions_b[t,r] variable.

{{:howtos:toolcoding:mapresults4b.gif|image}}

===== Mapcat Tool =====

Categorizations are useful ways of grouping elements into meaningfull collections. By categorizing related elements together you can create elements that are more descriptive while also reducing the number of elements you are carrying through your model.

The mapcat tool is used to map group and member element informants onto a category and conversely it is also used to "break" a category apart into its compnent group and member informants using the mapcat tool.

{{:howtos:toolcoding:mapdata5.gif|}}

The supporting tool script code for building the informants and importing data from the data source in the table above can be found [[howtos:toolcoding:mapEx5|here]].

The mapping template for a category is held in the category itself. As you can see in the code below the provinces is the group place holder and the location are members of the province and they are related to each based on a relationship provided by the modeler.

<code>

localinformant provLoc[p->l] = create (; object=category, groups=province, members=location, \
	"Alberta"="west", \
	"British Columbia"="west",\
	"Newfoundland"="east",\
	"Nova Scotia"="east",\
	"Ontario"="central",\
	"PEI"="east")

</code>

This categorization or map can then be applied using the mapcat tool below to either bring the elements together in the category or split the category apart

<code>

local regionsCat[p->l] = mapcat (regionData[p,l]; category=provLoc)

table (regionsCat[p->l])

</code>

The table below displays how the province and location informants have been categorized into the provLoc category.

{{:howtos:toolcoding:mapresults5a.gif|image}}

<code>

local regionsSplit[p,l] = mapcat (regionsCat[p->l])

table (regionsSplit[p,l])


</code>

Inversely the table below displays how we can split the category onto its component group and member informants

{{:howtos:toolcoding:mapresults5b.gif|image}}
whatIf? Wiki

User Tools

Site Tools

Page Tools
