search

OpenMS / pyopenms-docs

pyOpenMS readthedocs documentation, additional utilities, addons, scripts, and examples.
https://pyopenms.readthedocs.io
Other
43 stars 50 forks source link

fix many glossary terms #331

Closed jpfeuffer closed 1 year ago

jpfeuffer commented 1 year ago

@timosachsenberg @tjeerdijk we desperately need to agree on a scheme on how to label our glossary terms and document it.

Factors:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-glossary https://sublime-and-sphinx-guide.readthedocs.io/en/latest/glossary.html#link-a-term-to-its-a-glossary-entry

timosachsenberg commented 1 year ago

No strong feeling here. Anything that is consistent works for me.

jpfeuffer commented 1 year ago

Since there are no opinions: my decision is here: https://github.com/OpenMS/pyopenms-docs/pull/327#issuecomment-1413419909

Please adhere to it from now on.

matteopilz commented 1 year ago

Should we update the glossary here or also add the term references?

greengypsy commented 1 year ago

I have no problem with the proposed changes so long as the tooltips on the terms are working. If you merge this PR, I will go through the background and introduction and make sure that all the tooltips are displayed on hover.

matteopilz commented 1 year ago

I have started linking the terms to the glossary. Should we leave things like mass, peptide, atom, ion, etc. in the glossary? I'm not sure, if the documentation becomes too convoluted, if we start linking these terms as well.

jpfeuffer commented 1 year ago

I had the same feeling. I would probably explain them only once in the beginning. And tell users in the beginning to read the background if they are not familiar with MS terms.

Similar things for classes. Instead of adding glossary entries for classes, just link to them in the API docs.

matteopilz commented 1 year ago

Should we do the same about retention time, m/z, peak and feature? Things, that are not as obvious but still common in the docs?

jpfeuffer commented 1 year ago

I think I would vote for yes, keep in glossary.

tjeerdijk commented 1 year ago

I would side with Julianus, put retention time, m/z, peak and feature in the glossary but leave mass, peptide, atom, ion out. Also check what Christina did for the openms glossary.

On 7. Feb 2023, at 13:22, Julianus Pfeuffer @.**@.>> wrote:

I think I would vote for yes, keep in glossary.

— Reply to this email directly, view it on GitHubhttps://github.com/OpenMS/pyopenms-docs/pull/331#issuecomment-1420686750, or unsubscribehttps://github.com/notifications/unsubscribe-auth/AGKDZEEYQY77BZGQ6UTITN3WWI5ALANCNFSM6AAAAAAUIZMZKM. You are receiving this because you were mentioned.Message ID: @.***>

matteopilz commented 1 year ago

I have renamed the files to further match the topic headers. Most terms should now also have correct links. What specific terms should be in the glossary and what their definition should be is probably something we would need to discuss. However, I have also added a few new ones like metabolomics. I added the terms spectra and spectrum only after changing many occurrences of it to mass spectra or mass spectrum. I don't think it matters that much, but we can also change it back. Including the plural as additional term in the glossary is also something we should discuss.

jpfeuffer commented 1 year ago

By the way, sorry to say, but using term for every occurrence of peak and m/z actually looks a bit distracting instead of helpful.

matteopilz commented 1 year ago

It's probably best to explain them in an introduction, but leave them out of the glossary.

jpfeuffer commented 1 year ago

Also "m/z" is not the unit. This should be Thompson "Th" for many uses of "m/z"

timosachsenberg commented 1 year ago

No please don't use Th. Since 2013, the thomson is deprecated by IUPAC (Definitions of Terms Relating to Mass Spectrometry).[11][12] Since 2014, Rapid Communications in Mass Spectrometry regards the thomson as a "term that should be avoided in mass spectrometry publications".

timosachsenberg commented 1 year ago

According to current IUPAC recommendations, m/z is an abbreviation for a dimensionless quantity. Use of thompson unit is indeed currently discouraged.

matteopilz commented 1 year ago

@jpfeuffer, @tjeerdijk, is there something that needs to be changed? Julianus, I think I fixed the [M+H] issue, with a whitespace. I have removed the lower level terms, as discussed with Timo and because the text would be overloaded otherwise. The idea is now to provide that information in the introduction.

jpfeuffer commented 1 year ago

And please update against the master branch. We merged the CI fix.

jpfeuffer commented 1 year ago

Sorry you need to merge again. Requirements were fixed. Not sure if/how to set the version compatibility numbers. Might be a hassle to always update them.