Coordinates and topology doc rework #1827

richardjgowers · 2018-03-13T10:09:45Z

Fixes #1817 and some of #1175

See the issue for motivations.

This basically adds a layer to the docs of "how to load X files", focusing on how to create a Universe, rather than talking about how this is implemented. I replaced the two tables of supported formats with a single one, which then also has links to a page for each format. This should hopefully be enough for 90% of people. There's then links to implementation details (our current docs) for the remaining 10%.

GRO format is mostly finished so you can see the overall structure of how I want each format to look.

richardjgowers · 2018-03-13T10:10:25Z

package/MDAnalysis/coordinates/GRO.py

@@ -28,39 +28,6 @@
 `GRO format`_ which includes a conversion routine for the box.


-Writing GRO files


So some docs have been "promoted" to the "loading your stuff" level. Eg user friendly stuff like this

richardjgowers · 2018-03-13T10:11:22Z

package/doc/sphinx/source/documentation_pages/loading_files.rst

+
+
+
+------------------+-----------+----------+--------------+-----+


I originally did a table like this, but then adding the links to this would be a complete mess, so I'm migrating slowly to a csv table below, which isn't aesthetically nice but is much faster to edit

CSV is fine with me in rst.

I am not against the move to a CSV table as, yes, the RST table format is a pain to edit. Though, the CSV is difficult to read in the raw file so editing and catching errors may not be much easier. Because we will only rarely add new rows to the table, I raise a shy whisper in favor of the RST format that looks clearer in the source file.

orbeckst

I like your approach, I am pretty sure that it will be better for users.

orbeckst · 2018-03-14T18:31:01Z

package/doc/sphinx/source/documentation_pages/loading_files.rst

+
+
+
+------------------+-----------+----------+--------------+-----+


CSV is fine with me in rst.

orbeckst · 2018-03-14T18:32:29Z

package/doc/sphinx/source/documentation_pages/loading_files.rst

+------------------+-----------+----------+--------------+-----+
+
+
+.. _Supported formats:


We link to the coordinates and topology formats table in many places (including web site and wiki). We will need to update all of them...

orbeckst · 2018-03-14T18:34:31Z

package/doc/sphinx/source/documentation_pages/loading_files.rst

+A full list of valid values for these keywords are given in the below table.
+
+
+.. note:: It is possible to pass tarballed/zipped versions of files.  The


tarballs??? Since when?? anyopen deals with zip, gz, bz2 as far as I know (and possibly streams although that's very brittle and I wouldn't mention it except when discussing magic with NamedStream).

orbeckst · 2018-03-14T18:35:35Z

package/doc/sphinx/source/documentation_pages/loading_files/amber.rst

+
+.. _load_amber_trj:
+
+Loading TRJ files


I would talk about NCDF first – that's much better supported. See current docs (which I recently rewrote a little bit)

orbeckst · 2018-03-14T18:36:58Z

package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst

+are currently supported. The known working versions and the
+approximate Gromacs release numbers are listed in the table
+:ref:`TPR format versions <TPR-format-table>`.
+


I might keep the technical info in the original place and link to it from here.

orbeckst · 2018-03-14T18:38:02Z

package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst

+  (type 3), Fourier dihedrals (type 5), restricted dihedrals (type 10),
+  combined bending-torsion potentials (type 11), tabulated dihedral (type 8)
+* impropers: improper dihedrals (type 2), periodic improper dihedrals (type 4)
+


Can also read the molnum (?) attribute, that was something recent #1555

orbeckst · 2018-03-14T18:38:40Z

package/doc/sphinx/source/documentation_pages/loading_files/hoomd.rst

+Loading GSD files with MDAnalysis
+---------------------------------
+
+GSD files in MDA.


Limitations of the gsd package? #1829

richardjgowers · 2018-03-14T20:06:34Z

@orbeckst thanks for the review, I'll keep pushing ahead with this then

orbeckst

more comments

orbeckst · 2018-03-21T18:25:22Z

package/doc/sphinx/source/documentation_pages/loading_files.rst

+
+.. note:: If a file which also provides coordinates is used as a topology, no trajectory
+	  information is read from this file.  Ie the first frame will come from the trajectory
+	  unless the `all_coordinates` keyword is set to ``True``. 


Is all_coordinates new?

Maybe link to the Universe docs?

orbeckst · 2018-03-21T18:25:57Z

package/doc/sphinx/source/documentation_pages/loading_files.rst

+Single file Universes
+---------------------
+
+Occaisionally a file may contain both topology and trajectory information,


typo: Occasionally

orbeckst · 2018-03-21T18:28:23Z

package/doc/sphinx/source/documentation_pages/loading_files.rst

+
+   import MDAnalysis as mda
+
+   u = mda.Universe('topol.tpr', ['traj1.trr', 'traj2.trr'])


Add a SeeAlso for the ChainReader – I know that this is technical but it is useful to know where to look regarding the details of how trajectories are concatenated, especially with #1728 in the works.

orbeckst · 2018-03-21T18:29:45Z

package/doc/sphinx/source/documentation_pages/loading_files/amber.rst

+
+   The Amber charge is converted to electron charges as used in
+   MDAnalysis and other packages. To get back Amber charges, multiply
+   by 18.2223.


Perhaps point to MDAnalysis.units where we store the value (and should also have written down what all these units are).

orbeckst · 2018-03-21T18:32:14Z

package/doc/sphinx/source/documentation_pages/loading_files/charmm.rst

+.. _load_charmm:
+
+####################################
+Loading Charmm files with MDAnalysis


CHARMM is all caps.

orbeckst · 2018-03-21T18:33:07Z

package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst

+
+MDAnalysis is able to read most files used by Gromacs with the exception
+of the TNG format which is currently in development.
+


start with TPR (as the topology format)

orbeckst · 2018-03-21T18:34:20Z

package/doc/sphinx/source/documentation_pages/loading_files/lammps.rst

+.. _load_lammps:
+
+####################################
+Loading Lammps files with MDAnalysis


LAMMPS is all-caps

orbeckst · 2018-03-21T18:35:05Z

package/doc/sphinx/source/documentation_pages/loading_files/lammps.rst

+
+Loading DCD files
+-----------------
+


Need to say something about units and how to set them.

Tbh I don't really understand how units work. If there's existing docs I'll copy them over but I won't be able to write these myself

I'll have a look... need to remind myself.

added Amber and Gromacs stubs added pdbqt stub added hoomd docs stubs too enthusiastic with hoooomd name WIP of new loading files docs added link to GROParser in loading_gro docs added ibisco loading stub added tinker stub added lammps load stubs fixed up docs table added pdb load stubs added charmm load doc stubs more load doc stubs finished stubs for load docs wrote docs for loading ibisco/yasp updated TOP loading docs finished Amber loading docs rearranged gromacs docs typos for docs reworked PQR docs

- fixed mistyped DUECREDIT_ENABLE environment variable - put note to "please cite us" at the top

coveralls · 2018-06-12T21:36:22Z

Coverage increased (+0.1%) to 89.892% when pulling 2a36ddd on issue-1817-docs into 70b9e9f on develop.

Fix errors that are preventing the build.

orbeckst · 2018-07-02T04:29:39Z

package/doc/sphinx/source/documentation_pages/loading_files.rst

+
+MDAnalysis aims to read any and all molecular simulation data,
+from whatever files you provide to it.
+This is done via the `Universe` object,


Are single backtics allowed here? Does napoleon generate links to Universe? Otherwise I suggest using

:class:`~MDAnalysis.groups.universe.Universe`

orbeckst · 2018-07-02T04:33:52Z

package/doc/sphinx/source/documentation_pages/loading_files/gromacs.rst

+
+TRR and XTC files
+-----------------
+


Note to myself: also mention the special continuous ChainReader magic in #1728 once available.

orbeckst · 2020-01-18T23:10:25Z

@richardjgowers do we still want to work on this PR, now with @lilyminium 's work? Otherwise we can close it.

richardjgowers · 2020-02-25T09:29:42Z

I think this is done with the new user guide

richardjgowers commented Mar 13, 2018

View reviewed changes

orbeckst reviewed Mar 14, 2018

View reviewed changes

orbeckst added Component-Docs Work in progress labels Mar 14, 2018

orbeckst mentioned this pull request Mar 19, 2018

add reader keywords to table in docs #360

Open

orbeckst reviewed Mar 21, 2018

View reviewed changes

richardjgowers force-pushed the issue-1817-docs branch 3 times, most recently from ddb6e74 to 58a559a Compare April 5, 2018 19:26

richardjgowers and others added 6 commits June 12, 2018 16:10

wrote loading autodock docs

318daf1

wrote loading DMS docs

ba6ddf0

updated DMS loading docs

481be08

wrote loading xyz docs

16a8919

minor fixes in References page

8fe1f70

- fixed mistyped DUECREDIT_ENABLE environment variable - put note to "please cite us" at the top

richardjgowers force-pushed the issue-1817-docs branch from 7d1e176 to 8fe1f70 Compare June 12, 2018 21:10

richardjgowers and others added 6 commits June 25, 2018 13:31

tinker docs

680e7d6

psf docs

a2ec239

dcd docs

4d29bab

CRD docs

7561007

more on Gromacs files and small updates

692c981

Minor syntax fices inthe doc

2a36ddd

Fix errors that are preventing the build.

orbeckst reviewed Jul 2, 2018

View reviewed changes

This was referenced Jul 5, 2018

release 0.19.0 #1971

Closed

frame offset files for all Readers to universaly support random access #314

Closed

Proof of concept trajectory class iterators #1934

Merged

richardjgowers closed this Feb 25, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Coordinates and topology doc rework #1827

Coordinates and topology doc rework #1827

richardjgowers commented Mar 13, 2018

richardjgowers Mar 13, 2018

richardjgowers Mar 13, 2018

orbeckst Mar 14, 2018

jbarnoud Mar 19, 2018

orbeckst left a comment

orbeckst Mar 14, 2018

orbeckst Mar 14, 2018

orbeckst Mar 14, 2018

orbeckst Mar 14, 2018

orbeckst Mar 14, 2018

orbeckst Mar 14, 2018

orbeckst Mar 14, 2018

richardjgowers commented Mar 14, 2018

orbeckst left a comment

orbeckst Mar 21, 2018

orbeckst Mar 21, 2018

orbeckst Mar 21, 2018

orbeckst Mar 21, 2018

orbeckst Mar 21, 2018

orbeckst Jun 26, 2018

orbeckst Mar 21, 2018

orbeckst Mar 21, 2018

orbeckst Mar 21, 2018

orbeckst Mar 21, 2018

richardjgowers Jun 25, 2018

orbeckst Jun 26, 2018

coveralls commented Jun 12, 2018 •

edited

Loading

orbeckst Jul 2, 2018

orbeckst Jul 2, 2018

orbeckst commented Jan 18, 2020

richardjgowers commented Feb 25, 2020

		@@ -28,39 +28,6 @@
		`GRO format`_ which includes a conversion routine for the box.


		Writing GRO files




		+------------------+-----------+----------+--------------+-----+

		+------------------+-----------+----------+--------------+-----+


		.. _Supported formats:

		A full list of valid values for these keywords are given in the below table.


		.. note:: It is possible to pass tarballed/zipped versions of files. The


		import MDAnalysis as mda

		u = mda.Universe('topol.tpr', ['traj1.trr', 'traj2.trr'])


		MDAnalysis is able to read most files used by Gromacs with the exception
		of the TNG format which is currently in development.

Coordinates and topology doc rework #1827

Coordinates and topology doc rework #1827

Conversation

richardjgowers commented Mar 13, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

orbeckst left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

richardjgowers commented Mar 14, 2018

orbeckst left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Jun 12, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

orbeckst commented Jan 18, 2020

richardjgowers commented Feb 25, 2020

coveralls commented Jun 12, 2018 •

edited

Loading