Skip to content

Commit 7990c90

Browse files
johnmayjohnmay
committed
Rename and improve description.
1 parent 97a820e commit 7990c90

File tree

4 files changed

+168
-86
lines changed

4 files changed

+168
-86
lines changed

‎base/standard/src/main/java/org/openscience/cdk/tools/manipulator/AtomContainerManipulator.java‎

Lines changed: 78 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
/*
1+
/*
22
* Copyright (C) 2003-2007 The Chemistry Development Kit (CDK) project
33
* 2014 Mark B Vine (orcid:0000-0002-7794-0426)
44
*
@@ -91,11 +91,43 @@
9191
*/
9292
public class AtomContainerManipulator {
9393

94+
/**
95+
* For use with {@link #getMass(IAtomContainer)}. This option uses the mass
96+
* stored on atoms ({@link IAtom#getExactMass()}) or the average mass of the
97+
* element when unspecified.
98+
*/
99+
public static final int MolWeight = 0x1;
100+
101+
/**
102+
* For use with {@link #getMass(IAtomContainer)}. This option ignores the
103+
* mass stored on atoms ({@link IAtom#getExactMass()}) and uses the average
104+
* mass of each element. This option is primarily provided for backwards
105+
* compatibility.
106+
*/
107+
public static final int MolWeightIgnoreSpecified = 0x2;
108+
109+
/**
110+
* For use with {@link #getMass(IAtomContainer)}. This option uses the mass
111+
* stored on atoms {@link IAtom#getExactMass()} or the mass of the major
112+
* isotope when this is not specified.
113+
*/
114+
public static final int MonoIsotopic = 0x3;
115+
116+
/**
117+
* For use with {@link #getMass(IAtomContainer)}. This option uses the mass
118+
* stored on atoms {@link IAtom#getExactMass()} and then calculates a
119+
* distribution for any unspecified atoms and uses the most abundant
120+
* distribution. For example C<sub>6</sub>Br<sub>6</sub> would have three
121+
* <sup>79</sup>Br and <sup>81</sup>Br because their abundance is 51 and
122+
* 49%.
123+
*/
124+
public static final int MostAbundant = 0x4;
125+
94126
/**
95127
* Extract a substructure from an atom container, in the form of a new
96128
* cloned atom container with only the atoms with indices in atomIndices and
97129
* bonds that connect these atoms.
98-
*
130+
*
99131
* Note that this may result in a disconnected atom container.
100132
*
101133
* @param atomContainer the source container to extract from
@@ -226,11 +258,6 @@ private static double getMassOrAvg(IsotopeFactory isofact, IIsotope atom) {
226258
return getExactMass(isofact, atom);
227259
}
228260

229-
public static final int MolWeight = 0x1;
230-
public static final int AverageWeight = 0x2;
231-
public static final int MonoIsotopic = 0x3;
232-
public static final int MostAbundant = 0x4;
233-
234261
public static final Comparator<IIsotope> NAT_ABUN_COMP = new Comparator<IIsotope>() {
235262
@Override
236263
public int compare(IIsotope o1, IIsotope o2) {
@@ -277,26 +304,33 @@ private static int getAtomicNum(IElement atom) {
277304

278305
/**
279306
* Calculate the mass of a molecule, this function takes an optional
280-
* 'mass flavour' that switches the computation type, the flavours are:
307+
* 'mass flavour' that switches the computation type. The key distinction
308+
* is how specified/unspecified isotopes are handled. A specified isotope
309+
* is an atom that has either {@link IAtom#setMassNumber(Integer)}
310+
* or {@link IAtom#setExactMass(Double)} set to non-null and non-zero.
311+
* <br>
312+
* The flavours are:
281313
* <br>
282314
* <ul>
283-
* <li>{@link #MolWeight} (default) - use and isotopes the natural mass
284-
* unless a specific isotope is specified</li>
285-
* <li>{@link #AverageWeight} - use and isotopes the natural mass even
286-
* if a specific isotope is specified</li>
287-
* <li>{@link #MonoIsotopic} - use and isotopes the major isotope mass
288-
* even if a specific isotope is specified</li>
289-
* <li>{@link #MostAbundant} - use the distribution of isotopes
290-
* based on their abundance and select the most abundant. For example
291-
* C<sub>6</sub>Br<sub>6</sub> would have three <sup>79</sup>Br and
292-
* <sup>81</sup>Br because their abundance is 51 and 49%.
315+
* <li>{@link #MolWeight} (default) - uses the exact mass of each
316+
* atom when specified, if not specified the average mass of the element
317+
* is used.</li>
318+
* <li>{@link #MolWeightIgnoreSpecified} - uses the average mass of each
319+
* element ignoring any exact mass that has been specified.</li>
320+
* <li>{@link #MonoIsotopic} - uses the exact mass of each atom when
321+
* specified, if not specified the major isotope mass for that
322+
* element is used.</li>
323+
* <li>{@link #MostAbundant} - uses the exact mass of each atom when
324+
* specified, if not specified a distribution is calculated and the
325+
* most abundant isotope pattern is used.</li>
293326
* </ul>
294327
*
295328
* @param mol molecule to compute mass for
296-
* @param flav the mass flavour
329+
* @param flav flavor
297330
* @return the mass of the molecule
331+
* @see #getMass(IAtomContainer, int)
298332
* @see #MolWeight
299-
* @see #AverageWeight
333+
* @see #MolWeightIgnoreSpecified
300334
* @see #MonoIsotopic
301335
* @see #MostAbundant
302336
*/
@@ -320,7 +354,7 @@ public static double getMass(IAtomContainer mol, int flav) {
320354
}
321355
mass += hcnt * isofact.getNaturalMass(1);
322356
break;
323-
case AverageWeight:
357+
case MolWeightIgnoreSpecified:
324358
for (IAtom atom : mol.atoms()) {
325359
mass += isofact.getNaturalMass(getAtomicNum(atom));
326360
hcnt += getImplHCount(atom);
@@ -358,26 +392,32 @@ public static double getMass(IAtomContainer mol, int flav) {
358392

359393
/**
360394
* Calculate the mass of a molecule, this function takes an optional
361-
* 'mass flavour' that switches the computation type, the flavours are:
395+
* 'mass flavour' that switches the computation type. The key distinction
396+
* is how specified/unspecified isotopes are handled. A specified isotope
397+
* is an atom that has either {@link IAtom#setMassNumber(Integer)}
398+
* or {@link IAtom#setExactMass(Double)} set to non-null and non-zero.
399+
* <br>
400+
* The flavours are:
362401
* <br>
363402
* <ul>
364-
* <li>{@link #MolWeight} (default) - use and isotopes the natural mass
365-
* unless a specific isotope is specified</li>
366-
* <li>{@link #AverageWeight} - use and isotopes the natural mass even
367-
* if a specific isotope is specified</li>
368-
* <li>{@link #MonoIsotopic} - use and isotopes the major isotope mass
369-
* even if a specific isotope is specified</li>
370-
* <li>{@link #MostAbundant} - use the distribution of isotopes
371-
* based on their abundance and select the most abundant. For example
372-
* C<sub>6</sub>Br<sub>6</sub> would have three <sup>79</sup>Br and
373-
* <sup>81</sup>Br because their abundance is 51 and 49%.
403+
* <li>{@link #MolWeight} (default) - uses the exact mass of each
404+
* atom when specified, if not specified the average mass of the element
405+
* is used.</li>
406+
* <li>{@link #MolWeightIgnoreSpecified} - uses the average mass of each
407+
* element ignoring any exact mass that has been specified.</li>
408+
* <li>{@link #MonoIsotopic} - uses the exact mass of each atom when
409+
* specified, if not specified the major isotope mass for that
410+
* element is used.</li>
411+
* <li>{@link #MostAbundant} - uses the exact mass of each atom when
412+
* specified, if not specified a distribution is calculated and the
413+
* most abundant isotope pattern is used.</li>
374414
* </ul>
375415
*
376416
* @param mol molecule to compute mass for
377417
* @return the mass of the molecule
378418
* @see #getMass(IAtomContainer, int)
379419
* @see #MolWeight
380-
* @see #AverageWeight
420+
* @see #MolWeightIgnoreSpecified
381421
* @see #MonoIsotopic
382422
* @see #MostAbundant
383423
*/
@@ -386,19 +426,20 @@ public static double getMass(IAtomContainer mol) {
386426
}
387427

388428
/**
389-
* @deprecated use {@link #getMass(IAtomContainer, int)} and
429+
* @deprecated uses {@link #getMass(IAtomContainer, int)} and
390430
* {@link #MonoIsotopic}
391431
*/
392432
public static double getTotalExactMass(IAtomContainer mol) {
393433
return getMass(mol, MonoIsotopic);
394434
}
395435

396436
/**
397-
* @deprecated use {@link #getMass(IAtomContainer, int)} and
398-
* {@link #AverageWeight}
437+
* @deprecated uses {@link #getMass(IAtomContainer, int)} and
438+
* {@link #MolWeightIgnoreSpecified}. You probably want
439+
* {@link #MolWeight}!
399440
*/
400441
public static double getNaturalExactMass(IAtomContainer mol) {
401-
return getMass(mol, AverageWeight);
442+
return getMass(mol, MolWeightIgnoreSpecified);
402443
}
403444

404445
/**

‎base/test-standard/src/test/java/org/openscience/cdk/tools/manipulator/AtomContainerManipulatorTest.java‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1341,7 +1341,7 @@ static void assertRemoveH(String smiIn, String smiExp) throws Exception {
13411341
IAtomContainer mol = smipar.parseSmiles("Brc1c(Br)c(Br)c(Br)c(Br)c1Br");
13421342
assertThat(AtomContainerManipulator.getMass(mol, MolWeight),
13431343
closeTo(551.485, 0.001));
1344-
assertThat(AtomContainerManipulator.getMass(mol, AverageWeight),
1344+
assertThat(AtomContainerManipulator.getMass(mol, MolWeightIgnoringSpecified),
13451345
closeTo(551.485, 0.001));
13461346
assertThat(AtomContainerManipulator.getMass(mol, MonoIsotopic),
13471347
closeTo(545.510, 0.001));
@@ -1356,7 +1356,7 @@ static void assertRemoveH(String smiIn, String smiExp) throws Exception {
13561356
bldr);
13571357
assertThat(AtomContainerManipulator.getMass(mol, MolWeight),
13581358
closeTo(4730.397, 0.001));
1359-
assertThat(AtomContainerManipulator.getMass(mol, AverageWeight),
1359+
assertThat(AtomContainerManipulator.getMass(mol, MolWeightIgnoringSpecified),
13601360
closeTo(4730.397, 0.001));
13611361
assertThat(AtomContainerManipulator.getMass(mol, MonoIsotopic),
13621362
closeTo(4727.140, 0.001));
@@ -1371,7 +1371,7 @@ static void assertRemoveH(String smiIn, String smiExp) throws Exception {
13711371
bldr);
13721372
assertThat(AtomContainerManipulator.getMass(mol, MolWeight),
13731373
closeTo(4729.147, 0.001));
1374-
assertThat(AtomContainerManipulator.getMass(mol, AverageWeight),
1374+
assertThat(AtomContainerManipulator.getMass(mol, MolWeightIgnoringSpecified),
13751375
closeTo(4730.397, 0.001));
13761376
assertThat(AtomContainerManipulator.getMass(mol, MonoIsotopic),
13771377
closeTo(4729.147, 0.001));
@@ -1386,7 +1386,7 @@ static void assertRemoveH(String smiIn, String smiExp) throws Exception {
13861386
bldr);
13871387
assertThat(AtomContainerManipulator.getMass(mol, MolWeight),
13881388
closeTo(4732.382, 0.001));
1389-
assertThat(AtomContainerManipulator.getMass(mol, AverageWeight),
1389+
assertThat(AtomContainerManipulator.getMass(mol, MolWeightIgnoringSpecified),
13901390
closeTo(4730.397, 0.001));
13911391
assertThat(AtomContainerManipulator.getMass(mol, MonoIsotopic),
13921392
closeTo(4729.147, 0.001));

0 commit comments

Comments
 (0)