Metadata-Version: 2.4
Name: blastdbbuilder-gui
Version: 1.0.6
Summary: GUI for blastdbbuilder
Author: M. Asaduzzaman Prodhan
License: GPL-3.0
Project-URL: Homepage, https://github.com/asadprodhan/blastdbbuilder
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: blastdbbuilder
Requires-Dist: customtkinter

blastdbbuilder GUI: Building a Customised BLASTn Database

M. Asaduzzaman Prodhan* 

 DPIRD Diagnostics and Laboratory Services 

 Department of Primary Industries and Regional Development 

 31 Cedric St, Stirling WA 6021, Australia 

 *Correspondence: asad.prodhan@dpird.wa.gov.au; prodhan82@gmail.com 

---

## **Content**

- [Introduction](#introduction)
- [blastdbbuilder GUI](#blastdbbuilder-gui)
- [Features](#features)
- [Computer Setup](#computer-setup-using-conda)
- [Installation](#installation)
- [Using the GUI](#how-to-use-the-gui-locally)
- [Running Remotely](#how-to-use-the-gui-remotely)
- [Checking progress later](#checking-progress-later)
- [Stopping a job](#stopping-a-job)
- [Citation](#citation)
- [Support](#support)

---

## **Introduction**

A BLASTn database provides the essential reference framework for comparing query sequences, forming the backbone of any sequence-based analysis. Accurate results—whether in diagnostics, biosecurity surveillance, microbial studies, evolutionary research, environmental surveys, or functional genomics—depend on a high-quality, well-curated database.

Public databases are comprehensive but rapidly expanding, often containing redundant, low-quality or irrelevant entries. This leads to slower searches and reduced search resolution.

In contrast, a custom database is like a well‑organised library where every book is precisely indexed—smaller in volume, faster to search, and more focused in results.

To simplify this process for end users, **blastdbbuilder GUI** provides a graphical interface to the proven `blastdbbuilder` backend, allowing fully reproducible database construction without requiring command‑line interaction.

---

## **blastdbbuilder GUI**

`blastdbbuilder GUI` is a Linux graphical front‑end for the `blastdbbuilder` command‑line toolkit.

It enables users to:

- download public reference genomes
- concatenate genome FASTA files
- build customised BLASTn databases

using an interactive graphical interface.

The GUI internally executes the same backend commands as the original `blastdbbuilder` toolkit.

---

## **Features**

- Graphical selection of genome groups (Archaea, Bacteria, Fungi, Virus, Plants)
- Graphical execution of genome download, FASTA concatenation and BLAST database building
- Background execution (safe to close the GUI)
- Reconnect to running jobs
- Live log monitoring
- Safe termination and emergency kill options
- Directory‑based job management

---

## **Computer Setup (Using Conda)**

You need:

- Linux computer, Mac, or Windows using **WSL**
- Python ≥ 3.9
- tkinter
- Singularity / Apptainer

Example setup:

```bash
conda create -n blastdbbuilder python=3.9 -y
conda activate blastdbbuilder
conda install tk
conda install -c bioconda singularity
```

---

## **Installation**

### Recommended installation (PyPI)

Install using pip:

```bash
pip install blastdbbuilder-gui
```

Launch the GUI:

```bash
blastdbbuilder-gui
```

### Optional: Create a Desktop launcher (Linux)

Run once:

```bash
blastdbbuilder-gui-desktop
```

This creates:

```
~/.local/share/applications/blastdbbuilder-gui.desktop
~/.local/share/icons/hicolor/256x256/apps/blastdbbuilder-gui.png
~/Desktop/blastdbbuilder-gui.desktop
```

You can then **double‑click the Desktop icon** to start the GUI.

---

Figure 1. blastdbbuilder graphical user interface (GUI) automating construction of custom BLASTn reference databases from NCBI RefSeq genomes.

---

## **Introduction of the Buttons and their meaning**

**Browse...** Select the working directory.

**Detect running job** Reconnect to a running job in the selected directory.

**Run** Starts the selected action.

**Stop** Gracefully stops the running job.

**Force Kill** Immediately terminates the job and all related processes.

**Clear log view** Clears the GUI log window only.

**Exit** Closes the GUI window.

---

## **How to use the GUI locally**

1. Launch the program using the desktop icon or:

```
blastdbbuilder-gui
```

2. Select the working directory through navigating into the directory and DOUBLE-CLICK the folder to select it, and then pressing OK

3. Choose genome groups:

- Archaea
- Bacteria
- Fungi
- Virus
- Plants

4. Select action:

- Download only
- Concat only
- Build only
- Run all

5. Enable **Run in background**.

6. Click **Run**.

Jobs continue running even if the GUI is closed.

---

## **How to use the GUI remotely**

The GUI is fully supported on remote Linux and HPC systems using X11 forwarding.

1. From your local computer, connect to the remote machine:

```
ssh -X user@remote_server
```

2. Then open a terminal and run the following command

```
blastdbbuilder-gui
```

This will open the blastdbbuilder GUI on your local screen. Then, run the job as you would do it locally. See **How to Use the GUI Locally**

---

## **Checking progress later**

1. Launch the GUI again by double-clicking on the Desktop icon (if you use it locally) or by running `blastdbbuilder-gui` in a terminal 
2. Click **Browse…**
3. Navigate to the **same working directory**
4. **DOUBLE-CLICK** that directory to select it
5. Click **Detect running job**

The GUI will reconnect and continue displaying the live log.

**This directory selection step is essential. The GUI cannot detect jobs without using the same directory.**

---

## **Stopping a job**

To stop a running job:

1. Select the same working directory
2. Click **Detect running job**
3. Click **Stop**

If the job does not stop (for example, a stalled container), click **Force Kill**.

---

## **Citation**

If you use this software in your work, please cite:

Prodhan, M. A. (2025). blastdbbuilder: Building a Customised BLASTn Database. https://doi.org/10.5281/zenodo.17394137

---

## **Support**

For issues, bug reports, or feature requests, please contact:

**Asad Prodhan**  
E-mail: asad.prodhan@dpird.wa.gov.au, prodhan82@gmail.com
