{"id":9207,"library":"pybedtools","title":"pybedtools","description":"pybedtools wraps and extends BEDTools and offers feature-level manipulations from within Python. It allows for genomic interval manipulation, also known as 'genome algebra'. The current version is 0.12.0, and it generally follows the release cadence of BEDTools, with major updates happening periodically.","status":"active","version":"0.12.0","language":"en","source_language":"en","source_url":"https://github.com/daler/pybedtools","tags":["bioinformatics","genomics","BEDTools","DNA","RNA","interval-arithmetic"],"install":[{"cmd":"pip install pybedtools","lang":"bash","label":"PyPI"},{"cmd":"conda install -c bioconda pybedtools","lang":"bash","label":"Conda (Recommended)"}],"dependencies":[{"reason":"pybedtools is a Python wrapper for the BEDTools suite of command-line tools, so BEDTools itself must be installed and accessible in the system's PATH.","package":"BEDTools"},{"reason":"Used for handling BAM files; replaced the direct dependency on `samtools` as of v0.7.9/v0.8.0.","package":"pysam"},{"reason":"Required for pybedtools development; Cythonized C++ files are now shipped with the distribution for end-users.","package":"Cython","optional":true},{"reason":"Necessary for building C++ components, especially if installing via pip without pre-compiled wheels or if Cython recompilation is triggered.","package":"A C/C++ compiler"}],"imports":[{"symbol":"BedTool","correct":"from pybedtools import BedTool"},{"note":"Directly importing 'scripts' can conflict with an 'scripts' module from Anaconda, causing an ImportError. Use `import pybedtools.scripts` or rename your script file if it's named 'scripts.py'.","wrong":"from pybedtools import scripts","symbol":"scripts","correct":"import pybedtools.scripts"}],"quickstart":{"code":"import pybedtools\nimport os\n\n# Create dummy files for demonstration\n# In a real scenario, these would be your actual genomic files\nwith open('snps.bed', 'w') as f:\n    f.write('chr1\\t10\\t20\\tSNP1\\n')\n    f.write('chr1\\t30\\t40\\tSNP2\\n')\nwith open('exons.bed', 'w') as f:\n    f.write('chr1\\t15\\t25\\tEXON1\\n')\n    f.write('chr1\\t35\\t45\\tEXON2\\n')\n\n# Create BedTool objects from files\nsnps = pybedtools.BedTool('snps.bed')\nexons = pybedtools.BedTool('exons.bed')\n\n# Perform an intersection and save the results\n# This example saves a new BED file of intersections\n# between snps.bed and exons.bed\nintersected_bed = snps.intersect(exons)\noutput_filename = 'snps_in_exons.bed'\nintersected_bed.saveas(output_filename, trackline=\"track name='SNPs in exons' color=128,0,0\")\n\nprint(f\"Intersection results saved to {output_filename}:\")\nwith open(output_filename, 'r') as f:\n    print(f.read())\n\n# Clean up dummy files\nos.remove('snps.bed')\nos.remove('exons.bed')\nos.remove(output_filename)\n","lang":"python","description":"This quickstart demonstrates how to create `BedTool` objects from existing BED files, perform an intersection operation (like `intersectBed`), and save the results to a new file, including adding a track line."},"warnings":[{"fix":"Upgrade to a supported Python version (3.9+ for v0.11.0+, 3.8+ for v0.9.1 to <0.11.0).","message":"Python 3.8 support was removed in pybedtools v0.11.0. Python 3.6 and 3.7 support was dropped in v0.9.1.","severity":"breaking","affected_versions":">=0.11.0, >=0.9.1"},{"fix":"Minimize `BedTool` object creation. Many operations can be chained or filtered without creating new intermediate `BedTool` objects. Construct 'streaming' BedTools or apply `filter()` methods upfront to reduce the number of open files.","message":"Repeatedly creating `BedTool` objects, especially within loops, can lead to a 'Too many files open' error.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always assume 0-based coordinates when programmatically accessing `Interval` object's `.start` and `.stop` attributes. Be mindful of the output format's conventions when saving to file.","message":"pybedtools adheres to 0-based (BED) and 1-based (GFF) coordinate systems in the raw string output, but internally converts all `Interval` object start/stop attributes to 0-based for consistency.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `pysam` is installed if working with BAM files; direct `samtools` installation is no longer required or supported by pybedtools itself.","message":"The `samtools` dependency was removed and replaced by `pysam` for BAM file handling.","severity":"deprecated","affected_versions":"<0.7.9"},{"fix":"Pre-process input files to ensure they conform strictly to BEDTools specifications or use `pybedtools.remove_invalid()` to clean them. Review BEDTools documentation for expected file formats.","message":"pybedtools relies on the underlying BEDTools executables. If BEDTools issues a warning (e.g., about malformed lines), pybedtools might raise an error and fail to create a `BedTool` object, even if BEDTools itself would produce output.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statement to `import pybedtools.scripts` instead of `from pybedtools import scripts`. Alternatively, ensure no other module or script in your Python path is named 'scripts.py'.","cause":"This typically occurs when using an Anaconda environment where another package or a user-created script is named 'scripts', shadowing the `pybedtools.scripts` module.","error":"ImportError: cannot import name scripts"},{"fix":"Refactor your code to minimize the number of `BedTool` objects created simultaneously. Utilize chaining of methods, `BedTool.filter()`, or `BedTool.each()` to process data efficiently without creating excessive temporary files. Use `pybedtools.cleanup()` if necessary to force deletion of temporary files.","cause":"Too many `BedTool` objects were created, exhausting the operating system's file handle limit. This often happens in loops.","error":"IOError: [Errno 24] Too many open files"},{"fix":"Inspect the problematic lines in your input file. Ensure `start <= end` and all fields are tab-delimited. Use `pybedtools.remove_invalid()` to attempt to clean the file or manually correct the lines.","cause":"The input BED file contains lines that do not conform to the BED format specification (e.g., start coordinate is greater than end, incorrect number of fields, non-tab-delimited fields).","error":"pybedtools.helpers.MalformedBedLineError: Malformed BED line:"},{"fix":"Install BEDTools on your system (e.g., `conda install -c bioconda bedtools`). Verify that the `bedtools` command is accessible from your terminal by typing `bedtools --version`.","cause":"The underlying BEDTools executable is not found in the system's PATH. pybedtools acts as a wrapper and requires BEDTools to be installed separately.","error":"command not found: bedtools"},{"fix":"Ensure you have a C/C++ compiler installed (e.g., `build-essential` on Linux, Xcode on macOS). If using `pip`, consider installing via Conda (`conda install -c bioconda pybedtools`) which often handles compiler dependencies more robustly.","cause":"This (or similar compilation errors) can occur during `pip install pybedtools` if a suitable C/C++ compiler is not found or is outdated, particularly when building Cython components.","error":"g++: error: unrecognized command line option '-std=c++11'"}]}