pyBigWig
0.3.23
Ekstensi Python, ditulis dalam C, untuk akses cepat ke file -file besar dan akses ke dan membuat file bigwig. Ekstensi ini menggunakan libbigwig untuk akses file lokal dan jarak jauh.
Anda dapat menginstal ekstensi ini langsung dari GitHub dengan:
pip install pyBigWig
atau dengan conda
conda install pybigwig -c conda-forge -c bioconda
Persyaratan ikuti non-python harus diinstal:
curl-config )Diperlukan header dan perpustakaan untuk ini.
Penggunaan dasar adalah sebagai berikut:
>>> import pyBigWig
Ini akan berfungsi jika direktori kerja Anda adalah direktori kode sumber Pybigwig.
>>> bw = pyBigWig.open("test/test.bw")
Perhatikan bahwa jika file tidak ada, Anda akan melihat pesan kesalahan dan None yang akan dikembalikan. Jadilah default, semua file dibuka untuk membaca dan tidak menulis. Anda dapat mengubah ini dengan melewati mode yang berisi w :
>>> bw = pyBigWig.open("test/output.bw", "w")
Perhatikan bahwa file yang dibuka untuk menulis tidak dapat ditanyai interval atau statistiknya, itu hanya dapat ditulis. Jika Anda membuka file untuk menulis maka Anda selanjutnya perlu menambahkan header (lihat bagian di bawah ini).
Akses Baca Bigbed Lokal dan Remote juga didukung:
>>> bb = pyBigWig.open("https://www.encodeproject.org/files/ENCFF001JBR/@@download/ENCFF001JBR.bigBed")
Meskipun Anda dapat menentukan mode untuk file besar, itu diabaikan. Objek yang dikembalikan oleh pyBigWig.open() adalah sama terlepas dari apakah Anda membuka file bigwig atau besar.
Karena file bigwig dan bigbed keduanya dapat dibuka, mungkin perlu untuk menentukan apakah objek bigWigFile yang diberikan menunjuk ke bigwig atau file besar. Untuk itu, seseorang dapat menggunakan fungsi isBigWig() dan isBigBed() :
>>> bw = pyBigWig.open("test/test.bw")
>>> bw.isBigWig()
True
>>> bw.isBigBed()
False
Objek bigWigFile berisi kamus yang menahan panjang kromosom, yang dapat diakses dengan aksesor chroms() .
>>> bw.chroms()
dict_proxy({'1': 195471971L, '10': 130694993L})
Anda juga dapat secara langsung menanyakan kromosom tertentu.
>>> bw.chroms("1")
195471971L
Panjangnya disimpan sebagai tipe integer "panjang", itulah sebabnya ada akhiran L Jika Anda menentukan kromosom yang tidak ada maka tidak ada output.
>>> bw.chroms("c")
>>>
Terkadang berguna untuk mencetak header bigwig. Ini disajikan di sini sebagai kamus Python yang mengandung: versi (biasanya 4 ), jumlah level zoom ( nLevels ), jumlah basis yang dijelaskan ( nBasesCovered ), nilai minimum ( minVal ), nilai maksimum ( maxVal ), itu jumlah semua nilai ( sumData ), dan jumlah semua nilai kuadrat ( sumSquared ). Dua yang terakhir diperlukan untuk menentukan rata -rata dan standar deviasi.
>>> bw.header()
{'maxVal': 2L, 'sumData': 272L, 'minVal': 0L, 'version': 4L, 'sumSquared': 500L, 'nLevels': 1L, 'nBasesCovered': 154L}
Perhatikan bahwa ini juga dimungkinkan untuk file besar dan kunci kamus yang sama akan ada. Entri seperti maxVal , sumData , minVal , dan sumSquared kemudian sebagian besar tidak bermakna.
File bigwig digunakan untuk menyimpan nilai yang terkait dengan posisi dan rentangnya. Biasanya kami ingin dengan cepat mengakses nilai rata -rata pada kisaran, yang sangat sederhana:
>>> bw.stats("1", 0, 3)
[0.2000000054637591]
Misalkan bukan nilai rata -rata, kami malah menginginkan nilai maksimum:
>>> bw.stats("1", 0, 3, type="max")
[0.30000001192092896]
Opsi lain adalah "min" (nilai minimum), "cakupan" (fraksi pangkalan yang dibahas), dan "std" (standar deviasi nilai).
Sering kali kita ingin menghitung nilai dari sejumlah tempat sampah berjarak merata dalam interval tertentu, yang juga sederhana:
>>> bw.stats("1",99, 200, type="max", nBins=2)
[1.399999976158142, 1.5]
nBins default ke 1, sama seperti type default ke mean .
Jika posisi awal dan akhir dihilangkan maka seluruh kromosom digunakan:
>>> bw.stats("1")
[1.3351851569281683]
Catatan untuk pembaca awam: Bagian ini agak teknis dan hanya dimasukkan demi kelengkapan. Ringkasannya adalah jika kebutuhan Anda membutuhkan rata -rata/maks/dll. Nilai ringkasan untuk interval atau interval dan bahwa trade-off dalam kecepatan dapat diterima, bahwa Anda harus menggunakan opsi
exact=Truedalam fungsistats().
Secara default, ada beberapa aspek yang tidak intuitif untuk komputasi statistik pada rentang dalam file bigwig. Format bigwig awalnya dibuat dalam konteks browser genom. Di sana, komputasi statistik ringkasan yang tepat untuk interval yang diberikan kurang penting daripada dengan cepat dapat menghitung statistik perkiraan (setelah semua, browser harus dapat dengan cepat menampilkan sejumlah interval yang berdekatan dan mendukung pengguliran/zooming). Karena itu, file bigwig tidak hanya mengandung asosiasi nilai interval, tetapi juga sum of values / sum of squared values / minimum value / maximum value / number of bases covered untuk nampan berukuran sama dari berbagai ukuran. Ukuran yang berbeda ini disebut sebagai "level zoom". Level zoom terkecil memiliki nampan yang 16 kali ukuran interval rata -rata dalam file dan setiap level zoom berikutnya memiliki nampan 4 kali lebih besar dari sebelumnya. Metodologi ini digunakan dalam alat Kent dan, oleh karena itu, kemungkinan digunakan di hampir setiap file bigwig yang ada saat ini.
Ketika file bigwig ditanya untuk statistik ringkasan, ukuran interval digunakan untuk menentukan apakah akan menggunakan level zoom dan, jika demikian, yang mana. Level zoom yang optimal adalah yang memiliki tempat sampah terbesar tidak lebih dari setengah lebar interval yang diinginkan. Jika tidak ada tingkat zoom seperti itu, interval asli sebaliknya digunakan untuk perhitungan.
Demi konsistensi dengan alat lain, Pybigwig mengadopsi metodologi yang sama ini. Namun, karena ini adalah (a) tidak intuitif dan (b) tidak diinginkan dalam beberapa aplikasi, Pybigwig memungkinkan perhitungan statistik ringkasan yang tepat terlepas dari ukuran interval (yaitu, memungkinkan mengabaikan level zoom). Ini awalnya diusulkan di sini dan contoh di bawah ini:
>>> import pyBigWig
>>> from numpy import mean
>>> bw = pyBigWig.open("http://hgdownload.cse.ucsc.edu/goldenPath/hg19/encodeDCC/wgEncodeMapability/wgEncodeCrgMapabilityAlign75mer.bigWig")
>>> bw.stats('chr1', 89294, 91629)
[0.20120902053804418]
>>> mean(bw.values('chr1', 89294, 91629))
0.22213841940688142
>>> bw.stats('chr1', 89294, 91629, exact=True)
[0.22213841940688142]
Sementara metode stats() dapat digunakan untuk mengambil nilai asli untuk setiap basis (misalnya, dengan mengatur nBins ke jumlah basis), lebih baik untuk menggunakan values() Accessor.
>>> bw.values("1", 0, 3)
[0.10000000149011612, 0.20000000298023224, 0.30000001192092896]
Daftar yang diproduksi akan selalu berisi satu nilai untuk setiap basis dalam kisaran yang ditentukan. Jika basis tertentu tidak memiliki nilai terkait dalam file bigwig maka nilai yang dikembalikan akan menjadi nan .
>>> bw.values("1", 0, 4)
[0.10000000149011612, 0.20000000298023224, 0.30000001192092896, nan]
Terkadang lebih mudah untuk mengambil semua entri yang tumpang tindih dengan beberapa rentang. Ini dapat dilakukan dengan fungsi intervals() :
>>> bw.intervals("1", 0, 3)
((0, 1, 0.10000000149011612), (1, 2, 0.20000000298023224), (2, 3, 0.30000001192092896))
Apa yang dikembalikan adalah daftar tupel yang berisi: posisi awal, posisi akhir, dan nilainya. Dengan demikian, contoh di atas memiliki nilai 0.1 , 0.2 , dan 0.3 pada posisi 0 , 1 , dan 2 , masing -masing.
Jika posisi awal dan akhir dihilangkan maka semua interval pada kromosom yang ditentukan dikembalikan:
>>> bw.intervals("1")
((0, 1, 0.10000000149011612), (1, 2, 0.20000000298023224), (2, 3, 0.30000001192092896), (100, 150, 1.399999976158142), (150, 151, 1.5))
Berbeda dengan file bigwig, file bigbed menahan entri, yang merupakan interval dengan string terkait. Anda dapat mengakses entri ini menggunakan fungsi entries() :
>>> bb = pyBigWig.open("https://www.encodeproject.org/files/ENCFF001JBR/@@download/ENCFF001JBR.bigBed")
>>> bb.entries('chr1', 10000000, 10020000)
[(10009333, 10009640, '61035t130t-t0.026t0.42t404'), (10014007, 10014289, '61047t136t-t0.029t0.42t404'), (10014373, 10024307, '61048t630t-t5.420t0.00t2672399')]
Outputnya adalah daftar tupel entri. Elemen tuple adalah posisi start dan end dari setiap entri, diikuti oleh string yang terkait. String dikembalikan persis seperti yang disimpan dalam file besar, jadi parsing diserahkan kepada Anda. Untuk menentukan apa berbagai bidang dalam string ini, konsultasikan dengan string SQL:
>>> bb.SQL()
table RnaElements
"BED6 + 3 scores for RNA Elements data"
(
string chrom; "Reference sequence chromosome or scaffold"
uint chromStart; "Start position in chromosome"
uint chromEnd; "End position in chromosome"
string name; "Name of item"
uint score; "Normalized score from 0-1000"
char[1] strand; "+ or - or . for unknown"
float level; "Expression level such as RPKM or FPKM. Set to -1 for no data."
float signif; "Statistical significance such as IDR. Set to -1 for no data."
uint score2; "Additional measurement/count e.g. number of reads. Set to 0 for no data."
)
Perhatikan bahwa tiga entri pertama dalam string SQL bukan bagian dari string.
Jika Anda hanya perlu tahu di mana entri berada dan bukan nilai yang terkait, Anda dapat menyimpan memori dengan juga menentukan withString=False di entries() :
>>> bb.entries('chr1', 10000000, 10020000, withString=False)
[(10009333, 10009640), (10014007, 10014289), (10014373, 10024307)]
Jika Anda telah membuka file untuk menulis maka Anda harus memberikan header sebelum Anda dapat menambahkan entri apa pun. Header berisi semua kromosom, secara berurutan , dan ukurannya. Jika genom Anda memiliki dua kromosom, CHR1 dan CHR2, dengan panjang 1 dan 1,5 juta pangkalan, maka berikut ini akan menambahkan header yang sesuai:
>>> bw.addHeader([("chr1", 1000000), ("chr2", 1500000)])
Header bigwig sensitif terhadap case, jadi chr1 dan Chr1 berbeda. Demikian juga, 1 dan chr1 tidak sama, jadi Anda tidak dapat mencampur nama kromosom Ensembl dan UCSC. Setelah menambahkan header, Anda kemudian dapat menambahkan entri.
Secara default, hingga 10 "level zoom" dibangun untuk file bigwig. Anda dapat mengubah nomor default ini dengan argumen opsional maxZooms . Penggunaan umum dari ini adalah untuk membuat file bigwig yang hanya menyimpan interval dan tidak ada level zoom:
>>> bw.addHeader([("chr1", 1000000), ("chr2", 1500000)], maxZooms=0)
Jika Anda mengatur maxTooms=0 , harap dicatat bahwa IGV dan banyak alat lain tidak akan berfungsi karena mereka mengasumsikan bahwa setidaknya satu level zoom akan hadir. Anda disarankan untuk menggunakan default kecuali Anda tidak mengharapkan file bigwig digunakan oleh paket lain.
Dengan asumsi Anda telah membuka file untuk menulis dan menambahkan header, Anda kemudian dapat menambahkan entri. Perhatikan bahwa entri harus ditambahkan secara berurutan, karena file bigwig selalu berisi interval yang dipesan. Ada tiga format yang dapat digunakan file bigwig secara internal untuk menyimpan entri. Format yang paling umum diamati identik dengan file bedgraph:
chr1 0 100 0.0
chr1 100 120 1.0
chr1 125 126 200.0
Entri ini akan ditambahkan sebagai berikut:
>>> bw.addEntries(["chr1", "chr1", "chr1"], [0, 100, 125], ends=[5, 120, 126], values=[0.0, 1.0, 200.0])
Setiap entri menempati 12 byte sebelum kompresi.
Format kedua menggunakan rentang tetap, tetapi ukuran langkah variabel antara entri. Ini dapat diwakili dalam file gerak sebagai:
variableStep chrom=chr1 span=20
500 -2.0
600 150.0
635 25.0
Entri di atas menjelaskan posisi (berbasis 1) 501-520, 601-620 dan 636-655. Ini akan ditambahkan sebagai berikut:
>>> bw.addEntries("chr1", [500, 600, 635], values=[-2.0, 150.0, 25.0], span=20)
Setiap entri jenis ini menempati 8 byte sebelum kompresi.
Format akhir menggunakan langkah dan rentang tetap untuk setiap entri, sesuai dengan format Wiggle FixedStep:
fixedStep chrom=chr1 step=30 span=20
-5.0
-20.0
25.0
Entri di atas menggambarkan (berbasis 1) basis 901-920, 931-950 dan 961-980 dan akan ditambahkan sebagai berikut:
>>> bw.addEntries("chr1", 900, values=[-5.0, -20.0, 25.0], span=20, step=30)
Setiap entri jenis ini menempati 4 byte.
Perhatikan bahwa Pybigwig akan mencoba mencegah Anda menambahkan entri dalam urutan yang salah. Namun, ini membutuhkan tambahan kepala. Jika itu tidak dapat diterima, Anda dapat menentukan validate=False saat menambahkan entri:
>>> bw.addEntries(["chr1", "chr1", "chr1"], [100, 0, 125], ends=[120, 5, 126], values=[0.0, 1.0, 200.0], validate=False)
Anda jelas kemudian bertanggung jawab untuk memastikan bahwa Anda tidak menambahkan entri yang rusak. File yang dihasilkan sebaliknya Largley tidak dapat digunakan.
File dapat ditutup dengan bw.close() , seperti yang biasa dilakukan dengan jenis file lainnya. Untuk file yang dibuka untuk menulis, menutup file menulis entri buffered ke disk, membuat dan menulis indeks file, dan membangun level zoom. Akibatnya, ini bisa memakan waktu sedikit.
Pada versi 0.3.0, Pybigwig mendukung input koordinat menggunakan bilangan bulat dan vektor numpy dalam beberapa fungsi jika Numpy diinstal sebelum memasang pybigwig . Untuk menentukan apakah Pybigwig diinstal dengan dukungan numpy dengan memeriksa aksesor numpy :
>>> import pyBigWig
>>> pyBigWig.numpy
1
Jika pyBigWig.numpy adalah 1 , maka Pybigwig dikompilasi dengan dukungan numpy. Ini berarti bahwa addEntries() dapat menerima koordinat numpy:
>>> import pyBigWig
>>> import numpy
>>> bw = pyBigWig.open("/tmp/delete.bw", "w")
>>> bw.addHeader([("1", 1000)], maxZooms=0)
>>> chroms = np.array(["1"] * 10)
>>> starts = np.array([0, 10, 20, 30, 40, 50, 60, 70, 80, 90], dtype=np.int64)
>>> ends = np.array([5, 15, 25, 35, 45, 55, 65, 75, 85, 95], dtype=np.int64)
>>> values0 = np.array(np.random.random_sample(10), dtype=np.float64)
>>> bw.addEntries(chroms, starts, ends=ends, values=values0)
>>> bw.close()
Selain itu, values() dapat secara langsung menghasilkan vektor numpy:
>>> bw = bw.open("/tmp/delete.bw")
>>> bw.values('1', 0, 10, numpy=True)
[ 0.74336642 0.74336642 0.74336642 0.74336642 0.74336642 nan
nan nan nan nan]
>>> type(bw.values('1', 0, 10, numpy=True))
<type 'numpy.ndarray'>
Jika Anda tidak menginstal Curl, Pybigwig akan diinstal tanpa kemampuan untuk mengakses file jarak jauh. Anda dapat menentukan apakah Anda dapat mengakses file jarak jauh dengan pyBigWig.remote . Jika itu mengembalikan 1, maka Anda dapat mengakses file jarak jauh. Jika mengembalikan 0 maka Anda tidak bisa.
Pada versi 0.3.5, Pybigwig dapat membaca dan menulis file bigwig yang kekurangan entri. Harap dicatat bahwa file tersebut umumnya tidak kompatibel dengan program lain, karena tidak ada definisi tentang bagaimana file bigwig tanpa entri harus terlihat. Untuk file seperti itu, Accessor intervals() None akan mengembalikan, fungsi stats() akan mengembalikan daftar None panjang yang diinginkan, dan values() akan mengembalikan [] (daftar kosong). Ini umumnya harus memungkinkan program yang memanfaatkan Pybigwig untuk melanjutkan tanpa masalah.
Bagi mereka yang ingin meniru fungsionalitas pybigwig/libbigwig dalam hal ini, harap dicatat bahwa itu terlihat pada jumlah pangkalan yang dibahas (seperti yang dilaporkan dalam header file) untuk memeriksa file "kosong".
File Wiggle, Bigwig, dan Bigbed menggunakan koordinat setengah terbuka berbasis 0, yang juga digunakan oleh ekstensi ini. Jadi untuk mengakses nilai untuk basis pertama pada chr1 , orang akan menentukan posisi awal sebagai 0 dan posisi akhir sebagai 1 . Demikian pula, pangkalan 100 hingga 115 akan memiliki awal 99 dan akhir 115 . Ini hanya demi konsistensi dengan file bigwig yang mendasarinya dan dapat berubah di masa depan.
Pybigwig juga tersedia sebagai paket di Galaxy. Anda dapat menemukannya di toolshed dan IUC saat ini menjadi hosting definisi XML tentang ini di GitHub.
