tfeddlmZddlZddlZddlZddlZddlZ ddl m Z ddl m Z ddlmZmZmZmZmZmZmZmZddlmZddlmZmZmZmZd d gZhd ZGd d Z dd Z! d ddZ" d ddZ# d ddZ$ d ddZ% d ddZ&y)) annotationsN)is_integer_dtype) coo_matrix) CSRReaderDirectRangeQuery2DFillLowerRangeQuery2DRangeSelector1DRangeSelector2Dgetregion_to_extentregion_to_offset) list_coolers) closing_hdf5 open_hdf5parse_cooler_uri parse_regionCoolerannotate>KRVCVC_SQRTceZdZdZdddZddZddZddZdddZe ddZ e dd Z e dd Z e dd Z d d Zd!d Ze d"dZe d#dZd$dZd$dZd%d&dZ d' d(dZddZy))ra] A convenient interface to a cooler data collection. Parameters ---------- store : str, :py:class:`h5py.File` or :py:class:`h5py.Group` Path to a cooler file, URI string, or open handle to the root HDF5 group of a cooler data collection. root : str, optional [deprecated] HDF5 Group path to root of cooler group if ``store`` is a file. This option is deprecated. Instead, use a URI string of the form :file:`::`. kwargs : optional Options to be passed to :py:class:`h5py.File()` upon every access. By default, the file is opened with the default driver and mode='r'. Notes ----- If ``store`` is a file path, the file will be opened temporarily in when performing operations. This allows :py:class:`Cooler` objects to be serialized for multiprocess and distributed computations. Metadata is accessible as a dictionary through the :py:attr:`info` property. Table selectors, created using :py:meth:`chroms`, :py:meth:`bins`, and :py:meth:`pixels`, perform range queries over table rows, returning :py:class:`pd.DataFrame` and :py:class:`pd.Series`. A matrix selector, created using :py:meth:`matrix`, performs 2D matrix range queries, returning :py:class:`numpy.ndarray` or :py:class:`scipy.sparse.coo_matrix`. Nc t|tr|t|\|_|_nXt j |r8t|fi|5}|jj|_||_dddn td|jdz|jz|_ |j|_ ||_ ne|jj|_|j|_|jdz|jz|_ |j|_ i|_ |jy#1swYxYw)Nz!Not a valid path to a Cooler file::) isinstancestrrfilenamerooth5pyis_hdf5rfile ValueErroruristoreopen_kwsname_refresh)selfr%rkwargsh5s T/var/www/html/software/conda/envs/higlass/lib/python3.12/site-packages/cooler/api.py__init__zCooler.__init__Ds eS !|+;E+B( tye$u//%2$&GG$4$4DM $DI%%!!DEE}}t+dii7DHDJ"DM"JJ//DM DI}}t+dii7DHDJDM %%s #D44D=c  t|jfi|j5}||j}t |}|dj t |d<|jdd|_tt|dtt||_ t||_|jj!dd}|dk(|_dddy#1swYyxYw#t$$rId|jd}t'|j}t|r |d|dd zz }t%|dwxYw) Nr'length storage-modesymmetric-upperzNo cooler found at: .z Coolers found in z. z Use '::' to specify a group path)rr%r&rchromsastypeobject set_index _chromsizesdictziprangelen _chromidsinfo_infor _is_symm_upperKeyErrorr)r)r+grp_ctmodeerr_msglistings r,r(zCooler._refreshZs, .4::77 @2mSk!&k008F #&==#8#B !%c#f+uSX&G!H!#Y zz~~n6GH&*.?&?# @ @ @ .,TZZL:G"4::.G7|( 4897# - .s* C+B4CC+C($C+(C++AD=ct|jfi|j5}||j}||ddcdddS#1swYyxYwN)rr%r&rr)pathr+rAs r, _load_dsetzCooler._load_dsetosF tzz 3T]] 3 rTYY-Ct9Q<   s AA ct|jfi|j5}||j}t ||j cdddS#1swYyxYwrG)rr%r&rr8attrsrHs r, _load_attrszCooler._load_attrstsK tzz 3T]] 3 )rTYY-CD ( ) ) )s 'AAc ttj|j|fi||j}t |S)aOpen the HDF5 group containing the Cooler with :py:mod:`h5py` Functions as a context manager. Any ``open_kws`` passed during construction are ignored. Parameters ---------- mode : str, optional [default: 'r'] * ``'r'`` (readonly) * ``'r+'`` or ``'a'`` (read/write) Notes ----- For other parameters, see :py:class:`h5py.File`. )r Filerrr)r)rCr*rAs r,openz Cooler.openys1"ii t6v6tyyAC  c:|jjddS)zIndicates whether ordinary sparse matrix encoding is used (``"square"``) or whether a symmetric matrix is encoded by storing only the upper triangular elements (``"symmetric-upper"``). r0r1)r>r r)s r, storage_modezCooler.storage_modes zz~~n.?@@rQc |jdS)z-Resolution in base pairs if uniform else Nonezbin-sizer>rSs r,binsizezCooler.binsizeszz*%%rQc|jS)z=Ordered mapping of reference sequences to their lengths in bp)r7rSs r, chromsizeszCooler.chromsizessrQc@t|jjS)z List of reference sequence names)listr7indexrSs r, chromnameszCooler.chromnamessD$$**++rQc t|jfi|j5}||j}t ||j t ||j|jcdddS#1swYyxYw)a'Bin ID containing the left end of a genomic region Parameters ---------- region : str or tuple Genomic range Returns ------- int Examples -------- >>> c.offset('chr3') # doctest: +SKIP 1311 N) rr%r&rrr<rr7rWr)regionr+rAs r,offsetz Cooler.offsetf$tzz 3T]] 3 rTYY-C#VT%5%56     AA00A9c t|jfi|j5}||j}t ||j t ||j|jcdddS#1swYyxYw)aGBin IDs containing the left and right ends of a genomic region Parameters ---------- region : str or tuple Genomic range Returns ------- 2-tuple of ints Examples -------- >>> c.extent('chr3') # doctest: +SKIP (1311, 2131) N rr%r&rr r<rr7rWr_s r,extentz Cooler.extentrbrcct|jfi|j5}||j}t |cdddS#1swYyxYw)zUFile information and metadata Returns ------- dict N)rr%r&rr=)r)r+rAs r,r=z Cooler.infosDtzz 3T]] 3 rTYY-C9   s AAc(|jdfdzS)NnbinsrVrSs r,shapez Cooler.shapes 7#%))rQc Hfd}td|djdS)z[Chromosome table selector Returns ------- Table selector ctjfij5}|j}t ||||ficdddS#1swYyxYwrG)rr%r&rr3fieldslohir+rAr*r)s r,_slicezCooler.chroms.._slicesO4::77 =2mc2r6)r)r*rrs`` r,r3z Cooler.chromss$ = tVT4::i3HIIrQc Rfd}fd}td||jdS)zTBin table selector Returns ------- Table selector ctjfij5}|j}t ||||ficdddS#1swYyxYwrG)rr%r&rbinsrns r,rrzCooler.bins.._slicesO4::77 ;2mCR:6: ; ; ;rsc tjfij5}|j}t |j t |jjcdddS#1swYyxYwrGre)r`r+rAr)s r,_fetchzCooler.bins.._fetch se4::77 2m'NN )9)9:LL    s AA11A:Nriru)r)r*rrrzs`` r,rxz Cooler.binss) ;  tVVTZZ5HIIrQc Vfd}fd}td||jdS)aPixel table selector Parameters ---------- join : bool, optional Whether to expand bin ID columns into chrom, start, and end columns. Default is ``False``. Returns ------- Table selector ctjfij5}|j}t ||||ficdddS#1swYyxYwrG)rr%r&rpixels)rorprqr+rAjoinr*r)s r,rrzCooler.pixels.._slice$sU4::77 C2mc2r64B6B C C Cs A  Ac 4tjfij5}|j}t |j t |jj\}}|dd|}|dd|}||fcdddS#1swYyxYw)Nindexes bin1_offsetre)r`r+rAi0i1rprqr)s r,rzzCooler.pixels.._fetch)s4::77 2m)NN )9)9:LL B ^M226^M2262v   s A"BBNnnzru)r)r~r*rrrzs``` r,r}z Cooler.pixelss* C tVVTZZ5FGGrQc tvrdfd} dfd } t|| | jdfdzS)aContact matrix selector Parameters ---------- field : str, optional Which column of the pixel table to fill the matrix with. By default, the 'count' column is used. balance : bool, optional Whether to apply pre-calculated matrix balancing weights to the selection. Default is True and uses a column named 'weight'. Alternatively, pass the name of the bin table column containing the desired balancing weights. Set to False to return untransformed counts. sparse: bool, optional Return a scipy.sparse.coo_matrix instead of a dense 2D numpy array. as_pixels: bool, optional Return a DataFrame of the corresponding rows from the pixel table instead of a rectangular sparse matrix. False by default. join : bool, optional If requesting pixels, specifies whether to expand the bin ID columns into (chrom, start, end). Has no effect when requesting a rectangular matrix. Default is True. ignore_index : bool, optional If requesting pixels, don't populate the index column with the pixel IDs to improve performance. Default is True. divisive_weights : bool, optional Force balancing weights to be interpreted as divisive (True) or multiplicative (False). Weights are always assumed to be multiplicative by default unless named KR, VC or SQRT_VC, in which case they are assumed to be divisive by default. Returns ------- Matrix selector Notes ----- If ``as_pixels=True``, only data explicitly stored in the pixel table will be returned: if the cooler's storage mode is symmetric-upper, lower triangular elements will not be generated. If ``as_pixels=False``, those missing non-zero elements will automatically be filled in. Tct jfi j5}| j}t |||||| j cdddS#1swYyxYwrG)rr%r&rmatrixr?)fieldrrj0j1r+rA as_pixelsbalance chunksizedivisive_weights ignore_indexr~r)sparses r,rrzCooler.matrix.._slicerst4::77 2m $''   s 1AA&ct jfi j5}| j}||}t | j }t | j }t | j| j\}}t | j| j\}}||||fcdddS#1swYyxYwrG) rr%r&rrr7r r<rW) r`region2r+rAregion1rrrrr)s r,rzzCooler.matrix.._fetchs4::77 &2m?$G&vt/?/?@&w0@0@A)#t~~w UB)#t~~w UB2r2~ & & &s BB;;CrirjrG)_4DN_DIVISIVE_WEIGHTSr r>) r)rrrrr~rrrrrrzs ` ``````` r,rz Cooler.matrix8sNn + +0@0H#   ( &ufftzz'7J6Lq6PQQrQct|jtr;tjj |j}|d|j }nt|j}d|dS)Nrz )rr%rosrIbasenamerrepr)r)r containers r,__repr__zCooler.__repr__sY djj# &ww'' 3H#*Btyyk2ITZZ(I9+R((rQrG)r%zstr | h5py.Groupr str | None)returnNone)rIrrz np.ndarray)rIrrr8)r)rCrr h5py.Group)rr)r int | None)rz pd.Series)rz list[str])r`str | tuple[str, int, int]rint)r`rrtuple[int, int])rr8)rr)rr F)r~boolrr )NTFFFTN逖)rrr bool | strrrrrr~rrrrz bool | Nonerrrr )__name__ __module__ __qualname____doc__r-r(rJrMrPpropertyrTrWrYr]rarfr=rkr3rxr}rrrQr,rr sI!F,.* ) !(AA&&  ,,66  **J J4!HJ!"!(,!YRYRYR YR  YR  YRYR&YRYR YRv)rQci}|jjD]0\}}t|tr t j |}|||<2|S#t $rYwxYw)z File and user metadata dict. Parameters ---------- h5 : :py:class:`h5py.File` or :py:class:`h5py.Group` Open handle to cooler file. Returns ------- dict )rLitemsrrjsonloadsr#)r+dkvs r,r=r=si A 1 a  JJqM!  H  sA AAc |Xtjddgjtj|djj }t |d|||fi|S)a Table describing the chromosomes/scaffolds/contigs used. They appear in the same order they occur in the heatmap. Parameters ---------- h5 : :py:class:`h5py.File` or :py:class:`h5py.Group` Open handle to cooler file. lo, hi : int, optional Range of rows to select from the table. fields : sequence of str, optional Subset of columns to select from table. Returns ------- :py:class:`DataFrame` r'r/r3)pdIndexappendkeysdrop_duplicatesr )r+rprqror*s r,r3r3sc2~ HHfh' ( VBHHR\..01 2 _   r(|RV 6v 66rQc 4|Xtjgdjtj|djj }t |d|||fi|}d|vr|j dd}t |tr|}n|d}t|jrh|rft|d}tjj||d}t |tr"tj||j}|S||d<|S) a Table describing the genomic bins that make up the axes of the heatmap. Parameters ---------- h5 : :py:class:`h5py.File` or :py:class:`h5py.Group` Open handle to cooler file. lo, hi : int, optional Range of rows to select from the table. fields : sequence of str, optional Subset of columns to select from table. Returns ------- :py:class:`DataFrame` chromstartendrxr convert_enumTr')ro)ordered)rrrrrr rrrdtyper3 Categorical from_codesSeriesr\) r+rprqror*outr chrom_colr]s r,rxrxs0~ HH. / VBHHRZ__./ 0 _   bj"b& 3F 3C&zz.$7 fc "IG I IOO ,62J11)ZQU1VI&#&ii 3995 J )G JrQc &|Xtjddgjtj|djj }t |d|||fi|}|r"t |dddgdfi|}t ||d }|S) aG Table describing the nonzero upper triangular pixels of the Hi-C contact heatmap. Parameters ---------- h5 : :py:class:`h5py.File` or :py:class:`h5py.Group` Open handle to cooler file. lo, hi : int, optional Range of rows to select from the table. fields : sequence of str, optional Subset of columns to select from table. join : bool, optional Whether or not to expand bin ID columns to their full bin description (chrom, start, end). Default is True. Returns ------- :py:class:`DataFrame` Nbin1_idbin2_idr}rxrrTreplace)rrrrrr r)r+rprqror~r*dfrxs r,r}r}s:~ HHi+ , VBHHR\..01 2 _   R\2r6 4V 4B 2f:q$(ALVL b$ - IrQc|j}t|trd}nd}g}d|vr|djj t j dd}t|dk(rdx}}n=t|t|kDr!|j|j}}nd\}}||||} |j| j|| jdz jd jd d |vr|d jj t j dd} t| dk(rdx}}n=t|t|kDr!| j| j}}nd\}}||||} |j| j| | jdz jd jd |r'dD cgc] } | |vs|  } } |j| d}t!j"g||jd d}|j|_ |Scc} w)a Add bin annotations to a data frame of pixels. This is done by performing a relational "join" against the bin IDs of a table that describes properties of the genomic bins. New columns will be appended on the left of the output data frame. .. versionchanged:: 0.8.0 The default value of ``replace`` changed to False. Parameters ---------- pixels : :py:class:`DataFrame` A data frame containing columns named ``bin1_id`` and/or ``bin2_id``. If columns ``bin1_id`` and ``bin2_id`` are both present in ``pixels``, the adjoined columns will be suffixed with '1' and '2' accordingly. bins : :py:class:`DataFrame` or DataFrame selector Data structure that contains a full description of the genomic bins of the contact matrix, where the index corresponds to bin IDs. replace : bool, optional Remove the original ``bin1_id`` and ``bin2_id`` columns from the output. Default is False. Returns ------- :py:class:`DataFrame` c||||dzSdS)Nrr)selbegrs r, _loc_slicezannotate.._loc_slice_ssS1WB BTB BrQc |j||SrG)loc)rrrs r,rzannotate.._loc_slicees66#c? "rQrFsafe)copycastingr)rNc |dzS)N1rxs r,zannotate..z a#grQ)columnsT)droprc |dzS)N2rrs r,rzannotate..rrQ)rrr)axis)rrr to_numpyr4npint64r;minmaxrilocr\rename reset_indexrrconcat)r}rxrrrannsbin1bminbmaxann1bin2ann2col cols_to_droprs r,rr<s <nnG$( C  # DGi ))+22288%QW2X t9>OD4 YV $TXXZ$D JD$$d+ IIdTZZ]* + V-V . [d[ # Gi ))+22288%QW2X t9>OD4 YV $TXXZ$D JD$$d+ IIdTZZ]* + V-V . [d[ # '=PP P\2 )):d:F..D.9: CC CI J Qs , I 6I cJ|d}t|tr|}n|rd}|r|dvrtd|ddzdzt|d |d dd}|rt ||||||f| | }|j }|rit |jg}t||d }| r"d||dzz ||dz<d||dzz ||dz<||dz||dzz||z|d<| r,t |jgd}t||d }|S|r| rt||||||f| }nt ||||||f| }|j}|rZ|d}|||}||f||fk(r|n|||}| r d|z }d|z }||j||jz|jz|_ |S| rt||||||f| }nt ||||||f| }|j}|rB|d}|||}||f||fk(r|n|||}| r d|z }d|z }|tj ||z}|S)a Two-dimensional range query on the Hi-C contact heatmap. Depending on the options, returns either a 2D NumPy array, a rectangular sparse ``coo_matrix``, or a data frame of pixels. Parameters ---------- h5 : :py:class:`h5py.File` or :py:class:`h5py.Group` Open handle to cooler file. i0, i1 : int, optional Bin range along the 0th (row) axis of the heatmap. j0, j1 : int, optional Bin range along the 1st (col) axis of the heatmap. field : str, optional Which column of the pixel table to fill the matrix with. By default, the 'count' column is used. balance : bool, optional Whether to apply pre-calculated matrix balancing weights to the selection. Default is True and uses a column named 'weight'. Alternatively, pass the name of the bin table column containing the desired balancing weights. Set to False to return untransformed counts. sparse: bool, optional Return a scipy.sparse.coo_matrix instead of a dense 2D numpy array. as_pixels: bool, optional Return a DataFrame of the corresponding rows from the pixel table instead of a rectangular sparse matrix. False by default. join : bool, optional If requesting pixels, specifies whether to expand the bin ID columns into (chrom, start, end). Has no effect when requesting a rectangular matrix. Default is True. ignore_index : bool, optional If requesting pixels, don't populate the index column with the pixel IDs to improve performance. Default is True. Returns ------- ndarray, coo_matrix or DataFrame Notes ----- If ``as_pixels=True``, only data explicitly stored in the pixel table will be returned: if the cooler's storage mode is symmetric-upper, lower triangular elements will not be generated. If ``as_pixels=False``, those missing non-zero elements will automatically be filled in. NcountweightrxzNo column 'bins/'z(found. Use ``cooler.balance_cooler`` to z1calculate balancing weights or set balance=False.r}zindexes/bin1_offset) return_indexFrrrrbalancedrT)rrr#rrto_framerrxrr to_sparse_matrixrowrdatato_arrayrouter)r+rrrrrrrrr~rrr fill_lowerr'readerenginerweightsdf2rxmatbias1bias2arrs r,rrs| }'3 4r&z)tfA &8 9A B  r(|R(=%>q%A BF$ EBB+YEU __  Rjoo'/G2w6C"#c$*o"5D3J"#c$*o"5D3J _s4#:>UKBzN ":??$%>?D"dD1B  *652r2r:JIVF'BB7GSF%%' j&GBrNE "X"b1Ewr"~EE E SWW~cgg6ACH  *652r2r:JIVF'BB7GSFoo j&GBrNE "X"b1Ewr"~EE E ..C rQ)r+rrr8)rNN) r+rrprrqrrolist[str] | Noner pd.DataFrame)rNNT) r+rrprrqrror r~rrr r)r}r rxzpd.DataFrame | RangeSelector1Drrrr ) NTFFTTFrT)r+rrrrrrrrrrrrrrrrrr~rrrrrrrrrrz&np.ndarray | coo_matrix | pd.DataFrame)' __future__rrr numpyrpandasr simplejsonrpandas.api.typesr scipy.sparsercorerrr r r r r rfileopsrutilrrrr__all__rrr=r3rxr}rrrrQr,rs" -#   "II Z 0y)y)x  6# 77 7 7  7  7H# 55 5 5  5  5t# ** * *  *  **\QVZ Z >ZIMZZF"GG G G G G  GG GG GGGGG,GrQ