Estimate Economic Returns on Adaptation

import {
  dropdown_section,
  downloadCsvButton,
  downloadPngButton,
  makeTooltipLabel,
} from "/helpers/uiComponents.ojs";

import { formatUSD, inputTemplate, cleanAdminInput_SQL } from "/helpers/std.ojs";

import { createSqlBindings } from "/helpers/sql.js";

import { atlasTable, sparkbar } from "/helpers/atlasTable.ojs";

OverviewVue d’Ensemble

Understanding the economic impacts of adaptation investments in agriculture is vital for investment planning. This notebook provides a detailed financial analysis for agricultural projects focused on adaptation, crucial for assessing the viability and strategic value of such investments.

Use this tool to evaluate the returns on a potential adaptation investment through projected economic performance indicators, including the: Internal Rate of Return (IRR), Modified Internal Rate of Return(MIRR), Net Present Value (NPV), and Benefit-Cost Ratio (BCR).

Comprendre les impacts économiques des investissements d’adaptation dans l’agriculture est vital pour la planification des investissements. Ce notebook fournit une analyse financière détaillée des projets agricoles axés sur l’adaptation, essentielle pour évaluer la viabilité et la valeur stratégique de ces investissements.

Utilisez cet outil pour évaluer le rendement d’un investissement potentiel en matière d’adaptation au moyen d’indicateurs de performance économique projetés, notamment les suivants: Taux de rendement interne (TRI), Taux de rendement interne modifié (MIRR), Valeur actuelle nette (VAN), et Rapport coûts-avantages (RCA).

DefinitionsDéfinitions

Internal Rate of Return (IRR) — The Internal Rate of Return (IRR) is a financial metric used to evaluate the profitability of an investment or project. It represents the annual rate of return at which the net present value (NPV) of all (discounted) cash flows from the investment equals zero. A project is generally considered to be a good investment if its IRR exceeds the rate of return that could be earned elsewhere at a similar risk level (the opportunity cost of capital).

Modified Internal Rate of Return (MIRR) — MIRR improves upon IRR by assuming reinvestment of cash flows at a realistic rate and incorporating financing costs. It gives a clearer picture of project profitability in practical investment scenarios.

Net Present Value (NPV) — NPV measures an investment’s profitability for development projects by comparing incoming and outgoing money, considering the time value of money. It accounts for changes in money value over time due to inflation or interest rates. A positive NPV indicates that the project’s benefits are greater than its costs, marking it as a favorable investment.

Benefit-Cost Ratio (BCR) — This metric simply compares the benefits (or returns) of a project to its costs, with both values adjusted to present-day terms to account for the time value of money. A BCR greater than 1 indicates that the benefits of a project exceed its costs, suggesting the investment is likely to be profitable and beneficial. For projects focused on supporting farmers, a BCR above 1 means that for every dollar spent, the project is expected to return more than a dollar in benefits, making it a good investment that can improve farmers’ productivity and livelihoods. Conversely, a BCR less than 1 would imply that the costs outweigh the benefits, signaling that the project may not deliver sufficient value to justify the investment.

Taux de rendement interne (TRI) — Le taux de rendement interne (TRI) est une mesure financière utilisée pour évaluer la rentabilité d’un investissement ou d’un projet. Il représente le taux de rendement annuel auquel la valeur actuelle nette (VAN) de tous les flux de trésorerie (actualisés) de l’investissement est égale à zéro. Un projet est généralement considéré comme un bon investissement si son TRI dépasse le taux de rendement pouvant être obtenu ailleurs à un niveau de risque similaire (le coût d’opportunité du capital).

Taux de rendement interne modifié (MIRR) — Le MIRR améliore le TRI en supposant un réinvestissement des flux de trésorerie à un taux réaliste et en intégrant les coûts de financement. Il fournit une image plus claire de la rentabilité d’un projet dans des scénarios d’investissement concrets.

Valeur actuelle nette (VAN) — La VAN mesure la rentabilité d’un investissement pour les projets de développement en comparant l’argent entrant et l’argent sortant, en tenant compte de la valeur temporelle de l’argent. Elle tient compte des variations de la valeur de l’argent dans le temps dues à l’inflation ou aux taux d’intérêt. Une VAN positive indique que les bénéfices du projet sont supérieurs à ses coûts, ce qui en fait un investissement favorable.

Rapport coûts-avantages (RCA) — Cet indicateur compare simplement les avantages (ou le rendement) d’un projet à ses coûts, les deux valeurs étant ajustées au jour le jour pour tenir compte de la valeur temporelle de l’argent. Un RCA supérieur à 1 indique que les bénéfices d’un projet dépassent ses coûts, ce qui suggère que l’investissement est susceptible d’être rentable et bénéfique. Pour les projets axés sur le soutien aux agriculteurs, un RCA supérieur à 1 signifie que pour chaque dollar dépensé, le projet devrait rapporter plus d’un dollar de bénéfices, ce qui en fait un bon investissement susceptible d’améliorer la productivité et les moyens de subsistance des agriculteurs. À l’inverse, un RCA inférieur à 1 signifie que les coûts l’emportent sur les bénéfices, ce qui indique que le projet n’apporte peut-être pas une valeur suffisante pour justifier l’investissement.

Designed for high-level insights (national, regional, or continental), this tool helps investors gauge the likelihood of net-positive economic benefits from their projects. It focuses on projects that introduce innovations to farmers, enhancing crop or livestock yields, reducing climate hazard impacts, and achieving gradual farmer adoption over time. Together, these metrics allow investors to understand not only the profitability, but also the relative risk and efficiency of their investments, making them important indicators to gauge financial health of the (adaptation) project, for making informed decisions.

It is important to note that negative economic indicators might not deter investment if the initiative supports broader goals or offers significant societal or environmental benefits. In such cases, the project might be considered valuable for its potential to improve farmers’ livelihoods or environmental sustainability, even if if the costs are greater than value of production added or de-risked from climate hazards.

Conçu pour des analyses de haut niveau (national, régional ou continental), cet outil aide les investisseurs à évaluer la probabilité que leurs projets aient des retombées économiques nettes positives. Il se concentre sur les projets qui introduisent des innovations auprès des agriculteurs, améliorant les rendements des cultures ou du bétail, réduisant les impacts des risques climatiques et permettant une adoption progressive par les agriculteurs au fil du temps. Ensembles, ces mesures permettent aux investisseurs de comprendre non seulement la rentabilité, mais aussi le risque relatif et l’efficacité de leurs investissements, ce qui en fait des indicateurs importants pour évaluer la santé financière du projet (d’adaptation) et prendre des décisions en connaissance de cause.

Il est important de noter que des indicateurs économiques négatifs peuvent ne pas décourager l’investissement si l’initiative soutient des objectifs plus larges ou offre des avantages sociétaux ou environnementaux significatifs. Dans ce cas, le projet peut être considéré comme intéressant pour sa capacité à améliorer les moyens de subsistance des agriculteurs ou la durabilité de l’environnement, même si les coûts sont supérieurs à la valeur de la production ajoutée ou à la réduction des risques liés aux aléas climatiques.

Project Set-UpConfiguration de Project

Agricultural projects can have different levels of production outcomes (in terms of production gains), while also helping in reducing climate impacts. The project set-up allows investors to gauge project cashflows and financial metrics by adjusting such parameters.

To begin, select target crops and locations. Then, specify project cost and duration. Finally, set-up the innovation impact on yields and climate hazard reduction and its annual rate of adoption.

Les projets agricoles peuvent avoir différents niveaux de résultats de production (en termes de gains de production), tout en contribuant à réduire les impacts climatiques. Le montage du projet permet aux investisseurs d’évaluer les flux de trésorerie et les paramètres financiers du projet en ajustant ces paramètres.

Pour commencer, sélectionnez les cultures et les lieux cibles. Ensuite, précisez le coût et la durée du projet. Enfin, définissez l’impact de l’innovation sur les rendements et la réduction des risques climatiques, ainsi que son taux d’adoption annuel.

htl.html`
<div style="display: flex; flex-wrap: wrap; align-items: flex-start; gap: 3em; margin-bottom: 1.5em;">
    ${viewof select_country}
    ${viewof select_region}
    ${viewof select_crop}
  </div>
`

viewof productionView = Inputs.radio(["plot", "table"], {
  value: "table",
  label: _lang(general_translations.vizType.title),
  format: (d) => _lang(general_translations.vizType?.[d]),
})

{
  if (productionView == "table") {
    const a0_clean = _lang(general_translations.country);
    const a1_clean = _lang(general_translations.region);
    const commodity_clean = _lang(general_translations.commodity);
    const maxVal = d3.max(exposure_data, (d) => d.value);
    return atlasTable(exposure_data, {
      columns: ["admin0_name", "admin1_name", "crop", "value"],
      header: { value: "USD", crop: commodity_clean, admin0_name: a0_clean, admin1_name: a1_clean },
      sort: "value",
      reverse: true,
      format: {
        value: sparkbar({
          max: maxVal,
          align: "right",
          background: "#D9ECD9",
          color: "black",
          formatter: (d) => formatUSD()(d),
        }),
      },
    });
  } else {
    return renderProductionBars();
  }
}

renderProductionBars = () => {
  const data = exposure_data.filter((d) => regionSet.has(`${d.iso3}_${d.admin1_name}`));

  const totals = d3.rollup(
    data,
    (v) => d3.sum(v, (d) => d.value),
    (d) => d.admin0_name,
    (d) => d.crop
  );

  const flatTotals = Array.from(totals, ([admin0_name, crops]) =>
    Array.from(crops, ([crop, value]) => ({ admin0_name, crop, value }))
  ).flat();

  const _title = nbText.ui.vopPlotTitle;

  return Plot.plot({
    subtitle: _title,
    marginLeft: 50,
    width,
    height: 500,
    x: { label: null, tickFormat: (d) => `${d}` },
    y: { tickFormat: (d) => formatUSD()(d) },
    color: {
      legend: true,
      label: nbText.ui.commodityLegend,
    },
    marks: [
      Plot.barY(flatTotals, {
        x: "admin0_name",
        y: "value",
        fill: "crop",
        tip: true,
      }),
    ],
  });
}

Costs and DurationCouts et Durée

Choose your project’s cost and the length of time you expect to spend paying for it. Payments will be divided evenly across this span.

Choisissez le coût de votre projet et la durée pendant laquelle vous prévoyez de le financer. Les paiements seront répartis de manière égale sur cette période.

viewof inputProjectOptions = {
  const inputProjectCost = Inputs.text({
    label: makeTooltipLabel({
      labelText: inputOptions_projectCost.label,
      tooltipText: inputOptions_projectCost.tooltip,
    }),
    pattern: inputOptions_projectCost.pattern,
    placeholder: inputOptions_projectCost.placeholder,
    value: inputOptions_projectCost.valueString,
  });
  const inputProjectYears = Inputs.select(inputOptions_projectYears.data, {
    format: (x) => x.label,
    label: makeTooltipLabel({
      labelText: inputOptions_projectYears.label,
      tooltipText: inputOptions_projectYears.tooltip,
    }),
    value: inputOptions_projectYears.data.find((d) => d.value == 8),
  });

  return Inputs.form(
    {
      cost: inputProjectCost,
      years: inputProjectYears,
    },
    {
      template: inputTemplate({ gap: "3em" }),
    }
  );
}

{
  const template = nbText.projectSetup.costs.calloutTemplate;
  const templateItems = [
    { name: "money", value: formatUSD({ locale: language.locale })(rangeProjectCost) },
    { name: "time", value: inputProjectOptions.years.label },
  ];
  const formatted = Lang.reduceReplaceTemplateItems(template, templateItems);
  return md`${formatted}`;
}

ImpactsImpacts

These parameters allow you to explore how the impact of an innovation changes project returns. You can adjust how much the innovation improves production yields, the rate at which your target community might adopt it, and how much it reduces the negative impacts of climate variability.

Ces paramètres vous permettent d’étudier comment l’impact d’une innovation modifie les résultats du projet. Vous pouvez ajuster la mesure dans laquelle l’innovation améliore les rendements de production, le taux auquel votre communauté cible pourrait l’adopter et la mesure dans laquelle elle réduit les effets négatifs de la variabilité climatique.

viewof selections_econPerfWalkthrough = {
  const _label_prodImpact = makeTooltipLabel({
    labelText: nbText.projectSetup.impacts.inputs.prodImpactDropdown.label,
    tooltipText: nbText.projectSetup.impacts.inputs.prodImpactDropdown.tooltip,
  });

  const _label_Adoption = makeTooltipLabel({
    labelText: nbText.projectSetup.impacts.inputs.adoptionRateDropdown.label,
    tooltipText: nbText.projectSetup.impacts.inputs.adoptionRateDropdown.tooltip,
  });

  const _label_CisImpact = makeTooltipLabel({
    labelText: nbText.projectSetup.impacts.inputs.cisImpactDropdown.label,
    tooltipText: nbText.projectSetup.impacts.inputs.cisImpactDropdown.tooltip,
  });

  const inputProdImpact = Inputs.range([0, 55], {
    step: 5,
    label: _label_prodImpact,
    value: 30,
  });

  const inputAdoption = Inputs.range([0.25, 2], {
    step: 0.25,
    label: _label_Adoption,
    value: 1,
  });

  const inputCisImpact = Inputs.range([0, 55], {
    step: 5,
    label: _label_CisImpact,
    value: 25,
  });

  return Inputs.form(
    {
      inputProdImpact,
      inputAdoption,
      inputCisImpact,
    },
    {
      template: inputTemplate({ gap: "3em" }),
    }
  );
}

options_econPerfWalkthrough = {
  const formatted = {};
  for (const [key, value] of Object.entries(selections_econPerfWalkthrough)) {
    formatted[key] = {
      label: `${value}%`,
      value: value / 100,
    };
  }
  return formatted;
}

{
  const advancedControlsText = nbText.projectSetup.costs.advancedControls;

  const _benefitLowLabel = makeTooltipLabel({
    labelText: advancedControlsText.inputs.benefitScaleLow.label,
    tooltipText: advancedControlsText.inputs.benefitScaleLow.tooltip,
  });
  const _benefitHighLabel = makeTooltipLabel({
    labelText: advancedControlsText.inputs.benefitScaleHigh.label,
    tooltipText: advancedControlsText.inputs.benefitScaleHigh.tooltip,
  });
  const _costLowLabel = makeTooltipLabel({
    labelText: advancedControlsText.inputs.costScaleLow.label,
    tooltipText: advancedControlsText.inputs.costScaleLow.tooltip,
  });
  const _costHighLabel = makeTooltipLabel({
    labelText: advancedControlsText.inputs.costScaleHigh.label,
    tooltipText: advancedControlsText.inputs.costScaleHigh.tooltip,
  });

  const formBenefitScale = Inputs.form(
    {
      low: Inputs.range([0.5, 1], {
        step: 0.01,
        label: _benefitLowLabel,
        value: 0.85,
      }),
      high: Inputs.range([1, 1.6], {
        step: 0.01,
        label: _benefitHighLabel,
        value: 1.15,
      }),
    },
    {
      template: inputTemplate({ gap: "3em" }),
    }
  );

  const formCostScale = Inputs.form(
    {
      low: Inputs.range([0.5, 1], {
        step: 0.01,
        label: _costLowLabel,
        value: 0.9,
      }),
      high: Inputs.range([1, 1.8], {
        step: 0.01,
        label: _costHighLabel,
        value: 1.2,
      }),
    },
    {
      template: inputTemplate({ gap: "3em" }),
    }
  );

  const _discountLabel = makeTooltipLabel({
    labelText: advancedControlsText.inputs.discountRate.label,
    tooltipText: advancedControlsText.inputs.discountRate.tooltip,
  });

  const _roiLabel = makeTooltipLabel({
    labelText: advancedControlsText.inputs.roi.label,
    tooltipText: advancedControlsText.inputs.roi.tooltip,
  });

  const formFinancialControls = Inputs.form(
    {
      discountRate: Inputs.bind(
        Inputs.range([0, 1], {
          step: 0.01,
          format: (x) => x * 100,
          label: _discountLabel,
          value: 0.12,
        }),
        viewof discountRate
      ),
      bcr: Inputs.bind(
        Inputs.range([0.5, 2], { step: 0.01, label: _roiLabel, value: 1.62 }),
        viewof bcr
      ),
    },
    {
      template: inputTemplate({ gap: "3em" }),
    }
  );

  return dropdown_section(
    _lang(general_translations.advancedControls),
    false,
    formFinancialControls,
    `<b>${advancedControlsText.modelUncertainty}</b>`,
    Inputs.bind(formBenefitScale, viewof uncertaintyBenefitScale),
    Inputs.bind(formCostScale, viewof uncertaintyCostScale)
  );
}

uncertainty = runSimulationFromCashflowRows(recipe_dataCashflow, {
  simulations: 250,
  discountRate: discountRate,
  benefitScale: {
    low: uncertaintyBenefitScale.low,
    mode: 1.0,
    high: uncertaintyBenefitScale.high,
  },
  costScale: {
    low: uncertaintyCostScale.low,
    mode: 1.0,
    high: uncertaintyCostScale.high,
  },
})

Investment ReturnsRetours d’Investissements

Each of these indicators plays a vital role in the evaluation process, offering different perspectives on an investment’s financial viability. Together, they provide a comprehensive understanding, enabling investors and managers to make well-informed decisions.

Chacun de ces indicateurs joue un rôle essentiel dans le processus d’évaluation, en offrant différentes perspectives sur la viabilité financière d’un investissement. Ensemble, ils fournissent une compréhension globale, permettant aux investisseurs et aux gestionnaires de prendre des décisions en connaissance de cause.

bigNumbersResults()

resultTable();

downloadCsvButton(walkthroughEconomicIndicators?.enriched, {
  filename: "roi_data.csv",
  label: nbText.ui.download,
});

resultFigure = resultPlot()

downloadPngButton(resultFigure, {
  filename: "roi_figure",
  label: nbText.ui.downloadFigure,
})

indicatorSelector = {
  // Bind input for a dynamic tooltip.
  return Inputs.bind(
    Inputs.select(dataPickMetric, {
      label: makeTooltipLabel({
        labelText: nbText.ui.indicator,
        tooltipText: pickMetricWalkthrough.tooltip,
      }),
      format: (x) => x.labelFull,
    }),
    viewof pickMetricWalkthrough
  );
}

{
  const listWhat = nbText.investmentReturns.infoListHeaders.what;
  const listInterpret = nbText.investmentReturns.infoListHeaders.interpret;
  const listTell = nbText.investmentReturns.infoListHeaders.tell;

  // Indicator metadata.
  return md`### ${pickMetricWalkthrough.labelFull}

- **${listWhat}**: ${pickMetricWalkthrough.info.what}
- **${listInterpret}**: ${pickMetricWalkthrough.info.interpret}
- **${listTell}**: ${pickMetricWalkthrough.info.tell}
`;
}

SummaryRésumé

The internal rate of return, net present value, and benefit-cost ratio offer valuable insight into the potential returns for an agriculture adaptation investment, which can help project makers evaluate and compare investment opportunities. In this tool, these indicators provide an economic performance analysis for agriculture projects based on key project criteria. This analysis can help guide organizations and farmers in making informed investment decisions aligned with their financial goals.

Le taux de rendement interne, la valeur actuelle nette et le ratio coûts-avantages donnent une idée précieuse du rendement potentiel d’un investissement dans l’adaptation de l’agriculture, ce qui peut aider les responsables de projets à évaluer et à comparer les possibilités d’investissement. Dans cet outil, ces indicateurs fournissent une analyse de la performance économique des projets agricoles sur la base de critères clés. Cette analyse peut aider les organisations et les agriculteurs à prendre des décisions d’investissement éclairées et conformes à leurs objectifs financiers.

{
  const npv_rate = discountRate * 100 + "%";
  const farm_bcr = bcr;

  const template = nbText.summary.assumptionsTemplate;
  const templateItems = [
    { name: "npvDisountRate", value: npv_rate },
    { name: "farmBcr", value: farm_bcr },
  ];
  const formatted = Lang.reduceReplaceTemplateItems(template, templateItems);
  return md`${formatted}`;
}

Methods & SourcesMéthodes & Sources

The tool utilizes the best available production value datasets covering all of sub-Saharan Africa, enabling cross-country, crop, and livestock comparisons. While suitable for macro-scale analysis to determine economic viability and regional differences, the data’s applicability diminishes at smaller scales. For projects with defined targets and contexts, we recommend engaging with local communities and governance through participatory approaches to refine investment targeting and design.

This Spotlight implements a model developed for the Accelerating the Impact of CGIAR Climate Research in Africa (AICCRA) program.

Datasets

• Spatial crop production data for 2017 comes from MapSPAM 2017 V2r3 (Spatial Production Allocation Model)
• Spatial livestock distribution data comes from the Gridded Livestock of the World - 2015 dataset.
• National producer price data comes from FAOstat
• National production and yield data comes from FAOstat
• Administrative boundaries are provided by geoBoundaries 6.0.0. The gbHumanitarian boundaries are used and if not available then the gbOpen boundaries are substituted.

Methodology

This tool implements the methodology developed by Philip Thorton used to inform the Economic and Financial Analysis (EFA) for the Accelerating Impacts of CGIAR Climate Research for Africa (AICCRA) project.

Data preparation

Producer Prices

1. FAOstat production in USD is averaged by commodity and country for the period 2015-2019.
2. Data gaps for combinations of country and commodity are filled by using, in order of preference: a) the average of neighbouring countries; b) the regional average for the worldbank region the country belongs to; c) the continental average for sub-Saharan Africa.
3. The producer prices are then merged with country level (admin0) administrative boundaries and rasterized.
4. Code availability: fao_producer_prices.R

Livestock Value of Production

1. As spatial livestock production comes from 2000, we rescaled values to 2017 using the proportional national change in faostat production between 2000 and 2017. The scaling method preferentially adds production increases to the middle of the production distribution for a country and not the tails. For example, areas without production in 2000 do not suddenly become producers and heavy producing areas do not increase as much as intermediate producing areas.
2. Livestock production scaled to 2017 is then multiplied by the corresponding producer price data to generate livestock value of production in USD in 2017.
3. Meat and milk are added together for sheep, goats and cattle.
4. Values are extracted for administrative areas, summed and converted into tabular form.
5. Code availability: fao_producer_prices_livestock.R

Crop Value

1. MapSPAM crop production is multiplied by the corresponding producer price data to live crop value of production in USD in 2017.
2. Code availability: fao_producer_prices.R

Calculations

Yield and Production Variability

• FAOstat yield and production data from 2000-2022 are used to calculate the coefficient of variation(CV) for crops (yield) and livestock (production). We use production data rather than yields for livestock because livestock yield data appears to be highly calculated in FAOstat and shows very little variability over time, whereas production data is variable.
• Commodity yields and production amounts in many countries show a strong increase over time. Where temporal trends are significant, we detrend to the data (linear) before calculating the CV.
• Data gaps in CV for combinations of country and commodity are filled by using, in order of preference: a) the average of neighbouring countries; b) the regional average for the World Bank region the country belongs to; c) the continental average for sub-Saharan Africa.
• Code availability: fao_production_cv.R

Economic Benefits

We estimate project-level economic benefits by heuristically modeling how innovations affect value of production (VoP) and climate-related losses across time, space, and user-defined adoption rates. The main steps are:

1. VoP under Innovation Adoption:
   We apply user-defined adoption rates over time, shrinking the pool of non-adopters each year. For instance, with an initial VoP of 1000 and 10% adoption: year 1 sees 100 under innovation, year 2 adds 90 (from the remaining 900), totaling 190, and so on.

2. Production Impact Gains:
   We multiply the total VoP under adoption by the selected production impact (e.g. 20% yield increase). The marginal gain is the difference between VoP with and without innovation.

3. Avoided Climate Losses:
   To estimate avoided losses due to innovations that reduce climate impacts, we assume:

   • Yield/production follows a normal distribution
   • Adoption reduces yield variability (CV) proportionally
     For each crop and area, we generate two normal distributions (mean = 1): one for non-adopters (baseline CV) and one for adopters (reduced CV). The avoided loss proportion is the difference in expected loss in the lower tail (below 0) of each distribution.

4. Total Marginal Benefit:
   The total VoP under adoption is adjusted upward using the avoided loss proportion. The marginal benefit from climate impact reduction is added to the production gain, giving total marginal benefit.

5. Total Project Benefit:
   The total benefit is calculated as:
   Total Benefit = Marginal Benefit – (Marginal Benefit / BCR) where BCR = 1.62 (assumed from Harris & Orr, 2014). We then discount both benefits and costs over time using the selected discount rate to obtain time-adjusted values for indicator computation.

6. Code Availability:
   See 4_roi.R

Economic Indicators

The four indicators presented — IRR, MIRR, NPV, and BCR — capture different aspects of financial performance and can diverge for several reasons:

1. Timing of cash flows: IRR and MIRR reflect return rates over time and can appear high when large benefits arrive late in a project. However, NPV and BCR account for discounting, so delayed benefits reduce their values even if the project is profitable in the long run.

2. Scale of investment: Small investments with modest benefits can generate high IRR or MIRR due to efficiency, but the total net gain (NPV) or cost-effectiveness (BCR) may still be low.

3. Discount rate effects: Since NPV and BCR rely on discounting, a high discount rate (default 8%) can make delayed gains appear smaller. IRR and MIRR are unaffected by this rate in their core calculation, but MIRR incorporates reinvestment assumptions (also 8% here).

4. Cumulative structure: Each year’s values represent cumulative discounted returns to date, which helps track how financial indicators evolve across the life of the project.

These indicators should be used together for a balanced view of financial viability.

Methodological Notes on Indicator Calculations

This notebook computes four financial indicators — Internal Rate of Return (IRR), Modified Internal Rate of Return (MIRR), Net Present Value (NPV), and Discounted Benefit-Cost Ratio (BCR) — using the following methodology:

1. Cash Flow Construction:
   • A project cash flow is created by subtracting user-defined project costs from estimated economic benefits.
   • Benefits are derived from the value of increased agricultural production (VoP) and the reduction of climate-related yield losses, both calculated annually based on user inputs.
   • Adoption rate is applied progressively over time, reducing the pool of non-adopters and reflecting diminishing marginal expansion.
2. Discounting:
   • All future cash flows are discounted to present value using a user-specified discount rate (default: 8%).
   • Cumulative discounted benefits and cumulative discounted costs are stored for each project year.
3. Net Present Value (NPV):
   • NPV is calculated as the sum of discounted net returns (benefit minus cost) up to the selected year.
   • A positive NPV implies the project’s benefits exceed its costs in present-value terms.
   • Note: We use discrete annual discounting PV = FV / (1 + r)^t, not continuous compounding.
4. Discounted Benefit-Cost Ratio (BCR):
   • BCR is calculated as the ratio of cumulative discounted benefits to cumulative discounted costs.
   • A BCR > 1 indicates a financially efficient project.
   • Unlike some simplified BCR approaches, this version uses full discounted benefit and cost streams.
5. Internal Rate of Return (IRR):
   • IRR is estimated via a secant method to find the discount rate that sets the net present value of the project’s cumulative cash flow to zero.
   • IRR reflects the annualized rate of return implied by the cash flows.
6. Modified Internal Rate of Return (MIRR):
   • MIRR addresses limitations of IRR by assuming:
     • Negative cash flows (investments) are financed at the discount (finance) rate
     • Positive cash flows (returns) are reinvested at the same (reinvestment) rate
   • MIRR is calculated from the future value of positive flows and the present value of negative flows using the formula:
     MIRR = (FV of inflows / |PV of outflows|)^(1/n) - 1, where n is the project duration.
   • We assume the finance and reinvestment rates are equal to the discount rate used in NPV and BCR (default: 8%).
7. Cumulative Time Horizon:
   • Each metric is calculated cumulatively: i.e., IRR and MIRR at year 3 reflect performance based on the first 4 years of project cash flows (year 0 to year 3).
   • This provides a dynamic view of how financial indicators evolve as the project progresses.
8. Edge Case Handling:
   • If IRR or MIRR cannot be calculated (e.g., due to all-positive or all-negative flows), the result is returned as null.
   • Indicators are rounded (NPV to 1 decimal, BCR to 2 decimals, IRR and MIRR to 1 decimal %) for clarity.

All indicator calculations are implemented natively within the Observable notebook (no external APIs), enabling real-time interactivity and transparency.

An earlier and more technical version of this methodology was developed into a tool using Shiny R and can be found on the github AICCRA_EFA.

L’outil utilise les meilleurs ensembles de données disponibles sur la valeur de la production couvrant l’ensemble de l’Afrique subsaharienne, ce qui permet des comparaisons entre les pays, les cultures et le bétail. S’il convient à l’analyse macroéconomique pour déterminer la viabilité économique et les différences régionales, l’applicabilité des données diminue à plus petite échelle. Pour les projets dont les objectifs et les contextes sont définis, nous recommandons de s’engager avec les communautés locales et la gouvernance par le biais d’approches participatives afin d’affiner le ciblage et la conception des investissements.

Ce Spotlight met en œuvre un modèle développé pour le programme AICCRA (Accelerating the Impact of CGIAR Climate Research in Africa).

Ensembles de Données

• Les données spatiales sur la production végétale pour 2017 proviennent de MapSPAM 2017 V2r3 (Modèle d’Allocation de Production Spatiale).

• Les données spatiales sur la répartition des animaux proviennent de Gridded Livestock of the World - 2015.

• Les données nationales sur les prix à la production proviennent de FAOstat

• Les données sur les productions et les rendements nationaux proviennent de FAOstat

• Les frontières administratives sont fournies par geoBoundaries 6.0.0. Les frontières gbHumanitarian sont utilisées et, si elles ne sont pas disponibles, les frontières gbOpen sont substituées.`

  Méthodes

  Cet outil met en œuvre la méthodologie développée par Philip Thorton et utilisée pour informer l’Analyse Économique et Financière (AEF) pour le projet AICCRA (Accelerating Impacts of CGIAR Climate Research for Africa) project.

  Préparation des données

Prix des Producteurs

1. La production de la FAOstat en USD est calculée en moyenne par produit et par pays pour la période 2015-2019.
2. Les données manquantes pour les combinaisons de pays et de produits sont comblées en utilisant, par ordre de préférence : a) la moyenne des pays voisins ; b) la moyenne régionale pour la région de la Banque mondiale à laquelle le pays appartient ; c) la moyenne continentale pour l’Afrique subsaharienne.
3. Les prix à la production sont ensuite fusionnés avec les limites administratives du pays (admin0) et tramés.
4. Disponibilité du code: fao_producer_prices.R

Valeur de la Production Animale

1. Étant donné que la production animale spatiale date de 2000, nous avons remis à l’échelle les valeurs pour 2017 en utilisant la variation nationale proportionnelle de la production faostat entre 2000 et 2017. La méthode de mise à l’échelle ajoute de préférence les augmentations de production au milieu de la distribution de la production pour un pays et non aux queues. Par exemple, les régions sans production en 2000 ne deviennent pas soudainement productrices et les régions à forte production n’augmentent pas autant que les régions à production intermédiaire.
2. La production animale ramenée à 2017 est ensuite multipliée par les données de prix à la production correspondantes pour générer la valeur de la production animale en USD en 2017.
3. La viande et le lait sont additionnés pour les ovins, les caprins et les bovins.
4. Les valeurs sont extraites pour les zones administratives, additionnées et converties sous forme de tableau.
5. Disponibilité du code: fao_producer_prices_livestock.R

Valeur des Cultures

1. La production végétale de MapSPAM est multipliée par les données de prix à la production correspondantes pour obtenir la valeur de la production végétale en USD en 2017.
2. Disponibilité du code: fao_producer_prices.R

Calculs

Variabilité du Rendement et de la Production

• Les données de rendement et de production de la FAOstat pour la période 2000-2022 sont utilisées pour calculer le coefficient de variation (CV) des cultures (rendement) et du bétail (production). Nous utilisons les données de production plutôt que les rendements pour le bétail parce que les données de rendement du bétail semblent être très bien calculées dans la FAOstat et montrent très peu de variabilité dans le temps, alors que les données de production sont variables.
• Les rendements des produits et les quantités produites dans de nombreux pays montrent une forte augmentation au fil du temps. Lorsque les tendances temporelles sont significatives, nous procédons à une désintégration des données (linéaire) avant de calculer le CV.
• Les données manquantes dans les CV pour les combinaisons de pays et de produits sont comblées en utilisant, par ordre de préférence: a) la moyenne des pays voisins; b) la moyenne régionale pour la région de la Banque mondiale à laquelle le pays appartient; c) la moyenne continentale pour l’Afrique subsaharienne.
• Disponibilité du code: fao_production_cv.R

Bénéfices économiques

Nous estimons les bénéfices économiques d’un projet en modélisant de manière heuristique comment les innovations influencent la valeur de la production (VoP) et les pertes liées au climat dans le temps, l’espace, et selon les taux d’adoption définis par l’utilisateur. Les principales étapes sont :

1. VoP sous adoption de l’innovation :
   Nous appliquons des taux d’adoption progressifs définis par l’utilisateur, réduisant chaque année la part de non-adoptants. Par exemple, pour une VoP initiale de 1000 et un taux d’adoption de 10 %, la première année voit 100 sous innovation, la deuxième ajoute 90 (des 900 restants), totalisant 190, et ainsi de suite.

2. Gains liés à l’impact sur la production :
   Nous multiplions la VoP totale sous adoption par l’impact de production sélectionné (par exemple, +20 % de rendement). Le gain marginal est la différence entre la VoP avec et sans innovation.

3. Pertes climatiques évitées :
   Pour estimer les pertes évitées grâce à des innovations réduisant les impacts climatiques, nous supposons :

   • Une distribution normale des rendements/productions
   • Une réduction proportionnelle de la variabilité des rendements (CV) liée à l’adoption
     Pour chaque culture et zone, nous générons deux distributions normales (moyenne = 1) : une pour les non-adoptants (CV de référence), une pour les adoptants (CV réduite). La proportion de perte évitée correspond à la différence entre les queues gauches (en dessous de 0) de ces distributions.

4. Bénéfice marginal total :
   La VoP totale sous adoption est ajustée à la hausse via la proportion de perte évitée. Le bénéfice marginal lié à la réduction des impacts climatiques est ajouté au gain de production pour obtenir le bénéfice marginal total.

5. Bénéfice total du projet :
   Le bénéfice total est calculé comme :
   Bénéfice total = Bénéfice marginal – (Bénéfice marginal / BCR) où BCR = 1.62 (valeur tirée de Harris & Orr, 2014). Les bénéfices et coûts sont ensuite actualisés à l’aide du taux d’actualisation sélectionné afin d’obtenir des valeurs ajustées dans le temps pour le calcul des indicateurs.

6. Disponibilité du code :
   Voir 4_roi.R

---

Indicateurs économiques

Quatre indicateurs — TRI (IRR), TRI modifié (MIRR), VAN (NPV) et RCA actualisé (BCR) — capturent différents aspects de la performance financière et peuvent diverger selon plusieurs facteurs :

1. Calendrier des flux de trésorerie :
   Le TRI et le MIRR reflètent les taux de rendement dans le temps et peuvent être élevés si les bénéfices arrivent tardivement. La VAN et le RCA appliquent l’actualisation, ce qui diminue la valeur des bénéfices différés, même si le projet reste rentable à long terme.

2. Échelle de l’investissement :
   Des projets de petite taille avec des bénéfices modestes peuvent afficher un TRI ou MIRR élevé, mais des gains nets totaux (VAN) ou une efficacité (BCR) faibles.

3. Effets du taux d’actualisation :
   La VAN et le BCR sont sensibles au taux d’actualisation (par défaut 8 %). Un taux élevé réduit la valeur des bénéfices futurs. Le TRI et le MIRR n’y sont pas sensibles dans leur formule de base, mais le MIRR incorpore les hypothèses de réinvestissement (également à 8 % ici).

4. Structure cumulative :
   Chaque année reflète les retours cumulés actualisés jusqu’à ce point, ce qui permet de suivre l’évolution de la viabilité financière dans le temps.

Ces indicateurs doivent être utilisés ensemble pour une lecture équilibrée de la performance financière.

---

Notes méthodologiques sur le calcul des indicateurs

1. Construction des flux de trésorerie
   • Les flux sont construits en soustrayant les coûts du projet (uniformément répartis) des bénéfices économiques estimés.
   • Les bénéfices incluent l’augmentation de la VoP et les pertes climatiques évitées, calculés annuellement.
   • Le taux d’adoption est appliqué progressivement, réduisant la base des non-adoptants chaque année.
2. Actualisation
   • Tous les flux futurs sont actualisés selon PV = FV / (1 + r)^t (actualisation discrète annuelle).
   • Les coûts et bénéfices actualisés sont enregistrés cumulativement par année.
3. Valeur actuelle nette (VAN)
   • La VAN est la somme des flux nets actualisés jusqu’à l’année sélectionnée.
   • Une VAN positive indique que les bénéfices surpassent les coûts en valeur actuelle.
4. Ratio coût-bénéfice actualisé (RCA)
   • Le BCR est le ratio des bénéfices actualisés cumulés sur les coûts actualisés cumulés.
   • Un BCR > 1,0 suggère un projet efficient financièrement.
   • Cette approche utilise les séries temporelles complètes actualisées.
5. Taux de rendement interne (TRI)
   • Estimé par méthode des sécantes, il est le taux qui annule la VAN du flux cumulatif.
   • Le TRI exprime le rendement annuel implicite du projet.
6. Taux de rendement interne modifié (TRIM)
   • Corrige les limites du TRI en supposant que :
     • Les investissements sont financés au taux d’actualisation
     • Les retours sont réinvestis à ce même taux
   • Calcul :
     MIRR = (VF des flux positifs / |VA des flux négatifs|)^(1/n) - 1 où n est la durée du projet (en années).
   • Les taux de financement et de réinvestissement sont fixés au taux d’actualisation (par défaut 8 %).
7. Horizon temporel cumulatif
   • Tous les indicateurs sont calculés de manière cumulative : par ex. le TRI à l’année 3 utilise les flux des années 0 à 3.
   • Cela permet d’analyser la performance au fil du projet.
8. Traitement des cas limites
   • Si le TRI ou le MIRR ne peuvent être calculés (tous les flux étant positifs ou négatifs), la valeur retournée est null.
   • Les résultats sont arrondis pour clarté : VAN à 1 décimale, BCR à 2, TRI/MIRR à 1 décimale (%).

Tous les calculs sont réalisés localement dans le notebook Observable (aucune API externe), assurant interactivité et transparence.

Une version antérieure et plus technique de cette méthodologie a été implémentée dans l’outil R Shiny AICCRA_EFA.

ContributorsContributeurs

AuthorsAuteurs

Pete Steward¹, Todd Rosenstock^1,2, Phillip Thornton³, Brayden Youngberg¹, Lolita Muller¹

Technical DevelopmentDéveloppement technique

Zach Bogart⁴, Brayden Youngberg¹, Pete Steward¹

AffiliationsAffiliations

¹ Alliance Bioversity and CIAT

² CGIAR

³ ILRI

⁴ Periscopic

CitationRéférence

CGIAR. (2026). Estimate Economic Returns on AdaptationEstimer les retombées économiques de l'adaptation. Africa Agriculture Adaptation Atlas. https://adaptationatlas.cgiar.org

AppendixAnnexe

Source code

Data import and cleaning

db = {
  let db = await DuckDBClient.of({
    cv_raw: FileAttachment("/data/economicReturns/faostat_prod_cv.parquet"),
  });
  await db.query(`
    CREATE TABLE exposure AS
      SELECT
        iso3,
        admin0_name,
        admin1_name,
        REGEXP_REPLACE(crop, '-tropical|-highland', '') AS crop,
        CONCAT(exposure, '_', unit) AS exposure,
        SUM(value) AS value
      FROM read_parquet("s3://digital-atlas/domain=exposure/type=combined/source=glw4-2020_spam2020AA/region=ssa/processing=atlas-harmonized/variable=vop_nominal-usd-2021.parquet")
      WHERE
        admin2_name IS NULL AND admin1_name IS NOT NULL
        AND (tech = 'all' OR tech IS NULL)
        AND isfinite(value)
        AND crop !~ '(^other-|rest-of|temperate-fruit|tropical-fruit|vegetables)'
      GROUP BY
        iso3,
        admin0_name,
        admin1_name,
        crop,
        CONCAT(exposure, '_', unit)
  `);
  await db.query(`
    CREATE VIEW cv AS
      SELECT
        admin0_name,
        -- clean and standardize crop names
        REGEXP_REPLACE(
          REGEXP_REPLACE(
            REPLACE(REPLACE(crop, '_meat', ''), ' ', '-'),
            'goat$', 'goats'
          ),
          'pig$', 'pigs'
        ) AS crop,
        value_filled AS cv
      FROM cv_raw
      WHERE NOT (crop ILIKE '%milk%' OR crop ILIKE '%eggs%' OR LOWER(crop) = 'total')

      UNION ALL
      -- add robusta-coffee and small-millet substitutes
      SELECT admin0_name, 'robusta-coffee', value_filled AS cv
      FROM cv_raw
      WHERE crop = 'arabica-coffee'

      UNION ALL
      SELECT admin0_name, 'small-millet', value_filled AS cv
      FROM cv_raw
      WHERE crop = 'pearl-millet';
`);
  return db;
}

countries = {
  const country_list = await FileAttachment("/data/shared/atlas_countries.json").json();
  const filteredCountries = country_list
    .filter((c) => c.include && c.iso3c !== "SDN")
    .map(({ include, ...rest }) => rest);
  return filteredCountries;
}

dataAdminRegions = {
  const bind = createSqlBindings();
  const regions = await db.query(
    `
    SELECT DISTINCT admin0_name, admin1_name, iso3
    FROM exposure
    WHERE admin1_name IS NOT null
    AND iso3 IN (${bind.list(select_country)})
  `,
    bind.params
  );

  return regions.map((row) => ({
    ...row,
    id: `${row.iso3}_${row.admin1_name}`,
  }));
}

// TODO: Translate and normalize item labels.
dataCrops = await db.query(`
  SELECT DISTINCT crop AS item
  FROM exposure
  ORDER BY item
`)

Inputs

inputOptions_projectCost = {
  return {
    range: [1e6, 5e8],
    label: nbText.projectSetup.costs.inputs.costInput.label,
    tooltip: nbText.projectSetup.costs.inputs.costInput.tooltip,
    step: 1e5,
    value: 50_000_000,
    format: d3.format("$.3s"),
    outputWidth: 90,
    placeholder: "Ex. $5,000,000",
    pattern: "^[$]?[1-9]+[0-9,$]*$",
    valueString: "$50,000,000",
  };
}

inputOptions_projectYears = {
  const years = nbText.projectSetup.costs.inputs.projectYearDropdown.terms.year.plural;
  return {
    range: [2, 16],
    data: d3.range(2, 16 + 1, 1).map((d) => ({ label: `${d} ${years}`, value: d })),
    label: nbText.projectSetup.costs.inputs.projectYearDropdown.label,
    tooltip: nbText.projectSetup.costs.inputs.projectYearDropdown.tooltip,
    step: 1,
    value: 8,
    outputWidth: 90,
  };
}

Scope Selectors - country, region, crop

viewof select_country = {
  const data = countries.map((d) => ({
    value: d.iso3c, //Migrating to iso codes for future flexability
    label: _lang(d.translation),
  }));
  const labels = new Map(data.map((d) => [d.value, d.label]));
  return atlasMultiSelect(
    data.map((d) => d.value),
    {
      label: makeTooltipLabel({
        labelText: nbText.words.country.plural,
        tooltipText: nbText.projectSetup.locations.inputs.countryDropdown.tooltip,
      }),
      value: ["KEN", "TZA"],
      format: (value) => labels.get(value) ?? value,
      enableSelectAll: true,
      requireAtLeastOne: false,
      language: language.key,
    }
  );
}

viewof select_region = {
  // Filter regions by selected country IDs.
  const filteredRegions = dataAdminRegions;
  const translateCountry = (iso) => _lang(countries.find((c) => c.iso3c === iso).translation);
  const data = filteredRegions.map((d) => ({
    value: d.id,
    label: `${translateCountry(d.iso3)}: ${d.admin1_name}`,
  }));
  const selectedIds = filteredRegions.map((d) => d.id);
  const text = {
    label: nbText.words.region.plural,
    tooltip: nbText.projectSetup.locations.inputs.regionDropdown.tooltip,
  };
  const labels = new Map(data.map((d) => [d.value, d.label]));
  return atlasMultiSelect(
    data.map((d) => d.value),
    {
      label: makeTooltipLabel({ labelText: text.label, tooltipText: text.tooltip }),
      value: selectedIds,
      format: (value) => labels.get(value) ?? value,
      enableSelectAll: true,
      requireAtLeastOne: false,
      language: language.key,
    }
  );
}

viewof select_crop = {
  const data = dataCrops
    .map((d) => ({
      value: d.item,
      label: Lang.toSentenceCase(d.item), //TODO: Add translations
    }))
    .sort((a, b) => a.label > b.label);
  const selectedId = dataCrops
    .filter((d) => ["bean", "goats", "maize"].includes(d.item))
    .map((d) => d.item);
  const text = {
    label: nbText.words.commodity.plural,
    tooltip: nbText.projectSetup.locations.inputs.commodityDropdown.tooltip,
  };
  const labels = new Map(data.map((d) => [d.value, d.label]));
  return atlasMultiSelect(
    data.map((d) => d.value),
    {
      label: makeTooltipLabel({
        labelText: text.label,
        tooltipText: text.tooltip,
      }),
      value: selectedId,
      format: (value) => labels.get(value) ?? value,
      enableSelectAll: true,
      requireAtLeastOne: false,
      language: language.key,
    }
  );
}

Economic Input Variables

Main Control Variables

rangeProjectCost = {
  const unpack = Number(inputProjectOptions.cost.replace(/[,|$]/g, ""));
  const number = Number(unpack);
  return number;
}

projectYears = inputProjectOptions.years.value

render_econPerfWalkthrough = () => {
  const terms = {
    none: nbText.projectSetup.impacts.terms.none,
    low: nbText.projectSetup.impacts.terms.low,
    moderate: nbText.projectSetup.impacts.terms.moderate,
    high: nbText.projectSetup.impacts.terms.high,
    incremental: nbText.projectSetup.impacts.terms.incremental,
    transformative: nbText.projectSetup.impacts.terms.transformative,
  };
  const dataProdImpact = [
    { label: `10% (${terms.incremental})`, value: 0.1 },
    { label: `20%`, value: 0.2 },
    { label: `30% (${terms.moderate})`, value: 0.3 },
    { label: `40%`, value: 0.4 },
    { label: `50% (${terms.transformative})`, value: 0.5 },
  ];
  const inputProdImpact = Inputs.select(dataProdImpact, {
    label: makeTooltipLabel({
      labelText: nbText.projectSetup.impacts.inputs.prodImpactDropdown.label,
      tooltipText: nbText.projectSetup.impacts.inputs.prodImpactDropdown.tooltip,
    }),
    format: (x) => x.label,
    value: dataProdImpact.find((d) => d.value == 0.3),
  });
  const dataAdoption = [
    { label: `0.5% (${terms.low})`, value: 0.005 },
    { label: `1% (${terms.moderate})`, value: 0.01 },
    { label: `2% (${terms.high})`, value: 0.02 },
  ];
  const inputAdoption = Inputs.select(dataAdoption, {
    label: makeTooltipLabel({
      labelText: nbText.projectSetup.impacts.inputs.adoptionRateDropdown.label,
      tooltipText: nbText.projectSetup.impacts.inputs.adoptionRateDropdown.tooltip,
    }),
    format: (x) => x.label,
    value: dataAdoption.find((d) => d.value == 0.01),
  });
  const dataCisImpact = [
    { label: `0% (${terms.none})`, value: 0 },
    { label: `10% (${terms.low})`, value: 0.1 },
    { label: `25% (${terms.moderate})`, value: 0.25 },
    { label: `50% (${terms.high})`, value: 0.5 },
  ];
  const inputCisImpact = Inputs.select(dataCisImpact, {
    label: makeTooltipLabel({
      labelText: nbText.projectSetup.impacts.inputs.cisImpactDropdown.label,
      tooltipText: nbText.projectSetup.impacts.inputs.cisImpactDropdown.tooltip,
    }),
    format: (x) => x.label,
    value: dataCisImpact.find((d) => d.value == 0.25),
  });
  return Inputs.form(
    {
      inputProdImpact,
      inputAdoption,
      inputCisImpact,
    },
    {
      template: inputTemplate({ gap: "3em" }),
    }
  );
}

Advanced Control Variables

viewof discountRate = Inputs.range([0, 1], {
  step: 0.01,
  format: (x) => x * 100,
  value: 0.12,
  label: "Discount Rate",
}) // 0-1 as a pct
viewof bcr = Inputs.range([0.5, 2], { step: 0.01, label: "BCR", value: 1.62 })

viewof uncertaintyBenefitScale = Inputs.form(
  {
    low: Inputs.range([0.5, 1], {
      step: 0.01,
      value: 0.9,
    }),
    high: Inputs.range([1, 1.8], {
      step: 0.01,
      value: 1.2,
    }),
  },
  {
    template: inputTemplate({ gap: "3em" }),
  }
)

viewof uncertaintyCostScale = Inputs.form(
  {
    low: Inputs.range([0.5, 1], {
      step: 0.01,
      value: 0.9,
    }),
    high: Inputs.range([1, 1.8], {
      step: 0.01,
      value: 1.2,
    }),
  },
  {
    template: inputTemplate({ gap: "3em" }),
  }
)

Other Selections

// Metric selector.
viewof pickMetricWalkthrough = {
  return Inputs.select(dataPickMetric, {
    label: nbText.ui.indicator,
    format: (x) => x.labelFull,
    value: dataPickMetric.find((d) => d.key == "irr"),
  });
}

Elements

import { atlasMultiSelect } from "/helpers/enhancedMultiSelect.ojs";

Helper Functions

Language

import { lang as Lang } from "/helpers/lang.js";

general_translations = await FileAttachment("/data/shared/generalTranslations.json").json()

languages = [
  { key: "en", label: "English", locale: "en-US" },
  { key: "fr", label: "Français", locale: "fr-FR" },
]

// Language state lives in the navbar switcher; this cell just subscribes.
langKey = Generators.observe((notify) => {
  notify(window.atlasLang ?? "en");
  const onChange = (e) => notify(e.detail);
  window.addEventListener("atlas:lang", onChange);
  return () => window.removeEventListener("atlas:lang", onChange);
})

language = languages.find((l) => l.key === langKey) ?? languages[0]

_lang = Lang.lg(language.key)

import { loadNotebookText, readNotebookConfig } from "/helpers/notebook.js";

notebookConfig = readNotebookConfig()

notebookText = await loadNotebookText(notebookConfig)

nbText = notebookText[language.key]

nbTitle = notebookConfig.title[language.key]

tmpl = (template, values) =>
  Lang.reduceReplaceTemplateItems(
    template,
    Object.entries(values).map(([name, value]) => ({ name, value }))
  )

Markdown notebook text

dataPickMetric = {
  return [
    {
      key: "irr",
      columnName: "irr",
      label: nbText.indicators.irr.label,
      tooltip: nbText.indicators.irr.tooltip,
      labelLong: nbText.indicators.irr.labelLong,
      labelFull: nbText.indicators.irr.labelFull,
      info: {
        what: nbText.indicators.irr.info.what,
        interpret: nbText.indicators.irr.info.interpret,
        tell: nbText.indicators.irr.info.tell,
      },
      yFormat: (d) => `${d.toFixed(1)}%`,
    },
    {
      key: "mirr",
      columnName: "mirr",
      label: nbText.indicators.mirr.label,
      tooltip: nbText.indicators.mirr.tooltip,
      labelLong: nbText.indicators.mirr.labelLong,
      labelFull: nbText.indicators.mirr.labelFull,
      info: {
        what: nbText.indicators.mirr.info.what,
        interpret: nbText.indicators.mirr.info.interpret,
        tell: nbText.indicators.mirr.info.tell,
      },
      yFormat: (d) => `${d.toFixed(1)}%`,
    },
    {
      key: "npv",
      columnName: "npv",
      label: nbText.indicators.npv.label,
      tooltip: nbText.indicators.npv.tooltip,
      labelLong: nbText.indicators.npv.labelLong,
      labelFull: nbText.indicators.npv.labelFull,
      info: {
        what: nbText.indicators.npv.info.what,
        interpret: nbText.indicators.npv.info.interpret,
        tell: nbText.indicators.npv.info.tell,
      },
      yFormat: (d) => formatUSD()(d),
    },
    {
      key: "bcr",
      columnName: "discounted_bcr",
      label: nbText.indicators.bcr.label,
      tooltip: nbText.indicators.bcr.tooltip,
      labelLong: nbText.indicators.bcr.labelLong,
      labelFull: nbText.indicators.bcr.labelFull,
      info: {
        what: nbText.indicators.bcr.info.what,
        interpret: nbText.indicators.bcr.info.interpret,
        tell: nbText.indicators.bcr.info.tell,
      },
      yFormat: d3.format(".2f"),
    },
  ];
}

renderReview1 = () => {
  const langBasePath = nbText.investmentReturns.insightReview.setupBlock;
  const langMissingTemplate = langBasePath.missingMessage;

  const isoSet = new Set(select_country);

  const admin0List = countries.filter((d) => isoSet.has(d.iso3c)).map((d) => d.admin0_name);

  const cropList = select_crop;

  const truncateSize = 3;
  const admin0ListTruncated = admin0List.slice(0, truncateSize);
  const cropListTruncated = cropList.slice(0, truncateSize); // .map((d) => _lang(d.translation));

  if (admin0List.length == 0 || cropList.length == 0) {
    return md`${langMissingTemplate}`;
  }

  const insertCropCount = cropList.length;
  const insertCropWord =
    cropList.length == 1 ? nbText.words.crop.singular : nbText.words.crop.plural;
  const insertCropList = `(**${cropListTruncated.join(", ")}${
    cropList.length > truncateSize ? "..." : ""
  }**)`;
  const insertCrop = `**${insertCropCount} ${insertCropWord}** ${insertCropList}`;

  const insertRegionCount = select_region.length;
  const insertRegionWord =
    insertRegionCount == 1 ? nbText.words.region.singular : nbText.words.region.plural;
  const insertRegion = `${insertRegionCount} ${insertRegionWord}`;

  const insertCountryCount = admin0List.length;
  const insertCountryWord =
    insertCountryCount == 1 ? nbText.words.country.singular : nbText.words.country.plural;
  const insertCountryList = `(**${admin0ListTruncated.join(", ")}${
    insertCountryCount > truncateSize ? "..." : ""
  }**)`;
  const insertCountry = `**${insertCountryCount} ${insertCountryWord}** ${insertCountryList}`;

  const langTemplate = langBasePath.template;
  const langTemplateItems = [
    { name: "crop_string", value: insertCrop },
    { name: "region_string", value: insertRegion },
    { name: "country_string", value: insertCountry },
    {
      name: "cost_string",
      value: formatUSD({ locale: language.locale })(rangeProjectCost),
    },
    { name: "year_string", value: projectYears + " years" }, //TODO: add correct "years" string at end of this
  ];
  const selectionFormattedTemplate = Lang.reduceReplaceTemplateItems(
    langTemplate,
    langTemplateItems
  );

  return md`${selectionFormattedTemplate}`;
}

renderReview2 = () => {
  const investmentTemplate = nbText.investmentReturns.insightReview.indicatorBlock;
  const investmentTemplateItems = [
    {
      name: "prod_impact_label",
      value: options_econPerfWalkthrough.inputProdImpact.label,
    },
    {
      name: "adoption_rate_label",
      value: options_econPerfWalkthrough.inputAdoption.label,
    },
    {
      name: "cis_impact_label",
      value: options_econPerfWalkthrough.inputCisImpact.label,
    },
    { name: "year_string", value: projectYears + " years" },
  ];

  return md`${Lang.reduceReplaceTemplateItems(investmentTemplate, investmentTemplateItems)}:`;
}

Result Elements

bigNumbersResults = () => {
  const y = projectYears;
  const e = walkthroughEconomicIndicators?.enriched?.find((d) => d.year === y);

  const data = dataPickMetric.map((d) => {
    let value;

    if (d.key === "irr" && e?.irr != null) {
      value = e.irr; // IRR as percentage
    } else if (d.key === "mirr" && e?.mirr != null) {
      value = e.mirr; // MIRR as percentage
    } else if (
      d.key === "npv" &&
      e?.discounted_benefit_cum != null &&
      e?.discounted_cost_cum != null
    ) {
      value = +(e.discounted_benefit_cum - e.discounted_cost_cum).toFixed(1); // NPV, 1 dp
    } else if (d.key === "bcr") {
      value = e?.discounted_bcr;
    }

    return { ...d, value };
  });

  return htl.html`
  <style>
    .outer-div {
      display: flex;
      gap: 2em;
    }
    .inner-div {
      width: 30%;
      padding: 80px 30px;
      border: 1px solid #efefef;
    }
    .label {
      display: block;
      font-weight: 400;
      font-size: 14px;
      text-transform: uppercase;
      color: #666;
    }
    .value {
      font-weight: bold;
      font-size: 42px;
    }
    .negative {
      color: #EC5A47;
    }
    .tooltip-card {
        position: relative;
        display: inline-block;
        cursor: pointer;
        width: 100%;
    }
    .tooltip-card .tooltiptext-card {
        position: absolute;
        z-index: 1;
        visibility: hidden;
        left: 0;
        bottom: 90%;
        background-color: #efefef;
        color: #333;
        padding: 14px 20px;
        font-size: 14px;
        line-height: 1.6;
        text-align: left;
        opacity: 0;
        transition: opacity 0.3s;
    }
    .tooltip-card:hover .tooltiptext-card {
        visibility: visible;
        opacity: 1;
        cursor: default;
    }
  </style>

  <body>
    <div class="outer-div">
      ${data.map(
        (d) => htl.html`<div class="inner-div">
          <span class="tooltip-card">
            <span class="tooltiptext-card">${d.tooltip}</span>
            <span class="value ${d.value != null && d.value < 0 ? "negative" : ""}">${
              d.value != null ? d.yFormat(d.value) : "---"
            }</span>
            <span class="label">${d.labelFull}</span>
          </span>
        </div>`,
      )}
    </div>
  </body>`;
};

resultTable = () => {
  const fmtUSD = formatUSD({ locale: language.locale });
  const selectedYear = projectYears;
  const enriched = (walkthroughEconomicIndicators?.enriched ?? []).filter(
    (d) => d.year <= selectedYear,
  );

  const tableHeaders =
    nbText.investmentReturns.exploreIndicators.tableHeaders;
  // nbText already contains the selected locale.
  const headerNames = [
    tableHeaders.year,
    tableHeaders.benefit,
    tableHeaders.cost,
    tableHeaders.cashflow,
    tableHeaders.discountedBenefitCum,
    tableHeaders.discountedCostCum,
    tableHeaders.discountedNpvCum,
    tableHeaders.discountedBcr,
    tableHeaders.irr,
    tableHeaders.mirr,
  ];

  return html`
    <style>
      .econ-table {
        font-family: sans-serif;
        border-collapse: collapse;
        font-size: 13.75px;
        margin-top: 1em;
        min-width: 100%;
      }
      .econ-table th, .econ-table td {
        border: 1px solid #ddd;
        padding: 6px 10px;
        text-align: right;
      }
      .econ-table th {
        background-color: #f4f4f4;
        white-space: normal;
        text-align: center;
      }
      .econ-table td.year-col {
        text-align: center;
        font-weight: bold;
      }
      .econ-table tr.final-row td {
        font-weight: bold;
        background-color: #f1f1f1;
      }
      .table-container {
        overflow-x: auto;
        display: block;
        padding-bottom: 4px;
      }
    </style>

    <div class="table-container">
      <table class="econ-table">
        <thead>
          <tr>
            ${headerNames.map((h) => html`<th title="${h}">${h}</th>`)}
          </tr>
        </thead>
        <tbody>
          ${enriched.map((d, i) => {
            const isFinal = i === enriched.length - 1;
            const npv_i =
              d.discounted_benefit_cum != null && d.discounted_cost_cum != null
                ? d.discounted_benefit_cum - d.discounted_cost_cum
                : null;

            return html`<tr class=${isFinal ? "final-row" : ""}>
              <td class="year-col">${d.year}</td>
              <td>${d.project_benefit != null ? fmtUSD(d.project_benefit) : "—"}</td>
              <td>${d.cost != null ? fmtUSD(d.cost) : "—"}</td>
              <td>${d.cashflow != null ? fmtUSD(d.cashflow) : "—"}</td>
              <td>${d.discounted_benefit_cum != null ? fmtUSD(d.discounted_benefit_cum) : "—"}</td>
              <td>${d.discounted_cost_cum != null ? fmtUSD(d.discounted_cost_cum) : "—"}</td>
              <td>${npv_i != null ? fmtUSD(npv_i) : "—"}</td>
              <td>${d.discounted_bcr != null ? d.discounted_bcr.toFixed(2) : "—"}</td>
              <td>${d.irr != null ? `${(d.irr).toFixed(2)}%` : "—"}</td>
              <td>${d.mirr != null ? `${(d.mirr).toFixed(2)}%` : "—"}</td>
            </tr>`;
          })}
        </tbody>
      </table>
    </div>
  `;
};

resultPlot = () => {
  const projectYearCutoff = walkthroughSelections.project_years;
  const selector = pickMetricWalkthrough;
  const plotData = walkthroughEconomicIndicators?.enriched ?? [];
  const uncertaintyYearly = uncertainty?.yearly ?? [];

  // Keep the x-axis consistent across selections.
  const fullYears = d3.range(0, projectYears + 1); // 0 to 8 inclusive
  const completePlotData = fullYears.map((y) => {
    const row = plotData.find((d) => d.year === y);
    return row ?? { year: y };
  });

  const bandData = (() => {
    const metricKey = selector.key;
    return fullYears
      .map((year) => {
        const row = uncertaintyYearly.find((d) => d.year === year);
        const low = row?.[metricKey]?.p10;
        const high = row?.[metricKey]?.p90;
        if (!Number.isFinite(low) || !Number.isFinite(high)) return null;
        return { year, low, high };
      })
      .filter((d) => d != null);
  })();

  const ruleYValue = selector.key === "bcr" ? 1 : 0;

  return Plot.plot({
    width,
    marginRight: 80,
    inset: 5,
    x: {
      label: nbText.investmentReturns.exploreIndicators.projectYear,
      ticks: fullYears,
      tickFormat: "d",
      labelAnchor: "center",
      labelArrow: "none",
    },
    y: {
      label: selector.label,
      tickFormat: selector.yFormat,
    },
    marks: [
      Plot.axisY({
        anchor: "right",
        label: selector.label,
        tickFormat: selector.yFormat,
        tickSize: 0,
        color: (d) => {
          return d >= 0 ? "black" : "#EC5A47";
        },
      }),
      Plot.ruleY([ruleYValue], {
        stroke: "#333",
        strokeDasharray: [3],
      }),

      Plot.areaY(bandData, {
        x: "year",
        y1: "low",
        y2: "high",
        fill: "#2c7fb8",
        fillOpacity: 0.16,
      }),

      Plot.line(completePlotData, {
        x: "year",
        y: selector.columnName,
        stroke: "#444",
        strokeOpacity: 0.7,
        strokeWidth: 2,
        tip: true,
      }),

      Plot.dot(completePlotData, {
        x: "year",
        y: selector.columnName,
        r: 3,
        fill: "#444",
        stroke: "#fff",
        strokeWidth: 0.5,
        tip: {
          format: {
            x: true,
            y: selector.yFormat,
          },
        },
      }),

      Plot.dot(
        completePlotData.filter((d) => d.year === projectYearCutoff),
        {
          x: "year",
          y: selector.columnName,
          r: 7,
          fill: "#fff",
          stroke: (d) => (d[selector.columnName] >= 0 ? "#333" : "#EC5A47"),
          strokeWidth: 2,
        },
      ),
    ],
  });
};

Data Analysis and Processing

admin0_names = {
  const isoSet = new Set(select_country);
  return countries.filter((d) => isoSet.has(d.iso3c)).map((d) => d.admin0_name);
}

CV Data

import {
  avlossCalc,
  avlossCalcUncertainty,
  calcMIRR,
  calcIRR,
  npvDiscreteCumulative,
  runSimulationFromCashflowRows,
} from "/notebooks/roi/roi_tools.js";

mutable cv_result = [];
mutable cv_cache_key = '';

calcCV = async () => {
  const cis_impact = options_econPerfWalkthrough.inputCisImpact.value;

  const cache_key = `${[...admin0_names].sort().join(',')}|${[...select_crop].sort().join(',')}|${cis_impact}`;

  if (cv_cache_key === cache_key) {
    return cv_result;
  }

  console.log('Running the cv analysis as inputs changed')
  const bind = createSqlBindings();
  const cv_data = await db.query(`
    SELECT *
    FROM cv
    WHERE crop IN (${bind.list(select_crop)})
    AND admin0_name IN (${bind.list(admin0_names)}) -- This needs the a0_name rather than iso3
  `, bind.params);

  const cv_monteCarlo = await Promise.all(
    cv_data.map(async ({ crop, admin0_name, cv }) => {
      const av = await avlossCalc(cv, cis_impact);
      const avloss = Math.abs(Number(av.toFixed?.(4) ?? av));
      return { admin0_name, crop, cv, cis_impact, avloss };
    }),
  );

  const cv_index = new Map();
  for (const { admin0_name, crop, avloss } of cv_monteCarlo) {
    cv_index.set(`${admin0_name}|${crop}`, avloss);
  }

  mutable cv_result = cv_index
  mutable cv_cache_key = cache_key
  return cv_index
}

Other ROI X Exposure Variables

// Recompute only for crop/country changes; retain admin-1 rows for local filtering.

exposure_data = {
  let crops = select_crop;
  let countries = select_country;
  const bind = createSqlBindings();
  let data = await db.query(
    `
    SELECT *
    FROM exposure
    WHERE crop IN (${bind.list(crops)})
    AND iso3 IN (${bind.list(countries)})
    -- POSSIBLY add admin1 name filter, but defaults to full country, so maybe bigger query is better.
  `,
    bind.params
  );
  return data;
}

crop_adoption = async () => {
  const adoption = options_econPerfWalkthrough.inputAdoption.value;
  const years = projectYears;
  const prod_impact = options_econPerfWalkthrough.inputProdImpact.value;
  const data = exposure_data;
  const result = [];

  for (const row of data) {
    const value = row.value || 0;
    let xPrev = 0;

    for (let i = 1; i <= years; i++) {
      let x;
      if (i === 1) {
        x = Math.round(value * adoption * 10) / 10;
      } else {
        x = Math.round((value - xPrev) * adoption * 10) / 10 + xPrev;
      }

      xPrev = x;

      result.push({
        admin0_name: row.admin0_name,
        admin1_name: row.admin1_name,
        iso3c: row.iso3,
        crop: row.crop,
        exposure: row.exposure,
        value: row.value,
        adoption: adoption,
        prod_impact: prod_impact,
        year_char: `y${i}`,
        year: i,
        result: x,
      });
    }
  }

  return result.map((row) => {
    const result_w_impact = Math.round(row.result * (1 + (row.prod_impact ?? 0)) * 10) / 10;
    const marginal_impact = Math.round((result_w_impact - row.result) * 10) / 10;
    return { ...row, result_w_impact, marginal_impact };
  });
}

// QA: A single region/crop matches the R reference exactly.

roiResults = async () => {
  const index = await calcCV();
  const data = await crop_adoption();

  const withImpact = data.map((row) => {
    const key = `${row.admin0_name}|${row.crop}`;
    const avloss = index.get(key) ?? 0; // default to 0 if missing

    const result_w_impact_cis = Math.round(row.result_w_impact * (1 + avloss) * 10) / 10;
    const marginal_cis = Math.round((result_w_impact_cis - row.result_w_impact) * 10) / 10;
    const marginal_impact_cis = (marginal_cis || 0) + (row.marginal_impact || 0);

    return {
      ...row,
      avloss,
      result_w_impact_cis,
      marginal_cis,
      marginal_impact_cis,
    };
  });

  return withImpact.map((d) => {
    const project_benefit =
      Math.round((d.marginal_impact_cis - d.marginal_impact_cis / bcr) * 10) / 10;
    const cis_impact = options_econPerfWalkthrough.inputCisImpact.value;
    return { ...d, bcr, cis_impact, project_benefit };
  });
}

// QA: Monte Carlo output stays within a few hundred dollars of the R reference.

ROI X inputs Calculations

Sum across admins and crops

We select all the data for admin regions and crops, and sum up to get the benefit across all parameter combos.

regionSet = new Set(select_region)

recipe_dataSummed = async () => {
  document.body.style.cursor = "wait";
  const roi_data = await roiResults();

  // Apply the selected-region filter after aggregation.
  const roi_data_filtered = roi_data.filter((d) => regionSet.has(`${d.iso3c}_${d.admin1_name}`));

  const aggregated = d3
    .flatGroup(
      roi_data_filtered,
      (d) => d.adoption,
      (d) => d.prod_impact,
      (d) => d.cis_impact,
      (d) => d.bcr,
      (d) => d.year
    )
    .map(([adoption, prod_impact, cis_impact, bcr, year, group]) => ({
      adoption,
      prod_impact,
      cis_impact,
      bcr,
      year,
      project_benefit: d3.sum(group, (d) => d.project_benefit),
    }));

  document.body.style.cursor = "default";
  return aggregated;
}

Define project payment schedule

Below we define the project cost schedule

• Cost is evenly distributed across years (
  • Ex. 1M over 5 years is 200K, 400K, 600K, 800K, 1M; the first year has no project benefit ($200K, 0 benefit)

recipe_paymentSchedule = Array.from({ length: projectYears }).map((_, i) => {
  return {
    year: i,
    cost: (1 / projectYears) * rangeProjectCost,
    cost_cum: ((i + 1) / projectYears) * rangeProjectCost,
  };
})

Add project scope to data

• Add a zero year at the start (the return rate is hardcoded to one year)
• Also if the project cost is zero, return an empty array

recipe_dataCashflow = {
  if (!rangeProjectCost || rangeProjectCost === 0) return [];

  const payByYear = new Map(recipe_paymentSchedule.map((d) => [d.year, d]));

  const data = await recipe_dataSummed();

  return d3
    .flatGroup(
      data,
      (d) => d.adoption,
      (d) => d.prod_impact,
      (d) => d.cis_impact,
      (d) => d.bcr
    )
    .flatMap(([adoption, prod_impact, cis_impact, bcr, rows]) => {
      const allRows = [
        ...rows,
        { adoption, prod_impact, cis_impact, bcr, year: 0, project_benefit: 0 },
      ].sort((a, b) => a.year - b.year);

      return allRows.map((r) => {
        const pay = payByYear.get(r.year) || {};
        const cost = pay.cost ?? 0;
        const cost_cum = pay.cost_cum ?? rangeProjectCost;
        return {
          ...r,
          cost,
          cost_cum,
          cashflow: (r.project_benefit ?? 0) - cost,
          discount_rate: discountRate,
        };
      });
    });
}

Format that into final indicators

walkthroughEconomicIndicators = {
  const selection = walkthroughSelections;

  const data = recipe_dataCashflow;

  const years = data.map((d) => d.year);
  const benefit = data.map((d) => d.project_benefit);
  const cost = data.map((d) => d.cost);
  const cashflow = benefit.map((b, i) => b - cost[i]);
  const discountRate = selection.discount_rate;

  const npv = npvDiscreteCumulative(cashflow, discountRate);
  const npv_benefit = npvDiscreteCumulative(benefit, discountRate);
  const npv_cost = npvDiscreteCumulative(cost, discountRate);
  const discounted_bcr = npv_benefit.map((b, i) => (npv_cost[i] === 0 ? null : b / npv_cost[i]));

  const proj_irr = calcIRR(cashflow);
  const proj_mirr = calcMIRR(cashflow, discountRate, discountRate);
  const proj_npv = npv.at(-1);
  const proj_bcr = discounted_bcr.at(-1);

  const enrichedData = years.map((year, i) => {
    const cashflowToDate = cashflow.slice(0, i + 1);
    return {
      year,
      project_benefit: benefit[i],
      cost: cost[i],
      cashflow: cashflow[i],
      discounted_benefit_cum: npv_benefit[i],
      discounted_cost_cum: npv_cost[i],
      discounted_bcr: discounted_bcr[i],
      irr: calcIRR(cashflowToDate) * 100,
      mirr: calcMIRR(cashflowToDate, discountRate, discountRate) * 100,
      npv: npv[i],
    };
  });

  return {
    summary: {
      proj_npv,
      proj_irr,
      proj_mirr,
      proj_bcr,
    },
    enriched: enrichedData,
  };
}

Calculate final values

At this point, following the recipe, we have the timeseries for the selected parameters, with financial values calculated. Specifically:

• adoption
• prod_impact
• cis_impact
• bcr
• discount_rate

Across:

• year

Data:

• project_benifit
• cost and cashflow
• Project IRR
• Project NPV
• Project BCR

Selections

walkthroughSelections = {
  return {
    countries: select_country,
    regions: select_region,
    crops: select_crop,
    project_years: projectYears,
    project_cost: rangeProjectCost,
    prod_impact: options_econPerfWalkthrough.inputProdImpact.value,
    adoption: options_econPerfWalkthrough.inputAdoption.value,
    cis_impact: options_econPerfWalkthrough.inputCisImpact.value,
    discount_rate: discountRate,
    bcr: bcr,
  };
}