timsplot: A Python Shiny App for Visualizing tims-TOF Proteomics Results

This is a Shiny App designed to facilitate quick and easy data visualization for Bruker timsTOF data. The app uses the reports from common software (Spectronaut, DIA-NN, FragPipe, and Bruker ProteoScape) to generate informative figures that can be adjusted on-the-fly for data inspection and presentation.

Tutorial

Instructions on how to install and use the app can be found in 'timsTOF Visualization App Tutorial' in the main directory.

Getting Started

Installation

1. Install Python: Make sure you have Python installed on your computer. Alphatims does not support newer versions of Python, so make sure to use versions prior to 3.13. (https://www.python.org/downloads/release/python-3119/)
2. Install Visual Studio Code: This will be the primary interface for the app (https://code.visualstudio.com/). Make sure to set the Python interpreter in the IDE to the current installed version of Python or Anaconda.
3. Install required Python libraries: Most of the libraries needed for the app are built into the installation of Python. The libraries listed below need to be installed manually:

Python Libraries

Note: When installing Python libraries, make sure that the installation is under the selected Python interpreter in Visual Studio Code (e.g. if Anaconda is used as the Python interpreter, perform the installations in a Conda powershell prompt).

Each library can be installed in a powershell terminal by typing pip install {library}.

Alternatively, make sure the requirements.txt file is in the same directory as the app.py and use py -m pip install -r requirements.txt to bulk-install all the nececssary libraries

• alphatims
• colorcet
• faicons
• hvplot
• logomaker
• matplotlib-venn
• pyarrow
• python-pptx
• seaborn
• scikit-learn
• shiny
• shinyswatch
• textalloc
• upsetplot

4. Install required extensions in Visual Studio Code: In Visual Studio Code, make sure to install the Python and Shiny extensions so the IDE can properly interpret the app file through the Extensions:Marketplace tab.
5. Download the app from the GitHub repository: Clone or download the repository containing the app code from the GitHub repository (https://github.com/zack-kirsch/timsplot).
6. Run and access the app: Set the downloaded app directory as the working directory under the Explorer tab in Visual Studio Code and open the app.py file. Click the play button in the top right to launch the Shiny app. If the extensions have been installed properly, you should see Run Shiny App when hovering over the button.

Necessary Files for Using timsplot

• ptmdict.csv
  • Contains keys and replacements for PTMs in search files to unify how PTMs are notated and can be edited for custom PTM input
  • To note: FragPipe has a specific format considering how it denotes PTMs in modified sequences. The key should be amino acid letter followed by the integer mass of the modified residue (e.g. carbamidomethylated Cys key would be C160) and the replacement should be the amino acid letter followed by the PTM name in square brackets (e.g. carbamidomethylated Cys replacement would be C[Carbamidomethyl (C)])
• images folder
  • Contains images for showing color options in the Settings panel in timsplot

Input File Format

Note: multiple files from the same software can be uploaded at a time. In the Upload Search Report section, just select the multiple files in the file explorer window that pops up.

• Spectronaut: Use the report template listed as "timsplot_spectronaut_report.rs" to export the search results.
• DIA-NN: The input is the main report .tsv file. (for DIA-NN 2.0, the input is the report.parquet file).
• FragPipe (and FragPipe Glyco): The input is the psm.tsv result file.
• BPS Novor, tims-rescore, tims-DIANN, Spectronaut (from BPS), Pulsar, and GlycoScape: download artefacts for selected runs in BPS. The input is the .zip folder that's generated from BPS.
• Sage: Use the results.tsv file as input.
• Spectronaut: Use the report template listed as "timsplot_spectromine_report.rs" to export the search results.
• PEAKS: Use the db.psms.csv file from the Peptides export.

Alternative Launch Method

timsplot may also be run using the command line after having installed python and the necessary libraries without the need for using Visual Studio Code

• Navigate to the folder containing all of the timsplot files, right click and click on "Open in Terminal"
• Type the command py -m shiny run --reload --launch-browser app.py to launch timsplot

Disclaimer

This application is not supported by or affiliated with Bruker. It has been developed and tested to the best of the author's abilities, but please use caution when using the application as it may not have had the same level of testing and scrutiny as officially supported software. The application is provided "as-is" and the author assumes no responsibility for errors, bugs, or issues that may arise. Any inquiries, bug reports, or features requests for this application should not be directed to Bruker. This software is provided "as-is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages, or any liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use of other dealings in the software.