Documentation

[mariaubiali]

Outstanding to-do-list

Done

• Added a link to the docs in the wiki and substitute obsolete wiki pages with new pages on the official documentation @mariaubiali
• Add list of Git repos to GitHub instructions @voisey
• Add list of rules for the mailing lists to the doc pages @mariaubiali
• Add page on documentation on the documentation @siranipour
• Split up documentation on theory cov. matrix in different pages @RosalynLP
• Finalise page on how to generate APPLgrids @enocera
  Add missing tutorial pages:
• how to compare PDF sets @voisey @siranipour
• how to get a list of available fits @voisey
• how to generate a report @voisey @siranipour
• how to run a fit @JesusUrtasun
• how to make code reviews @Zaharid
• n3fit
• how code testing works in python @Zaharid
• Add a list of theories and theory specs @voisey
• Postfit docs that include the selection criteria, how to change them, where they're recorded @voisey
• validphys --help @RosalynLP
• Sort out structure of docs - add intros for sections explaining what's in there @RosalynLP @voisey Restructure docs #1121 Restructuring the documentation #1122
• Move section on filter to a independent section outside of vp-guide @siranipour (decided not to do this)
• how to add new plotting functionalities in VP @RosalynLP
• how to include theory covariance matrix in a fit @RosalynLP
• How to plot PDFs @RosalynLP
• namespaces @RosalynLP
• PLOTTING files @siranipour
• Positivity & integrability implementation in n3fit @tgiani
• Add links to validphys report tutorial @voisey
• Fix search bar Docs search bar doesn't work #1125 @RosalynLP
• reportengine @Zaharid
• The reportengine execution model @Zaharid
• [ ] libnnpdf (we want a light introduction) @wilsonmr
• reportengine reports @Zaharid
• General introduction to the code/code layout

To do

• SWIG wrappers @Zaharid
• Default settings for datasets (cfactors, *_SF datasets, etc.) @enocera
• Paramfits module (see Document the paramfits module #266) @Zaharid

[enocera]

It seems to me that the item "Finalise page on how to generate APPLgrids" has already been addressed in #633 .

[mariaubiali]

Thank you @enocera
At the moment the page is not yet online, right?
https://docs.nnpdf.science/tutorials/APPLgrids.html

[Zaharid]

Should be fixed now. I think nothing was uploading because the tests failed.

[mariaubiali]

@voisey I noticed that on the github-gitlab page of the documentation there are no instructions on how to clone the repositories, namely those on slide 4 of the slides that Stefano C added to the wiki. Is there a reason for that? Or should we add them?

[voisey]

@mariaubiali It seems that we only have the ones required to run a fit, which are under point 3 here https://docs.nnpdf.science/get-started/installation-source.html. If so I think we should add the others somewhere

[mariaubiali]

@voisey I think it would make sense to add the full list on the github-gitlab page that you wrote. Are you OK taking care of this?

[voisey]

@mariaubiali Yes, sure, no problem at all

[Zaharid]

I have added a couple of items that came in in the last code meeting and have no proper documentation.

[mariaubiali]

I have added the mailing list rules on the access.md page and made a commit.

[Zaharid]

@enocera the bullet point regarding

" Default settings for datasets (cfactors, *_SF datasets, etc.) @enocera @scarrazza" which was #495.

seems particularly pressing given that we have several bugfixes which are currently implemented by renaming datasets (happier times will feature #494). Note that this also links to #675 .

[alecandido]

I agree with the second one: the evolution it's not involved in the NNPDF code, it has been always provided by an external source, so you should just mention the one you are using and delegate to the documentation of that one.

APFEL has a proper paper paper and some PortableDocumentFormat in its doc/ folder, since you are using APFEL this is the documentation you should refer to. The moment eko and yadism will replace it they will come with their own docs.

[siranipour]

I can take care of the ones assigned to me modulo the swig wrappers thing, tbh don't know the first thing about them

[RosalynLP]

I can take care of the ones assigned to me modulo the swig wrappers thing, tbh don't know the first thing about them

@siranipour thanks, yeah sorry about assigning you the swig wrappers, Cameron and I had no idea so just had a guess at who might know.

We can discuss at the code call who to assign the swig wrappers to unless anyone wants to volunteer/swap one of their existing tasks?

[RosalynLP]

For "namespaces" does anyone know what kind of thing the aim was to write? This was on the list so I assigned it to myself but I don't know who put it on the list or what they had in mind. @Zaharid ?

[Zaharid]

I guess something like https://data.nnpdf.science/validphys-docs/guide.html#reportengine-namespaces-specifications

[voisey]

Regarding the item that's assigned to me, which is "How to choose the training fraction for a new dataset. Define some threshold for N_dat above which threshold is 0.5?", I have a couple of questions.

@wilsonmr Am I right in thinking that the default training fractions are still a WIP? Or has the 0.75 been settled on?

Also, in these studies has a rule been set for which datasets have the training fraction as 1? I.e. can something be written in the docs that says something like "If the set has X or fewer post-cut data points with the default cuts, it should be assigned a training fraction of 1, otherwise it should be 0.75"?

[wilsonmr]

I would say the training fraction has been settled on.

I think this rule:

"If the set has X or fewer post-cut data points with the default cuts, it should be assigned a training fraction of 1, otherwise it should be 0.75"

exists, but you might have to work out what that magic number is. In practice I only modified the training fraction for datasets which were 0.5. I honestly think that this rule makes absolutely no difference but whatever

[RosalynLP]

@Zaharid there's quite a bit in the vp guide here https://data.nnpdf.science/validphys-docs/guide.html which isn't in the NNPDF docs... would it not be a good idea to just transfer this over rather than write new docs for e.g. namespaces?

[Zaharid]

@RosalynLP yes, see #656 (comment)

[RosalynLP]

@RosalynLP yes, see #656 (comment)

OK good thank you we can make a separate PR for it

[RosalynLP]

@RosalynLP yes, see #656 (comment)

OK good thank you we can make a separate PR for it

@Zaharid where is the source code for the existing guide?

[Zaharid]

@RosalynLP https://github.com/NNPDF/nnpdf/tree/master/doc/validphys2

[voisey]

I've ticked off "namespaces" thanks to #1159 and "Positivity & integrability implementation in n3fit" thanks to #1134, but please say if this was wrong @RosalynLP @tgiani. There are only a few items left until we can close this PR (woohoo!) but they are only assigned to three people, so I would suggest to @Zaharid @wilsonmr and @enocera that they say if they would like any help with these, and then we can try to split the work up

[wilsonmr]

Sorry, I've been naughty and not done my task yet, I will do it before the next code meeting.

[RosalynLP]

What's left here? Is it still all of the unticked tasks?

[Zaharid]

I am going to go ahead and tick the items related to reportengine. They are well explained enough in the improved version of the guide. This is not to say it shouldn't have its own documentation, but...

As for "general introduction to the code" I think one could take Sec 2 of the code paper as a template. @RoyStegeman would you like to have a go?

For economic reasons I think one could adopt the view that libnnpdf is "legacy" and thus does not have to be documented beyond the introduction above. Thanks to the good progress by @siranipour this will be true sooner rather than later. I want to write a page on the SWIG wrappers somewhere but honestly that's of low priority.

@enocera I feel very sorry to even mention this but I would say that the "document the defaults" tasks is something important that we want to have.

[RoyStegeman]

Sure, where in the docs are you thinking of putting this? As a link under `getting started' seems like a reasonable place.

Slightly off-topic, I think we should also update the READMEmd.

Also, is #1303 almost ready to be merged?

[Zaharid]

@RoyStegeman Will merge #1303 today.

[scarlehoff]

The landing page "docs.nnpdf.science" feels a bit dry. Maybe we should also add the logo (even if it is already in the left column)?

Also, what about giving links with people's university or personal pages (this is more of a pain because of the logistics of 1) asking people for a link 2) changing the link when people change university)

[mariaubiali]

Hi @scarlehoff what about adding the group picture that we have on the NNPDF website (given that the logo is already on the left column)? Concerning the link, I agree! We can add the links that we find in Google and let people add theirs. I can take care of this!

[scarlehoff]

Hi @scarlehoff what about adding the group picture that we have on the NNPDF website

Which one? But yes, we could put it at the bottom under the names (so that the documentation is the first thing people see).

For the links, we can also create an issue with a list and ask people if they are happy with the link / affiliation. @scarrazza Given that we need to update the zenodo-citation list of authors maybe it makes sense to do both in one go (the list of people in the documentation should be equal -or greater if we add people who left- to the list of people in zenodo)

[scarlehoff]

Closed as complete now although I still think the https://docs.nnpdf.science is a bit dry and maybe we should go back to the idea of putting a picture below the name.s..

[alecandido]

Closed as complete now although I still think the docs.nnpdf.science is a bit dry and maybe we should go back to the idea of putting a picture below the name.s..

We should put profile pictures for every tutorial and thumbs up/down buttons on pages :P