Installation, Troubleshooting & FAQ - ChromatinCloud/SeqForge GitHub Wiki

This page guides you through installing BaseBuddy, troubleshooting common issues, and answers frequently asked questions to get you up and running smoothly.

• Operating System: BaseBuddy is primarily developed and tested on Linux and macOS.
• Python: Python 3.8 or newer is recommended.
• Conda/Mamba (Recommended): For managing Python environments and some dependencies. We recommend using Mamba for faster environment solving: conda install -n base -c conda-forge mamba.
• External Tools: Key bioinformatics tools like art_illumina, samtools, curl (and a conceptual addsnv.py or similar for variant spiking) must be installed and accessible in your system's PATH. See the Dependencies page for details.

Clone the repository from GitHub (replace with your actual repository URL):

git clone [https://github.com/ChromatinCloud/BaseBuddy.git](https://github.com/ChromatinCloud/BaseBuddy.git)
cd BaseBuddy

Using Conda/Mamba (Recommended): If an environment.yml file is provided:

mamba env create -f environment.yml  # Or conda env create -f environment.yml
conda activate basebuddy_env       # Or the name specified in environment.yml

This will install Python and any specified Python package dependencies.

Using pip (if pyproject.toml or requirements.txt is set up for it): Ensure you have Python 3.8+ and pip.

python -m venv .venv
source .venv/bin/activate
pip install . # If pyproject.toml is configured for installation
# or pip install -r requirements.txt (if provided)

After activating your environment, check that the required external tools are found:

which art_illumina
which samtools
which curl
# which addsnv.py # If you have a specific script for this

If these commands don't show a path, you'll need to install them and/or adjust your system's PATH. See Dependencies.

Once installed, try a basic command. First, ensure you have a small FASTA reference (e.g., test_ref.fa) and it's indexed (or use the auto-indexing feature).

# If test_ref.fa is not indexed, BaseBuddy will attempt to index it:
./basebuddy.py --output-root ./my_first_run short --reference /path/to/your/test_ref.fa --depth 1 --readlen 50 --profile MSv3 --run-name quick_test

Check the ./my_first_run/quick_test/ directory for output files and a manifest.json.

• Error: BaseBuddyConfigError: External tool 'art_illumina' not found in PATH.

  • Cause: The specified tool (e.g., art_illumina, samtools) is not installed or not in your system's PATH environment variable.
  • Solution: Install the tool (see Dependencies) and ensure its installation directory is added to your PATH. Verify with which <tool_name>.

• Error: BaseBuddyFileError: Reference FASTA is not indexed (.fai missing): /path/to/ref.fa. (if auto-indexing is off)

  • Cause: The provided FASTA file needs a .fai index for tools like ART or samtools to access it efficiently.
  • Solution:
    1. BaseBuddy attempts to auto-index FASTA files by default for relevant commands.
    2. If you've used --no-auto-index-fasta, you'll need to index it manually: samtools faidx /path/to/ref.fa.

• Error: Permission denied when running BaseBuddy or external tools.

  • Cause: The script basebuddy.py might not have execute permissions, or external tools might not be executable, or you lack permissions for input/output directories/files.
  • Solution:
    • Ensure basebuddy.py is executable: chmod +x basebuddy.py.
    • Check permissions of external tools.
    • Verify you have read access to input files and write access to output directories.

• Command Fails / Unexpected Behavior:

  • Solution:
    1. Check the console output for specific error messages from BaseBuddy or the underlying tool.
    2. Increase verbosity: basebuddy --log-level DEBUG ...
    3. Check the log file if specified: basebuddy --log-file basebuddy_run.log ...
    4. Examine the manifest.json in the run's output directory for parameters used.

• Q: How do I install art_illumina or samtools?

  • A: Please refer to their official websites/repositories. samtools is typically available via package managers (conda, apt, brew) or compiled from source from HTSlib. ART binaries or source can be found on its official page. See our Dependencies page for more links.

• Q: BaseBuddy says my FASTA isn't indexed. What do I do?

  • A: BaseBuddy will try to run samtools faidx your_ref.fasta for you if the .fai file is missing for commands like short and spike. If this fails (e.g., samtools not found, or no write permission in the FASTA's directory), you'll see an error. You can manually index it using samtools faidx /path/to/your/reference.fasta.

• Q: A command failed. Where can I find detailed error information?

  • A: BaseBuddy tries to provide informative messages. For more detail:
    1. The console output should show the error from the specific tool if it was an external command.
    2. Use --log-level DEBUG for more verbose output during the run.
    3. If you used --log-file <filename>, check that file.

• Q: Can I use reference files stored on cloud storage (e.g., S3, GCS)?

  • A: Currently, BaseBuddy primarily expects local file paths for reference genomes, BAM files, VCFs, etc. For the download-ref command, it fetches from HTTP/FTP URLs. To use files from cloud storage, you'd typically need to download them to a local accessible path first (e.g., using aws s3 cp or gsutil cp).