PageRenderTime 97ms CodeModel.GetById 84ms app.highlight 8ms RepoModel.GetById 1ms app.codeStats 1ms

/rcdk/R/atoms.R

http://github.com/rajarshi/cdkr
R | 302 lines | 86 code | 19 blank | 197 comment | 17 complexity | 09b9329e790ac036937a5a602c6f199b MD5 | raw file
  1#' @name Atoms
  2#' @title Operations on Atoms
  3#' 
  4#' @description 
  5#' \code{\link{get.symbol}} returns the chemical symbol for an atom
  6#' \code{\link{get.point3d}} returns the 3D coordinates of the atom
  7#' \code{\link{get.point2d}} returns the 2D coordinates of the atom
  8#' \code{\link{get.atomic.number}} returns the atomic number of the atom
  9#' \code{\link{get.hydrogen.count}}  returns the number of implicit H’s on the atom. 
 10#'           Depending on where the molecule was read from this may be \code{NULL}
 11#'           or an integer greater than or equal to \code{0}
 12#' \code{\link{get.charge}} returns the partial charge on the atom. If charges 
 13#'           have not been set the return value is \code{NULL}, otherwise 
 14#'           the appropriate charge.
 15#' \code{\link{get.formal.charge}} returns the formal charge on the atom. By 
 16#'            default the formal charge will be \code{0} (i.e., \code{NULL}
 17#'            is never returned)
 18#' \code{\link{is.aromatic}} returns \code{TRUE} if the atom is aromatic,
 19#'            \code{FALSE} otherwise
 20#' \code{\link{is.aliphatic}} returns \code{TRUE} if the atom is part of an 
 21#'            aliphatic chain, \code{FALSE} otherwise
 22#' \code{\link{is.in.ring}} returns \code{TRUE} if the atom is in a ring, 
 23#'             \code{FALSE} otherwise
 24#' \code{\link{get.atom.index}} eturns the index of the atom in the molecule
 25#'             (starting from \code{0})
 26#' \code{\link{get.connected.atoms}} returns a list of atoms that are connected to the specified atom
 27#' 
 28#' @section Usage:
 29#' get.symbol(atom)
 30#' get.point3d(atom)
 31#' get.point2d(atom)
 32#' get.atomic.number(atom)
 33#' get.hydrogen.count(atom)
 34#' get.charge(atom)
 35#' get.formal.charge(atom)
 36#' get.connected.atoms(atom, mol)
 37#' get.atom.index(atom, mol)
 38#' is.aromatic(atom)
 39#' is.aliphatic(atom)
 40#' is.in.ring(atom) 
 41#' 
 42#' 
 43#' @section Arguments:
 44#'  atom A jobjRef representing an IAtom object
 45#'  mol  A jobjRef representing an IAtomContainer object
 46#' 
 47#' @section Value:
 48#'  In the case of \code{\link{get.point3d}} the return value is a 3-element vector 
 49#'  containingthe X, Y and Z co-ordinates of the atom.  If the atom does not 
 50#'  have 3D coordinates, it returns a vector of the form \code{c(NA,NA,NA)}.
 51#'  Similarly for \code{\link{get.point2d}}, in which case the return vector is of 
 52#'  length \code{2}.
 53#'  
 54#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
 55#' @docType package
 56NULL
 57
 58## An example of getting all the coordinates for a molecule
 59## atoms <- get.atoms(mol)
 60## coords <- do.call('rbind', lapply(apply, get.point3d))
 61
 62.valid.atom <- function(atom) {
 63  if (is.null(attr(atom, 'jclass'))) stop("Must supply an Atom or IAtom object")
 64  if (!.check.class(atom, "org/openscience/cdk/interfaces/IAtom") &&
 65      !.check.class(atom, "org/openscience/cdk/Atom"))
 66    stop("Must supply an Atom or IAtom object")
 67
 68  if (.check.class(atom, "org/openscience/cdk/Atom"))
 69    atom <- .jcast(atom, "org/openscience/cdk/interfaces/IAtom")
 70  return(atom)
 71}
 72
 73#' @name get.point3d
 74#' @title Get the 3D coordinates of the atom.
 75#' 
 76#' In case, coordinates are unavailable (e.g., molecule was read in from a 
 77#' SMILES file) or have not been generated yet, `NA`'s are returned for the 
 78#' X, Y and Z coordinates.
 79#' 
 80#' @param atom The atom to query
 81#' @return A 3-element numeric vector representing the X, Y and Z coordinates.
 82#' @seealso \code{\link{get.point2d}}
 83#' @export
 84#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
 85#' @examples 
 86#' \dontrun{
 87#' atoms <- get.atoms(mol)
 88#' coords <- do.call('rbind', lapply(apply, get.point3d))
 89#' }
 90get.point3d <- function(atom) {
 91  atom <- .valid.atom(atom)
 92  p3d <- .jcall(atom, "Ljavax/vecmath/Point3d;", "getPoint3d")
 93  if (is.jnull(p3d)) return( c(NA,NA,NA) )
 94  else {
 95    c(.jfield(p3d, name='x'),
 96      .jfield(p3d, name='y'),
 97      .jfield(p3d, name='z'))
 98  }
 99}
100
101#' @name get.point2d
102#' @title Get the 2D coordinates of the atom.
103#' 
104#' In case, coordinates are unavailable (e.g., molecule was read in from a 
105#' SMILES file) or have not been generated yet, `NA`'s are returned for the 
106#' X & Y coordinates.
107#' 
108#' @param atom The atom to query
109#' @return A 2-element numeric vector representing the X & Y coordinates.
110#' @seealso \code{\link{get.point3d}}
111#' @export
112#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
113#' @examples 
114#' \dontrun{
115#' atoms <- get.atoms(mol)
116#' coords <- do.call('rbind', lapply(apply, get.point2d))
117#' }
118get.point2d <- function(atom) {
119  atom <- .valid.atom(atom)    
120  p3d <- .jcall(atom, "Ljavax/vecmath/Point2d;", "getPoint2d")
121  if (is.jnull(p3d)) return( c(NA,NA) )
122  else {
123    c(.jfield(p3d, name='x'),
124      .jfield(p3d, name='y'))
125  }
126}
127
128#' @name get.symbol
129#' @title Get the atomic symbol of the atom.
130#' 
131#' Get the atomic symbol of the atom.
132#' 
133#' @param atom The atom to query
134#' @return A character representing the atomic symbol
135#' @export
136#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
137get.symbol <- function(atom) {
138  atom <- .valid.atom(atom)  
139  .jcall(atom, "S", "getSymbol")
140}
141
142#' @name get.atomic.number
143#' @title Get the atomic number of the atom.
144#' 
145#' @param atom The atom to query
146#' @return An integer representing the atomic number
147#' @export
148#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
149get.atomic.number <- function(atom) {
150  atom <- .valid.atom(atom)
151  .jcall(.jcall(atom, "Ljava/lang/Integer;", "getAtomicNumber"), "I", "intValue")
152}
153
154#' @name get.charge
155#' @title Get the charge on the atom.
156#' 
157#' This method returns the partial charge on the atom. If charges have not been set the
158#' return value is \code{NULL}, otherwise the appropriate charge.
159#' 
160#' @param atom The atom to query
161#' @return An numeric representing the partial charge. If charges have not been set,
162#' `NULL` is returned
163#' @seealso \code{\link{get.formal.charge}}
164#' @export
165#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
166get.charge <- function(atom) {
167  atom <- .valid.atom(atom)
168  ch <- .jcall(atom, "Ljava/lang/Double;", "getCharge")
169  if (!is.null(ch)) return(.jcall(ch, "D", "doubleValue"))
170  else return(ch)
171}
172
173#' @name get.formal.charge
174#' @title Get the formal charge on the atom.
175#' 
176#' By default the formal charge will be 0 (i.e., \code{NULL} is never returned).
177#' 
178#' @param atom The atom to query
179#' @return An integer representing the formal charge
180#' @seealso \code{\link{get.charge}}
181#' @export
182#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
183get.formal.charge <- function(atom) {
184  atom <- .valid.atom(atom)
185  ch <- .jcall(atom, "Ljava/lang/Integer;", "getFormalCharge")
186  if (!is.null(ch)) return(.jcall(ch, "I", "intValue"))
187  else return(ch)  
188}
189
190#' @name get.hydrogen.count
191#' @title Get the implicit hydrogen count for the atom.
192#' 
193#' This method returns the number of implicit H's on the atom. 
194#' Depending on where the molecule was read from this may be \code{NULL} or an integer
195#' greater than or equal to 0
196#' 
197#' @param atom The atom to query
198#' @return An integer representing the hydrogen count
199#' @aliases hydrogen
200#' @export
201#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
202get.hydrogen.count <- function(atom) {
203  atom <- .valid.atom(atom)  
204  .jcall(.jcall(atom, "Ljava/lang/Integer;", "getImplicitHydrogenCount"), "I", "intValue")
205}
206
207#' @name is.aromatic
208#' @title Tests whether an atom is aromatic.
209#' 
210#' This assumes that the molecule containing the atom has been 
211#' appropriately configured.
212#' 
213#' @param atom The atom to test
214#' @return `TRUE` is the atom is aromatic, `FALSE` otherwise
215#' @seealso \code{\link{is.aliphatic}}, \code{\link{is.in.ring}}, \code{\link{do.aromaticity}}
216#' @export
217#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
218is.aromatic <- function(atom) {
219  atom <- .valid.atom(atom)
220  flag.idx <- .jfield("org/openscience/cdk/CDKConstants", "I", "ISAROMATIC")
221  .jcall(atom, "Z", "getFlag", as.integer(flag.idx))
222}
223
224#' @name is.aliphatic
225#' @title Tests whether an atom is aliphatic.
226#' 
227#' This assumes that the molecule containing the atom has been 
228#' appropriately configured.
229#' 
230#' @param atom The atom to test
231#' @return `TRUE` is the atom is aliphatic, `FALSE` otherwise
232#' @seealso \code{\link{is.in.ring}}, \code{\link{is.aromatic}}
233#' @export
234#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
235is.aliphatic <- function(atom) {
236  atom <- .valid.atom(atom)
237  flag.idx <- .jfield("org/openscience/cdk/CDKConstants", "I", "ISALIPHATIC")
238  .jcall(atom, "Z", "getFlag", as.integer(flag.idx))
239}
240
241#' @name is.in.ring
242#' @title Tests whether an atom is in a ring.
243#' 
244#' This assumes that the molecule containing the atom has been 
245#' appropriately configured.
246#' 
247#' @param atom The atom to test
248#' @return `TRUE` is the atom is in a ring, `FALSE` otherwise
249#' @seealso \code{\link{is.aliphatic}}, \code{\link{is.aromatic}}
250#' @export
251#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
252is.in.ring <- function(atom) {
253  atom <- .valid.atom(atom)
254  flag.idx <- .jfield("org/openscience/cdk/CDKConstants", "I", "ISINRING")
255  .jcall(atom, "Z", "getFlag", as.integer(flag.idx))
256}
257
258#' @name get.connected.atoms
259#' @title Get atoms connected to the specified atom
260#' 
261#' Returns a `list`` of atoms that are connected to the specified atom.
262#' @param atom The atom object
263#' @param mol The `IAtomContainer` object containing the atom
264#' @return A `list` containing `IAtom` objects, representing the atoms directly
265#' connected to the specified atom
266#' @export
267#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
268get.connected.atoms <- function(atom, mol) {
269  if (is.null(attr(mol, 'jclass')))
270    stop("object must be of class IAtomContainer")
271  
272  if (attr(mol, 'jclass') != "org/openscience/cdk/interfaces/IAtomContainer")
273    stop("object must be of class IAtomContainer")
274  
275  atom <- .valid.atom(atom)
276  ret <- .jcall(mol, "Ljava/util/List;", "getConnectedAtomsList", atom)
277  ret <- lapply(.javalist.to.rlist(ret), .jcast, new.class='org/openscience/cdk/interfaces/IAtom')
278  return(ret)
279}
280
281#' @name get.atom.index
282#' @title Get the index of an atom in a molecule.
283#' 
284#' Acces the index of an atom in the context of an IAtomContainer. 
285#' Indexing starts from 0. If the index is not known, -1 is returned.
286#' 
287#' @param atom The atom object
288#' @param mol The `IAtomContainer` object containing the atom
289#' @return An integer representing the atom index. 
290#' @seealso \code{\link{get.connected.atom}}
291#' @export
292#' @author Rajarshi Guha (\email{rajarshi.guha@@gmail.com})
293get.atom.index <- function(atom, mol) {
294  if (is.null(attr(mol, 'jclass')))
295    stop("object must be of class IAtomContainer")
296  
297  if (attr(mol, 'jclass') != "org/openscience/cdk/interfaces/IAtomContainer")
298    stop("object must be of class IAtomContainer")
299  
300  atom <- .valid.atom(atom)
301  .jcall(mol, "I", "getAtomNumber", atom)
302}