# DeepRTAlign v1.2.2
## Overview
DeepRTAlign is a deep learning-based retention time alignment tool for large cohort LC-MS data analysis.
## Installation
1. Install Python3.
2. Install Pytorch CPU version, please refer to https://pytorch.org/.
3. Use `pip install deeprtalign` to install deeprtalign OR download `deeprtalign-1.2.2-py3-none-any.whl` from github [releases](https://github.com/PHOENIXcenter/deeprtalign/releases), and use `pip install deeprtalign-1.2.2-py3-none-any.whl` to install deeprtalign. This step will take 3-4 minutes.
DeepRTAlign is not dependent on a specific operating system, we have tested it on Windows 10, Ubuntu 18.04 and macOS 12.1.
## Getting Started
1. Feature lists and sample list should be prepared before running DeepRTAlign. Feature lists are the output of feature extraction tools (DeepRTAlign supports Dinosaur, OpenMS, MaxQuant, XICFinder and any other text list containing m/z, charge, RT and Intensity information ). The sample list is an excel file recording the correspondences between feature files and sample names. You can find the test data in the example_files folder.
Note that if you use MaxQuant as the feature extraction tool, you should use the allPeptides.txt as the input file or files, and the sample list should correspond to the first column of allPeptides.txt file. DO NOT use "allPeptdes.txt" as the file name in sample list if you use MaxQuant. If you use the old version of MaxQuant (<2.0),please check the 7th column, delete the "Resolution" column if you see it (in MaxQuant v2.0, "Resolution" column is not exists, so we have changed corresponding code).
2. You can get the help information by command `deeprtalign -h`, the basic arguments are as follows:
```
--method {Dinosaur,XICFinder,OpenMS,MaxQuant,TXT,CSV}, -m {Dinosaur,XICFinder,OpenMS,MaxQuant,TXT,CSV}
the feature extraction method, support Dinosaur,
XICFinder, OpenMS, MaxQuant and any other text list containing m/z, charge, RT and Intensity information
--file_dir FILE_DIR, -f FILE_DIR
the data folder
--sample_file SAMPLE_FILE, -s SAMPLE_FILE
the sample file
```
As an example, to handle the Dinosaur test data in example_files folder, you can **create a new folder** and put the file_dir (containing result files from feature extraction tool ) and sample_file in, **switch the working directory to this folder**, then use command `deeprtalign -m Dinosaur -f file_dir -s sample_file.xlsx ` . On a normal computer, this will take about 30 minutes. We strongly recommend users to use the `-pn` parameter according to the CPU core numbers. This will make it run much faster.
If you choose TXT method (txt file separated by '\t') or CSV method (txt file separated by ','), you must provide optional arguments `--mz_col` `--charge_col` `--rt_col` `--intensity_col`.
optional arguments:
```
--processing_number PROCESSING_NUMBER, -pn PROCESSING_NUMBER
processing number, choose according to the number of
CPUs, -1 will use all CPUs
--percent PERCENT, -pt PERCENT
skip the bins with sample numbers below the percent of
total sample numbers
--time_window TIME_WINDOW, -tw TIME_WINDOW
min, the time window in the coarse alignment step
--bin_width BIN_WIDTH, -bw BIN_WIDTH
the bin width, choose according to the feature
extraction step
--bin_precision BIN_PRECISION, -bp BIN_PRECISION
the decimal place of bins, choose according to the
feature extraction step
--dict_size DICT_SIZE, -ds DICT_SIZE
the dict size, choose according to the memory size
--min_time_diff MIN_TIME_DIFF, -mtd MIN_TIME_DIFF
min, the time window used to filter the features, only
keep the highest feature
--max_mz MAX_MZ, -mm MAX_MZ
ppm, the m/z threshold used to filter the features,
only align features within the threshold
--max_time MAX_TIME, -mt MAX_TIME
min, the time threshold used to filter the features,
only align features within the threshold
--max_log_intensity MAX_LOG_INTENSITY, -mli MAX_LOG_INTENSITY
log2 intensity value, the intensity threshold used to
filter the features, only align features within the
threshold
--max_sample_number MAX_SAMPLE_NUMBER, -msn MAX_SAMPLE_NUMBER
the max number of candidate feature pairs, if set to
-1, all candidate feature pairs will be calculated
--disk_mode DISK_MODE, -dm DISK_MODE
if use disk mode,disk mode is slower, but can keep the
temp files, 0 do not use disk mode, 1 use disk mode
--keep_temp KEEP_TEMP, -kt KEEP_TEMP
if keep the temp files, 0 remove, 1 keep
--begin_step BEGIN_STEP, -bs BEGIN_STEP
begin from any step, only work in disk mode
--fdr FDR, -fd FDR the FDR cutoff
--mz_col MZ_COL, -mz MZ_COL
m/z column location, count from 1, for TXT or CSV
method
--rt_col RT_COL, -rt RT_COL
rt column location, count from 1, for TXT or CSV
method
--intensity_col INTENSITY_COL, -int INTENSITY_COL
intensity column location, count from 1, for TXT or
CSV method
--charge_col CHARGE_COL, -cha CHARGE_COL
charge column location, count from 1, for TXT or CSV
method
--keep_best_feature KEEP_BEST_FEATURE, -kbf KEEP_BEST_FEATURE
0 keep all the candidate features, 1 only keep the
best feature for each sample in each group
--keep_best_group KEEP_BEST_GROUP, -kbg KEEP_BEST_GROUP
0 keep all the candidate groups, 1 only keep the group
with most features if there is conflict
```
processing_number (int, default -1) depends on your hardware. percent (float:0-1, default 0) is a threshold, DeepRTAlign will skip the bins with sample numbers below the percent of total sample numbers. time_window (float, default 1) depends on your chromatography, 1 min is the parameter we used in training and is suitable for most situations. bin_width (float, default 0.03) and bin_precision (int, default 2) depends on your feature extraction parameters, bin_width is the m/z window size, and bin_precision is the number of decimal places used in this step. Only the features in the same m/z window will be aligned, default values are suitable for most situations. dict_size (int, default 1024) depends on your memory size, default 1024MB. min_time_diff (float, default 0) is the time window (min) used to used to filter the feature, only keep the highest feature within a time window. max_mz (float, defaut 20),max_time (float, default 5), max_log_intensity (float, default 3) and max_sample_number (int, default 3) are used for reducing calculation. disk_mode will write temp files on your disk, and is not used by default. If you want to keep the temp files, set the keep_temp (int, default 0) to 1. In disk_mode, you can begin from any begin_step (int, default 1). step 1: preprocessing of input files, step 2: coarse alignment, step 3: bining, step 4: filtering, step 5: alignment, step 6: generating result file. fdr (float, 0-1, default 0.01) is the threshold used in quality control part. mz_col, rt_col, intensity_col and charge_col are used in TXT method and CSV method, please note they are counted from 1. Multiple features from a sample may exist in a group after alignment and quality control, keep_best_feature=1 (default) will only keep the feature with the highest score for each sample in each group, or you can set keep_best=0 to keep all candidate features in a group. A feature may exist in multiple groups after alignment and quality control, keep_best_group=1 (default) will only keep the group with the largest number of features, other features of a sample will be divided into new groups, or you can set keep_best=0 to keep all candidate groups.
3. The results will output to the mass_align_all_information folder.If you set kt to 0 (default), there will be only one file in the mass_align_all_information folder: information_target.csv (target results after QC). If you set kt to 1, there will be two files in the mass_align_all_information folder: information_target.csv (target results after QC) and information_all.csv (results before QC, and containing decoy samples).
## Result Description
In result files, each line represent a feature, the meaning of each column is as follows.
### Main columns
- sample: the sample name corresponding to this feature.
- fraction: the fraction corresponding to this feature.
- time: the RT (min) corresponding to this feature.
- mz: the m/z corresponding to this feature.
- charge: the charge corresponding to this feature.
- intensity: the intensity corresponding to this feature.
- score: the score of aligned pairs.
- group: the group name corresponding to this feature, aligned features share the same group name.
In the default workflow, score will be used for quality control (default). This workflow works well in most cases. But when the samples are quite different, or there are too many features with the almost same m/z, the default workflow usually report very few results. In this case, set FDR to 1, and select features with score greater than 0.5 are recomended.
### Other columns
Other columns are intermediate results and can be ignored.
## Note
Do not run the different projects under a same folder, the results will be overwritten. That is why we recommend **create a new folder**.
## Demo
The demo are in the example_files folder. We use part of features in UPS2-Y dataset as examples. On a normal computer, each work will take about 30 minutes. We strongly recommend users to use the `-pn` parameter according to the CPU core numbers. This will make it run much faster.
We provide Dinosaur, MaxQuant, OpenMS and XICFinder results for user to test DeepRTAlign.
To handle the Dinosaur test data in example_files folder, you can **create a new folder** and put the file_dir (containing result files from feature extraction tool ) and sample_file in, **switch the working directory to this folder**, then use command `deeprtalign -m Dinosaur -f file_dir -s sample_file.xlsx `. The results will output to the mass_align_all_information folder.
To handle the MaxQuant test data in example_files folder, you can **create a new folder** and put the file_dir (containing result files from feature extraction tool ) and sample_file in, **switch the working directory to this folder**, then use command `deeprtalign -m MaxQuant -f file_dir -s sample_file.xlsx `. The results will output to the mass_align_all_information folder.
To handle the OpenMS test data in example_files folder, you can **create a new folder** and put the file_dir (containing result files from feature extraction tool ) and sample_file in, **switch the working directory to this folder**, then use command `deeprtalign -m OpenMS -f file_dir -s sample_file.xlsx `. The results will output to the mass_align_all_information folder.
To handle the XICFinder test data in example_files folder, you can **create a new folder** and put the file_dir (containing result files from feature extraction tool ) and sample_file in, **switch the working directory to this folder**, then use command `deeprtalign -m XICFinder -f file_dir -s sample_file.xlsx `. The results will output to the mass_align_all_information folder.
Expected output is in expected_output folder.
## Code for the experiments
Code for comparing with other alignment tools are in this folder.
## License
GPLv3 (General Public License version 3.0), details in the LICENSE file.
## Contacts
For any questions involving DeepRTAlign, please contact us by email.
**Yi Liu**, leoicarus@163.com
**Cheng Chang**, changchengbio@163.com or changcheng@ncpsb.org.cn
Raw data
{
"_id": null,
"home_page": "https://github.com/FineLiu/deeprtalign",
"name": "deeprtalign",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.4",
"maintainer_email": "",
"keywords": "",
"author": "Yi Liu",
"author_email": "leoicarus@163.com",
"download_url": "https://files.pythonhosted.org/packages/8a/e9/de5c01bfd07187f2c4e5213a77d9f95b01d0df7a70e46efabb5478489481/deeprtalign-1.2.2.tar.gz",
"platform": null,
"description": "# DeepRTAlign v1.2.2\n\n## Overview\n\nDeepRTAlign is a deep learning-based retention time alignment tool for large cohort LC-MS data analysis.\n\n## Installation\n\n1. Install Python3.\n2. Install Pytorch CPU version, please refer to https://pytorch.org/.\n3. Use `pip install deeprtalign` to install deeprtalign OR download `deeprtalign-1.2.2-py3-none-any.whl` from github [releases](https://github.com/PHOENIXcenter/deeprtalign/releases), and use `pip install deeprtalign-1.2.2-py3-none-any.whl` to install deeprtalign. This step will take 3-4 minutes.\n\nDeepRTAlign is not dependent on a specific operating system, we have tested it on Windows 10, Ubuntu 18.04 and macOS 12.1.\n\n## Getting Started\n\n1. Feature lists and sample list should be prepared before running DeepRTAlign. Feature lists are the output of feature extraction tools (DeepRTAlign supports Dinosaur, OpenMS, MaxQuant, XICFinder and any other text list containing m/z, charge, RT and Intensity information ). The sample list is an excel file recording the correspondences between feature files and sample names. You can find the test data in the example_files folder. \n\n Note that if you use MaxQuant as the feature extraction tool, you should use the allPeptides.txt as the input file or files, and the sample list should correspond to the first column of allPeptides.txt file. DO NOT use \"allPeptdes.txt\" as the file name in sample list if you use MaxQuant. If you use the old version of MaxQuant (<2.0),please check the 7th column, delete the \"Resolution\" column if you see it (in MaxQuant v2.0, \"Resolution\" column is not exists, so we have changed corresponding code).\n\n2. You can get the help information by command `deeprtalign -h`, the basic arguments are as follows:\n\n ```\n --method {Dinosaur,XICFinder,OpenMS,MaxQuant,TXT,CSV}, -m {Dinosaur,XICFinder,OpenMS,MaxQuant,TXT,CSV}\n the feature extraction method, support Dinosaur,\n XICFinder, OpenMS, MaxQuant and any other text list containing m/z, charge, RT and Intensity information\n --file_dir FILE_DIR, -f FILE_DIR\n the data folder\n --sample_file SAMPLE_FILE, -s SAMPLE_FILE\n the sample file\n ```\n\n As an example, to handle the Dinosaur test data in example_files folder, you can **create a new folder** and put the file_dir (containing result files from feature extraction tool ) and sample_file in, **switch the working directory to this folder**, then use command `deeprtalign -m Dinosaur -f file_dir -s sample_file.xlsx ` . On a normal computer, this will take about 30 minutes. We strongly recommend users to use the `-pn` parameter according to the CPU core numbers. This will make it run much faster.\n\n If you choose TXT method (txt file separated by '\\t') or CSV method (txt file separated by ','), you must provide optional arguments `--mz_col` `--charge_col` `--rt_col` `--intensity_col`.\n\n optional arguments:\n \n ```\n --processing_number PROCESSING_NUMBER, -pn PROCESSING_NUMBER\n processing number, choose according to the number of\n CPUs, -1 will use all CPUs\n --percent PERCENT, -pt PERCENT\n skip the bins with sample numbers below the percent of\n total sample numbers\n --time_window TIME_WINDOW, -tw TIME_WINDOW\n min, the time window in the coarse alignment step\n --bin_width BIN_WIDTH, -bw BIN_WIDTH\n the bin width, choose according to the feature\n extraction step\n --bin_precision BIN_PRECISION, -bp BIN_PRECISION\n the decimal place of bins, choose according to the\n feature extraction step\n --dict_size DICT_SIZE, -ds DICT_SIZE\n the dict size, choose according to the memory size\n --min_time_diff MIN_TIME_DIFF, -mtd MIN_TIME_DIFF\n min, the time window used to filter the features, only\n keep the highest feature\n --max_mz MAX_MZ, -mm MAX_MZ\n ppm, the m/z threshold used to filter the features,\n only align features within the threshold\n --max_time MAX_TIME, -mt MAX_TIME\n min, the time threshold used to filter the features,\n only align features within the threshold\n --max_log_intensity MAX_LOG_INTENSITY, -mli MAX_LOG_INTENSITY\n log2 intensity value, the intensity threshold used to\n filter the features, only align features within the\n threshold\n --max_sample_number MAX_SAMPLE_NUMBER, -msn MAX_SAMPLE_NUMBER\n the max number of candidate feature pairs, if set to\n -1, all candidate feature pairs will be calculated\n --disk_mode DISK_MODE, -dm DISK_MODE\n if use disk mode,disk mode is slower, but can keep the\n temp files, 0 do not use disk mode, 1 use disk mode\n --keep_temp KEEP_TEMP, -kt KEEP_TEMP\n if keep the temp files, 0 remove, 1 keep\n --begin_step BEGIN_STEP, -bs BEGIN_STEP\n begin from any step, only work in disk mode\n --fdr FDR, -fd FDR the FDR cutoff\n --mz_col MZ_COL, -mz MZ_COL\n m/z column location, count from 1, for TXT or CSV\n method\n --rt_col RT_COL, -rt RT_COL\n rt column location, count from 1, for TXT or CSV\n method\n --intensity_col INTENSITY_COL, -int INTENSITY_COL\n intensity column location, count from 1, for TXT or\n CSV method\n --charge_col CHARGE_COL, -cha CHARGE_COL\n charge column location, count from 1, for TXT or CSV\n method\n --keep_best_feature KEEP_BEST_FEATURE, -kbf KEEP_BEST_FEATURE\n 0 keep all the candidate features, 1 only keep the\n best feature for each sample in each group\n --keep_best_group KEEP_BEST_GROUP, -kbg KEEP_BEST_GROUP\n 0 keep all the candidate groups, 1 only keep the group\n with most features if there is conflict\n ``` \n processing_number (int, default -1) depends on your hardware. percent (float:0-1, default 0) is a threshold, DeepRTAlign will skip the bins with sample numbers below the percent of total sample numbers. time_window (float, default 1) depends on your chromatography, 1 min is the parameter we used in training and is suitable for most situations. bin_width (float, default 0.03) and bin_precision (int, default 2) depends on your feature extraction parameters, bin_width is the m/z window size, and bin_precision is the number of decimal places used in this step. Only the features in the same m/z window will be aligned, default values are suitable for most situations. dict_size (int, default 1024) depends on your memory size, default 1024MB. min_time_diff (float, default 0) is the time window (min) used to used to filter the feature, only keep the highest feature within a time window. max_mz (float, defaut 20),max_time (float, default 5), max_log_intensity (float, default 3) and max_sample_number (int, default 3) are used for reducing calculation. disk_mode will write temp files on your disk, and is not used by default. If you want to keep the temp files, set the keep_temp (int, default 0) to 1. In disk_mode, you can begin from any begin_step (int, default 1). step 1: preprocessing of input files, step 2: coarse alignment, step 3: bining, step 4: filtering, step 5: alignment, step 6: generating result file. fdr (float, 0-1, default 0.01) is the threshold used in quality control part. mz_col, rt_col, intensity_col and charge_col are used in TXT method and CSV method, please note they are counted from 1. Multiple features from a sample may exist in a group after alignment and quality control, keep_best_feature=1 (default) will only keep the feature with the highest score for each sample in each group, or you can set keep_best=0 to keep all candidate features in a group. A feature may exist in multiple groups after alignment and quality control, keep_best_group=1 (default) will only keep the group with the largest number of features, other features of a sample will be divided into new groups, or you can set keep_best=0 to keep all candidate groups. \n3. The results will output to the mass_align_all_information folder.If you set kt to 0 (default), there will be only one file in the mass_align_all_information folder: information_target.csv (target results after QC). If you set kt to 1, there will be two files in the mass_align_all_information folder: information_target.csv (target results after QC) and information_all.csv (results before QC, and containing decoy samples).\n\n## Result Description\nIn result files, each line represent a feature, the meaning of each column is as follows.\n### Main columns\n- sample: the sample name corresponding to this feature.\n- fraction: the fraction corresponding to this feature.\n- time: the RT (min) corresponding to this feature.\n- mz: the m/z corresponding to this feature.\n- charge: the charge corresponding to this feature.\n- intensity: the intensity corresponding to this feature.\n- score: the score of aligned pairs.\n- group: the group name corresponding to this feature, aligned features share the same group name.\n\nIn the default workflow, score will be used for quality control (default). This workflow works well in most cases. But when the samples are quite different, or there are too many features with the almost same m/z, the default workflow usually report very few results. In this case, set FDR to 1, and select features with score greater than 0.5 are recomended.\n\n### Other columns\nOther columns are intermediate results and can be ignored.\n## Note\n\nDo not run the different projects under a same folder, the results will be overwritten. That is why we recommend **create a new folder**.\n\n## Demo\nThe demo are in the example_files folder. We use part of features in UPS2-Y dataset as examples. On a normal computer, each work will take about 30 minutes. We strongly recommend users to use the `-pn` parameter according to the CPU core numbers. This will make it run much faster.\nWe provide Dinosaur, MaxQuant, OpenMS and XICFinder results for user to test DeepRTAlign.\n\nTo handle the Dinosaur test data in example_files folder, you can **create a new folder** and put the file_dir (containing result files from feature extraction tool ) and sample_file in, **switch the working directory to this folder**, then use command `deeprtalign -m Dinosaur -f file_dir -s sample_file.xlsx `. The results will output to the mass_align_all_information folder.\n\nTo handle the MaxQuant test data in example_files folder, you can **create a new folder** and put the file_dir (containing result files from feature extraction tool ) and sample_file in, **switch the working directory to this folder**, then use command `deeprtalign -m MaxQuant -f file_dir -s sample_file.xlsx `. The results will output to the mass_align_all_information folder.\n\nTo handle the OpenMS test data in example_files folder, you can **create a new folder** and put the file_dir (containing result files from feature extraction tool ) and sample_file in, **switch the working directory to this folder**, then use command `deeprtalign -m OpenMS -f file_dir -s sample_file.xlsx `. The results will output to the mass_align_all_information folder.\n\nTo handle the XICFinder test data in example_files folder, you can **create a new folder** and put the file_dir (containing result files from feature extraction tool ) and sample_file in, **switch the working directory to this folder**, then use command `deeprtalign -m XICFinder -f file_dir -s sample_file.xlsx `. The results will output to the mass_align_all_information folder.\n\nExpected output is in expected_output folder.\n\n## Code for the experiments\nCode for comparing with other alignment tools are in this folder.\n\n## License\n\nGPLv3 (General Public License version 3.0), details in the LICENSE file.\n\n## Contacts\n\nFor any questions involving DeepRTAlign, please contact us by email.\n\n**Yi Liu**, leoicarus@163.com\n\n**Cheng Chang**, changchengbio@163.com or changcheng@ncpsb.org.cn\n\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "retention time alignment tool for large cohort LC-MS data analysis",
"version": "1.2.2",
"project_urls": {
"Homepage": "https://github.com/FineLiu/deeprtalign"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3401ef6c7442e08d987db1cf956883c5dc7c7b5b3fe0d4f4b10216f9ba29e12a",
"md5": "257dc8bdf17cff34304193aa986c5a23",
"sha256": "514d7c13b4e1a4be73269e83fcfeecc104dcb84d4fb5835d51af6d773d08a7b2"
},
"downloads": -1,
"filename": "deeprtalign-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "257dc8bdf17cff34304193aa986c5a23",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.4",
"size": 186503673,
"upload_time": "2023-12-06T07:26:30",
"upload_time_iso_8601": "2023-12-06T07:26:30.438842Z",
"url": "https://files.pythonhosted.org/packages/34/01/ef6c7442e08d987db1cf956883c5dc7c7b5b3fe0d4f4b10216f9ba29e12a/deeprtalign-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8ae9de5c01bfd07187f2c4e5213a77d9f95b01d0df7a70e46efabb5478489481",
"md5": "b1b9297bf7afd463fbd323070d900922",
"sha256": "33a027ce9cd71f13c089400a80e6041584dd336792f4bc978dd4d589e95fd5ad"
},
"downloads": -1,
"filename": "deeprtalign-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "b1b9297bf7afd463fbd323070d900922",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.4",
"size": 186381393,
"upload_time": "2023-12-06T07:28:13",
"upload_time_iso_8601": "2023-12-06T07:28:13.596557Z",
"url": "https://files.pythonhosted.org/packages/8a/e9/de5c01bfd07187f2c4e5213a77d9f95b01d0df7a70e46efabb5478489481/deeprtalign-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-06 07:28:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FineLiu",
"github_project": "deeprtalign",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "deeprtalign"
}
JSON
