SWD v4 dataReloadRatio is the opposite of the Data Cache Ratio

[thibaudcolas]

Describe the bug

The SWD v4 model has a Data Cache Ratio parameter, which is documented as:

The portion of data that is loaded from cache for returning visitors.

The perVisitTrace of the SWDv4 implementation supports a dataReloadRatio option, documented as:

The percentage of data that is downloaded by return visitors.

Both are figures between 0 and 1 but they appear to be opposites? With a "cache ratio" of 100% corresponding to a "reload ratio" of 0%? This seems overly confusing, and possibly unintended.

---

The actual CO2.js implementation is per the SWD v4 model’s formula, but isn’t logical with how this dataReloadRatio is documented.

To Reproduce

Compare the results of those two calculations:

const estimate = swdmV4.perVisitTrace(100_000, true, {
  firstVisitPercentage: 0.8,
  returnVisitPercentage: 0.2,
-  dataReloadRatio: 0,
+  dataReloadRatio: 1,
});

A "reload ratio" of 0 (0% data downloaded by return visitors) is calculated as higher emissions at 0.012 than a "reload ratio" of 1 (100% data downloaded by return visitors) at 0.009.

Expected behavior

The parameter should be renamed and documentation updated so it matches the SWD v4 model’s "cache" ratio, where 100% means "all data cached, no data loaded"

Environment (please complete the following information):

N/A

Additional context (if applicable)

N/A

[fershad]

@thibaudcolas thanks for this. I'm leaving a note here so that you know we've seen the issue. We've got some high priority work at GWF that needs to be wrapped up in the coming week so getting around to this issue might be a bit delayed.

[fershad]

@thibaudcolas this naming is a relic from the v3 implementation, but you are right in that the way its used in SWDMv4 within CO2.js would most likely cause confusion.

To resolve this without breaking things for people who are already using CO2.js in their projects, we can:

1. Add the dataCacheRatio option & use that as it is specified in the SWDM docs.
2. Where someone provides dataReloadRatio instead, we will set dataCacheRatio === dataReloadRatio and show a console warning advising them to use dataCacheRatio instead. This will allow us to deprecate the dataReloadRatio option in a future release.
3. Update the docs to reflect the dataCacheRatio as the right option to use.

[thibaudcolas]

Sounds great!