{"id":19592823,"url":"https://github.com/soedinglab/tejaas","last_synced_at":"2025-04-27T14:33:56.979Z","repository":{"id":57473819,"uuid":"106803031","full_name":"soedinglab/tejaas","owner":"soedinglab","description":"Tejaas - a tool for discovering trans-eQTLs","archived":false,"fork":false,"pushed_at":"2022-10-14T18:42:25.000Z","size":38564,"stargazers_count":11,"open_issues_count":2,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-24T11:52:00.417Z","etag":null,"topics":["eqtl","eqtl-mapping","gene-expression","gtex","reverse-regression","trans-eqtl"],"latest_commit_sha":null,"homepage":"https://github.com/soedinglab/tejaas/wiki","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soedinglab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-13T09:11:45.000Z","updated_at":"2024-12-21T15:55:42.000Z","dependencies_parsed_at":"2022-09-10T11:42:34.894Z","dependency_job_id":null,"html_url":"https://github.com/soedinglab/tejaas","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soedinglab%2Ftejaas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soedinglab%2Ftejaas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soedinglab%2Ftejaas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soedinglab%2Ftejaas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soedinglab","download_url":"https://codeload.github.com/soedinglab/tejaas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251154823,"owners_count":21544563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eqtl","eqtl-mapping","gene-expression","gtex","reverse-regression","trans-eqtl"],"created_at":"2024-11-11T08:37:07.037Z","updated_at":"2025-04-27T14:33:51.965Z","avatar_url":"https://github.com/soedinglab.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tejaas: Discover trans-eQTLs\n\n## Description\n\nTejaas is a command line tool to find trans-eQTLs from eQTL data.\nIt is released under the GNU General Public License version 3.\n\nTejaas is based on the hypothesis that a trans-eQTL should regulate the expression levels of multiple genes.\nIn brief, it implements two statistical methods to find trans-eQTLs:\n- **RR-score (Reverse Regression)**: It performs a multiple linear regression with L\u003csub\u003e2\u003c/sub\u003e-regularization \nusing expression levels of all genes to explain the genotype of a candidate SNP.\nIn contrast to conventional methods, the direction of the regression is reversed, with the gene expressions as explanatory variables.\nRR-score is a statistic which estimates whether more genes are required to explain the allele counts of a SNP than expected by chance.\n- **JPA-score (Joint P-value Analysis)**: It evaluates the distribution of p-values of the pairwise linear association of a candidate SNP with all available gene expression levels. \nAny null SNP (no trans-effect) will have a uniform distribution of p-values,\nwhile a trans-eQTL will be associated with more genes than expected by chance, leading to overdispersion near zero. \nThe JPA-score is a statistic which estimates whether the distribution of p-values is significantly overdispersed near zero.\n\nAdditionally, it also implements a non-linear unsupervised confounder correction using k-nearest neighbors called **KNN correction**.\n\n## Dependencies\n\n- Python version 3.6 or higher\n- C compiler\n- Any linear algebra routine, e.g. Intel MKL, OpenBLAS, etc.\n- Any flavor of Message Passing Interface (MPI), e.g. OpenMPI, MPICH, etc.\n- Other Python libraries:\n  - [NumPy](http://www.numpy.org/) / array operations\n  - [SciPy](https://www.scipy.org/) / optimization and other special functions\n  - [statsmodel](http://www.statsmodels.org/stable/index.html) / used for ECDF calculation in JPA-score\n  - [Pygtrie](https://pypi.org/project/pygtrie/) / used for reading MAF file in RR-score / maf null\n  - [mpi4py](https://mpi4py.readthedocs.io/en/stable/) / linked to MPI and MKL for python parallelization\n  - [scikit-learn](https://scikit-learn.org/stable/index.html) / used for PCA decomposition in KNN correction\n\n\u003c!--\nYou can find examples of getting started here:\n- [Example 1 (GWDG Cluster)](https://github.com/soedinglab/tejaas/wiki/GWDG-Cluster)\n- [Example 2 (Minion)](https://github.com/soedinglab/tejaas/wiki/Minion2)\n--\u003e\n\n## Installation\n\nSee the wiki for detailed [installation instructions](https://github.com/soedinglab/tejaas/wiki/Installation). \nHere is a quick start guide:\n\n### 1. Install dependencies\nInstallation of Tejaas depends on other dependencies. If you are using `conda`, then they can be installed using\n```\nconda install numpy scipy statsmodels scikit-learn\npip install mpi4py\n```\n\n### 2. Install Tejaas\n2a. Tejaas can be installed directly from the PyPI repository:\n```\npip install tejaas\n```\n2b. You can also download this repository and build Tejaas:\n```\ngit clone git@github.com:soedinglab/tejaas.git\ncd tejaas\npip install -e .\n```\n\n### 3. Run Tejaas!\n```\ntejaas [OPTIONS]\n```\nSee below for valid options or try `tejaas --help`.\n\n#### Run an example to check installation\nAn example script `example/run_example.sh` is provided to check the installation.\n```\ncd tejaas/example\n./run_example.sh \u003coutdir\u003e \u003cncpu\u003e\n```\nThe script will download some example input files in `\u003coutdir\u003e/data` and run Tejaas on `\u003cncpu\u003e` cores.\nThe output will be created in `\u003coutdir\u003e/data`. \nNote that the `data` subdirectory is automatically created within the `\u003coutdir\u003e` specified by the user.\nCheck if the output is correct:\n```\npython compare_with_gold.py --outdir \u003coutdir\u003e\n```\nThis will check if the output in `\u003coutdir\u003e/data` \n(again note that `data` subdirectory is automatically appended and need not be specified by the user)\nmatches with the results provided in the `example/gold` subdirectory.\n\n## Input Files\n- Gene expression file\n- Genotype file\n  - VCF\n  - Oxford\n  - Dosage\n- GENCODE file\n- Population minor allele frequency\n\n## Tejaas [OPTIONS]\n\nOption\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;| Argument | Description | Priority | Default value\n:--- | :--- | :---        |:---      | :--\n`--vcf`       | `FILEPATH` | Input genotype file in vcf.gz format | Required (vcf or oxf) | --\n`--oxf`       | `FILEPATH` | Input genotype file in Oxford format | Required (vcf or oxf) | --\n`--dosage`    |            | Flag for reading dosage files. The file is specified with the `--oxf` option, e.g. `--oxf FILEPATH --dosage` | Optional | `False` \n`--fam`       | `FILEPATH` | Input fam file for samples names of Oxford genotype | Optional | -- \n`--chrom`     | `INT`      | Chromosome number of the genotype file | Required | -- \n`--include-SNPs` | `START:END` | Colon-separated index of SNPs to be included | Optional | -- \n`--gx`        | `FILEPATH` | Input gene expression file for trans-eQTL discovery | Required | --\n`--gxcorr`    | `FILEPATH` | Input gene expression file for target gene discovery | Optional | `--gx` file\n`--gxfmt`     | `OPTION`   | Input gene expression file format (see format details below). Supported options: `gtex`, `cardiogenics`, `geuvadis` | Optional | `gtex`\n`--gtf`       | `FILEPATH` | Input GTF file from GENCODE to read gene Ensembl IDs. Used for selecting biotypes and getting genomic locations. | Required | --\n`--trim`      |            | Flag to trim version number from GENCODE Ensembl IDs | Optional | `False`\n`--biotype`   | `OPTION`   | Which biotypes to select from the GTF file. Supported options: `protein_coding`, `lncRNA`. | Optional | `protein_coding lncRNA`\n`--outprefix` | `STRING`   | Full path to output file names. The extensions are generated by Tejaas. | Optional | `out`  \n`--method`    | `OPTION`   | Name of method to run. Supported options: `jpa` or `rr` | Optional | `rr`\n`--null`      | `OPTION`   | Null model to use for RR-score. Supported options: `perm` or  `maf` | Optional | `perm` \n`--cismask`   |            | Flag to mask cis-Genes within a window  for each candidate SNP. Gene positions are obtained from the GENCODE annotation file.  | Optional | `False`\n`--window`    | `FLOAT`    | Window (number of base pairs) used for masking cis genes | Optional | 1e6 \n`--prior-sigma`| `FLOAT`   | Standard deviation of the normal prior for reverse multiple linear regression | Optional | 0.1\n`--knn`       | `INT`      | Number of neighbours for KNN (use 0 if you do not want to use KNN) | Optional | 0\n`--psnpthres` | `FLOAT`    | Target genes will be reported only for trans-eQTLs below this threshold p-value for RR/JPA-score | Optional | 0.0001\n`--pgenethres`| `FLOAT`    | Target genes will be reported only if their association with trans-eQTLs are below this threshold p-value | Optional | 0.05\n`--jpanull`   | `FILEPATH` | File containing list of null model JPA-scores | Optional | -- \n`--maf-file`  | `FILEPATH` | Read minor allele frequency (MAF) of SNPs from this file, e.g. to read population MAF for `maf` null (see documentation for file format) | Optional | -- \n`--shuffle`   |            | Flag to randomly shuffle the genotypes to obtain a null distribution | Optional | `False`\n`--shuffle-with` | `FILEPATH` | Shuffle the genotypes in the same order of donor IDs specified in `FILEPATH` | Optional | --\n\u003c!--\n`--test`      |            | Flag to do test run | Optional | -- \n--\u003e\n\n## Usage Examples\n\n1. For quick start or installation check, run Tejaas with all default options:\n```\ntejaas --vcf ${VCFFILE} --chrom ${CHRM} --gx ${GXFILE} --gtf ${GTFFILE} --cismask --outprefix ${OUTPREFIX}\n```\nThis will create RR-scores at \u0026gamma;=0.1 and masking all genes within 1Mb of each SNP. The p-values will be computed from the permuted null model.\nDefault format for the gene expression is the same as the GTEx format, and default gtf file is the [GENCODE v26](https://www.gencodegenes.org/human/release_26.html) release.\nFor target gene discovery, it will use the same file as used for trans-eQTL discovery.\n\n2. Example of running Tejaas RR-score.\nWe recommend using the `perm` null model for calcuting p-values from the RR-score\nand a separate confounder-corrected gene expression file for target gene discovery.\nIn this example, RR-score is calculated for first 1000 SNPs excluding the first 20 `--include-SNPs 21:1000`.\nKNN correction is performed with 20 nearest neighbors `--knn 20`.\nAll cis-genes within +2MB and -2Mb are masked during analysis `--cismask --window 2e6`.\nRR-score calculation uses a prior normal distribution with standard deviation of 0.05 `--prior-sigma 0.05`.\nThe output reports target genes only for SNPs with p-value \u003c 1e-6 `--psnpthres 0.000001`.\nHere, `GXFILE` is the raw gene expression file, `GXCORRFILE` is the confounder-corrected gene expression file,\n`VCFFILE` is the genotype file in `.vcf.gz` format and `GTFFILE` is the GENCODE annotation file.\n```\nmpirun -n 8 tejaas --vcf ${VCFFILE} --chrom ${CHRM} --include-SNPs 21:1000 --gx ${GXFILE} --gxcorr ${GXCORRFILE} \\\n                   --gxfmt gtex --gtf ${GTFFILE} --trim  --outprefix ${OUTPREFIX} \\\n                   --cismask --window 2e6 --psnpthres 0.000001 \\\n                   --knn 20 --method rr --null perm --prior-sigma 0.05\n```\n\n3. Example of running JPA-score with no KNN correction. \nEmpirical p-values are calculated from the null scores loaded from `NULLFILE` specified by the `--jpanull` option.\nIf `NULLFILE` does not exist, then it will create `100000` null scores and write them in the `NULLFILE` before calculating JPA-scores.\nIf `--jpanull` option is not used, then p-values for the JPA-scores are calculated from an analytical construction of null model.\n```\nmpirun -n 8 tejaas --vcf ${VCFFILE} --chrom ${CHRM} --include-SNPs 1:100 \\\n                   --gx ${GXFILE} --gxfmt gtex --gtf ${GTFFILE} --outprefix ${OUTPREFIX} \\\n                   --knn 0 --method jpa --jpanull ${NULLFILE}\n```\n\n4. Example of parallelizing job submission.\n```\nNMAX=20000 # number of SNPs per job\nfor CHRM in $( seq 1 22 ); do\n    VCFFILE=\"file_path_here_${CHRM}.vcf.gz\"\n    NTOT=$( calculate_no_of_SNPs_in_this_chromosome )\n    NJOB=$( echo $(( (NTOT + NMAX - 1)/NMAX )) )\n    for (( i=0; i \u003c ${NJOB}; i++ )); do\n        STARTSNP=$(( NMAX * i + 1 ))\n        ENDSNP=$(( NMAX * (i + 1) ))\n        if [ ${ENDSNP} -gt ${NTOT} ]; then\n            ENDSNP=${NTOT}\n        fi\n        mpirun -n 8 tejaas --vcf ${VCFFILE} --chrom ${CHRM} --include-SNPs ${STARTSNP}:${ENDSNP} --gx ${GXFILE} --gxcorr ${GXCORRFILE} \\\n                           --gxfmt gtex --gtf ${GTFFILE} --trim  --outprefix ${OUTPREFIX} \\\n                           --cismask --psnpthres 0.000001 --knn 20 --method rr --null perm --prior-sigma 0.05\n    done\ndone\n```\n\n## Contributors\n\u003ca href=\"https://github.com/soedinglab/tejaas/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contributors-img.web.app/image?repo=soedinglab/tejaas\" /\u003e\n\u003c/a\u003e\n\n## Version History\n1.0.2 Bump release version\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoedinglab%2Ftejaas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoedinglab%2Ftejaas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoedinglab%2Ftejaas/lists"}