fix and factor out generateIIASASubmission() functionality to be used as general REMIND output filter for submissions

[0UmfHxcvx5J7JoaOhFSs5mncnisTJJ6q]

As generateIIASASubmission() is now the designated way of filtering REMIND
data for publication submissions, there are a couple of issues that need
addressing.

• generateIIASASubmission() documentation is missing.
  The description only repeats the title, there is no explanation what steps
  are taken between .mif files and submission file, the interaction of
  different parameters are not clarified.
  • added in improve documentation for generateIIASASubmission, harmonize logFile use #237
• no documentation on how different mapping parameters interact (set
  union, set difference, …?)
  • added in improve documentation for generateIIASASubmission, harmonize logFile use #237
• the possibility to pass mapping file paths via the mapping parameter is
  not documented
  • added in improve documentation for generateIIASASubmission, harmonize logFile use #237
• logFile parameter has unstated dependency on outputDirectory
  Setting outputDirectory to something other then output, but not adjusting
  logFile, leads to

  Error in file(file, ifelse(append, "a", "w")) : 
    cannot open the connection
  In addition: Warning message:
  In file(file, ifelse(append, "a", "w")) :
    cannot open file 'output/missing.log': No such file or directory
  

  Either make sure the directory exists, or better, always write the log to the
  stated output directory, which should be what most users expect.
  • added in improve documentation for generateIIASASubmission, harmonize logFile use #237
• logFile should default to something based on outputFilename
  Like sub('\\.[^\\.]+$', '_missing.log', outputFilename), in case users want
  to write several submission files but do not want to adjust the name of the
  log file everytime.
  • added in improve documentation for generateIIASASubmission, harmonize logFile use #237
• option to deactivate the log file is missing
  Users might not be interested in the file (when converting lots of mifs and
  being aware of the state of the reporting). They should be able to set
  logFile to NULL to deactivate it.
  • added in improve documentation for generateIIASASubmission, harmonize logFile use #237. set logFile to FALSE please.
• add a helper function for getting a list of available mappings
  Currently users have to fake-run generateIIASASubmission() without mapping
  parameters to get a list of the available mappings.
  • see names(templateNames())
• model parameter should default to NULL
  If users want to change the parameter from what is in the mifs, they should
  do so explicitly. Preset defaults are easily overlooked.
  • added in improve documentation for generateIIASASubmission, harmonize logFile use #237
• no-ops should not issue any messages
  • # Adapt scenario names: '' will be prepended, '' will be removed.
  • # iiasatemplate does not exist, returning full list of variables.
  • fixed in improve documentation for generateIIASASubmission, harmonize logFile use #237
• cannot combine mapping and mappingFile parameters
  Since the documentation is lacking, I was under the impression that the
  mapping and mappingFile parameters work basically the same, but that the
  latter explicitly expects a path to a file, while the former accepts both
  mapping names and paths.
  But while it is possible to pass multiple mappings to mapping

  generateIIASASubmission(
      mapping = c('AR6', 'AR6_NGFS'),
      …)
  

  passing multiple mappings as mappingFile

  generateIIASASubmission(
      mappingFile = system.file('templates', 
                                paste0('mapping_template_',
                                       c('AR6', 'AR6_NGFS'),
                                       '.csv'), 
                                package = 'piamInterfaces'),
      …)
  

  leads to an uncaught error

  Error in length(mapping) > 0 || is.null(mappingFile) || !file.exists(mappingFile) :                                                      
    'length = 2' in coercion to 'logical(1)'
  

  Using both a mapping and a mappingFile ignores the mapping in
  mappingFile, while reporting using it

  generateIIASASubmission(
      mapping = 'AR6',
      mappingFile = system.file('templates',
                                'mapping_template_AR6_NGFS.csv', 
                                package = 'piamInterfaces'),
      …)
  

  says

  ### Generating mapping  based on templates AR6
  
  # Read AR6
  
  ### Generating submission file using mapping AR6, /home/pehl/R/x86_64-pc-linux-gnu-library/4.3/piamInterfaces/templates/mapping_template_AR6_NGFS.csv.
  # Adapt scenario names: '' will be prepended, '' will be removed.
  # Apply mapping /home/pehl/R/x86_64-pc-linux-gnu-library/4.3/piamInterfaces/templates/mapping_template_AR6_NGFS.csv
  

  but the resulting file is identical to the one produced by
  generateIIASASubmission(mapping = 'AR6', …).
  • corrected in improve documentation for generateIIASASubmission, harmonize logFile use #237. If you specify a mapping, you cannot also use a mappingFile at the moment. The script will now warn you.

[orichters]

I improved the documentation. I think quite a bit regarding the difference of "mapping templates" and "mapping files" is still confusing, but @fbenke-pik will probably address that by making a larger cleanup. Please use the format used by the csv files in ./inst/template/ for your project.