• English
• 中文

---

[TOC]

---

1. Verify pLink3 Installation and Hardware Requirements
2. Unsupported Mass Spectrometry Data Acquisition Methods
3. If Stopped When Starting: Check Successful Spectra Extraction from RAW Files
4. Prolonged Search: Determine Whether Still Running or Crashed
5. Causes of Prolonged Search Time
6. How to Report Software Bugs

---

1. Windows 7 is NOT supported.

2. Verify complete installation:

   • Some Python modules packaged with pyinstaller may be silently quarantined by antivirus software.
   • Confirm the existence of these files in the ./bin/ subdirectory of pLink3 installation folder:
     • ./pParse2Plus/pParse2Plus.exe
     • ./MultiProcess/MultiProcess.exe
     • ./RerankOut/RerankOut.exe
     • ./pLinkFDR/pLinkFDR.exe
   • If any EXE is missing, restore it from your antivirus quarantine and whitelist the folder. Reinstallation may also help.
   • Rest assured: We've scanned our software with Windows Defender—it is safe.

3. Verify Integrity of pLink BAT Scripts

   • pLink internally executes BAT scripts (.bat) to complete specific tasks (these are safe operations calling pLink's own modules).
   • However, some users have reported that antivirus software may mistakenly flag and erase the contents of certain BAT script files.
   • Example: The ./bin/MultiProcess.bat file was found empty by some users, which should contain the following code:

     @echo off
     
     set fpath=%1
     echo [MultiProcess] %fpath%
     "MultiProcess\MultiProcess.exe" %fpath%

   • Verification Method: Open BAT files with a text editor to confirm they are not empty.
   • Other critical BAT scripts to check include:
     • ./bin/pParse2Plus.bat
     • ./bin/RerankOut.bat
     • ./bin/pLinkFDR.bat

4. Antivirus Software Blocking Program Execution

   • Some users reportedthat despite verifying a complete installation, pLink3 still stopped immediately upon start. It was later discovered that 360 Security was blocking the program from running.
   • Please check if any antivirus software pop-up appears when running pLink3.
   • Besides 360 Safeguard, other antivirus software that may interfere includes: Microsoft Defender, McAfee, Jiangmin, Kingsoft Antivirus, Huorong, etc.

5. Memory Requirements:

   • The more CPU threads or processes you set, the more memory will be required.
   • The more variable modifications you add, the more memory will be needed.
   • When setting only one variable modification Oxidation[M], each thread will require approximately 1-2GB RAM.

6. Avoid spaces or special characters in pLink3 installation path:

   • Possible issues: Spaces in the computer username.
   • Common issues: Spaces in installation folders like Program Files or Program Files (x86).
   • Do not include special characters, such as: Chinese, =, non-Latin scripts, etc.
   • Recommended path format: Use only numbers, English letters, ., -, _, etc.

7. Ensure read/write permissions for:

   • pLink3 installation directory (especially ./bin/)
   • Folders containing RAW files, FASTA databases, and search task results.
   • Quick test: Create/edit a TXT file in these folders to verify permissions.

---

• Supported:
  • MS2-HCD-Orbitrap
  • MS2-HCD-Astral
  • MS2-CID-TOF
• Unsupported:
  • MS2-IonTrap
  • MS3

---

1. Check successful spectrum extraction:

   • If you see an entry like the following in the log window of the interface, it indicates that spectra were successfully extracted and the search phase has begun: [pLink3] Loaded 5000 spectra, 5000 / 123456
   • Check if .pf2 and _pParse2Plus.flag files are generated in the folder stored the raw files.
     • The number of .pf2 and _pParse2Plus.flag files should match the number of raw files.

2. Important: For different pLink versions, it's best to reprocess RAW files in a new empty folder, especially when switching between pLink2 and pLink3, as spectrum extraction algorithm is significantly different.

3. Select correct MS Data Format for your data:

   • Explanation of MS Data Format Options

4. Selecting RAW (Orbitrap) requires MSFileReader installation:

   • Tutorial: how-to-install-msfilereader
     • The MSFileReader version must not be too high. Please follow the tutorial's requirements carefully.
   • When the following log appears, it means MSFileReader is not installed:

     [pXtract] Begin to extract C:\xxx.raw  
     [pXtract] pXtract tries to use MSFileReader  
     [pXtract] <Exception>: MSFileReader should be 32/64 bit version corresponding to pFind.  
     [pXtract] <Exception>: Please ensure XRawfile2_x64.dll, fregistry_x64.dll, fileio_x64.dll are inside the directory: C:\Program Files\Thermo\MSFileReader.  
     

   • Please check:
     • Whether files like Fileio_x64.dll, fregistry_x64.dll, and XRawfile2_x64.dll exist in the folder C:\Program Files\Thermo\MSFileReader\.
     • Whether files like fileio.dll, fregistry.dll, and XRawfile2.dll exist in the folder C:\Program Files (x86)\Thermo\MSFileReader\.
   • MSFileReader is not supported on Windows systems with ARM architecture chips.

5. Sometimes RAW files may be corrupted:

   • Test with Thermo’s official Xcalibur software. If Xcalibur cannot open the file, it is corrupted.
   • If the raw files were downloaded from platforms like ProteomeXchange, try re-downloading them.

6. RAW file attributes: Ensure file attribute is A (not N). Fix guide: pXtract Exception: Find no raws in *.raw

---

1. Check process status:

   • In Task Manager, verify if searcher.exe is still running and utilizing CPU.

2. Search speed performance reference:

   • pLink3 is quite fast. If the search still hasn't completed after 1 or several days for smaller datasets, it may have crashed.
   • We tested a search with 167 raw files (QEHF instrument, Ecoli-4k full database) that completed in about 4 hours:
     • CPU: Intel(R) Xeon(R) Gold 6254 CPU @ 3.10GHz
     • Multi-Process: 36 processes

3. Avoid spaces or special characters in search-related paths or filenames

   • Involves paths or filenames for items such as raw data, fasta files, search tasks (result output), etc.
   • Do not include special characters, such as: Chinese, =, non-Latin scripts, etc.
   • Recommended path format: Use only numbers, English letters, ., -, _, etc.

---

1. Oversized FASTA database:
   • While pLink3 supports human-reviewed databases (~20k proteins), databases with >100k proteins will significantly slow searches.
2. Too many variable modifications added:
   • While pLink3 supports multiple variable modifications, an excessive number will drastically increase search time due to the exponential growth of search space.
   • Critical distinctions:
     • Acetyl[AnyN-term]: Modifies all peptide N-termini.
     • Acetyl[ProteinN-term]: Modifies only protein N-termini.
3. Non-specific modification sites: Allowing modifications on multiple residue types.

---

Submit the following to help us diagnose issues:

1. Screenshots of pLink GUI:
   • GUI Log window
     • It's recommended to click the Save Report button in the upper-left corner of the Output window to save the logs, then send the file to us.
   • GUI Parameter Summary window
2. Search parameter file: .plink file from the result folder.
3. Log files (if available): In the result task folder
   • *_MultiProcess.log
   • ./tmps/log.out
   • ./tmps/RerankOut.log
   • ./tmps/pLinkFDR.log
4. Run the search in command-line mode, then provide a screenshot of the error message displayed in the command prompt (cmd) window.
   • Command-line mode tutorial: Running pLink via Command Line
5. If you selected the disulfide bond workflow:
   • In the ./tmps/ folder, you’ll find two sub-tasks: basic_ss, complex_ss0
   • In addition to the main task parameter file, include parameter/log files from these subfolders.

---

• Licenses are not interchangeable between different computers, and sometimes licenses for different versions of pLink are also incompatible.

  • You can obtain a new license from the self-service license website.

• The bin directory of the pLink installation requires read and write permissions.

  • A quick way to test folder permissions:
    • Create a new text file (.txt) in the folder, write something, and check if it saves successfully.
  • For example, if you copied the installation folder from another computer instead of reinstalling, the folder often loses write permissions on the new computer.

• Changes in the Activation code in the registration window

  • Modifying hardware or reinstalling the operating system may cause the Activation code to change.
  • You can obtain a new activation code from the self-service license website.

---

1. 确认pLink3符合安装与硬件要求
2. 不支持的质谱数据采集方式
3. 若开始即停止，判断是否成功从raw文件中成功提取到谱图
4. 搜索时间过长，判断是否仍在搜索中，还是已经崩溃
5. 搜索时间过长的原因
6. 如何报告软件bug

---

1. 不支持Windows7的操作系统。

2. 确认安装完整：

   • 因部分python模块使用pyinstaller打包，可能有时会被杀毒软件静默误杀。
   • 确认在安装目录的./bin/文件夹中各文件存在:
     • ./pParse2Plus/pParse2Plus.exe
     • ./MultiProcess/MultiProcess.exe
     • ./RerankOut/RerankOut.exe
     • ./pLinkFDR/pLinkFDR.exe
   • 若发现部分exe缺失，请从杀毒软件中还原放出，并设入白名单，也可重新安装。
   • 请放心，我们使用windows defender扫描过，我们的软件是安全的。

3. 确认pLink调用的bat脚本完整

   • pLink内部通过调用一些bat脚本来完成某些环节的任务（这是安全的，都是在调用pLink自己的模块）。
   • 但有用户发现因杀毒软件误判，清空了部分bat脚本文件内的内容。
   • 例如：./bin/MultiProcess.bat有用户打开后发现是个空文件，但本该内容如下：

     @echo off
     
     set fpath=%1
     echo [MultiProcess] %fpath%
     "MultiProcess\MultiProcess.exe" %fpath%

   • 核查方法：可文本编辑器打开bat文件，确认每个bat脚本文件不为空。
   • 其它还包括bat脚本：
     • ./bin/pParse2Plus.bat
     • ./bin/RerankOut.bat
     • ./bin/pLinkFDR.bat

4. 杀毒软件拦截程序运行

   • 有用户报告，尽管已检查安装完整，但仍然在pLink3运行开始即停止，最后发现是360安全卫士拦截了程序运行。
   • 请注意pLink3运行时，是否有杀毒软件拦截弹窗。
   • 除360安全卫士拦截，其它杀毒软件可能还包括：Microsoft Defender、McAfee、江民、金山毒霸、火绒等。

5. 足够的内存：

   • 设置的CPU线程数或进程越多，需要的内存越多。
   • 可变修饰越多，需要的内存越多。
   • 在仅设置一个可变修饰Oxidation[M]时，每个线程大约需要1-2GB的内存。

6. pLink3安装路径中不要带空格或特殊字符：

   • 可能电脑用户名中有空格。
   • 安装在了带空格的文件夹中，例如 Program Files、Program Files (x86)。
   • 不要含特殊字符，包括：中文、=、小语种等。
   • 安装路径建议：最好仅由数字、英文字母、.、-、_等组成。

7. pLink3相关文件夹有读写的权限：

   • 包括pLink3安装目录的 ./bin/文件夹，储存raw、fasta、任务结果等文件夹。
   • 测试文件夹有读写权限的简单办法：
     • 在文件夹中新建一个文本txt文件，随便写点什么，看是否可以成功保存。

---

• 支持：
  • MS2-HCD-Orbitrap
  • MS2-HCD-Astral
  • MS2-CID-TOF
• 不支持：
  • MS2-IonTrap
  • MS3

---

1. 判断是否成功从raw文件中成功提取到谱图：

   • 在界面的日志窗口中，若出现下面类似条目，才证明成功提取谱图，已经进入到搜索环节： [pLink] Loaded 5000 spectra, 5000 / 123456
   • 存放raw的文件夹中，有产生 .pf2和 _pParse2Plus.flag结尾的文件。
     • _pParse2Plus.flag文件数目应与raw总数相同。

2. 注意：不同版本的pLink，最好将raw文件单独放在一个新的干净的文件夹，重新让pLink提取谱图，特别是pLink2和pLink3谱图提取有了较大的不同。

3. 不同仪器采集数据，选用正确的 MS Data Format：

   • MS Data Format各项的解释

4. 选用 RAW (Orbitrap)，需要安装MSFileReader：

   • 教程：how-to-install-msfilereader
     • MSFileReader版本不能过高，请注意教程中的要求。
   • 当出现以下日志时，即没有安装MSFileReader:

     [pXtract] Begin to extract C:\xxx.raw
     [pXtract] pXtract tries to use MSFileReader
     [pXtract] <Exception>: MSFileReader should be 32/64 bit version corresponding to pFind.
     [pXtract] <Exception>: Please reassure XRawfile2_x64.dll, fregistry_x64.dll, fileio_x64.dll are inside the directory: C:\Program Files\Thermo\MSFileReader.
     

   • 请检查：
     • C:\Program Files\Thermo\MSFileReader\文件夹中是否存在Fileio_x64.dll，fregistry_x64.dll，XRawfile2_x64.dll等文件。
     • C:\Program Files (x86)\Thermo\MSFileReader\文件夹中是否存在fileio.dll，fregistry.dll，XRawfile2.dll等文件。
   • ARM架构芯片的windows系统不支持MSFileReader。

5. 有时raw文件会有损坏：

   • 可通过Thermo官方的Xcalibur软件测试。若Xcalibur也打不开，证明raw文件已损坏。
   • 若是从ProteomeXchange等平台上下载的raw，可以尝试重新下载。

6. raw文件属性为 N，修改为 A。

   • 教程: pXtract Exception: Find no raws in *.raw

---

1. 判断是否仍在搜索中，还是已经崩溃：

   • 在任务管理器中，查看是否还存在searcher.exe的进程，并占用着CPU。

2. 速度性能参考：

   • pLink3有较快的速度。若数据量不大时，超过1天或几天搜索仍没有结束，可能已经崩溃。
   • 我们测试搜索167个raw(QEHF仪器采集)，Ecoli-4k全库，搜索仅用时约4hr
     • CPU：Intel(R)Xeon(R) Gold 6254 CPU @ 3.10GHz
     • Multi-Process: 36进程

3. 相关路径或文件名中不要有空格或特殊字符

   • 涉及：raw、fasta、search task(result output)等路径或文件名。
   • 不要含特殊字符，包括：中文、=、小语种等。
   • 路径或文件名建议：最好仅由数字、英文字母、.、-、_等组成。

---

1. fasta数据库特别巨大
   • 虽pLink3支持human-reviewed（含2w蛋白）全库的搜索，但若fasta中有几十万的蛋白，那将耗时非常长。
2. 添加了太多可变修饰
   • 虽pLink3支持多个可变修饰，但若可变修饰太多，将耗时非常长。因可变修饰引起的搜索空间膨胀是指数级的。
   • 需要特别注意:
     • Acetyl[AnyN-term]: 意为修饰所有的肽段的N端。
     • Acetyl[ProteinN-term]: 意为仅修饰蛋白的N端。
3. 可变修饰的位点非特异，即允许修饰在多个氨基酸位点。

---

可以一次性给我们提交以下材料，方便定位bug:

1. pLink界面的截图
   • 界面日志窗口
     • 最好是点击Output窗口左上角Save Report按钮，保存窗口的日志，然后将文件发于我们。
   • 界面参数Summary窗口
2. 搜索参数： 在结果任务文件夹中，后缀为 .plink
3. 日志文件（若存在）： 在结果任务文件夹中
   • _MultiProcess.log结尾文件
   • ./tmps/log.out
   • ./tmps/RerankOut.log
   • ./tmps/pLinkFDR.log
4. 使用命令行模式运行搜索，然后提供命令提示符（cmd）窗口显示的错误信息截图
   • 命令行模式教程：命令行运行pLink
5. 若选择二硫键流程：
   • ./tmps/中有两个子任务: basic_ss, complex_ss0
   • 除主任务参数文件，也包括两个子任务的参数文件和日志文件。

---

• 不同电脑的license不通用，有时候不同pLink版本的license也不通用

  • 在自助license网站获取新的即可

• pLink安装bin目录需要读写的权限

  • 测试文件夹有读写权限的简单办法：
    • 在文件夹中新建一个文本txt文件，随便写点什么，看是否可以成功保存。
  • 例如，不是重新安装，而是直接拷贝了另外一台电脑的安装文件夹，往往这个文件夹会在新电脑上丧失写的权限

• 注册窗口Activation code变动

  • 更改电脑硬件或重装系统等，可能会引起Activation code变动，在自助license网站获取新的即可

---