# -*- coding: utf-8 -*-
from setuptools import setup

packages = \
['lta', 'lta.commands', 'lta.helpers']

package_data = \
{'': ['*']}

install_requires = \
['ConfigArgParse>=1.5,<2.0', 'numpy>=1.22.2,<2.0.0', 'pandas>=1.3,<2.0']

entry_points = \
{'console_scripts': ['lta = lta.cli:main']}

setup_kwargs = {
    'name': 'lipidta',
    'version': '3.0.0',
    'description': 'Lipid Traffic Analysis',
    'long_description': '# Lipid Traffic Analysis\n\n[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![PyPI Version](https://img.shields.io/pypi/v/lipidta)](https://pypi.org/project/gtexquery/)\n[![Python Versions](https://shields.io/pypi/pyversions/lipidta)](https://shields.io/pypi/pyversions/lipidta)\n[![CI/CD](https://github.com/IMS-Bio2Core-Facility/lta/actions/workflows/cicd.yaml/badge.svg)](https://github.com/IMS-Bio2Core-Facility/lta/actions/workflows/cicd.yaml)\n[![codecov](https://codecov.io/gh/IMS-Bio2Core-Facility/lta/branch/main/graph/badge.svg?token=2TGYX69U3N)](https://codecov.io/gh/IMS-Bio2Core-Facility/lta)\n[![Documentation Status](https://readthedocs.org/projects/lta/badge/?version=latest)](https://lta.readthedocs.io/en/latest/?badge=latest)\n[![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n[![Codestyle: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)\n\n**aka LTA, aka LipidTA**\n\nA python commandline interface for analysing lipidomics data.\n\nThe source code lives on [github][github].\n\nThe documentation lives at [ReadTheDocs][readthedocs].\n\nThe project can be installed from [PyPI][pypi].\n\n## Abstract\n\nLipid Traffic Analysis (LTA) is a tool for using lipidomics data to test hypotheses about how metabolism is controlled.\nLipidomics data from several, metabolically connected tissues from control and experimental groups\ncan be used to plot the spatial or temporal distribution of lipids.\nThese distributions identify where changes in lipid metabolism occur and in which lipid pathways,\nindicating the locus and biochemical alterations that occur in a given group.\nLTA was conceived in two parts.\nOne is an Abundance Analysis,\nin which the error-normalised fold change (ENFC) for the control and given group group is calculated.\nBecause the ratio of the control and experimental values is scaled by the error,\nthe ENFCs are easy to plot and compare between compartments.\nThe second part is a Switch Analysis.\nThis computes the presence of variables across the network.\nCurrent development is focused on developing the technique for complex networks and on the rate of lipid transport.\n\n### On Version Numbers\n\n```{admonition} TLDR\nPrior to version 3,\nthe Python implementation version **does not** correlate to the academic versions.\nFrom version 3,\nthe Python and academic versions are the same.\n```\n\nLTA was developed initially in R,\nproducing [LTA v1.0][lta_v1].\nThis was used for the LTA in the first study to use the analysis,\nbased on the hypothesis that differing carbohydrate intakes by fathers\ninfluenced their children\'s and grandchildren\'s lipid metabolism.\nSee [Furse et al 2021][paper_1].\nThe code was developed further in R to improve convenience for the user,\nand features such as the 0s threshold\n(the number of samples in which there is a non-zero value for abundance for it to count as present)\nwas added for LTA v2.3.\nThis version has been used in three subsequent studies.\nPlease see [here][paper_2],\n[here][paper_3],\nand [here][paper_4].\nA desire to add more features and move to a more stable platform led us to move to Python for LTA v3.0.\n\nThe Python implementation of LTA has strictly used automated semantic versioning over the course of its development.\nThus,\nprior to version 3,\n**the version numbers of the Python inplementation and past R implementations have no correlation.**\nBy convenient coincidence,\nthe semantic versioning release of LipidTA v3 brings\nthe python versioning and the academic versioning in-line.\n\n## Using LTA from the command line\n\n### Installation\n\nAny installation of this tool requires Python.\nHow to install Python correctly is beyond this scope,\nbut there are some excellent resources available\n[here][realpython]\nand [here][psf].\nIf you are planning to have multiple versions of python installed,\nyou might want to consider [pyenv][pyenv].\n\n```{warning}\nWe only support Python {math}`>=` 3.7.1\n```\n\n#### Installing from PyPI\n\nThis is the most straightforward way to set up the tool.\nWhen installing from PyPI,\nwe strongly reccomend using a virtual environment.\nThere are many ways to do this!\nIf you already have a preferred method -\nI use [pipx][pipx] for command line tools -\nfeel free to use that.\nOtherwise,\nuse the builtin Python module [venv][venv].\nThe exact instructions are OS-specific and detailed at the above link.\nInstructions for installing the most recent version of LTA on MacOS are given below:\n\n```shell\n# Make a directory for the project\nmkdir lta && cd lta\n# Create the virtual environment\npython3 -m venv .venv\n# Activate the environment\nsource .venv/bin/activate\n# Install lta\npip install -U LipidTA\n```\n\n```{note}\nOur pip package is `LipidTA`.\nUnfortunately,\n`lta` was "too similar to existing package names",\nso PyPi wouldn\'t let us use it.\n```\n\nIf you want to install a specific version,\nthen change the last line in the previous code block to:\n\n```shell\npip install LipidTA==1.0.0\n```\n\nreplacing the version number with the version number you want.\nA list of all released versions can be found at our [tags][tags].\n\n#### Installing from Source\n\n```{important}\nMost users **will not need** these instructions.\n```\n\nIf you need to customise the code in some manner,\nyou\'ll need to install from source.\nTo do that,\neither clone the repository from github,\nor download one of our releases.\nFor full instructions,\nplease see our guide on [contributing](./contributing.md).\n\n(data)=\n\n### The Data\n\nThe input should be a csv containing the lipidomics results.\nThough we strive to be as flexible as possible,\nwe must make some assumptions about the data to be able to use it.\nFirstly,\nthe first 3 columns must be the multiindex for the lipids,\nand include the lipid name,\ncategory,\nand m/z, respectively.\nSecondly,\nthe values must be numeric.\n\nThe analysis depends on a number of key metadata variables,\nnamely:\n\n- Mode: the lipidomics mode\n- Sample ID: a unique sample identifier\n- Group: the experimental condition\n- Compartment: the comartment of origin for the sample\n\nThese rows should be in the first {math}`n` rows of your data file,\nwhere n is specified with the option `--n-rows-metadata`.\nYou can name these metadata rows whatever you want in the data file,\nand tell `lta` where to find them with the appropriate flags.\nWe\'ve done our best to choose sane defaults\n(please see the section on [default values](defaults)),\nand you can see the section on [customising your run](customising)\nfor more details.\nHowever,\nif these data are not present,\nthe tool will not run,\nas the analysis only makes sense in the context of these variables.\n\n```{important}\nShould we make any changes to data format expectations,\nit will be well documented and will only occur in a major/breaking releas.\n```\n\n### Running the analysis\n\nOnce you\'ve installed the tool and activated your virtual environment,\nrunning the analysis **can** be as simple as:\n\n```shell\nlta data.csv results\n```\n\nThe first argument is path to the combined input file.\nIf the file doesn\'t exist,\nis a directory,\nor doesn\'t contain any data files,\nthe command will error with an apropriate message.\nThe secont argument identifies a folder in which the results will be saved.\nIt will be created if it doesn\'t exist.\n\n```{important}\nTo help get you up and running,\na minimum dataset and configuration file are provided [here][examples].\n```\n\n(defaults)=\n\n#### The Defaults\n\nTo keep it as simple as above,\nyou will need to use the defaults,\noutlined in the below table:\n\n| Parameter | Description | Default |\n| :--- | :---: | ---: |\n| threshold | The fraction of samples in which a lipid is 0 before it is dropped | 0.3 |\n| boot-reps | The number of bootstrap repetitions used to calculate probability | 1000 |\n| n-rows-metadata | The number of rows of metadata at the beginning of the data file| 11 |\n| group | The metadata row containing experimental conditions | Group |\n| control | The "control" condition, used as reference for fold change | control |\n| comartment | The metadata row containing the compartment of origin for each sample | Compartment |\n| mode | The metadata row containing the lipidomics mode | Mode |\n| sample-id | The metadata ro containing unique sample identifiers | SampleID |\n\nDon\'t worry if it looks intimidating!\nYou can check out the section on [customising your run](customising)\nfor further details,\nand help can always be found at our [documentation][readthedocs]\nor from the command line with:\n\n```shell\nlta -h\n```\n\n(customising)=\n\n#### Customising\n\nWhile it can be that simple,\nyou\'ll likely have to customise some options for your run.\nIn that case,\nit will likely look a bit more like:\n\n```shell\nlta --n-rows-metadata 11 \\\n--group Group \\\n--control lean \\\n--compartment Compartment \\\n--sample-id mouse\n```\n\nAlternatively,\nyou might prefer to use a configuration file to keep things simple.\nIn that case,\nsee the section on [configuration](configuration)\nfor more information.\n\nThere are a few options that can be customised for any given run.\nThe statistics are calculated using a bootstrapping approach,\nwhich (by definition) involves repeated replicates.\nTo control the number of replicates,\npass the ``-b/--boot-reps`` flag with a number.\nGenerally, more reps improves the accuracy of the estimates,\nthough I find little improvement beyond 20,000 reps.\n1000 (the default number) seems to provide a good balance between speed and accuracy.\n\nA critical step of the analysis is binarizing the lipid expression.\nA lipid is classed as 0 in a compartment/condition if\nthe lipid is **not** detected in more than a particular fraction of samples.\nThe default values is 0.2 (one-fifth of the samples).\nIf you want to change it,\npass the ``-t/--threshold`` flag with a decimal between 0 and 1.\nThis value can have a significant impact on the analysis,\nso explore how it impacts your data!\n\nMany calculations are dependent on knowing where certain metadata is stored.\nNamely, the experimental conditions (specified with ``--group``)\nthe compartment of origin (specified with ``--compartment``),\nthe sample ID (specified with ``--sample-id``),\nand the lipidomics mode (specified with ``--mode``).\nIf these are not passed,\nthen they default to "Group", "Compartment", "SampleID", and "Mode" respectively.\nTo find these rows,\nwe also need to know the number of lines in your column metadata.\nThis is specified with ``--n-rows-metadata``.\nPlease the section on [expected data file structure](data) for more information.\n\nThe error-normalised fold change (ENFC) calculation must know the labels for\nexperimental and control group.\nWithout this knowledge,\nthe concept of fold change is meaningless.\nTo specify, pass ``--control control``.\nEvery condition specified in ``Group`` will then be divided by ``control``\nto calculate the ENFC for all conditions.\n\n```shell\nlta data results --control lean\n```\n\n(configuration)=\n\n#### Configuration files\n\nIf you find yourself regularly passing arguments via the CLI,\nyou might want to try a configuration file!\nThis is a simple text file that stores options in a simple format:\n\n```shell\noption=value\n```\n\nBy default,\nLTA looks for ``lta_conf.txt`` in your current directory.\nHowever,\nyou can name this file whatever you want,\nand let LTA know where to find it,\nby passing the config flag like so:\n\n```shell\nlta -c path/to/your/config.txt data results\n```\n\nIf you specify an option in the configuration file,\nthat will override LTA\'s defaults,\nand specifying an option at the command line will override the configuration file!\nThe config file doesn\'t need do exist, however,\nand is just a bit of sugar.\n\n### The Output\n\n```{warning}\nRe-running the analysis overwrites existing results,\nso be sure to either back up your data,\nor pass a different output folder!\n```\n\nThe output folder will contain 2 files and 2 directories.\nFor each type of lipid, you should see the following:\n\n1. `switch_individual_lipid.csv` - a table of lipids and their A/B/U/N classification.\n1. `switch_lipid_classes.csv` - a table counting the frequency of each lipid class within the A/B/U/N classification.\n1. `jaccard` - the Jaccard similarity and p-value for each lipid class.\n1. `enfc` - a folder containing the ENFC results.\n\nWithin the ENFC folder,\nyou should see 2 files per group:\n\n1. `GROUP_by_CONTROL_individual_lipids.csv` - the ENFC results for each lipid.\n1. `GROUP_by_CONTROL_lipid_classes.csv` - the mean and St.Dev. of ENFC, grouped by lipid class.\n\nWithing the Jaccard folder,\nyou should see 1 file per group:\n\n1. `GROUP_by_CONTROL_jaccard_similarity.csv` - the Jaccard similarity and p-value\nfor each lipid class\n\nA few notes!\nFold change will **always** be {math}`group / control`.\nThe Jaccard similarities are calculated between conditions specified in ``--group``\nacross both compartments and lipid classes.\nThe p-values for these similarities are calculated using the method outlined by\n[N. Chung, et. al.][jaccard].\nFor ENFC,\nfold change is only meaningful if both values are non-0.\nWhere this is *not* true,\nNaN has been substituted,\nleaving an empty cell in the output.\n\n## Contributing\n\nOpen-source software is only open-source becaues of the excellent community,\nso we welcome any and all contributions!\nIf you think you have found a bug,\nplease log a report in our [issues][issues].\nIf you think you can fix a bug,\nor have an idea for a new feature,\nplease see our guide on [contributing](./contributing.md)\nfor more information on how to get started!\nWhile here,\nwe request that you follow our [code of conduct](./coc.md)\nto help maintain a welcoming,\nrespectful environment.\n\n## Future Developments\n\n- [x] Improve Github actions to use caching for poetry and Nox\n- [x] Allow for multiple ENFC calculations in 1 run\n- [x] Provide example configuration and data\n- [ ] Increase test coverage\n- [ ] Automate plotting\n\n## Citations\n\nIf you use LTA in your work,\nplease cite the following manuscripts:\n\n1. Furse, S., _et al._ Lipid Traffic Analysis reveals the impact of high paternal carbohydrate intake on offsprings’ lipid metabolism. _Commun Biol_ **4**, 163 (2021). [https://doi.org/10.1038/s42003-021-01686-1][paper_1]\n1. Furse, S.[^eq], Fernandez-Twinn, D.S.[^eq], _et al._ Lipid metabolism is dysregulated before, during and after pregnancy in a mouse model of gestational diabetes. _Int. J. Mol. Sci._ **22**, 7452 (2021). [https://doi.org/10.3390/ijms22147452][paper_2]\n1. Furse, S., _et al._ Paternal nutritional programming of lipid metabolism is propagated by sperm and seminal plasma. _Metabolomics_ **2022**, [https://doi.org/10.17863/CAM.79565][paper_3]\n1. Furse, S., _et al._ A mouse model of gestational diabetes shows dysregulated lipid metabolism post-weaning, after return to euglycaemia.  _Nutrition & Diabetes_ **2022**, [_In Press_][paper_4]\n\n[^eq]: These authors contributed equally to this work.\n\n[github]: https://github.com/IMS-Bio2Core-Facility/lta "LTA Source Code"\n[readthedocs]: http://lta.readthedocs.io/ "LTA Documentation"\n[pypi]: https://pypi.org/project/gtexquery/ "LTA PyPI Package"\n[realpython]: https://realpython.com/installing-python/ "RealPython Install Python"\n[psf]: https://wiki.python.org/moin/BeginnersGuide/Download "PSF Install Python"\n[pyenv]: https://github.com/pyenv/pyenv "PyEnv"\n[pipx]: https://pypa.github.io/pipx/ "pipx"\n[venv]: https://docs.python.org/3/tutorial/venv.html "Python venv"\n[tags]: https://github.com/IMS-Bio2Core-Facility/lta/releases "LTA releases"\n[issues]: https://github.com/IMS-Bio2Core-Facility/lta/issues "LTA issues"\n[examples]: https://github.com/IMS-Bio2Core-Facility/lta/tree/main/examples "Examples"\n[jaccard]: https://doi.org/10.1186/s12859-019-3118-5 "Jaccard Probabilities"\n[lta_v1]: https://doi.org/10.5281/zenodo.4309347 " LTA, R version 1"\n[paper_1]: https://www.nature.com/articles/s42003-021-01686-1 "LTA citation 1"\n[paper_2]: https://www.mdpi.com/1422-0067/22/14/7452 "LTA citation 2"\n[paper_3]: https://doi.org/10.17863/CAM.79565 "LTA citation 3"\n[paper_4]: https://www.repository.cam.ac.uk/handle/1810/332691 "LTA citation 4"\n',
    'author': 'rbpatt2019',
    'author_email': 'rb.patterson.cross@gmail.com',
    'maintainer': None,
    'maintainer_email': None,
    'url': 'https://github.com/IMS-Bio2Core-Facility/LTA',
    'packages': packages,
    'package_data': package_data,
    'install_requires': install_requires,
    'entry_points': entry_points,
    'python_requires': '>=3.8.0,<3.11',
}


setup(**setup_kwargs)
