From a35b2c7c300a441ba87c85b4ad40afdb34e186f2 Mon Sep 17 00:00:00 2001
From: Ben Young <ben.young@erg.com>
Date: Wed, 4 Sep 2024 10:33:25 -0400
Subject: [PATCH] derive an M matrix for IEF models #311

---
 R/ExternalImportFactors.R | 35 ++++++++++++++++++++++++++++++++++-
 man/deriveMMatrix.Rd      | 21 +++++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 man/deriveMMatrix.Rd

diff --git a/R/ExternalImportFactors.R b/R/ExternalImportFactors.R
index 5eb01866..28f43453 100644
--- a/R/ExternalImportFactors.R
+++ b/R/ExternalImportFactors.R
@@ -100,7 +100,7 @@ castImportFactors <- function(IFTable, model) {
 buildModelwithImportFactors <- function(model, configpaths = NULL) {
   # (see Palm et al. 2019)
 
-  logging::loginfo("Building Import A (A_m) accounting for ITA in Domestic FD.\n")
+  logging::loginfo("Building A_m (import requirements) accounting for international trade adjustment in domestic final demand.\n")
   # Re-derive import values in Use and final demand
   # _m denotes import-related structures
   model$UseTransactions_m <- model$UseTransactions - model$DomesticUseTransactions
@@ -126,5 +126,38 @@ buildModelwithImportFactors <- function(model, configpaths = NULL) {
   
   model$M_m <- M_m
   
+  model$M <- deriveMMatrix(model)
+  
   return(model)
 }
+
+#' Derives an aggregate M matrix from M_d and M_m based on the Consumption demand vector and
+#' FINAL perspective. Results from this M matrix match those calculated using the Import Emission
+#' Factors when using the Consumption demand vector and FINAL perspective.
+#' @param model, An EEIO model object with model specs and crosswalk table loaded
+#' @return An M matrix of flows x sector
+deriveMMatrix <- function(model) {
+  y <- prepareDemandVectorForStandardResults(model, demand="Consumption",
+                                             location=model$specs$ModelRegionAcronyms[1],
+                                             use_domestic_requirements=FALSE)
+  y_d  <- prepareDemandVectorForStandardResults(model, demand="Consumption",
+                                                location=model$specs$ModelRegionAcronyms[1],
+                                                use_domestic_requirements=TRUE)
+  y_m <- prepareDemandVectorForImportResults(model, demand="Consumption",
+                                             location=model$specs$ModelRegionAcronyms[1])
+  if(!all.equal(y, y_d+y_m)) {
+    stop("Error in calculating demand for coupled model approach")
+  }
+  logging::loginfo("Deriving M matrix (total emissions and resource use per dollar) consistent with the FINAL perspective ...")
+  result <- calculateResultsWithExternalFactors(model, demand="Consumption", perspective="FINAL",
+                                                location=model$specs$ModelRegionAcronyms[1])[["LCI_f"]]
+  # Derive M by dividing the result by the final demand
+  M <- t(result) %*% solve(diag(as.vector(replace(y, y == 0 , 1))))
+  colnames(M) <- colnames(model$M_d)
+  result2 <- calculateFinalPerspectiveLCI(M, y)
+  if(!all.equal(result, result2)) {
+    stop("Error deriving M matrix for coupled model approach")
+  }
+
+  return(M)
+}
diff --git a/man/deriveMMatrix.Rd b/man/deriveMMatrix.Rd
new file mode 100644
index 00000000..69cfa82b
--- /dev/null
+++ b/man/deriveMMatrix.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/ExternalImportFactors.R
+\name{deriveMMatrix}
+\alias{deriveMMatrix}
+\title{Derives an aggregate M matrix from M_d and M_m based on the Consumption demand vector and
+FINAL perspective. Results from this M matrix match those calculated using the Import Emission
+Factors when using the Consumption demand vector and FINAL perspective.}
+\usage{
+deriveMMatrix(model)
+}
+\arguments{
+\item{model, }{An EEIO model object with model specs and crosswalk table loaded}
+}
+\value{
+An M matrix of flows x sector
+}
+\description{
+Derives an aggregate M matrix from M_d and M_m based on the Consumption demand vector and
+FINAL perspective. Results from this M matrix match those calculated using the Import Emission
+Factors when using the Consumption demand vector and FINAL perspective.
+}