Troubleshooting

Common Issues

UCSC Tools Not Found

Error: gtfToGenePred: command not found

Solution:

1. Run the installation script:

   bash install_ucsc_tools.sh

2. Or add the tools to your PATH:

   export PATH="/path/to/tools:$PATH"

Hub Not Loading in UCSC

Problem: Hub URL doesn't work in UCSC Genome Browser

Solutions:

1. Ensure files are publicly accessible (no authentication required)
2. Check that hub.txt URL is correct
3. Verify all referenced files exist at the specified URLs
4. Use raw URLs for GitHub (https://raw.githubusercontent.com/...)

Tracks Not Showing Changes

Problem: Hub not updating after requesting changes

Solutions:

1. Regenerate the hub (the issue was fixed in recent versions)
2. Clear your UCSC browser cache
3. Ensure track is in "full" or "pack" mode (not "dense")
4. Insert 'udcTimeout=5&' just after the "hgTracks" portion of the URL so that it reads http://genome.ucsc.edu/cgi-bin/hgTracks?udcTimeout=5& (with the remainder of the URL following the ampersand)

Filters Not Working

Problem: Dropdown filters or range sliders not appearing

Solutions:

1. Right-click on the track → Configure (not just the main filter page)
2. Regenerate the hub with the latest version
3. Check that the bigBed file was created successfully
4. Insert 'udcTimeout=5&' just after the "hgTracks" portion of the URL so that it reads http://genome.ucsc.edu/cgi-bin/hgTracks?udcTimeout=5& (with the remainder of the URL following the ampersand)

Trix Search Returns No Results

Problem: Searching in UCSC returns "no results"

Solutions:

1. Ensure trix.ix and trix.ixx files were generated
2. Check that trackDb.txt includes the searchTrix directive
3. Use the correct search syntax (e.g., structural_category_novel_in_catalog)
4. Refresh the hub in UCSC (remove and re-add)
5. Insert 'udcTimeout=5&' just after the "hgTracks" portion of the URL so that it reads http://genome.ucsc.edu/cgi-bin/hgTracks?udcTimeout=5& (with the remainder of the URL following the ampersand)

bedToBigBed Fails

Error: bedToBigBed failed or file not sorted

Solutions:

1. Ensure your GTF file has valid chromosome names matching the genome
2. Check for special characters in transcript IDs
3. Use --keep-temp to inspect intermediate files

Memory Issues

Problem: Script runs out of memory with large files

Solutions:

1. Ensure you have sufficient RAM (4GB+ recommended)
2. Close other applications
3. Try processing on a machine with more memory

Debugging

Enable Verbose Logging

Edit the script to change logging level:

logging.basicConfig(level=logging.DEBUG, ...)

Keep Temporary Files

Use --keep-temp to preserve intermediate files:

python sqanti3_to_UCSC.py ... --keep-temp

This helps identify where the process is failing.

Validate Inputs

Use --validate-only to check inputs without processing:

python sqanti3_to_UCSC.py ... --validate-only

Dry Run

Use --dry-run to test up to BED generation:

python sqanti3_to_UCSC.py ... --dry-run

Getting Help

1. Check the GitHub Issues for similar problems
2. Run python test_installation.py to verify your setup
3. Open a new issue with:
   • Error message
   • Command used
   • Input file sizes
   • Python and tool versions

Version Compatibility

• Python: 3.7+
• pandas: 1.0+
• UCSC Tools: Latest versions recommended

Check your versions:

python --version
python -c "import pandas; print(pandas.__version__)"
gtfToGenePred 2>&1 | head -1