core
Class AtomSpecifier

java.lang.Object
  core.AtomSpecifier

public class AtomSpecifier

extends java.lang.Object

Simple hierarchical selection language for atoms.

Specify groups of atoms as a command line argument. Atoms may be specified by the

• molecule name/number
• residue name/number
• atom name/number

The syntax is defined as three ":"-separated fields, each consisting of a list of ","-separated alphanumerical strings with "-". The string must consist of

• just alphanumerical characters, in which case it is treated as a name,
• just numerical characters, in which case it is treated as a number,
• just numerical characters, separated by just one "-", in which case it is treated as a range of numbers. in a range specification, the first number is included, the second number is excluded. i.e. 3-5 corresponds to the set 3,4.

The first list specifies the molecules (like, real molecules, i.e. GROMOS submolecules), the second list specifies the residues, the third list specifies the atoms.
The ":" correspond to boolean AND operations, while the "," correspond to boolean OR operations. Empty lists are allowed and indicate that for the corresponding field, any value is acceptable.

Examples:

• 1:: specifies all atoms of the first molecule,
• :LYSH: specifies all protonated lysine atoms,
• 1:3-5:CA specifies all alpha-carbons in the 3rd and 4th residue of the first molecule.

Version:

0.1, March 2005

Author:

Vincent Kraeutler

Field Summary

static java.lang.String	anyNameCharacter
static java.util.regex.Pattern	namePattern
static java.lang.String	namePatternString
static java.util.regex.Pattern	numberPattern
static java.lang.String	numberPatternString
static java.util.regex.Pattern	rangePattern
static java.lang.String	rangePatternString
static java.lang.String	warnString
static java.lang.String	wildCard
static java.lang.String	wildCardReplacement

Constructor Summary

AtomSpecifier()

Method Summary

static void	assertMatch(java.util.ArrayList patternStrings, java.lang.String[] names) Checks makes sure every member of patternStrings matches at least one member of names[].
static java.util.ArrayList	f2c(java.util.ArrayList fNumbers) Takes an ArrayList of Integer objects and creates a new ArrayList by subtracting 1 from each element (C-style indexing vs.
static int[]	getAtomNumbers(java.util.ArrayList atomSpecifiers, Particles particles) Same as getAtomNumbers(ArrayList, Particles), but returns int[] rather than an ArrayList of Integer objects.
static int[]	getAtomNumbers(java.lang.String[] atomSpecifiers, Particles particles) Same as getAtomNumbers(ArrayList, Particles), but returns int[] rather than an ArrayList of Integer objects.
static int[]	getAtomNumbers(java.lang.String atomSpecifier, Particles particles) Same as getAtomsNumbers(ArrayList, Particles), but takes a String rather than an ArrayList of Strings.
static java.util.ArrayList	getAtoms(java.util.ArrayList atomNumbers, java.util.ArrayList atomNames, java.util.ArrayList residueNumbers, java.util.ArrayList residueNames, java.util.ArrayList moleculeNumbers, Particles particles) Go over all atoms in the first molecule and see if they conform to an atomPattern (atomNumbers and atomNames) (if any) and a residuePattern (residueNumbers and residueNames) (if any) and return those that do.
static java.util.ArrayList	getAtoms(java.lang.String[] atomSpecifiers, Particles particles) Parses an ArrayList of atomSpecifier Strings, by iteratively calling getAtoms(String, Particles).
static java.util.ArrayList	getAtoms(java.lang.String atomSpecifier, Particles particles) Parses an atomSpecifier string, generating an ArrayList of atom numbers (Integer objects).
static boolean	isNameToken(java.lang.String token)
static boolean	isNumberToken(java.lang.String token)
static boolean	isRangeToken(java.lang.String token)
static boolean	isValidToken(java.lang.String token)
static java.util.ArrayList	joinExclusive(java.util.ArrayList aa, java.util.ArrayList bb) Join two ArrayLists, removing non-unique elements.
static boolean	matchPatterns(java.util.ArrayList patterns, java.lang.String name) does any of the supplied patterns match the string?
static java.util.HashMap	namedTokens(java.util.ArrayList tokensList) ArrayList to HashMap conversion.
static java.util.HashMap	namesAndNumbers(java.util.ArrayList tokens) Partitioning of tokens into name and number lists.
static java.util.ArrayList	tokenize(java.lang.String spec) Parse and validate the atom specifier string obtained from the command line.
static java.util.ArrayList	validateAtomNames(java.util.ArrayList atomNames, Particles particles) Checks if all supplied atom names are in the topology; no atom name is supplied more than once;
static java.util.ArrayList	validateResidueNames(java.util.ArrayList residueNames, Particles particles) Checks if all supplied residue names are in the topology; no residue name is supplied more than once;
static java.lang.String	validateToken(java.lang.String token)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

warnString

public static final java.lang.String warnString

See Also:

Constant Field Values

wildCard

public static final java.lang.String wildCard

See Also:

Constant Field Values

anyNameCharacter

public static final java.lang.String anyNameCharacter

See Also:

Constant Field Values

namePatternString

public static final java.lang.String namePatternString

See Also:

Constant Field Values

wildCardReplacement

public static final java.lang.String wildCardReplacement

See Also:

Constant Field Values

numberPatternString

public static final java.lang.String numberPatternString

See Also:

Constant Field Values

rangePatternString

public static final java.lang.String rangePatternString

See Also:

Constant Field Values

namePattern

public static final java.util.regex.Pattern namePattern

numberPattern

public static final java.util.regex.Pattern numberPattern

rangePattern

public static final java.util.regex.Pattern rangePattern

Constructor Detail

AtomSpecifier

public AtomSpecifier()

Method Detail

joinExclusive

public static java.util.ArrayList joinExclusive(java.util.ArrayList aa,
                                                java.util.ArrayList bb)

Join two ArrayLists, removing non-unique elements.

Parameters:

aa -

bb -

Returns:

cc

f2c

public static java.util.ArrayList f2c(java.util.ArrayList fNumbers)

Takes an ArrayList of Integer objects and creates a new ArrayList by subtracting 1 from each element (C-style indexing vs. Fortran-Style indexing).

Parameters:

fNumbers -

Returns:

an ArrayList of C-style indices

isNameToken

public static boolean isNameToken(java.lang.String token)

Parameters:

token - one token from the comma-separated list

Returns:

a boolean that indicates whether token is a valid AtomSpecifier name token.

See Also:

AtomSpecifier#isValidToken(String)

isNumberToken

public static boolean isNumberToken(java.lang.String token)

Parameters:

token - one token from the comma-separated list

Returns:

a boolean that indicates whether token is a valid AtomSpecifier number token.

See Also:

tokenize(String), isValidToken(String)

isRangeToken

public static boolean isRangeToken(java.lang.String token)

Parameters:

token - one token from the comma-separated list

Returns:

a boolean that indicates whether token is a valid AtomSpecifier range token.

See Also:

tokenize(String), isValidToken(String)

isValidToken

public static boolean isValidToken(java.lang.String token)

Parameters:

token - one token from the comma-separated list

Returns:

a boolean that indicates whether token is a valid AtomSpecifier token.

See Also:

tokenize(String)

validateToken

public static java.lang.String validateToken(java.lang.String token)

Parameters:

token - one token from the comma-separated list

Returns:

a boolean that indicates whether token is a valid AtomSpecifier token.

See Also:

isValidToken(String)

tokenize

public static java.util.ArrayList tokenize(java.lang.String spec)

Parse and validate the atom specifier string obtained from the command line.

Parameters:

spec - the atom specifier string

Returns:

a list of lists of (validated) tokens

namedTokens

public static java.util.HashMap namedTokens(java.util.ArrayList tokensList)
                                     throws java.lang.IllegalArgumentException

ArrayList to HashMap conversion. Takes the list of lists of tokens (such as generated by tokenize()) and names the lists (i.e. the first list of tokens corresponds to the molecule, the second to the residue, the third to the atoms).

Parameters:

tokensList - output of tokenize()

Returns:

hash map of the contents of tokensList

Throws:

java.lang.IllegalArgumentException

See Also:

tokenize(String)

namesAndNumbers

public static java.util.HashMap namesAndNumbers(java.util.ArrayList tokens)

Partitioning of tokens into name and number lists. Partitions the list of tokens into two lists -- one containing the name patterns (e.g. atom & residue names), the containing just numbers (ranges are expanded, Fortran->C index mangling is performed). The numbers come in the form of Integer objects.

Parameters:

tokens -

Returns:

a HashMap of two lists

assertMatch

public static void assertMatch(java.util.ArrayList patternStrings,
                               java.lang.String[] names)
                        throws java.lang.RuntimeException

Checks makes sure every member of patternStrings matches at least one member of names[].

Parameters:

patternStrings -

names -

Throws:

java.lang.RuntimeException

validateResidueNames

public static java.util.ArrayList validateResidueNames(java.util.ArrayList residueNames,
                                                       Particles particles)

Checks

• if all supplied residue names are in the topology;
• no residue name is supplied more than once;

Parameters:

residueNames -

Returns:

residueNames -- if they are valid.

validateAtomNames

public static java.util.ArrayList validateAtomNames(java.util.ArrayList atomNames,
                                                    Particles particles)

Checks

• if all supplied atom names are in the topology;
• no atom name is supplied more than once;

Parameters:

atomNames -

Returns:

atomNames -- if they are valid.

See Also:

validateResidueNames(ArrayList, Particles), namesAndNumbers(ArrayList)

matchPatterns

public static boolean matchPatterns(java.util.ArrayList patterns,
                                    java.lang.String name)

does any of the supplied patterns match the string?

Parameters:

patterns -

name -

Returns:

whether any of the supplied patterns match the name

getAtoms

public static java.util.ArrayList getAtoms(java.util.ArrayList atomNumbers,
                                           java.util.ArrayList atomNames,
                                           java.util.ArrayList residueNumbers,
                                           java.util.ArrayList residueNames,
                                           java.util.ArrayList moleculeNumbers,
                                           Particles particles)

Go over all atoms in the first molecule and see if they conform to an atomPattern (atomNumbers and atomNames) (if any) and a residuePattern (residueNumbers and residueNames) (if any) and return those that do.

Parameters:

atomNumbers - a list of atom numbers (Integer objects)

atomNames - a list of atom names (Strings)

residueNumbers - a list of residue numbers (Integer objects)

residueNames - a list of residue names (Strings)

particles - a Particles instance (i.e. the topology)

Returns:

the (sorted) list of atom indices (C style, not Fortran style) in the first molecule that conforms to the above criteria.

getAtoms

public static java.util.ArrayList getAtoms(java.lang.String atomSpecifier,
                                           Particles particles)

Parses an atomSpecifier string, generating an ArrayList of atom numbers (Integer objects).

Parameters:

atomSpecifier -

particles -

Returns:

ArrayList of atom numbers (Integer objects, C style, not Fortran style))

getAtoms

public static java.util.ArrayList getAtoms(java.lang.String[] atomSpecifiers,
                                           Particles particles)

Parses an ArrayList of atomSpecifier Strings, by iteratively calling getAtoms(String, Particles).

Parameters:

atomSpecifiers - ArrayList of atomSpecifier Strings

particles - the topology

Returns:

ArrayList of atom numbers (Integer objects, C style, not Fortran style)

See Also:

getAtoms(String, Particles)

getAtomNumbers

public static int[] getAtomNumbers(java.lang.String[] atomSpecifiers,
                                   Particles particles)

Same as getAtomNumbers(ArrayList, Particles), but returns int[] rather than an ArrayList of Integer objects.

Parameters:

atomSpecifiers - ArrayList of atomSpecifier Strings

particles - the topology

Returns:

list of atom indices (C-style not Fortran style)

See Also:

getAtomNumbers(ArrayList, Particles)

getAtomNumbers

public static int[] getAtomNumbers(java.util.ArrayList atomSpecifiers,
                                   Particles particles)

Same as getAtomNumbers(ArrayList, Particles), but returns int[] rather than an ArrayList of Integer objects.

Parameters:

atomSpecifiers - ArrayList of atomSpecifier Strings

particles - the topology

Returns:

list of atom indices (C-style not Fortran style)

See Also:

getAtomNumbers(ArrayList, Particles)

getAtomNumbers

public static int[] getAtomNumbers(java.lang.String atomSpecifier,
                                   Particles particles)

Same as getAtomsNumbers(ArrayList, Particles), but takes a String rather than an ArrayList of Strings.

Parameters:

atomSpecifier -

particles -

Returns:

all the atom numbers of the matching atoms

See Also:

getAtomNumbers(ArrayList, Particles)