NAME

MS::Mass - core functions for molecular mass calculations

SYNOPSIS

    use MS::Mass qw/:all/;

    use constant PROTON => elem_mass('H');          # 1.007825035 

    use constant WATER  => formula_mass('H2O');     # 18.0105647

    my $add_NQ = mod_mass('Deamidated', 'average'); # 0.9848

    my $C_proline = atoms('aa' => 'P')->{C};        # 5

DESCRIPTION

MS::Mass provides a set of core functions for use in calculating and working with molecular mass values common in mass spectrometry. It is expected that more specialized libraries for mass calculations can build off of this module within the MS::Mass namespace.

The module utilizes a functional interface for speed and simplicity. It utilizes the Unimod database as its data source. For modification records, the basic delta mass (monoisotopic or average) can be retrieved via the mod_mass function. The rest of the information stored in Unimod (e.g. specificities, authors, etc) does not currently have associated retrieval functions but can, if needed, be directly accessed via the mod_data function, which returns a hash reference to a nested data structure containing all information from the Unimod record (use Data::Dumper to view the underlying structure if you require this functionality). Additional convenience functions to provide access to these modification attributes may be added in the future.

FUNCTIONS

elem_mass symbol [type]

    use constant PROTON     => elem_mass('H');
    use constant PROTON_AVG => elem_mass('H', 'average');

Takes one required argument (an element symbol) and one optional argument (the mass value to return, either 'mono' or 'average') and returns the associated mass value. By default, the monoisotopic mass is returned. Element symbols are case-sensitive;

aa_mass code [type]

    use constant PROLINE     => aa_mass('P');
    use constant PROLINE_AVG => aa_mass('P', 'average');

Takes one required argument (the 1-letter IUPAC code for an amino acid) and one optional argument (the mass value to return, either 'mono' or 'average') and returns the associated mass value. By default, the monoisotopic mass is returned.

mod_mass name [type]

    use constant DEAM     => mod_mass('Deamidated');
    use constant DEAM_AVG => brick_mass('Deamidated', average');

Takes one required argument (the modification name) and one optional argument (the mass value to return, either 'mono' or 'average') and returns the associated mass value. By default, the monoisotopic mass is returned.

brick_mass name [type]

    use constant WATER     => brick_mass('Water');
    use constant WATER_AVG => brick_mass('Water', average');

Takes one required argument (the brick name) and one optional argument (the mass value to return, either 'mono' or 'average') and returns the associated mass value. By default, the monoisotopic mass is returned. See list_bricks for more details.

formula_mass formula [type]

Takes one required argument (a string containing a chemical formula) and one optional argument (the mass value to return, either 'mono' or 'average') and returns the associated mass value. By default, the monoisotopic mass is returned.

Formulas are case-sensitive, for obvious reasons. Currently grouping is not supported. For example, to get the formula for Al2(SO4)3 you must flatten it out:

    my $al_sulf = formula_mass('Al2S3O12');

and not:

    my $al_sulf = formula_mass('Al2(SO4)3'); # this gives an error

Support for more complicated formulas may be added in the future.

atoms_mass hashref [type]

Takes one required argument (a hashref containing element counts) and one optional argument (the mass value to return, either 'mono' or 'average') and returns the associated mass value. By default, the monoisotopic mass is returned.

This function was added to make it easy to recalculate masses based on modifying the return reference from atoms.

atoms type name

    my $atoms = $atoms('aa' => 'G');
    my $n_C = $atoms->{C};

Takes two required arguments (the record type - 'aa', 'mod', or 'brick' - and the record name/symbol) and returns a hash reference where the keys are the elements present in the molecule and the values are their counts.

mod_id_to_name id

    my $name = mod_id_to_name(7);
    my $deam = mod_mass($name);

Takes one required arguments (a Unimod modification record id) and returns the associated name compatible with mod_mass or undef if not found.

mod_data id

    my $mod = mod_data('Carbamidomethyl');
    my @specificities = @{ $mod->{'umod:specificity'} }
    for (@specificities) {
        print "$_->{site}\n" if (! $_->{hidden});
    }

Takes one required argument (a modification name) and returns a hash reference containing a nested data structure with all information contained in the Unimod record. Use Data::Dumper for a view of the internal structure.

In the future an object-oriented interface may be added to make access to these details more user-friendly.

list_bricks

    print {$ref_table} list_bricks();

This is a convenience function that returns a tab-separated table of available Unimod "bricks" suitable for printing. These are elemental or molecular units that can be referenced as a group for convenience.

This function is provided mainly because this information does not seem to be readily available elsewhere without reading the XML.

db_version

Returns the version string of the Unimod database in use.

CAVEATS AND BUGS

Please report bugs to the author.

AUTHOR

Jeremy Volkening <jdv@base2bio.com>

COPYRIGHT AND LICENSE

Copyright 2016 Jeremy Volkening

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.