update marginal model docs

[kgostic]

Description

This PR closes #512.

• Added @details and additional documentation to explain internal aggregation, and the weights option in the marginal model.

Reviewer notes:

1. I did my best to follow the set of variables needed for grouping based on the code, but please check that I got this right @seabbs!
2. Currently, this documentation only renders for ?as_epidist_marginal_model.epidist_linelist_data, whereas it would probably be more useful if it rendered for ?as_epidist_marginal_model. The docs for the latter are so sparse as to not really be useful, but that's all people will know to search for. I wasn't sure how to change this, or whether changing it would have unintended consequences. Please weigh in!
3. There wasn't a pre-built dataset that was obviously good to use in the example, so I wrote something hypothetical and put into @details instead of @examples. Hope that's ok.

Checklist

• My PR is based on a package issue and I have explicitly linked it.
• I have included the target issue or issues in the PR title in the for Issue(s) issue-numbers: PR title
• I have read the contribution guidelines.
• I have tested my changes locally.
• I have added or updated unit tests where necessary.
• I have updated the documentation if required.
• My code follows the established coding standards.
• I have added a news item linked to this PR.
• I have reviewed CI checks for this PR and addressed them as far as I am able.

[kgostic]

Keeping this as a draft, but I think I need some feedback before I can do anything else. As far as I can tell the CI issues are being resolved elsewhere and unrelated to the changes made here.

[seabbs]

Thanks for this @kgostic.

additional documentation to explain internal aggregation

This doc page should probably link out to the internal aggregation page and doc it once there (if/as missing) I think.

did my best to follow the set of variables needed for grouping based on the

I think the aggregate data class may help resolve these issues.

There wasn't a pre-built dataset that was obviously good to use in the example, so I wrote something hypothetical and put into https://github.com/details?rgh-link-date=2025-01-29T23%3A04%3A03Z instead of https://github.com/examples?rgh-link-date=2025-01-29T23%3A04%3A03Z. Hope that's ok.

I have been resolving this in #513 as I also couldnt make examples without one there. It probably makes sense to adopt that approach. I think there is also some context etc in that PR that might help here and so perhaps it is worth waiting on that and then refactoring/reviewing this.

Currently, this documentation only renders for ?as_epidist_marginal_model.epidist_linelist_data, whereas it would probably be more useful if it rendered for ?as_epidist_marginal_model. The docs for the latter are so sparse as to not really be useful, but that's all people will know to search for. I wasn't sure how to change this, or whether changing it would have unintended consequences. Please weigh in!

I think this should be a more general issue as it impacts all the s3 methods (there may in fact be one as its been on the to do list for a while). There are two ways to go with this 1. As you suggest put everything on the same doc page and 2. Use a linking system (as we do for model/data related functions at the moment so people can navigate. epinowcast uses the latter as it extends base s3 generics and scoringutils uses the former. For scoringutils that has been a problem as that central doc page became so full (due to many methods) it became hard to read and so over time we have been moving from 1. to 2.

[seabbs]

Touching base one this

[kgostic]

It sounds like you added some data for an example in #513 and that changing the docs so that the help files are visible is a separate issue?

I'm not sure how quickly I'll get to this but can try to update the example bit later this week. I think linking to the help docs is pretty important.

[seabbs]

changing the docs so that the help files are visible is a separate issue?

I added more information and links in that information between functions but I didn't change the approach to s3 documentation. As above I think that this is a separate issue really as from past experience there are a few things to consider and a few viable approaches.

Noted on the update.