PageRenderTime 45ms CodeModel.GetById 14ms RepoModel.GetById 0ms app.codeStats 0ms

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