Metadata-Version: 2.1
Name: mieaa
Version: 0.1.0
Summary: miEAA command line interface and api wrapper
Home-page: https://www.ccb.uni-saarland.de/mieaa_tool
Author: Jeffrey Solomon
Maintainer: Chair for Clinical Bioinformatics at Saarland University
Maintainer-email: ccb.unisb@gmail.com
License: MIT
Download-URL: https://pypi.org/project/mieaa/#files
Project-URL: Bug Tracker, https://github.com/Xethic/miEAA-API/issues
Project-URL: Documentation, https://github.com/Xethic/miEAA-API
Project-URL: Source Code, https://github.com/Xethic/miEAA-API
Description: # miEAA CLI and API Wrapper
        
        The miRNA Enrichment Analysis and Annotation Tool (miEAA) facilitates the functional analysis of sets of miRNAs.  
        This package provides a command line interface and wrapper for the miEAA API.
        
        To learn more about miEAA or to utilize our online interface, please visit our [web server](https://www.ccb.uni-saarland.de/mieaa_tool).  
        All miEAA tools are provided and hosted by the [Chair for Clinical Bioinformatics at Saarland University](https://www.ccb.uni-saarland.de/).
        
        This package allows users to execute miEAA directly from the command line:
        
        ```
        $ mieaa -h
        ```
        
        An API wrapper is also provided for scripting purposes:
        
        ```Python
        from mieaa import API
        
        mieaa_api = API()
        ```
        
        ## Installation
        
        Dependencies:
        
        * Python >= 3.5
        * Requests >= 2.19
        
        miEAA can be easily installed via pip or Anaconda:
        
        ```
        $ pip install mieaa
        ```
        
        ```
        $ conda install -c ccb-sb mieaa
        ```
        
        ## Examples
        
        For example usage, see the [example Python script](https://github.com/Xethic/miEAA-API/tree/master/examples/Python/).  
        Using the [reticulate](https://github.com/rstudio/reticulate) library, users can utilize our package in R (Python installation is still required). As such, an [example R script](https://github.com/Xethic/miEAA-API/tree/master/examples/R/) is also provided.
        
        
        ## Command Line Interface
        
        Commands can be invoked using `mieaa SUBCOMMAND`.  
        Help and options for all subcommands can be invoked using `mieaa SUBCOMMAND -h`
        
        |Subcommand|Description|
        |-|-|
        |to_precursor|Convert miRNAs to precursors|
        |to_mirna|Convert precursors to miRNAs|
        |convert_mirbase|Convert mirBase version|
        |gsea|Run Gene Set Enrichment Analysis|
        |ora|Run Over-representation Analysis|
        
        Commands may require specifying if input is from a list of strings or a file (see `-m/M in examples, below`).  
        In such cases, the flag letter is identical, with lowercase specifying string/list, and uppercase specifying a file.
        
        
        ### Important Notes
        
        **Specifying precursors**  
        For subcommands where you need to specify precursor or mature, mature is always assumed unless the `--precursor` (`-p`) flag is set.
        
        **Mutually exclusive options**  
        Each subcommand requires either `--mirna-set` (`-m`) or `--mirna-set-file` (`-M`) to be specified. Enrichment analyses also require similarly behaving arguments for categories, and optionally for reference sets in the case of ORA. 
        
        * `miea SUBCOMMAND --mirna-set MIRNA [MIRNA ...]`
        * `miea SUBCOMMAND --mirna-set MIRNAS_STRING`
        * `miea SUBCOMMAND --mirna-set-file MIRNA_FILE`
        
        ### Converting miRNA -> precursor
        
        * `mieaa to_precursor [-m | -M] -FLAGS`
        
        ```
        $ mieaa to_precursor -m hsa-miR-20b-5p hsa-miR-144-5p --tabsep --unique
        $ mieaa to_precursor -m 'hsa-miR-20b-5p,hsa-miR-144-5p' -o precursors.txt
        $ mieaa to_precursor -M mirnas.txt --outfile precursors.txt
        ```
        
        ### Converting between precursor -> miRNA
        
        * `mieaa to_mirna [-m | -M] -FLAGS`
        
        ```
        $ mieaa to_mirna -m hsa-mir-20b hsa-mir-144 --tabsep --unique
        $ mieaa to_mirna -m 'hsa-mir-20b,hsa-mir-144' -o mirnas.txt
        $ mieaa to_mirna -M precursors.txt --outfile mirnas.txt
        ```
        
        ### Converting miRBase version
        
        `mieaa convert_mirbase FROM_VERSION [-m | -M] -FLAGS`
        
        ```
        $ mieaa convert_mirbase 16 -m hsa-miR-642b,hsa-miR-550b
        $ mieaa convert_mirbase 16 --to 22 -m hsa-miR-642b hsa-miR-550b
        $ mieaa convert_mirbase 16  -M version_16.txt -o version_22.txt
        ```
        
        ### Gene Set Enrichment Analysis (GSEA)
        
        `mieaa gsea SPECIES [-m | -M] [-c | -C] -FLAGS`
        
        Species can be specified as `hsa`, `mmu`, or `rno`.
        The category flags (`-c -C`) behave identically to the miRNA set flags (`-m -M`).
        
        ```
        $ mieaa gsea hsa --precursors -M precursors.txt -C categories.txt -o results.csv
        $ mieaa gsea hsa -p -M precursors.txt -c HMDD MNDR > results.csv
        $ mieaa gsea mmu -M mirnas.txt -C categories.txt --adjustment none
        $ mieaa gsea rno -M mirnas.txt -C categories.txt -a bonferonni --json -o results.json
        ```
        
        ### Over-representation Analysis (ORA)
        
        `mieaa ora SPECIES [-m | -M] [-c | -C] -FLAGS`
        
        Species can be specified as `hsa`, `mmu`, or `rno`.
        The category flags (`-c -C`)  and reference set flags (`-r -R`) behave identically to the miRNA set flags (`-m -M`).
        
        ```
        $ mieaa ora hsa --precursors -M precursors.txt -C categories.txt > results.csv
        $ mieaa ora hsa -p -M precursors.txt -c HMDD MNDR -o results.csv
        $ mieaa ora hsa -p -M precursors.txt -C categories.txt -R reference.txt
        $ mieaa ora mmu -M mirnas.txt -C categories.txt --adjustment none
        $ mieaa ora rno -M mirnas.txt -C categories.txt -a bonferonni --json -o results.json
        ```
        
        ## API Wrapper
        
        The miEAA API can be easily utilized via the `API` class.
        
        ### API Class
        
        ``` python
        from mieaa import API
        
        mieaa_api = API()
        ```
        
        ### Attributes
        `job_id` - unique job identifier tied to this instance after starting an enrichment analysis
        
        ### Methods
        
        #### convert_mirbase_version
        
        ```
        mieaa_api.convert_mirbase_version(mirnas, from_version, to_version, input_type, to_file='', output_format='oneline')
        ```
        
        *parameters*
        
        * `mirnas` - str, list-like, or file-object
          * set of either mature miRNAs or precursors we want to convert
        * `from_version` - float
          * miRBase version we want to convert given set from
        * `to_version` - float
          * miRBase version we want to convert given set to
        * `input_type` - 'precursor' or 'mirna'
          * Whether the provided set includes precursors or mature miRNAs
        * `to_file` - file-object or str
          * If provided, converted miRNA/precursor set will be saved
        * `output_format` - 'oneline' or 'tabsep'
          * 'oneline': Text containing only converted miRNAs/precursors
          * 'tabsep': Tab-separated input and output miRNAs/precursors
        
        *return*
        
          `list` - converted miRNAs/precursors
        
        #### convert_mirna_to_precursor
        
        ```
        mieaa_api.convert_mirna_to_precursor(mirnas,  to_file='', output_format='oneline', conversion_type='all')
        ```
        
        *parameters*
        
        * `mirnas` - str, list-like, or file-object
          * set of either mature miRNAs or precursors we want to convert
        * `to_file` - file-object or str
          * If provided, converted miRNA/precursor set will be saved
        * `output_format` - 'oneline' or 'tabsep'
          * 'oneline': Text containing only converted miRNAs/precursors
          * 'tabsep': Tab-separated input and output miRNAs/precursors
        * `conversion_type`: 'all' or 'unique'
          * 'all': Output all newly converted precursors
          * 'unique': Only output precursors with unique mappings
        
        *return*
        
          `list` - newly converted precursors
        
        #### convert_precursor_to_mirna
        
        ``` python
        mieaa_api.convert_precursor_to_mirna(mirnas,  to_file='', output_format='oneline', conversion_type='all')
        ```
        
        *parameters*
        
        * `mirnas` - str, list-like, or file-object
          * set of either mature miRNAs or precursors we want to convert
        * `to_file` - file-object or str
          * If provided, converted miRNA/precursor set will be saved
        * `output_format` - 'oneline' or 'tabsep'
          * 'oneline': Text containing only converted miRNAs/precursors
          * 'tabsep': Tab-separated input and output miRNAs/precursors
        * `conversion_type`: 'all' or 'unique'
          * 'all': Output all newly converted miRNAs
          * 'unique': Only output miRNAs with unique mappings
        
        *return*
        
          `list` - newly converted miRNAs
        
        #### run_gsea
        
        ``` python
        mieaa_api.run_gsea(test_set, categories, input_type, species, p_value_adjustment='fdr', significance_level=0.05, independent_p_adjust=True, threshold_level=2)
        ```
        
        *parameters*
        
        * `test_set` - str, list-like, or file-object
          * set of either mature miRNAs or precursors we want to convert
        * `categories` - str, list-like, or file-object
          * set of categories use in enrichment analysis
        * `input_type` - 'precursor' or 'mirna'
          * Whether the provided set includes precursors or mature miRNAs
        * `species` - 'hsa', 'mmu', 'rno'
          * 'hsa': Homo sapiens
          * 'mmu': Mus musculus
          * 'rno': Rattus norvegicus
        * `p_value_adjustment` - 'none','fdr','bonferroni','BY','holm','hochberg','hommel'
          * 'none' - No adjustment
          * 'fdr' - FDR (Benjamini-Hochberg) adjustment
          * 'bonferroni' - Bonferroni adjustmen
          * 'BY' - Benjamini-Yekutieli adjustment
          * 'hochberg' - Hochberg adjust
          * 'holm' - Holm adjustment
          * 'hommel' - Hommel adjustment
        * `significance_level` - float
          * Filter out p-values above specified level
        * `independent_p_adjust` - bool
          * True: Adjust p-values for each category independently
          * False: Adjust p-values for all categories collectively
        * `threshold_level` - int
          * Filter out subcategories containing less than this many miRNAs/precursors
        
        *return*
        
          `requests.Response` - API response
        
        #### run_ora
        
        ``` python
        mieaa_api.run_ora(test_set, categories, input_type, species, reference_set='', p_value_adjustment='fdr', significance_level=0.05, independent_p_adjust=True, threshold_level=2)
        ```
        
        *parameters*
        
        * `test_set` - str, list-like, or file-object
          * set of either mature miRNAs or precursors we want to convert
        * `categories` - str, list-like, or file-object
          * set of categories use in enrichment analysis
        * `input_type` - 'precursor' or 'mirna'
          * Whether the provided set includes precursors or mature miRNAs
        * `species` - 'hsa', 'mmu', 'rno'
          * 'hsa': Homo sapiens
          * 'mmu': Mus musculus
          * 'rno': Rattus norvegicus
        * `reference_set` - str, list-like, or file-object
          * If specified, use as background reference set
        * `p_value_adjustment` - 'none','fdr','bonferroni','BY','holm','hochberg','hommel'
          * 'none' - No adjustment
          * 'fdr' - FDR (Benjamini-Hochberg) adjustment
          * 'bonferroni' - Bonferroni adjustmen
          * 'BY' - Benjamini-Yekutieli adjustment
          * 'hochberg' - Hochberg adjust
          * 'holm' - Holm adjustment
          * 'hommel' - Hommel adjustment
        * `significance_level` - float
          * Filter out p-values above specified level
        * `independent_p_adjust` - bool
          * True: Adjust p-values for each category independently
          * False: Adjust p-values for all categories collectively
        * `threshold_level` - int
          * Filter out subcategories containing less than this many miRNAs/precursors
        
        *return*
        
          `requests.Response` - API response
        
        #### get_enrichment_Parameters
        
        ```
        mieaa_api.get_enrichment_Parameters()
        ```
        
        *return*
        
          `dict` - Parameters that were provided when calling `run_gsea()` or `run_ora()`
        
        #### get_results
        
        ```
        mieaa_api.get_results(results_format='json', check_progress_interval=5)
        ```
        
        *parameters*
        
        * `results_format` - 'json' or 'csv'
          * Whether to retrieve results as json or as a csv string
        * `check_progress_interval` - float
          * How many seconds to wait in between checking if results have finished computing
        
        *return*
        
          `list` or `str` containing the results
        
        #### save_enrichment_results
        
        ``` python
        mieaa_api.save_enrichment_results(save_file, file_type='csv', check_progress_interval=5)
        ```
        
        *parameters*
        
        * `save_file` - str or file-object
          * Where to save the results
        * `file_type` - 'csv' or 'json'
          * File format we want to save results as
        * `check_progress_interval` - float
          * How many seconds to wait in between checking if results have finished computing
        
        *return*
        
        * `str` - results as they were written to file
        
        #### invalidate
        Invalidate this instance. Previous results become irretrievable, but can now be used to run a fresh analysis.
        
        ``` python
        mieaa_api.invalidate()
        ```
        
        *return*
        
        None
        
        #### get_enrichment_categories
        
        ```
        mieaa_api.get_enrichment_categories(input_type, species, with_suffix=False)
        ```
        
        *parameters*
        
        * `input_type` - 'precursor' or 'mirna'
          * Whether the provided set includes precursors or mature miRNAs
        * `species` - 'hsa', 'mmu', 'rno'
          * 'hsa': Homo sapiens
          * 'mmu': Mus musculus
          * 'rno': Rattus norvegicus
        * `with_suffix` - bool
          * Whether to include '_precursor' or '_mature' suffix in category names
          
        *return*
          `dict` - keys are the category names, values are a short description
        
Keywords: mirna bioinformatics
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.5.*, <4
Description-Content-Type: text/markdown
