Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SWD v4 dataReloadRatio is the opposite of the Data Cache Ratio #248

Open
thibaudcolas opened this issue Jan 21, 2025 · 3 comments
Open

SWD v4 dataReloadRatio is the opposite of the Data Cache Ratio #248

thibaudcolas opened this issue Jan 21, 2025 · 3 comments

Comments

@thibaudcolas
Copy link
Contributor

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

@thibaudcolas thibaudcolas changed the title SWD v4 dataReloadRatio implementation is the opposite of the model’s Data Cache Ratio SWD v4 dataReloadRatio is the opposite of the model’s Data Cache Ratio Jan 21, 2025
@thibaudcolas thibaudcolas changed the title SWD v4 dataReloadRatio is the opposite of the model’s Data Cache Ratio SWD v4 dataReloadRatio is the opposite of the Data Cache Ratio Jan 21, 2025
@fershad
Copy link
Contributor

fershad commented Jan 22, 2025

@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
Copy link
Contributor

fershad commented Feb 10, 2025

@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.

@fershad fershad self-assigned this Feb 10, 2025
@thibaudcolas
Copy link
Contributor Author

Sounds great!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants