Add weekly_to_daily functionality, move time handling functions to their own module

[dylanhmorris]

Summary

• Adds weekly-to-daily value broadcasting functions + documentation and tests
• Moves timeseries handling to its own module
• Tweaks how input/output data first day of week handling (see breaking changes)

Breaking changes

This will introduce two breaking changes:
-from pyrenew.convolve import daily_to_weekly will need to become from pyrenew.time import daily_to_weekly.

• daily_to_weekly now defaults input_data_first_dow to the specified week_start_dow rather than to 0 (Monday) if input_data_first_dow is not specified. I think this is less surprising. The alternative would be to force the user always to specify input_data_first_dow.
  We could go through a deprecation cycle but I think Pyrenew is a bit young for that. @damonbayer / @sbidari lmk if you disagree.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.67%. Comparing base (5c29559) to head (7a85518).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #483      +/-   ##
==========================================
+ Coverage   96.61%   96.67%   +0.05%     
==========================================
  Files          41       42       +1     
  Lines         976      993      +17     
==========================================
+ Hits          943      960      +17     
  Misses         33       33              

Flag	Coverage Δ
unittests	96.67% <100.00%> (+0.05%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[github-actions]

Thank you for your contribution @damonbayer 🚀! Your github-pages is ready for download 👉 here 👈!
_{(The artifact expires on 2025-03-07T23:29:53Z. You can re-generate it by re-running the workflow here.)}

[sbidari]

Why isn't the weekly_values adjusted before repeating to create daily values in weekly_to_daily?

[dylanhmorris]

Why isn't the weekly_values adjusted before repeating to create daily values in weekly_to_daily?

For weekly_to_daily, all weekly values have to be assumed complete. So the key thing is to ensure that any partial starting week is only partially tiled, which the final [offset: ] operation accomplishes. If the user wishes to trim days off the ending week, they must do so manually. I suppose we could add an output_data_last_dow, but I'm not sure whether or not it would make the API clearer. Thoughts?

[sbidari]

The implementation looks okay to me.
However, I am missing the use case of this weekly_to_daily function. Why are the weekly values converted to daily by simply repeating instead of for example, diving by number of days in a week?

[dylanhmorris]

The implementation looks okay to me. However, I am missing the use case of this weekly_to_daily function. Why are the weekly values converted to daily by simply repeating instead of for example, diving by number of days in a week?

weekly $\mathcal{R}(t)$, for one. This PR is in part motivated by CDCgov/pyrenew-hew#344

[sbidari]

Thanks @dylanhmorris for clarification, LGTM!

[damonbayer]

Suggested change

	weekly_values = jnp.convolve(daily_values, jnp.ones(7), mode="valid")[::7]
	trimmed = daily_values[:len(daily_values) // 7 * 7]
	weekly_values = trimmed.reshape(-1, 7).sum(axis=1)

Seems to be about 5x faster

[dylanhmorris]

Nice, thanks! As written this function only accepts 1D inputs and will error with a greater than 1D input (because jnp.convolve does). The new version also assumes 1D but doesn't verify. We can verify 1D input but even better would be to generalize.

[damonbayer]

Suggested change

	weekly_values = jnp.convolve(daily_values, jnp.ones(7), mode="valid")[::7]
	n_weeks = daily_values.shape[0] // 7
	trimmed = daily_values[:n_weeks * 7]
	weekly_values = trimmed.reshape(n_weeks, 7, *daily_values.shape[1:]).sum(axis=1)

This works, assuming the 0th dimension is "time." It retains the speed benefit, as before.

[dylanhmorris]

Thanks! Would you be up for contributing an edit to the tests to check the multi-dim (1st dim time) case?

[damonbayer]

@dylanhmorris I pushed a test directly to this branch 7a85518 (#483)