---
title: "Adding a new crop to GLOBIOM"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Adding a new crop to GLOBIOM}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

GLOBIOM represents 18 crops globally and 27 crops for the European Union. The more detailed crop distribution maps generated with `mapspamc` can be used to add an additional crop for a specific country. Reasons for doing so may be that the crop is of large importance for the country in terms of production, consumption or trade. The first step is to ensure that the new crop is added to the updated land cover and crop distribution files that are created with the `create_globiom_input()` function. This is done by updating the table that maps the `mapspamc` crops to the 18 GLOBIOM crops, which is stored in `crop2globiom` - a data file that is part of the `mapspam2globiom` package. In the next step several adjustments need to be made in GLOBIOM.

In the example below, we will add coffee as a separate crop. 

```{r eval = FALSE}
# Update crop2globiom.csv and map coff to coff (instead of the rest category) and overwrite
crop_map <- crop2globiom %>%
  mutate(globiom_crop = ifelse(crop == "coff", "Coff", globiom_crop))
```

When `create_globiom_input()` is run with the updated mapping, coff will be includes as a separate crop in the gdx file. 

In GLOBIOM, a crop can enter the model either as a crop that is only produced in the country of interest and traded with the rest of the world, or a crop that is produced and consumed in the whole world and traded bilaterally. As the focus is here on country-level crop distribution maps, we take the example of including a specific crop in terms of area and production only for the country of interest, with trade to and from the rest of the world. This example starts from the point where the new crop distribution maps have been prepared and added to the GLOBIOM database to replace the global data. As described in the section on [Post-processing](post_process.html), the new crop also needs to be added to the `crop2globiom.csv` file that contains the mapping between the crop distribution maps generated with `mapspamc` and the GLOBIOM crops.
 
To add a new crop, we take the following steps:

1.	Assigning the new crop in sets
2.	Supply
3.	Demand
    a.	Adding demand in base year
    b.	Shifting demand in scenarios
4.	Trade

In the remainder, we take the example of cocoa production in Indonesia. All our changes take place in the model folder

###	Assigning the new crop in sets

we have to add the new crop in the relevant sets where other crops are reported. This happens in the following places:

```
decl_Rsets.gms
-	CROP(SPECIES)
-	PRODUCT(ALLPRODUCT)
-	PRIMARY(PRODUCT)
-	FINALP(PRODUCT)
-	CROPS(PRODUCT)

decl_sets.gms
-	ALLITEM
-	SPECIES(ALLITEM)   
-	ALLPRODUCT(ALLITEM)
-	ALLCROPS(ALLPRODUCT)
-	Cropprodmap(SPECIES,ALLPRODUCT)
```

###	Supply

Production and productivity of all crops, including the new crop, has been scaled to FAOstat data as described in the [Post-processing](post_process.html). Furthermore, in the base year, the producer price for the modeled crops is calibrated on FAOSTAT data. Therefore, the crop of interest should be added in the supply data (in 1000 tons) and production data (tonnes).

```
Data_supply.gms
TABLE SData(ANYREGION,ALLPRODUCT,CURVE)  Supply Data in 1000 units
Proddata_c.gms
PARAMETER
PRODATA_C(ANYREGION,ALLITEM,DataItems) Production data for crops (tonnes)
 /
   IndonesiaReg.Ccoa.YIELD                                              0.51
   IndonesiaReg.Ccoa.PRODQ                                         568535.80
   IndonesiaReg.Ccoa.AreaHarv                                     1138085.20
```

In addition to yield responses to prices, GLOBIOM has an assumption on technological change that reflect the increase of yield over time independently from market mechanisms, due to progress in e.g. breeding, introduction of new varieties, and technology diffusion. This exogenous yield change is stored in the parameter `YLD_SSP_STAT(*,ANYREGION,ALLPRODUCT,ALLYEAR)` and is dependent on the socio-economic pathways. For the year 2000, the exogenous yield change gets the value 1, after which it moves in a cumulative fashion. For the producing region and the crop to be added, the exogenous yield change needs to be added in the file `data_yld_SSPs.gms`, located in the finaldata folder.

```
TABLE YLD_SSP_STAT(*,ANYREGION,ALLPRODUCT,ALLYEAR) Crop yield shifter for SSPs - Static income groups (2000 = 1)
     	    2010      2020      2030      2040      2050
"SSP2"."IndonesiaReg"."Ccoa"  1.000     1.000     1.000     1.000     1.000    
```

###	Demand

Food demand is in GLOBIOM endogenous and depends on population, gross domestic product (GDP) and own product price. Population and GDP are exogenous variables while prices are endogenous. A change in income per capita in the baseline drives a change in the food diet, associated to changing preferences.

The demand for non-producing regions can be set-up in two ways. If the new crop is introduced for the whole world (i.e. everywhere where in the base year the crop did grow, production is initialized), the demand will also be initialized at each of the regions in the world in the DDATA parameter above. In case the crop is only produced in the country of focus (i.e. other countries are likely also producing but for these countries no data is available), a demand is only created for the country of focus.

#### Adding demand in base year

The `DDATA` parameter captures the nonlinear demand function parameters including initial demand quantity, price and own-price elasticity by final product and region. Every producing region is automatically also a consuming region and therefore these items need to be filled-in for the region in `data_demand.gms` using the following format:

```
DData(ANYREGION,ALLPRODUCT,CURVE) Demand Data in 1000 units
                                        Quantity          Price       PriceEla           TFAC
"IndonesiaReg".Ccoa                        78.55         913.02          -0.59          10.00
```

Prices are another driver for a change in food consumption patterns. When the price of a product increases in GLOBIOM, the level of consumption of this product decreases, by a value determined by the price elasticity associated to this product in the region considered. The price elasticity indicates by how much the relative change in consumption is affected with respect to relative change in price. The values of these elasticities in GLOBIOM are sourced from the USDA demand elasticity database and should be added in the following place:

```
Data_ElaUSDA.gms (model folder\finaldata)
PARAMETER
DemandPriceEla_USDA(ANYREGION,ALLPRODUCT) price elasticity of demand
   IndonesiaReg.Ccoa                                                   -0.59

Data_crops.gms (data folder)
DData(REGION,CROPS,'PriceEla') = DemandPriceEla_USDA(REGION,CROPS);
```


#### Shifting demand for a new crop

After the initialization of the new crop in the DDATA, the demand change over the years is dependent on the price elasticity of demand. The price elasticity indicates by how much the relative change in consumption is affected with respect to relative change in price and is calculated as a function depending on population size, gross domestic product (GDP) and product prices. In GLOBIOM, the demand system is set-up in such a way that the price elasticity of developing countries converges to the price elasticity of the USA in 2000 at the same pace as their GDP per capita reach the USA GDP per capita value of 2000 ([see GLOBIOM documentation for more information](https://globiom.org/)). However, one may want to diverge away from this assumption, for example when there is reason to believe that the price elasticity of the respective country does not follow the same trajectory as that of the US. This could for example be the case with products that are not used for food consumption, such as rubber and oil palm. In this case, alternative information, e.g. on the consumption of the specific crop per income class can be used to define how the price elasticity of demand may change over time for the product. The newly defined demand elasticity can then change based on the change in population and GDP in a similar fashion as the demand change:

```
Define_scenario.gms
DDATA(REGION,'ccoa',"Quantity")
         =  DDATA(REGION,'ccoa','quantity')
          * MACROSCEN_DATA(MacroScen,REGION,'POP_RelChng',ScenYear)
          *(MACROSCEN_DATA(MacroScen,REGION,'GDPpCAP_RelChng',ScenYear))
               **(CocoaDemGDPEla(REGION,'ccoa',MacroScen,ScenYear)) ;
```

### Trade

Economic market balances in GLOBIOM are solved at the level of 37 economic regions. GLOBIOM represents international markets and their various products traded between regions, relying on international trade statistics for trade and tariffs. It endogenously computes bilateral trade flows through the minimization of total trading costs. In this framework, trade patterns are determined by initial trade flows, the evolution of relative costs of production between regions and the trading costs. It leads to one unique price for one good on the market and the absence of intra-industry trade between different regions. There are two ways to initialize the trade for a new crop. First, if production and consumption is introduced at the bilateral level, also trade can be introduced at the bilateral level. Second, if the crop is only produced in the country of focus (i.e. other countries are likely also producing but for these countries no data is available), a specific import/export is only created for the country of focus, which is equal to the combined import/export to the rest of the world. Here, we assume the second option applies.

First, net trade of the country of focus is initialized. Net trade is computed as the difference between domestic production and consumption based on FAO food commodity balance over 1998-2002. It is computed at the regional level, so it excludes intra-regional trade flows. It is expressed in thousands of tons for crops. In GLOBIOM, this means the following items are initialized:

```
data_fbs.gms
PARAMETER
FBS_DATA_DET(ANYREGION,ALLPRODUCT,DataItems) Calorie consumption and production per crop (kcal per capita per day)
 /
   IndonesiaReg.Ccoa.ProdCal                                          3.6200
   IndonesiaReg. Ccoa.ConsCal                                         3.6200
/

PARAMETER
FBS_DATA_DET_N(*,ALLPRODUCT) Calorie supplied (kcal per capita per day)
 /
   World. Ccoa                                                         1.3986
/

PARAMETER
SUADATA_C(ANYREGION,ALLPRODUCT,SUADataItem) SUA data for crops (1000 tones)
 /
   "IndonesiaReg"."Ccoa".PRODQ                                        586.27
   "IndonesiaReg"."Ccoa".ConsQ                                        252.63
   "IndonesiaReg"."Ccoa".FoodQ                                        252.63
   "IndonesiaReg"."Ccoa".PureFoodQ                                    215.70
   "IndonesiaReg"."Ccoa".OtherNUses                                    34.48
   "IndonesiaReg"."Ccoa".NetExports                                   333.64
```

In case the crop is only produced in the country of focus, trade is also only set up for the country of focus with the rest of the world. In this case, trade from the country of focus is initialized with a parameter for exogenous exports or imports, say trade_exo:


```
3_precompute:
TRADE_EXO(REGION,CROPS)
 =  PRODUCTION(‘IndonesiaReg’,’Ccoa’))
 -  DDATA(‘IndonesiaReg’,’Ccoa’,"Quantity")
 -  SUADATA_C(‘IndonesiaReg’,’Ccoa’,'FeedQ')
 -  ABS_FUEL_REQ(‘IndonesiaReg’,’Ccoa’);
```

Where `TRADE_EXO` is defined as production (`PRODUCTION` - the sum of the area multiplied by the yield) minus consumption (`DDATA`), feed demand (`SUADATA_C`) and bioenergy demand (`ABS_FUEL_REQ`). In case of exports, the production is larger than the sum of consumption, feed and bioenergy demand and `TRADE_EXO` is positive. In the case of imports, production is smaller than the sum of consumption, feed and bioenergy demand and `TRADE_EXO` is negative.

To account for this outside demand in the model, `TRADE_EXO` is added to the objective function and the ds_balance:

```
4_model.gms:
Objective_equ
…
+ sum((REGION,PRODUCT),
TRADE_EXO(REGION,PRODUCT)
 * PRICE_EXP_EXO(REGION,PRODUCT))
```

Where `PRICE_EXP_EXO` is equal to `DDATA(REGION,CROPS,"Price")`.

```
Ds_balance
…
    + TRADE_EXO (REGION,PRODUCT)   
```

Subsequently, the outside demand and expectation on the country of focus’ reaction on outside demand needs to be captured by shifting the TRADE_EXO parameter through time. Depending on the crop and country of focus, a suitable way of extrapolation can be invented. For example, a usual extrapolation rule could be `x(t) = [x(baseyear) + dx]^(timeTrend)`, or export quantity in long run moves with the shifter factor based on historical FAO data. To calculate this shifter factor, a new parameter, e.g. `world_conso_shifter_yr` needs to be created and expressed per time-step:

```
6_scenarios:
PARAMETER
World_Conso_shifter_yr(PRODUCT,ALLSCENYEAR)  
```

The `TRADE_EXO` of year t-1 are subsequently stored in a new parameter called 
`TRADE_EXO_Base(REGION,PRODUCT) = TRADE_EXO(REGION,PRODUCT);`

This parameter is then shifted with the `World_Conso_Shifter_yr` in the `define_scenario.gms`.

```
Define_scenario.gms:
TRADE_EXO(REGION,PRODUCT)  = TRADE_EXO_Base(REGION,PRODUCT) ;

TRADE_EXO(REGION,PRODUCT) = TRADE_EXO(REGION,PRODUCT) *  World_Conso_shifter_yr(PRODUCT,SCENYEAR) ;
```



