Save Data to GEMPACK HAR Format

Writes one or more data matrices or arrays into a GEMPACK-compatible HAR file format, automatically generating associated 1C set headers.

Usage

save_har(
  data_list,
  file_path,
  dimensions,
  value_cols = NULL,
  long_desc = NULL,
  coefficients = NULL,
  export_sets = TRUE,
  lowercase = TRUE,
  dim_order = NULL,
  dim_rename = NULL
)

Arguments

data_list

A named list of data frames or arrays (names up to 4 characters).

file_path

Path to the output HAR file.

dimensions

A named list specifying dimension columns for each header.

HAR dimension names follow these column names; rename columns before saving to change them.

value_cols

A named vector of value column names. Defaults to "Value".

long_desc

A named vector of long descriptions (optional).

coefficients

A named vector of coefficient names (optional).

export_sets

Logical; if TRUE, exports dimension sets as 1C headers. Default is TRUE.

lowercase

Logical; if TRUE, converts elements to lowercase. Default is TRUE.

dim_order

Optional dimension ordering specification. Can be:

NULL (default): alphabetical A–Z ordering
a data frame with columns matching dimension names
a named list specifying order for each dimension
a character string giving the path to an Excel or CSV file with order definitions

dim_rename

Optional named list to rename dimensions in HAR output.

Names are original column names, values are desired HAR dimension names
Allows duplicate dimension names in HAR (e.g., COMMxREGxREG from COMMxSREGxDREG)
Example: list(RTMS = c(COMM = "COMM", SREG = "REG", DREG = "REG"))

Value

Invisibly returns a list containing export metadata, including file path and header summary.

Details

Supports 1CFULL (string sets) and REFULL (real arrays) headers
2IFULL (integer) and RESPSE (sparse) types are not implemented
Up to seven dimensions and ~2 million elements per chunk
No practical file-size limit or header count restriction

Author

Pattawee Puangchit

Examples

# Example 1: Save a single matrix
har_path <- system.file("extdata", "TAR10-WEL.har", package = "HARplus")
har_data <- load_harx(har_path)
welfare_data <- get_data_by_var("A", har_data)
welfare_data_A <- welfare_data[["har_data"]][["A"]]

save_har(
  data_list   = list(WELF = welfare_data),
  file_path   = file.path(tempdir(), "output_single.har"),
  dimensions  = list(WELF = c("REG", "COLUMN")),
  value_cols  = c(WELF = "Value"),
  long_desc   = c(WELF = "Welfare Decomposition"),
  export_sets = TRUE,
  lowercase   = FALSE
)
#> 
#> Successfully wrote 1 header(s) to HAR file
#>   Set headers (1C type): 0
#>   Data headers (RE type): 1
#> 
#> All dimensions sorted A-Z (no custom mapping provided)
#> 
#> Output file: /tmp/RtmpAJs0g8/output_single.har
#> File size: 308 bytes
#> 

# Example 2: Save multiple matrices
welfare_data <- get_data_by_var(c("A", "A1"), har_data)
welfare_data <- welfare_data[["har_data"]]

save_har(
  data_list   = list(WELF = welfare_data[["A"]],
                     DECOM = welfare_data[["A1"]]),
  file_path   = file.path(tempdir(), "output_multi.har"),
  dimensions  = list(WELF = c("REG", "COLUMN"),
                     DECOM = c("REG", "ALLOCEFF")),
  value_cols  = list(WELF = "Value",
                     DECOM = "Value"),
  long_desc   = list(WELF = "Welfare Decomposition",
                     DECOM = "Allocative efficiency effect"),
  export_sets = TRUE,
  lowercase   = FALSE
)
#> 
#> Successfully wrote 5 header(s) to HAR file
#>   Set headers (1C type): 3
#>   Data headers (RE type): 2
#> 
#> All dimensions sorted A-Z (no custom mapping provided)
#> 
#> Output file: /tmp/RtmpAJs0g8/output_multi.har
#> File size: 3,604 bytes
#> 

# Example 3: Apply mapping file for sorting
mapping <- list(
  REG    = c("RestofWorld", "MENA", "EU_28"),
  COLUMN = c("alloc_A1", "tot_E1")
)

save_har(
  data_list   = list(
    WELF  = welfare_data[["A"]],
    DECOM = welfare_data[["A1"]]
  ),
  file_path   = file.path(tempdir(), "output_sorted.har"),
  dimensions  = list(
    WELF  = c("REG", "COLUMN"),
    DECOM = c("REG", "ALLOCEFF")
  ),
  value_cols  = list(
    WELF  = "Value",
    DECOM = "Value"
  ),
  long_desc   = list(
    WELF  = "Welfare Decomposition",
    DECOM = "Allocative efficiency effect"
  ),
  export_sets = TRUE,
  dim_order   = mapping,
  lowercase   = FALSE
)
#> 
#> Successfully wrote 5 header(s) to HAR file
#>   Set headers (1C type): 3
#>   Data headers (RE type): 2
#> 
#> Dimension ordering applied:
#>   REG: 3 prioritized values, remaining A-Z
#>   COLUMN: 2 prioritized values, remaining A-Z
#> 
#> Dimensions with A-Z sorting (no custom mapping):
#>   COLU
#>   ALLO
#> 
#> Output file: /tmp/RtmpAJs0g8/output_sorted.har
#> File size: 3,604 bytes
#> 

# Example 4: Rename duplicated dimension names  
# to export as a single structure (e.g., COMMxREGxREG)
har_path <- system.file("extdata", "TAR10-WEL.har", package = "HARplus")
har_data <- load_harx(har_path)
welfare_data <- get_data_by_var("C17", har_data)
welfare_data <- welfare_data[["har_data"]][["C17"]] 

mapping <- list(
  COMM = c("TransComm", "MeatLstk"),
  REG  = c("SSA", "RestofWorld", "SEAsia")  
)

# Export HAR
save_har(
  data_list   = list(TEST = welfare_data),
  file_path   = file.path(tempdir(), "output_single.har"),
  dimensions  = list(TEST = c("COMM", "REG", "REG.1")),
  value_cols  = list(TEST = "Value"),
  long_desc   = list(TEST = "Shock RTMS"),
  dim_rename  = list(TEST = c(COMM = "COMM", SREG = "REG", DREG = "REG.1")),
  export_sets = TRUE,
  dim_order   = mapping,
  lowercase   = FALSE
)
#> 
#> Successfully wrote 4 header(s) to HAR file
#>   Set headers (1C type): 3
#>   Data headers (RE type): 1
#> 
#> Dimension ordering applied:
#>   COMM: 2 prioritized values, remaining A-Z
#>   REG: 3 prioritized values, remaining A-Z
#> 
#> Dimensions with A-Z sorting (no custom mapping):
#>   REG.
#> 
#> Output file: /tmp/RtmpAJs0g8/output_single.har
#> File size: 5,563 bytes
#>