Package: liputils
liputilsA small Python package to manipulate complex lipids.Overviewliputilsmakes it easy to strip fatty acids-like residues from individual molecular lipids. This is done byliputilsby parsing the lipid string identifier.Check it out! We have a paper out in Scientific Reports, with detailed step-by-step installation and usage protocols, and real use cases implemented and discussed:liputils: a Python module to manage individual fatty acid moieties from complex lipidsStefano Manzini, Marco Busnelli, Alice Colombo, Mostafa Kiamehr, Giulia ChiesaPMID:32770020PMCID:PMC7415148DOI:10.1038/s41598-020-70259-9Tracking individual residues is is particularly useful when wanting to track how the carbon chains move across the lipidome, independently from where they are attached to. For instance, it is possible to see if the general trend of long carbon residues in the plasma matches the data available from the dietary treatment.The swiftest way to convert your lipidomic data into a residue count (usually given in submolar fractions) is by usingliputils' built-in GUI:>>>fromliputilsimportGUI>>>GUI()This brings up the GUI (here's what it looks like in MacOS):The GUI acts as a wrapper formake_residues_table(), enabling a fast two-click conversion of any source table. All is required is to1) choose the tableto convert and 2)Processthe table. When hitting(2) Process, the user is first asked to choose where to put and how to call the newly produced table, then everything happens automatically.That's it!Try running it with default settings(the ones the GUI starts up with)on thesample data.Of course we're taking a lot for granted, but this was just a quick start, dig down in the doc to find out things likehow data needs to be shapedorwhat lipid identifiers are supported, as well as what elseliputilscan do for you within a Python REPL.TheLipidclass takes care of extracting information from the lipid name:>>>fromliputilsimportLipid>>>l=Lipid("PG 18:1/20:1",amount=0.012512)>>>l.lipid_class()'PG'>>>l.name'PG 18:1/20:1'>>>l.residues()(['18:1','20:1'],1)>>>l.molecules7534902640.2784>>>l.amount# the original value is stored here0.012512The number of molecules is calculated from theamountparameter, defaulting to picomoles. This can be changed:>>>l=Lipid("PG 18:1/20:1",amount=0.012512,unit="femtomoles")>>>l.molecules7534902.640278401In the case of unresolved ambiguities of the lipid isomers, it is possible to either extract all of them and choose how to manage that information by taking into consideration how many ambiguities there are:>>>l=Lipid("TAG 48:2 total (14:0/16:0/18:2)(14:0/16:1/18:1)(16:0/16:1/16:1)")>>>l.residues()(['14:0','16:0','18:2','14:0','16:1','18:1','16:0','16:1','16:1'],3)Or, it is possible to reject non unambiguous lipids altogether by calling.residues()with thedrop_ambiguousparameter:>>>l=Lipid("PG 18:1/20:1")>>>l.residues(drop_ambiguous=True)(['18:1','20:1'],1)>>>l=Lipid("TAG 48:2 total (14:0/16:0/18:2)(14:0/16:1/18:1)(16:0/16:1/16:1)")>>>l.residues(drop_ambiguous=True)([],0)Data formatsliputilsaccepts a generic lipid format in the form ofCLASS N:N/M:M/../..orCLASS(N:N/M:M/../..)(other mass isomers), or fullyRefMet-compliant residue naming. If unsure about your data format, you can try and batch-translate your lipid IDs withRefMet's online translator. By adhering to RefMet's nomenclature, any compliant lipid name will be properly managed byliputils's method.refmet_residues():>>>lip1=Lipid("octadecatrienoic acid")>>>lip2=Lipid("linolenic acid")>>>lip3=Lipid("FA(18:3)")>>>lip1.refmet_residues()(['18:3'],1)>>>lip2.refmet_residues()(['18:3'],1)>>>lip3.refmet_residues()(['18:3'],1)Composite compounds can also be fed toliputils:>>>l=Lipid("linoleyl palmitate")>>>l.refmet_residues()(['18:1','16:0'],1)One-step lipidomics data conversionLipidomics data should be loaded in apandas.DataFrametable. The accepted format is a vertical index with lipid names, and samples in column. Just like this:make_residues_table()will take care of dropping non-numerical columns, as well as to trim the lipid list of elements that should not be processed, like total lipid class counts. These can be further specified through theunwantedparameter.
Getting the transformed table is super easy:fromliputilsimportmake_residues_table# df is out dataframeres=make_residues_table(df)Inres, we will find the resulting table:To focus on particular residues, it is possible to mixsaturated()andmax_carbon()to dictate which residues to keep in the index and which to discard:fromliputilsimportsaturated,max_carbon>>>saturated("12:0")True>>>max_carbon("12:0",16)True>>>max_carbon("21:3",16)False>>>my_lipids=["12:0","17:1","24:0","24:1","24:2","26:3"]>>>[notsaturated(x)andmax_carbon(x,24)forxinmy_lipids][False,True,False,True,True,False]For further info, don't forget to investigate around:help(make_residues_table)Parameters
==========

dataframe: a pandas dataframe of data. Lipid names as index, and samples as columns
    (just unlike sklearn wants it, but as you might get it from Tableau software
    tables. Just dataframe.T your table - that would just do the trick).

drop_ambiguous: <bool> don't take isobars into consideration. Defaults to False. If True,
    each residue is divided by its uncertainty.

name: <str> a tag that gets attached to the returned dataframe, so you can use it
    to save it afterwards. The tag is found in the .name attribute.

replace_nan: <object> the object you would like to replace your missing values with.
    It can be set to False, but I would suggest against that.

cleanup: <bool> Whether to perform a cleanup of unwanted lipids that can be present
    in the index. Unwanted strings are read from the 'unwanted' parameter. Defaults
    to True

absolute_amount <bool> Wheter to count the individual number of residues, rather to
    sticking to the same units found in the original table. Defaults to False

unwanted: <list> <set> <tuple> Strings that must be removed from the lipid index. Defaults
    to ["total", "fc", "tc"]

returns:
========

pandas DataFrame