SimTk/mdtraj — pull request #593 by mpharrigan (2014-09-15 23:59:00+00:00)
Title: [WIP] Atom selection language

The goal is to be able to get atom indices using a natural query string:
```
indices = traj.select("name O and water")
```

I've based my implemetation loosely on VMD. The idea is that queries should closely follow the API. Therefore, all keywords map to a property of Atom, Element, Residue, Chain, etc. Multiple keywords (aliases) can be mapped to the same property. We parse the input string and generate a valid python list comprehension:
```
[a.index for a in top.atoms if a.name == 'O' and a.residue.is_water]
```
Which is then exec'ed

For this pull request, I'm going to stick to static, topology-based selections (e.g. no "water within 10 of protein" *just* yet)

I've also included a sphinx extension that auto-generates a table of valid keywords, what property they map to, and aliases for the keywords.

If you want to play around with it, use the `topology.select()` and `topology.select_expression()` methods. I haven't exposed them on `Trajectory` objects yet.

TODO:
- [ ] Figure out what properties we want to expose. Feedback needed! @rmcgibbo @kyleabeauchamp @cxhernandez
- [ ] Figure out how to generate documentation for attributes that are not properties. e.g. residue.index, etc.
- [ ] Refactor `select_atom_indices`, `remove_solvent` to be consistent with my paradigm by exposing some new properties (e.g. `Residue.is_solvent`)
- [ ] General cleanup; add docstrings