Allow using selection keywords as residue names (#5119)

* Allow selecting residues that share a name with a keyword
* Update selection docs with example of how to escape keywords when selecting atoms
* Add tests for selecting residues that share a name with a keyword

Author: p-j-smith

package/CHANGELOG

@@ -16,12 +16,15 @@ The rules for this file:
 -------------------------------------------------------------------------------
 ??/??/?? IAlibay, orbeckst, BHM-Bob, TRY-ER, Abdulrahman-PROG, pbuslaev,
          yuxuanzhuang, yuyuan871111, tanishy7777, tulga-rdn, Gareth-elliott,
-         hmacdope, tylerjereddy, cbouy, talagayev, DrDomenicoMarson, amruthesht
+         hmacdope, tylerjereddy, cbouy, talagayev, DrDomenicoMarson, amruthesht,
+         p-j-smith
 
 
  * 2.10.0
 
 Fixes
+ * Fix atom selection parsing to allow escaping keywords with a backslash
+   (Issue #5111, PR #5119)
  * Fix DCDWriter to correctly write unit cell angles as cosines following 
    NAMD/VMD convention (Issue #5069)
  * Fixed an integer overflow in large DCD file seeks on Windows

package/MDAnalysis/core/selection.py

@@ -85,6 +85,9 @@ def is_keyword(val):
 def grab_not_keywords(tokens):
     """Pop tokens from the left until you hit a keyword
 
+    Keywords can be escaped with a backslash to allow their use as names,
+    e.g. '\\protein'
+
     Parameters
     ----------
     tokens : collections.deque
@@ -113,8 +116,8 @@ def grab_not_keywords(tokens):
     values = []
     while not is_keyword(tokens[0]):
         val = tokens.popleft()
-        # Insert escape characters here to use keywords as names?
-        values.append(val)
+        # Remove escape sequence to allow use of keywords as names
+        values.append(val.removeprefix("\\"))
     return values
 
 

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

@@ -138,7 +138,8 @@ resnum *resnum-number-range*
     residue id in the original PDB structure.
 
 resname *residue-name*
-    select by residue name, e.g. ``resname LYS``
+    select by residue name, e.g. ``resname LYS``. If a residue shares a name
+    with a selection keyword, the name must be escaped e.g. ``resname \\water``.
 
 name *atom-name*
     select by atom name (as given in the topology). Often, this is force

testsuite/MDAnalysisTests/core/test_atomselections.py

@@ -107,6 +107,14 @@ def test_protein_resnames(self, resname):
         # check that contents (atom indices) are identical afterwards
         assert_equal(myprot.atoms.ix, sel.ix)
 
+    def test_residue_named_protein(self):
+        u = make_Universe(("resnames",))
+        myprot = u.residues[::2]
+        myprot.resnames = "protein"
+        sel = u.select_atoms("resname \\protein")
+        # check that contents (atom indices) are identical afterwards
+        assert_equal(myprot.atoms.ix, sel.ix)
+
     def test_backbone(self, universe):
         sel = universe.select_atoms("backbone")
         assert_equal(sel.n_atoms, 855)
@@ -1226,6 +1234,7 @@ def universe():
             "resnum ",
             "bynum or protein",
             "index or protein",
+            "resname protein",  # unexpected token
             "prop mass < 4.0 hello",  # unused token
             "prop mass > 10. and group this",  # missing group
             # bad ranges
@@ -1472,6 +1481,7 @@ def test_similarity_selection_icodes(u_pdb_icodes, selection, n_atoms):
         "name N*",
         "resname stuff",
         "resname ALA",
+        "resname \\protein",
         "type O",
         "index 0",
         "index 1",