Reader API cleanup

[richardjgowers]

So I'm going through the Reader API (for Issue #306) and it probably needs a spring clean.

"Required" attributes that I'm going to ditch:

• fixed (DCD specific, move it into DCD only)
• skip (step size of iterating through the trajectory? remove)
• skip_timestep (number of steps between saving the trajectory, move to optional)
• delta (md integrator timestep, move to optional)
• periodic (if the trajectory has box information, remove)
• dt (time between frames, moved to Timestep)

[orbeckst]

Can we create a dict metadata or data or whatever (similar to Timestep.data) that keeps all the specific information that one might want to know in specific cases but that is not essential for the API? Basically anything labelled "optional" would go there.

The two attributes that I have some more thoughts on are

• periodic
  • make optional
  • but keep around because some readers provide this information
• dt
  • Introduce a new optional trajectory keyword 'dt' to Timestep #307 and Timestep API interface discussion (was: should Timestep.time start with 0.0?) #252 say that Timestep gets the dt keyword but we still need a way to pass it through, and the only way that normally happens is when the Reader creates its own Timestep. Thus the Reader should accept an optional dt keyword so that I can tell the Reader the time step (e.g, to fix a trajectory)
  • Alternatively, we might need to compute dt from the trajectory header information (e.g. for DCD). That should be handled by the reader.
  • If the trajectory keeps per-frame timestamps then let's use those and in this case we could leave dt = None.

So basically, I think dt is pretty fundamental at the Reader level, too, and I think it makes sense to keep it as Reader.dt.

Opinions?

[richardjgowers]

Hmm ok, periodic gets a stay of execution.

And yeah, dt is going to be a bit more involved to get everything correct, but not impossible.

[orbeckst]

On 16 Jul, 2015, at 11:02, Richard Gowers wrote:

Hmm ok, periodic gets a stay of execution.

We don't really use it anywhere else, I think (maybe to decide what to do with unitcell), so just dropping it into Reader.data should be sufficient.

[dotsdl]

The list of attributes for Readers given here needs to be updated, right?

[dotsdl]

Scratch that...had a look at the actual doc source. Hadn't occurred to me that we might not have regenerated the development docs yet.

[orbeckst]

Ah... ok, I just regenerated the docs.

[richardjgowers]

Oops, forgot to regen docs. So if I've read #183 right, the reason we can't have online docs is the C extensions. Would it be possible to edit setup to build a (non working) version of MDA without C extensions?
ie

python setup.py install --for-docs

Then as long as we don't have docs inside C modules (or Cython I imagine), we can create enough for the docs to be built?

[orbeckst]

The way yo go about this is to make travis-ci build the docs (and possibly even deploy). Rob McGibbon wrote about this somewhere and I think it's a great idea.

Oliver

On 22 Jul, 2015, at 02:14, Richard Gowers wrote:

Oops, forgot to regen docs. So if I've read #183 right, the reason we can't have online docs is the C extensions. Would it be possible to edit setup to build a (non working) version of MDA without C extensions?

ie

python setup.py install --for-docs
Then as long as we don't have docs inside C modules (or Cython I imagine), we can create enough for the docs to be built?

�
Reply to this email directly or view it on GitHub.

Oliver Beckstein * orbeckst@gmx.net
skype: orbeckst * orbeckst@gmail.com

[orbeckst]

@richardjgowers : Update to my last comment: @rmcgibbo described how to deploy docs and binaries with travis-ci in mdtraj. I thought that was very neat.
I don't know if we can make this work with the current workflow where devdocs are part of the git repo but it's worth thinking about.

[richardjgowers]

Yeah, I was looking through the travis.yml on mdtraj, lots of cool hooks in their after_success.

I think it'd hinge on whether we could push to gh-pages as travis.. and my initial guess would be no because of keys/permissions etc, but it looks like there's such a thing as secure travis variables, which would then seem to make it possible.

[rmcgibbo]

It looks like other people have written about pushing to gh-pages from travis (e.g. here and here).

The one tricky issue that we had with the docs that's worth noting is that the implementation of the ability to move between different versions of the docs (e.g. the dropdown "Versions" menu in the lower left corner of mdtraj.org) is tricky. Since the site is static, you need the fixed old versions of the docs to "become aware" of new versions to properly populate the dropdown menu, so it needs to all be done dynamically in js. And if you realize that there's a bug in the js in a ~6 month old docs build of a prior release, it's kind of hard to fix.

[richardjgowers]

Cool thanks