---
title: "An offline ESG calculation workflow"
author: "Dr. Dimitrios Geromichalos"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{An offline ESG calculation workflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

The library accepts structured observations and explicit external assessments.
Its 47 functions implement selected numerical contracts. They do not decide
which laws apply to a company or investigate the supplied evidence. All data
in this example are fictional and loaded from the installed package.

## Start with a small calculation

```{r}
pay_gap(20, 18)
pay_gap(0, 18)$status
tryCatch(pay_gap(Inf, 18), esg_error = function(e) e$code)
```

The gap is signed percent, with male gross hourly pay as denominator. A zero
denominator is not applicable; a missing observation stays missing. Invalid
numbers produce an `esg_error` condition, not a fabricated result.

## Declare an edition and reporting boundary

```{r}
ctx <- esg_context(profile_id = "eu-taxonomy-2026-v1", as_of = "2026-09-30")
criterion <- check_quantitative_criterion("building_new_ped",
  list(ped = 90, nzeb_threshold = 100, unit = "kWh/m2/year"), context = ctx)
criterion$assessment
criterion$details$remaining_conditions
```

The selected numerical clause passes at this boundary. Full activity alignment
still requires substantial contribution, other screening conditions, DNSH and
minimum safeguards. The criterion catalog specifies 23 supported clauses and
their edition locators. Unsupported clauses are rejected explicitly.

## Derive a company rating from raw observations

```{r company}
source(system.file("examples", "realistic_pipeline.R", package = "esgcalc"))
cases <- load_reference_data("synthetic_realistic_cases.json")$value$cases
company <- calculate_company(cases[[1]])
company$energy$value$renewable_fraction
company$kpis$turnover$value
company$rating$value
company$rating$details$coverage
```

The example derives emissions, energy, water, waste, workforce, safety, pay
and governance metrics, then composes taxonomy KPIs and a six-indicator
E/S/G rating. The reference model is a normative performance model: its
scales, weights, coverage gates and caps are explicit choices. It is not an
empirical agency rating. Incomplete or stale observations can suppress a
pillar and the overall rating; the implementation does not reward missing data.

```{r explanation}
explanation <- explain_rating(company$rating)
explanation$value$details$pillar_contributions
explanation$value$details$triggered
```

## Trace inputs and reproduce results

```{r trace}
company$rating$function_id
company$rating$profile_id
company$rating$mode
company$rating$source_ids
substr(company$rating$input_hash, 1, 16)
```

Input and model hashes are deterministic within R. The R and Python JSON
numeric renderings can differ, so hash equality is not a cross-language
numerical acceptance criterion. Resource hashes, however, are identical
because the reference JSON files are copied byte for byte from Python.

## Inspect the complete contracts

`help("esgcalc-contracts")` documents row schemas and numerical conventions.
The installed `doc` directory contains `TAXONOMY_CRITERIA.md`, `RATING.md`,
`METHOD_ISSUES.md` and the synthetic casebook. In particular, PAI 18 requires
an explicit interpretation for post-2020 PED inputs; reversing the literal
reference comparison is an explicitly labelled scenario.

The package has no runtime network access or Python dependency. Local JSON
and CSV readers require explicit schemas for conversion; exports target a
caller-selected local directory and refuse to overwrite existing files.