updated CHEMFILES docs

[orbeckst]

Changes made in this Pull Request:

• add section on using chemfiles for reading and writing
• fixed broken link to chemfiles formats

PR Checklist

• Tests?
• Docs?
• CHANGELOG updated?
• Issue raised/referenced?

[pep8speaks]

Hello @orbeckst! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

• In the file package/MDAnalysis/coordinates/__init__.py:

Line 263:80: E501 line too long (95 > 79 characters)
Line 264:80: E501 line too long (95 > 79 characters)
Line 265:80: E501 line too long (95 > 79 characters)
Line 266:96: W291 trailing whitespace
Line 276:80: E501 line too long (89 > 79 characters)

• In the file package/MDAnalysis/coordinates/chemfiles.py:

Line 23:80: E501 line too long (81 > 79 characters)
Line 26:80: E501 line too long (83 > 79 characters)
Line 26:84: W291 trailing whitespace
Line 27:80: E501 line too long (86 > 79 characters)
Line 28:80: E501 line too long (84 > 79 characters)
Line 28:85: W291 trailing whitespace
Line 32:80: E501 line too long (89 > 79 characters)
Line 33:80: E501 line too long (91 > 79 characters)
Line 35:80: E501 line too long (86 > 79 characters)
Line 40:80: E501 line too long (85 > 79 characters)
Line 40:86: W291 trailing whitespace
Line 47:80: E501 line too long (136 > 79 characters)
Line 49:80: E501 line too long (89 > 79 characters)
Line 52:80: E501 line too long (83 > 79 characters)
Line 115:52: W291 trailing whitespace

Comment last updated at 2021-02-22 07:20:56 UTC

[orbeckst]

@Luthaf , perhaps you could have a quick look, too — any comments welcome.

[codecov]

Codecov Report

Merging #3128 (afe5bd4) into develop (f542aa4) will decrease coverage by 0.45%.
The diff coverage is n/a.

@@             Coverage Diff             @@
##           develop    #3128      +/-   ##
===========================================
- Coverage    93.12%   92.67%   -0.46%     
===========================================
  Files          171      171              
  Lines        22706    22706              
  Branches      3209     3209              
===========================================
- Hits         21146    21043     -103     
- Misses        1503     1615     +112     
+ Partials        57       48       -9     

Impacted Files	Coverage Δ
package/MDAnalysis/coordinates/__init__.py	100.00% <ø> (ø)
package/MDAnalysis/coordinates/chemfiles.py	31.81% <ø> (-58.53%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f542aa4...afe5bd4. Read the comment docs.

[Luthaf]

This looks good to me!

[orbeckst]

@Luthaf do you know why we restricted chemfiles to 0.9 ≤ v < 0.10 in MDAnalysis?

[Luthaf]

There were big API changes between 0.8 and 0.9, and 0.10 was far from done when I wrote this code so I did not know if there were going to be more API changes, hence the rather conservative compatibility bounds =). Now I think compatibility can be updated to any 0.9.x or 0.10.x version.

[orbeckst]

Thanks for the explanation. Would you mind raising an issue for lifting the upper bound? I don’t want to do this in docs-only PR because there might have to be considerations regarding testing with chemfiles 0.9 or 0.10 or at least a quick on/off test. Thanks!

…

On Feb 19, 2021, at 1:45 PM, Guillaume Fraux ***@***.***> wrote: There were big API changes between 0.8 and 0.9, and 0.10 was far from done when I wrote this code so I did not know if there were going to be more API changes, hence the rather conservative compatibility bounds =). Now I think compatibility can be updated to any 0.9.x or 0.10.x version.

[lilyminium]

LGTM, thank you @orbeckst!

[orbeckst]

Italicization to provide a sort-of inline heading of what the example is about. Did it give the wrong impression? Should we use a different example?

…

In package/MDAnalysis/coordinates/chemfiles.py: > +-------------------------- + +When reading, set the ``format="CHEMFILES"`` keyword argument and I/O is delegated to +`chemfiles`_. For example:: + + >>> import MDAnalysis as mda + >>> from MDAnalysis.tests import datafiles as data + >>> u = mda.Universe(data.TPR, data.TRR, format="CHEMFILES") + >>> print(u.trajectory) + <ChemfilesReader ~/anaconda3/envs/mda3/lib/python3.8/site-packages/MDAnalysisTests/data/adk_oplsaa.trr with 10 frames of 47681 atoms> + +You can then use the :class:`~MDAnalysis.core.universe.Universe` as usual while chemfiles +is handling the I/O transparently in the background. + +`chemfiles`_ can also *write* a number of formats for which there are no Writers in +MDAnalysis. For example, to *write a mol2 file*:: Just a small thing, why is "write a mol2 file" italicised? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[lilyminium]

I suppose I read the italicisation as emphasising that this particular example is for writing a mol2 file only, except that no other examples have been hitherto given. It's a small style thing but I personally wouldn't emphasise that, I suppose. Opinions from everyone else are welcome!

[orbeckst]

If anyone wants to merge it please just "squash and merge" everything into one commit and edit the commit message appropriately.

[IAlibay]

Just re-running CI here (checking for a certain failure we're seeing somewhere else), if it returns green I'll squash-merge.