Slicing and selection

[lilyminium]

Story: As a user, I want to get hydrogens bonded to oxygens that are not water molecules, where the hydrogen within 4 A of a protein domain but not within a certain cylindrical zone.

Story: As a user, I want to get atoms from my Universe by index, so that I can compute the angle defined by the ordered atoms. [Notebook example]

Acceptance criteria:

• I understand the available slicing and selection methods
• I understand which keywords are available and how to combine them with boolean logic
• I understand when atoms are sorted and when they are ordered by my selection
• I know how to make an ordered selection
• I understand how to join or separate AtomGroups
• I understand when atom duplicates are kept (concatenate/subtract) and when they are not (union/difference)
• I am aware of other set methods

[orbeckst]

Selections are really important.

It's a bit confusing that there are different ways by which to accomplish the same thing.

• select_atoms() (but only what's in the selection language)
• boolean indexing ag[ag.name == "CA"] (works for anything with a TopologyAttribute but not for spatial selections)
• bonded things via bond methods
• set operations on AtomGroups
• raw (fancy) indexing of AtomGroups

We need to prioritize what we want to teach users first and then give more options. Most nee users will likely start with the selection language.

Any opinions?

[orbeckst]

Perhaps it is important to get the idea across that the goal is always to create a new AtomGroup.

As an advanced topic: This AtomGroup can be static (AtomGroup) or dynamic (UpdatingAtomGroup).

[lilyminium]

I agree that most MD users probably are familiar with existing atom selection language and will use that first. Anyone with a passing introduction to Python will have also encountered numpy/pandas, so normal/fancy indexing isn't so niche either.

Boolean indexing is very useful but only once you have actually acquired a Boolean array, which is only likely to happen in the process of some other kind of tinkering -- using atom selection language seems far easier for simply going through TopologyAttributes. I suppose something like ag[ag.names in 'CA CT CS ...'.split()] saves some time typing.

Set operations are cool but I'm really scratching my head for a use case for creating an AtomGroup that you couldn't accomplish just as easily with selection language. concatenate/subtract seem very useful because they are ordered. The most interesting uses of the set methods are probably in the comparison operations.

Finally, I'm unclear how to create a new AtomGroup with a bond attribute/method. You can create a TopologyObject with ag.bond? I took a look at dir(ag) and found that you can also create a TopologyGroup with ag.bonds (which is not documented at all) but couldn't find anything more relevant. I do remember a Atom.bonded_atoms -> AtomGroup which is worthwhile mentioning... somewhere.

My current mental plan for this issue / user story is to split selection language off into its own page and keep all other AtomGroup creation methods on the AtomGroup page. UpdatingAtomGroups would be mentioned on both. I don't know that users would find them very advanced, as they behave virtually the same as far as the user is concerned (repr even returns a string with AtomGroup instead of UpdatingAtomGroup).

selections.rst

• available keywords, commands, etc
• will stay quite similar to the current page on selections

AtomGroups (currently shares a page with Universe information on data_structures.rst)

• What they are
• Creation
  • Selection language (links to selections.rst for full list of commands)
  • Indexing and slicing
    • Fancy indexing
    • Boolean indexing
  • Concatenate / subtract / split
  • Set operations
• Methods
  • creating and calculating topology objects
  • groupby()
  • analysis methods (center_of_mass(), etc.)
  • manipulation methods (rotate(), rotateby(), pack_into_box(), wrap() etc.)

In any case, entirely new users would probably be pointed to the quick start guide first (#11 ). There, I only introduce atom selection language, indexing/slicing, and fancy indexing. I would love your thoughts on that as a prioritised introduction that hopefully covers most of the typical use cases.

[lilyminium]

Closed by #14