Feat/7 harmonize parameters

.github/workflows/docker.yml

@@ -10,6 +10,7 @@ on:
 name: docker
 
 jobs:
+
   docker:
     name: Docker actions
     uses: RMI-PACTA/actions/.github/workflows/docker.yml@main
@@ -23,8 +24,8 @@ jobs:
       fail-fast: false
       matrix:
         config-name:
-          # - default_2022Q4
-          # - default_2023Q4
+          - default_2022Q4
+          - default_2023Q4
           - full_params_2022Q4
           - full_params_2023Q4
     with:

.github/workflows/test.yml

@@ -125,11 +125,17 @@ jobs:
           --env BENCHMARKS_DIR="/mnt/benchmarks_dir" \
           --env PACTA_DATA_DIR="/mnt/pacta-data" \
           --env PORTFOLIO_DIR="/mnt/portfolios" \
+          --env REAL_ESTATE_DIR="/mnt/real_estate_dir" \
           --env REPORT_OUTPUT_DIR="/mnt/report_output_dir" \
+          --env SCORE_CARD_DIR="/mnt/score_card_dir" \
           --env SUMMARY_OUTPUT_DIR="/mnt/summary_output_dir" \
+          --env SURVEY_DIR="/mnt/survey_dir" \
           --mount type=bind,readonly,source=${WORKSPACE}/${BENCHMARKS_DIR},target=/mnt/benchmarks_dir \
           --mount type=bind,readonly,source=${WORKSPACE}/${PACTA_DATA_DIR},target=/mnt/pacta-data \
           --mount type=bind,readonly,source=${WORKSPACE}/${PORTFOLIO_DIR},target=/mnt/portfolios \
+          --mount type=bind,readonly,source=${WORKSPACE}/${REAL_ESTATE_DIR},target=/mnt/real_estate_dir \
+          --mount type=bind,readonly,source=${WORKSPACE}/${SCORE_CARD_DIR},target=/mnt/score_card_dir \
+          --mount type=bind,readonly,source=${WORKSPACE}/${SURVEY_DIR},target=/mnt/survey_dir \
           --mount type=bind,source=${WORKSPACE}/${ANALYSIS_OUTPUT_DIR},target=/mnt/analysis_output_dir \
           --mount type=bind,source=${WORKSPACE}/${REPORT_OUTPUT_DIR},target=/mnt/report_output_dir \
           --mount type=bind,source=${WORKSPACE}/${SUMMARY_OUTPUT_DIR},target=/mnt/summary_output_dir \

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: workflow.pacta.webapp
 Title: Prepare PACTA reports
-Version: 0.0.0.9001
+Version: 0.0.1
 Authors@R: 
     c(person(given = "Alex",
              family = "Axthelm",
@@ -20,4 +20,4 @@ Imports:
     workflow.pacta.report
 Remotes:
     RMI-PACTA/workflow.pacta,
-    RMI-PACTA/workflow.pacta.report,
+    RMI-PACTA/workflow.pacta.report

README.md

@@ -0,0 +1,124 @@
+# workflow.pacta.webapp
+
+R package and Corresponding Docker image for PACTA web application.
+
+although this application can be run locally, it is primarily intended to be run as a Docker image.
+These instructions document using the Docker image, and running the workflow locally is left as an exercise for the reader.
+
+## Setup
+
+### Prerequisite Data
+
+Running the application requires access to a number of prepared datasets, which should be accesible to the Docker image through bind mounts.
+Each of the data sets listed can live in their own directory for clarity, or they can reside in the same directory for simplicity.
+The application is configured by setting the value of enironment variables to point to the path of the bind mound *as referenced inside the container* (the `target` of the volume).
+
+- `BENCHMARKS_DIR`:
+  Outputs of [`workflow.prepare.pacta.indices`](https://github.com/RMI-PACTA/workflow.prepare.pacta.indices).
+  (May be read only)
+- `PACTA_DATA_DIR`:
+  Outputs of [`workflow.data.preparation`](https://github.com/RMI-PACTA/workflow.data.preparation).
+  Note that `workflow.data.preparation` prepares data for a given holdings date (denoted by strings such as `2022Q4` or `2023Q4`), so running this application for different portfolios may require mounting different directories.
+  (May be read only)
+- `REAL_ESTATE_DIR`:
+  (*user specific*)
+  Contains prepared user real estate data results (Used as part of PA2022CH project). Frequently empty.
+  *This envvar is likely to be deprecated in an upcoming version*.
+  (May be read only)
+- `SCORE_CARD_DIR`:
+  (*user specific*)
+  Contains user results for score card (Used as part of PA2024CH project). Frequently empty.
+  See [workflow.prep.PA2024CH](https://github.com/RMI-PACTA/workflow.prep.PA2024CH) for more information.
+  *This envvar is likely to be made optional in an upcoming version*.
+  (May be read only)
+- `SURVEY_DIR`:
+  (*user specific*)
+  Contains user survey results (Used as part of PA2024CH project). Frequently empty.
+  See [workflow.prep.PA2024CH](https://github.com/RMI-PACTA/workflow.prep.PA2024CH) for more information.
+  *This envvar is likely to be made optional in an upcoming version*.
+  (May be read only)
+
+
+### Application Config
+
+The following environment variables must be set.
+
+- `ANALYSIS_OUTPUT_DIR`:
+  Suggested value: `/mnt/analysis_output_dir`.
+  This holds the outputs from [`workflow.pacta`](https://github.com/RMI-PACTA/workflow.pacta)
+  *MUST* point to a directory that is writable by the `workflow-pacta-webapp` user.
+- `BENCHMARKS_DIR`:
+  Suggested value: `/mnt/benchmarks_dir`.
+  See [Prerequisite Data](#prerequisite-data) for interpretation.
+- `OUTPUT_DIR`:
+  Suggested value: `/mnt/analysis_output_dir`.
+  See [Prerequisite Data](#prerequisite-data) for interpretation.
+- `PACTA_DATA_DIR`:
+  Suggested value: `/mnt/pacta-data`.
+  See [Prerequisite Data](#prerequisite-data) for interpretation.
+- `PORTFOLIO_DIR`:
+  Suggested value: `/mnt/portfolios`.
+  This is the directory in which portfolio `.csv` files reside.
+  *Note*: The application does *not* doe a recursive search, so if the application is searching for `foo.csv` in `/mnt/bar`, then the portfolio must be at `/mnt/bar/foo.csv`, not `/mnt/bar/bax/foo.csv`
+- `REAL_ESTATE_DIR`:
+  Suggested value: `/mnt/real_estate_dir`.
+  See [Prerequisite Data](#prerequisite-data) for interpretation.
+- `REPORT_OUTPUT_DIR`:
+  Suggested value: `/mnt/report_output_dir`.
+  This holds the interactive report `index.html` and friends, output from [`workflow.pacta.report`](https://github.com/RMI-PACTA/workflow.pacta.report)
+  *MUST* point to a directory that is writable by the `workflow-pacta-webapp` user.
+  *NOTE: The application currently outputs the report to `$REPORT_OUTPUT_DIR/report/index.html`, rather than `$REPORT_OUTPUT_DIR/index.html`. This is likely to be changed in an upcoming version*.
+- `SCORE_CARD_DIR`:
+  Suggested value: `/mnt/score_card_dir`.
+  See [Prerequisite Data](#prerequisite-data) for interpretation.
+- `SUMMARY_OUTPUT_DIR`:
+  Suggested value: `/mnt/summary_output_dir`.
+  TODO: Write this
+- `SURVEY_DIR`:
+  Suggested value: `/mnt/survey_dir`.
+  This holds the executive summary PDF, output from [`workflow.pacta.report`](https://github.com/RMI-PACTA/workflow.pacta.report)
+  *MUST* point to a directory that is writable by the `workflow-pacta-webapp` user.
+  *NOTE: The application currently outputs the report to `$SURVEY_DIR/executive_summary/*.pdf`, rather than `$SURVEY_DIR/*.pdf`. This is likely to be changed in an upcoming version*.
+
+The following envrionment variables are *optional*
+
+- `LOG_LEVEL`: Controls the verbosity of logging.
+  Accepts standard `log4j` levels (`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`).
+  Default is `INFO`.
+
+## Running the Application
+
+The easiest way to run the application is with `docker-compose up --build`.
+Do note that this builds the image, which may take a long time, espescially on `arm64` (Apple Silicon) machines.
+Up-to-date image can be found at the repo's [package page](https://github.com/RMI-PACTA/workflow.pacta.webapp/pkgs/container/workflow.pacta.webapp), with the `main` tag being the most reliable (stable).
+
+The image defines a script as `ENTRYPOINT`, allowing for passing a JSON object (as `command`) which defines the portfolio, and the options with which to run the analysis.
+
+There are many options that can control the analysis, most of which are out of scope of this document.
+The simplest form (and minimal example that passes validation) for the JSON object to pass in is something along the lines of:
+
+```json
+{
+  "portfolio": {
+    "files": "default_portfolio.csv",
+    "holdingsDate": "2023-12-31",
+    "name": "FooPortfolio"
+  },
+  "inherit": "GENERAL_2023Q4"
+}
+```
+
+Let's break that down.
+
+`"inherit": "GENERAL_2023Q4"` is doing a lot of the heavy lifting here.
+`workflow.pacta.webapp` makes use of an option inheritance engine (provided by [`pacta.workflow.utils::parse_json_params()`](https://github.com/RMI-PACTA/pacta.workflow.utils/blob/main/R/parse_json_params.R)) that allows for pre-defined configurations of reasonable defaults for most users.
+Currently, The application will work properly with `GENERAL_2023Q4` or `GENERAL_2022Q4`.
+
+The `portfolio` object has three required keys:
+
+- `files`: The name of the CSV file with the portfolio contents.
+  Note the lack of file extension.
+  *NOTE: The type of this object is likely to change to `array` (even if length 1) in the near future*
+- `holdingsDate`: The date for which the portfolio should be analyzed.
+  Acceptable values at this time are `2022-12-31` and `2023-12-31`.
+- `name`: A string defining the user-facing name for the portfolio (used in reporting).

docker-compose.yml

@@ -5,18 +5,19 @@ services:
     # stdin_open: true
     # tty: true
     # entrypoint: ["R", "--args"]
-    # command: '/workflow.pacta.webapp/tests/params/full_23q4.json'
+    command: '{\"portfolio\": {\"files\": \"default_portfolio.csv\", \"holdingsDate\": \"2023-12-31\", \"name\": \"FooPortfolio\"}, \"inherit\": \"GENERAL_2023Q4\"}'
     environment:
       LOG_LEVEL: TRACE
       ANALYSIS_OUTPUT_DIR: "/mnt/analysis_output_dir"
       BENCHMARKS_DIR: "/mnt/benchmarks_dir"
+      OUTPUT_DIR: "/mnt/analysis_output_dir"
+      PACTA_DATA_DIR: "/mnt/pacta-data"
+      PORTFOLIO_DIR: "/mnt/portfolios"
+      REAL_ESTATE_DIR: "/mnt/real_estate_dir"
       REPORT_OUTPUT_DIR: "/mnt/report_output_dir"
+      SCORE_CARD_DIR: "/mnt/score_card_dir"
       SUMMARY_OUTPUT_DIR: "/mnt/summary_output_dir"
-      REAL_ESTATE_DIR: "/mnt/real_estate_dir"
       SURVEY_DIR: "/mnt/survey_dir"
-      PACTA_DATA_DIR: "/mnt/pacta-data"
-      OUTPUT_DIR: "/mnt/analysis_output_dir"
-      PORTFOLIO_DIR: "/mnt/portfolios"
     volumes:
       - type: bind
         source: ${data_dir:-./pacta-data/}
@@ -38,6 +39,10 @@ services:
         source: ${real_estate_dir:-./real_estate_dir/}
         target: /mnt/real_estate_dir
         read_only: true
+      - type: bind
+        source: ${score_card_dir:-./survey_dir}
+        target: /mnt/score_card_dir
+        read_only: true
       - type: bind
         source: ${survey_dir:-./survey_dir/}
         target: /mnt/survey_dir

inst/extdata/scripts/run_pacta.R

@@ -1,4 +1,4 @@
-logger::log_threshold(Sys.getenv("LOG_LEVEL", "WARN"))
+logger::log_threshold(Sys.getenv("LOG_LEVEL", "INFO"))
 workflow.pacta:::run_pacta(commandArgs(trailingOnly = TRUE))
 workflow.pacta.report:::run_pacta_reporting_process(
   commandArgs(trailingOnly = TRUE)

tests/config/default_2022Q4.json

@@ -4,7 +4,11 @@
   "resultsURL": "https://pactadatadev.blob.core.windows.net/ghactions-workflow-pacta-results/73/merge/latest/default_2022Q4/output_dir",
   "benchmarksURL": "https://pactadatadev.file.core.windows.net/workflow-prepare-pacta-indices-outputs/2022Q4_20240529T002407Z",
   "parameters": {
-    "portfolio_files": "default_portfolio.csv",
+    "portfolio": {
+      "holdingsDate": "2023-12-31",
+      "files": "default_portfolio.csv",
+      "name": "Default Portfolio"
+    },
     "inherit": "GENERAL_2022Q4"
   }
 }

tests/config/default_2023Q4.json

@@ -4,7 +4,11 @@
   "resultsURL": "https://pactadatadev.blob.core.windows.net/ghactions-workflow-pacta-results/73/merge/latest/default_2023Q4/output_dir",
   "benchmarksURL": "https://pactadatadev.file.core.windows.net/workflow-prepare-pacta-indices-outputs/2023Q4_20240529T002355Z",
   "parameters": {
-    "portfolio_files": "default_portfolio.csv",
+    "portfolio": {
+      "holdingsDate": "2023-12-31",
+      "files": "default_portfolio.csv",
+      "name": "Default Portfolio"
+    },
     "inherit": "GENERAL_2023Q4"
   }
 }

tests/config/full_params_2022Q4.json

@@ -4,45 +4,72 @@
   "resultsURL": "https://pactadatadev.blob.core.windows.net/ghactions-workflow-pacta-results/73/merge/latest/default_2022Q4/output_dir",
   "benchmarksURL": "https://pactadatadev.file.core.windows.net/workflow-prepare-pacta-indices-outputs/2022Q4_20240529T002407Z",
   "parameters": {
-    "equity_market_list": ["GlobalMarket", "DevelopedMarket", "EmergingMarket"],
-    "scenario_geographies_list": ["Global", "GlobalAggregate", "NonOECD", "OECD"],
-    "sector_list": ["Power", "Automotive", "Oil&Gas", "Coal", "Steel", "Aviation", "Cement"],
-    "time_horizon": 5,
-    "start_year": 2022,
-    "holdingsDate": "2022-12-31",
-    "scenario_sources_list": ["GECO2022", "ISF2021", "WEO2022"],
-    "project_code": "GENERAL",
-    "portfolio_files": "default_portfolio.csv",
-    "select_scenario": "WEO2022_NZE_2050",
-    "scenario_other": "GECO2022_1.5C",
-    "project_report_name": "general",
-    "scenario_geography": "Global",
-    "portfolio_name": "Default Portfolio",
-    "investor_name": "Default Investor",
-    "peer_group": "bank",
-    "language_select": "EN",
-    "display_currency": "USD",
-    "currency_exchange_value": 1,
-    "portfolio_allocation_method": "portfolio_weight",
-    "tech_roadmap_sectors": [
-      "Power",
-      "Automotive",
-      "Oil&Gas",
-      "Coal"
-    ],
-    "pacta_sectors_not_analysed": [
-      "Steel",
-      "Aviation",
-      "Cement"
-    ],
-    "green_techs": [
-      "RenewablesCap",
-      "HydroCap",
-      "NuclearCap",
-      "Hybrid",
-      "Electric",
-      "FuelCell",
-      "Electric Arc Furnace"
-    ]
+    "portfolio": {
+      "holdingsDate": "2023-12-31",
+      "files": "default_portfolio.csv",
+      "name": "Default Portfolio"
+    },
+    "analysis": {
+      "equityMarketList": [
+        "GlobalMarket",
+        "DevelopedMarket",
+        "EmergingMarket"
+      ],
+      "scenarioGeographiesList": [
+        "Global",
+        "GlobalAggregate",
+        "NonOECD",
+        "OECD"
+      ],
+      "scenarioSourcesList": [
+        "GECO2022",
+        "ISF2021",
+        "WEO2022"
+      ],
+      "sectorList": [
+        "Power",
+        "Automotive",
+        "Coal",
+        "Steel",
+        "Aviation",
+        "Cement"
+      ],
+      "startYear": 2023,
+      "timeHorizon": 5
+    },
+    "user": {
+      "name": "Default Investor",
+      "languageSelect": "EN",
+      "peerGroup": "bank",
+      "currencyExchangeValue": 1,
+      "displayCurrency": "USD"
+    },
+    "reporting": {
+      "projectCode": "GENERAL",
+      "projectReportName": "general",
+      "greenTechs": [
+        "RenewablesCap",
+        "HydroCap",
+        "NuclearCap",
+        "Hybrid",
+        "Electric",
+        "FuelCell",
+        "Electric Arc Furnace"
+      ],
+      "pactaSectorsNotAnalysed": [
+        "Steel",
+        "Aviation",
+        "Cement"
+      ],
+      "portfolioAllocationMethod": "portfolio_weight",
+      "scenarioGeography": "Global",
+      "scenarioOther": "GECO2022_1.5C",
+      "selectScenario": "WEO2022_NZE_2050",
+      "techRoadmapSectors": [
+        "Power",
+        "Automotive",
+        "Coal"
+      ]
+    }
   }
 }