Skip to content

Commit f1fad59

Browse files
joachimwolffjoachimwolff
committed
Adding chi-c documentation and information on how to read / write h5 files via HiCMatrix
1 parent 1b72489 commit f1fad59

1 file changed

Lines changed: 256 additions & 8 deletions

File tree

‎docs/content/file-formats.rst‎

Lines changed: 256 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,73 @@ The matrix object is a scipy `csr_matrix`.
8080
Please refer to HiCMatrix for a reference implementation: https://github.com/deeptools/HiCMatrix/blob/master/hicmatrix/lib/h5.py
8181

8282

83+
To open a cool / h5 file with the HiCMatrix library, use the following code:
84+
85+
.. code-block:: python
86+
87+
import hicmatrix.HiCMatrix as hm
88+
89+
hic_ma = hm.hiCMatrix("/path/to/matrix")
90+
91+
# csr_matrix
92+
hic_ma.matrix
93+
94+
# the corresponding genomic regions as a list
95+
hic_ma.cut_intervals
96+
97+
98+
To write a h5 use the following code. Please consider, once the datatype of a matrix is specified, for example by reading a h5 matrix or by first time writing a h5 matrix, it cannot be changed to a cool file anymore (except by manipulating the internal matrixFilehandler object).
99+
100+
.. code-block:: python
101+
102+
import hicmatrix.HiCMatrix as hm
103+
from scipy.sparse import csr_matrix
104+
105+
106+
# create a HiCMatrix object
107+
hic_ma = hm.hiCMatrix()
108+
109+
# set important data structures
110+
111+
hic_ma.matrix = csr_matrix()
112+
hic_ma.cut_intervals = list[(chr1, start1, end1, 1), (chr1, start2, end2, 1), ..., (chr1, startN, endN, 1)]
113+
114+
# to store a h5 matrix
115+
hic_ma.save('/path/to/storage/matrix.h5')
116+
# to store a cool matrix
117+
hic_ma.save('/path/to/storage/matrix.cool')
118+
119+
Alternatively, the matrixFileHandler object can be accessed directly:
120+
121+
122+
.. code-block:: python
123+
124+
from hicmatrix.lib import MatrixFileHandler
125+
126+
127+
# Load a matrix via the MatrixFileHandler class
128+
129+
matrixFileHandlerInput = MatrixFileHandler(pFileType=args.inputFormat, pMatrixFile=matrix,
130+
pCorrectionFactorTable=args.correction_name,
131+
pCorrectionOperator=correction_operator,
132+
pChrnameList=chromosomes_to_load,
133+
pEnforceInteger=args.enforce_integer,
134+
pApplyCorrectionCoolerLoad=applyCorrectionCoolerLoad)
135+
136+
# Load data
137+
_matrix, cut_intervals, nan_bins, \
138+
distance_counts, correction_factors = matrixFileHandlerInput.load()
139+
140+
# create matrixFileHandler output object
141+
matrixFileHandlerOutput = MatrixFileHandler(pFileType=args.outputFormat, pEnforceInteger=args.enforce_integer, pFileWasH5=format_was_h5, pHic2CoolVersion=hic2CoolVersion, pHiCInfo=cool_metadata)
142+
143+
# set the variables
144+
matrixFileHandlerOutput.set_matrix_variables(_matrix, cut_intervals, nan_bins,
145+
correction_factors, distance_counts)
146+
147+
matrixFileHandlerOutput.save(args.outFileName, pSymmetric=True, pApplyCorrection=applyCorrection)
148+
149+
83150
84151
Capture Hi-C HDF containers
85152
---------------------------
@@ -114,11 +181,12 @@ chicViewpoint
114181
- gene name 2
115182
- ...
116183
- ...
117-
. ---
184+
- ...
118185
- chromosome 2
119186
- gene 1
120187
- ...
121188
- ...
189+
- ...
122190
- ...
123191
- ...
124192
- genes
@@ -142,7 +210,7 @@ chicViewpoint
142210
- gene name 2
143211
- ...
144212
- ...
145-
. ---
213+
- ...
146214
- chromosome 2
147215
- gene 1
148216
- ...
@@ -185,7 +253,7 @@ Depending on the combination mode (single / dual) the structure is slightly diff
185253
- gene name 2
186254
- ...
187255
- ...
188-
. ---
256+
- ...
189257
- chromosome 2
190258
- gene 1
191259
- ...
@@ -206,7 +274,7 @@ Depending on the combination mode (single / dual) the structure is slightly diff
206274
- gene name 2
207275
- ...
208276
- ...
209-
. ---
277+
- ...
210278
- chromosome 2
211279
- gene 1
212280
- ...
@@ -218,12 +286,68 @@ Depending on the combination mode (single / dual) the structure is slightly diff
218286
- gene name 1 (link to matrix 2 / chromosome 1 / gene name 1
219287
- ...
220288
221-
Significant interactions file:
289+
Combination mode 'dual' combines the target regions of one viewpoint region of two matrices.
290+
291+
.. code-block:: bash
292+
293+
- combinationMode = 'dual' (String)
294+
- fixateRange (int)
295+
- mode_preselection (String)
296+
- mode_preselection_value (float)
297+
- peakInteractionsThreshold (float)
298+
- pvalue (float)
299+
- range (int, int)
300+
- truncateZeroPvalues (Boolean)
301+
- type='target' (String)
302+
- matrix 1
303+
- matrix 2
304+
- chromosome 1
305+
- gene name 1
306+
- chromosome (String)
307+
- end_list (array)
308+
- reference_point_end (int)
309+
- reference_point_start (int)
310+
- start_list (array)
311+
- gene name 2
312+
- ...
313+
- ...
314+
- ...
315+
- chromosome 2
316+
- gene 1
317+
- ...
318+
- ...
319+
- genes
320+
- gene name 1 (link to matrix 1 / matrix 2 / chromosome 1 / gene name 1
321+
- ...
322+
- matrix 3
323+
- chromosome 1
324+
- gene name 1
325+
- ...
326+
- ...
327+
- genes
328+
- gene name 1 (link to matrix 1 / matrix 3 / chromosome 1 / gene name 1
329+
- ...
330+
- matrix 2
331+
- matrix 3
332+
- chromosome 1
333+
- gene name 1
334+
- ...
335+
- ...
336+
- ...
337+
- ...
338+
- genes
339+
- gene name 1 (link to matrix 2 / matrix 3 / chromosome 1 / gene name 1
340+
- ...
341+
- ...
342+
343+
344+
345+
Significant interactions file in the 'single' and 'dual' mode don't have a difference in their structure:
222346
223347
224348
.. code-block:: bash
225349
226-
- combinationMode (String)
350+
- combinationMode = 'single' (String) / 'dual' (String)
227351
- fixateRange (int)
228352
- mode_preselection (String)
229353
- mode_preselection_value (float)
@@ -290,5 +414,129 @@ Significant interactions file:
290414
- gene name 1 (link to matrix 2 / chromosome 1 / gene name 1
291415
- ...
292416
293-
chicSignificantInteractions
294-
~~~~~~~~~~~~~~~~~~~~~~~~~~~
417+
418+
419+
chicAggregateStatistic
420+
~~~~~~~~~~~~~~~~~~~~~~
421+
422+
423+
.. code-block:: bash
424+
425+
- type='aggregate' (String)
426+
- matrix_1_matrix_2
427+
- matrix 1
428+
- chromosome 1
429+
- gene name 1
430+
- chromosome (String)
431+
- end_list (array)
432+
- gene_name (String)
433+
- interaction_data_list (array)
434+
- raw_target_list (array)
435+
- relative_distance_list (array)
436+
- start_list (array)
437+
- sum_of_interactions (float)
438+
- gene name 2
439+
- ...
440+
- ...
441+
- genes
442+
- gene name 1 (link to matrix_1_matrix_2 / matrix 1 / chromosome 1 / gene name 1
443+
- ...
444+
- matrix 2
445+
- chromosome 1
446+
- gene name 1
447+
- chromosome (String)
448+
- end_list (array)
449+
- gene_name (String)
450+
- interaction_data_list (array)
451+
- raw_target_list (array)
452+
- relative_distance_list (array)
453+
- start_list (array)
454+
- sum_of_interactions (float)
455+
- gene name 2
456+
- ...
457+
- ...
458+
- genes
459+
- gene name 1 (link to matrix_1_matrix_2/ matrix 2 / chromosome 1 / gene name 1
460+
- ...
461+
- matrix_2_matrix_2
462+
- matrix 2
463+
- ...
464+
- matrix 3
465+
- ...
466+
467+
468+
469+
chicDifferentialTest
470+
~~~~~~~~~~~~~~~~~~~~
471+
472+
473+
.. code-block:: bash
474+
475+
- type='differential' (String)
476+
- alpha (float)
477+
- test: fisher / chi2 (String)
478+
- matrix_1
479+
- matrix 2
480+
- chromosome 1
481+
- gene name 1
482+
- accepted
483+
- chromosome (String)
484+
- end_list (array)
485+
- gene (String)
486+
- interaction_data_list (array)
487+
- pvalue (array)
488+
- raw_target_list_1 (array)
489+
- raw_target_list_2 (array)
490+
- relative_distance_list (array)
491+
- start_list (array)
492+
- sum_of_interactions_1 (float)
493+
- sum_of_interactions_2 (float)
494+
- all
495+
- chromosome (String)
496+
- end_list (array)
497+
- gene (String)
498+
- interaction_data_list (array)
499+
- pvalue (array)
500+
- raw_target_list_1 (array)
501+
- raw_target_list_2 (array)
502+
- relative_distance_list (array)
503+
- start_list (array)
504+
- sum_of_interactions_1 (float)
505+
- sum_of_interactions_2 (float)
506+
- rejected
507+
- chromosome (String)
508+
- end_list (array)
509+
- gene (String)
510+
- interaction_data_list (array)
511+
- pvalue (array)
512+
- raw_target_list_1 (array)
513+
- raw_target_list_2 (array)
514+
- relative_distance_list (array)
515+
- start_list (array)
516+
- sum_of_interactions_1 (float)
517+
- sum_of_interactions_2 (float)
518+
- gene name 2
519+
- accepted
520+
- all
521+
- rejected
522+
- ...
523+
- genes
524+
- gene name 1 (link to matrix_1 / matrix 2 / chromosome 1 / gene name 1
525+
- ...
526+
- matrix 3
527+
- chromosome 1
528+
- gene name 1
529+
- accepted
530+
- all
531+
- rejected
532+
- gene name 2
533+
- ...
534+
- ...
535+
- genes
536+
- gene name 1 (link to matrix_1 / matrix 3 / chromosome 1 / gene name 1
537+
- ...
538+
- ...
539+
- matrix 2
540+
- matrix 3
541+
- ...
542+

0 commit comments

Comments
 (0)