Skip to main content

2. Introduction to TidyScreen projects

TidyScreen projects provide a structured environment for organizing and managing all data, scripts, and results generated throughout your virtual screening workflows.

This short tutorial will guide you through the essential commands to create, list, and import TidyScreen projects, as well as to understand their directory layout.

We recommend creating a dedicated Python script, for example workshop.py, and executing each command within the tidyscreen conda environment.

⚙️ 2.1- Creating a new project​

Start by launching your conda environment in a terminal:

conda activate tidyscreen

You can easily create a new TidyScreen project using the create_project() function.

workshop.py
# Import tidyscreen module
from tidyscreen import tidyscreen as ts

# Create a new TidyScreen project named "la_workshop_2025" in the working directory
ts.create_project("/PATH/TO/PROJECT/DIR", "la_workshop_2025")
📝 Receptor description

When prompted, you will need to provide a short description of the project.
Try to include as many relevant details as possible. This information will be very useful in the future, especially when your database grows and you manage multiple projects.

Input project short description:

You should get the following output:

Project 'la_workshop_2025' created at: '/PATH/TO/PROJECT/DIR/la_workshop_2025'.

📁 2.2- Listing Locally Available Projects​

To list all projects registered in your local TidyScreen database, use:

workshop.py
ts.projects()

TidyScreen main database found! Continuing...
Project: la_workshop_2025
         located at /PATH/TO/PROJECT/DIR/la_workshop_2025

This command scans the main database and prints all recognized TidyScreen projects on your system, including their paths.

📦 2.3- Importing an Existing Project​

If you already have an existing project (for example, from another machine or collaborator), you can import it directly executing the following:

workshop.py
ts.import_project()

You will be asked to provide the full path where the project to import is located

Input the full path to the project to import:

🧱 2.4- Structure of a TidyScreen Project​

Each project generated by TidyScreen follows a consistent internal structure composed of several main folders. These are automatically created when running create_project():

Structure of TidyScreen projects
la_workshop_2025/
├── chemspace/          
│   └── ...  # storage of input chemical libraries and processed datasets
├── docking/            
│   └── ...  # receptor files, docking assays, docking parameters, etc.
├── dynamics/   
│   └── ...  # molecular dynamics simulations on selected systems
├── ml/   
    └── ...  # management of data associated to the development of machine learning models used in the campaign

We will be exploring the contents of each folder as this tutorial advances in the next sections.