-
Notifications
You must be signed in to change notification settings - Fork 20
Expand file tree
/
Copy pathH5P.R
More file actions
890 lines (814 loc) · 27.5 KB
/
H5P.R
File metadata and controls
890 lines (814 loc) · 27.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
####################################################
## General Property List Operations
####################################################
#' Create a new HDF5 property list
#'
#' @param type A character name of a property list type. See `h5const("H5P")`
#' for possible property list types.
#' @param native Defunct! Doesn't achieve anything for property lists.
#'
#' @export
H5Pcreate <- function(type = h5default("H5P"), native = FALSE) {
type <- h5checkConstants("H5P", type)
pid <- .Call("_H5Pcreate", type, PACKAGE = "rhdf5")
if (pid > 0) {
h5plist <- new("H5IdComponent", ID = pid, native = native)
} else {
message("HDF5: unable to create property list")
h5plist <- FALSE
}
invisible(h5plist)
}
#' Return the property list class identifier for a property list
#'
#' @param h5plist [H5IdComponent-class] object representing any type of HDF5
#' property list.
#'
#' @export
H5Pget_class <- function(h5plist) {
h5checktype(h5plist, "plist")
pclid <- .Call("_H5Pget_class", h5plist@ID, PACKAGE = "rhdf5")
if (pclid > 0) {
h5plistclass <- new("H5IdComponent", ID = pclid, native = h5plist@native)
} else {
message("HDF5: unable to get property list class")
h5plistclass <- FALSE
}
invisible(h5plistclass)
}
#' Copy an existing property list to create a new property list
#'
#' @param h5plist [H5IdComponent-class] object representing the property list
#' to be copied.
#'
#' @export
H5Pcopy <- function(h5plist) {
h5checktype(h5plist, "plist")
pid <- .Call("_H5Pcopy", h5plist@ID, PACKAGE = "rhdf5")
if (pid > 0) {
h5plistnew <- new("H5IdComponent", ID = pid, native = h5plist@native)
} else {
message("HDF5: unable to copy property list")
h5plistnew <- FALSE
}
invisible(h5plistnew)
}
#' Close and release a property list
#'
#' `H5Pclose()` terminates access to a property list. All property lists
#' should be closed when they no longer need to be accessed. This
#' frees resources used by the property list. Failing to call `H5Pclose()`
#' can lead to memory leakage over time.
#'
#' @param h5plist [H5IdComponent-class] object representing the property list
#' to close.
#'
#' @export
H5Pclose <- function(h5plist) {
h5checktype(h5plist, "plist")
invisible(.Call("_H5Pclose", h5plist@ID, PACKAGE = "rhdf5"))
}
####################################################
## File Creation Properties
####################################################
#' Get version information for objects in a file creation property list
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @returns Named integer vector
#' @export
H5Pget_version <- function(h5plist) {
h5checktype(h5plist, "plist")
.Call("_H5Pget_version", h5plist@ID, PACKAGE = "rhdf5")
}
#' Get and set the user block size
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param size of the user block in bytes
#' @rdname H5P_userblock
#' @export
H5Pset_userblock <- function(h5plist, size) {
h5checktype(h5plist, "plist")
invisible(.Call("_H5Pset_userblock", h5plist@ID, size, PACKAGE = "rhdf5"))
}
#' @rdname H5P_userblock
#' @export
H5Pget_userblock <- function(h5plist) {
h5checktype(h5plist, "plist")
.Call("_H5Pget_userblock", h5plist@ID, PACKAGE = "rhdf5")
}
#' Get and set the sizes of offsets and lengths used in an HDF5 file
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param sizeof_addr Offset size in bytes
#' @param sizeof_size Length size in bytes
#' @rdname H5P_sizes
#' @export
H5Pset_sizes <- function(h5plist, sizeof_addr, sizeof_size) {
h5checktype(h5plist, "plist")
invisible(.Call(
"_H5Pset_sizes",
h5plist@ID,
sizeof_addr,
sizeof_size,
PACKAGE = "rhdf5"
))
}
#' @rdname H5P_sizes
#' @export
H5Pget_sizes <- function(h5plist) {
h5checktype(h5plist, "plist")
.Call("_H5Pget_sizes", h5plist@ID, PACKAGE = "rhdf5")
}
#' Get and set the size of the symbol table B-tree 1/2 rank and the leaf node 1/2 size
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param ik Symbol table B-tree 1/2 rank
#' @param lk Symbol table leaf node 1/2 size
#' @rdname H5P_sym_k
#' @export
H5Pset_sym_k <- function(h5plist, ik, lk) {
h5checktype(h5plist, "plist")
invisible(.Call("_H5Pset_sym_k", h5plist@ID, ik, lk, PACKAGE = "rhdf5"))
}
#' @rdname H5P_sym_k
#' @export
H5Pget_sym_k <- function(h5plist) {
h5checktype(h5plist, "plist")
.Call("_H5Pget_sym_k", h5plist@ID, PACKAGE = "rhdf5")
}
#' Get and set the 1/2 rank of an indexed storage B-tree
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param ik chunked Storage B-tree 1/2 rank
#' @rdname H5P_istore_k
#' @export
H5Pset_istore_k <- function(h5plist, ik) {
h5checktype(h5plist, "plist")
invisible(.Call("_H5Pset_istore_k", h5plist@ID, ik, PACKAGE = "rhdf5"))
}
#' @rdname H5P_istore_k
#' @export
H5Pget_istore_k <- function(h5plist) {
h5checktype(h5plist, "plist")
.Call("_H5Pget_istore_k", h5plist@ID, PACKAGE = "rhdf5")
}
#' Get and set the number of object header message indexes
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param nindexes Number of shared object header message indexes to be available in files
#' @rdname H5P_shared_mesg_nindexes
#' @export
H5Pset_shared_mesg_nindexes <- function(h5plist, nindexes) {
h5checktype(h5plist, "plist")
invisible(.Call(
"_H5Pset_shared_mesg_nindexes",
h5plist@ID,
nindexes,
PACKAGE = "rhdf5"
))
}
#' @rdname H5P_shared_mesg_nindexes
#' @export
H5Pget_shared_mesg_nindexes <- function(h5plist) {
h5checktype(h5plist, "plist")
.Call("_H5Pget_shared_mesg_nindexes", h5plist@ID, PACKAGE = "rhdf5")
}
#' Get and set shared object header message index properties
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation
#' property list
#' @param index_num Index being configured. Indices use C-style 0-based counting,
#' so the first index will be numbered 0.
#' @param mesg_type_flags Character specifying the types of messages that may be stored in this index.
#' Valid values can be found with `h5const(type = "H5O_SHMESG_FLAG")`
#' @param min_mesg_size Minimum message size
#'
#' @returns `H5Pget_shared_mesg_index()` returns a list of length 2. The first element is the types of messages
#' that may be stored in the index, the second element is the minimum message size.
#'
#' @rdname H5Pshared_mesg_index
#' @export
H5Pset_shared_mesg_index <- function(
h5plist,
index_num,
mesg_type_flags = h5default(type = "H5O_SHMESG_FLAG"),
min_mesg_size
) {
h5checktype(h5plist, "plist")
mesg_type_flags <- h5checkConstants("H5O_SHMESG_FLAG", mesg_type_flags)
invisible(.Call(
"_H5Pset_shared_mesg_index",
h5plist@ID,
index_num,
mesg_type_flags,
min_mesg_size,
PACKAGE = "rhdf5"
))
}
#' @rdname H5Pshared_mesg_index
#' @export
H5Pget_shared_mesg_index <- function(h5plist, index_num) {
h5checktype(h5plist, "plist")
res <- .Call(
"_H5Pget_shared_mesg_index",
h5plist@ID,
index_num,
PACKAGE = "rhdf5"
)
return(list(
type_flags = h5const2String("H5O_SHMESG_FLAG", res[1]),
size = res[2]
))
}
#' Get and set threshold values for storage of shared object header message indexes
#'
#' @param h5plist [H5IdComponent-class] object representing the file creation property list
#' @param max_list Threshold above which storage shifts from list to B-tree
#' @param min_btree Threshold below which storage reverts to list format
#' @rdname H5P_shared_mesg_phase_change
#' @export
H5Pset_shared_mesg_phase_change <- function(h5plist, max_list, min_btree) {
h5checktype(h5plist, "plist")
invisible(.Call(
"_H5Pset_shared_mesg_phase_change",
h5plist@ID,
max_list,
min_btree,
PACKAGE = "rhdf5"
))
}
#' @rdname H5P_shared_mesg_phase_change
#' @export
H5Pget_shared_mesg_phase_change <- function(h5plist) {
h5checktype(h5plist, "plist")
.Call("_H5Pget_shared_mesg_phase_change", h5plist@ID, PACKAGE = "rhdf5")
}
####################################################
## File Access Properties
####################################################
#' Set the read-only S3 virtual file driver
#'
#' The read-only S3 virtual file driver can be used to read files hosted
#' remotely on Amazon's S3 storage.
#'
#' @details To access files in a private Amazon S3 bucket you will need to
#' provide three additional details: The AWS region where the files are
#' hosted, your AWS access key ID, and your AWS secret access key. More
#' information on how to obtain AWS access keys can be found at
#' <https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys>.
#' These are provided as a list to the `s3credentials` argument. If you
#' are accessing public data this argument should be `NULL`.
#'
#' @param h5plist [H5IdComponent-class] object representing a file access
#' property list.
#' @param s3credentials Either `NULL` or a list of length 3 specifying the AWS access credentials (see details).
#'
#' @examples
#'
#' ## this doesn't work on the Bioconductor Mac build machine
#' \dontrun{
#' pid <- H5Pcreate("H5P_FILE_ACCESS")
#' H5Pset_fapl_ros3(pid)
#' H5Pclose(pid)
#' }
#'
#' @export
H5Pset_fapl_ros3 <- function(h5plist, s3credentials = NULL) {
## this should really check it's a fapl, not just a plist.
h5checktype(h5plist, "plist")
## only do authentication if s3credentials are provided
if (!is.null(s3credentials)) {
auth <- TRUE
aws_region <- s3credentials[[1]]
access_key_id <- s3credentials[[2]]
secret_access_key <- s3credentials[[3]]
} else {
auth <- FALSE
aws_region <- access_key_id <- secret_access_key <- ""
}
res <- .Call(
"_H5Pset_fapl_ros3",
h5plist@ID,
auth,
aws_region,
access_key_id,
secret_access_key,
PACKAGE = "rhdf5"
)
invisible(res)
}
#' Control the range of HDF5 library versions that will be compatible with
#' a file.
#'
#'
#' @param h5plist [H5IdComponent-class] object representing a file access
#' property list.
#' @param libver_low,libver_high Define the earliest and latest versions of
#' the HDF5 library that will be used when writing object in the file.
#'
#' @name H5P_libver_bounds
NULL
#' @rdname H5P_libver_bounds
#' @export
H5Pset_libver_bounds <- function(
h5plist,
libver_low = "H5F_LIBVER_EARLIEST",
libver_high = "H5F_LIBVER_LATEST"
) {
h5checktype(h5plist, "plist")
libver_low <- h5checkConstants("H5F_LIBVER", libver_low)
libver_high <- h5checkConstants("H5F_LIBVER", libver_high)
res <- .Call(
"_H5Pset_libver_bounds",
h5plist@ID,
libver_low,
libver_high,
PACKAGE = "rhdf5"
)
invisible(res)
}
#' @rdname H5P_libver_bounds
#' @export
H5Pget_libver_bounds <- function(h5plist) {
h5checktype(h5plist, "plist")
res <- .Call("_H5Pget_libver_bounds", h5plist@ID, PACKAGE = "rhdf5")
res <- h5const2String("H5F_LIBVER", res)
names(res) <- c("libver_low", "libver_high")
res
}
####################################################
## Link Creation Properties
####################################################
H5Pset_char_encoding <- function(h5plist, encoding = h5default("H5T_CSET")) {
h5checktypeAndPLC(h5plist, "H5P_LINK_CREATE")
encoding <- h5checkConstants("H5T_CSET", encoding)
res <- .Call("_H5Pset_char_encoding", h5plist@ID, encoding, PACKAGE = "rhdf5")
invisible(res)
}
H5Pget_char_encoding <- function(h5plist) {
h5checktypeAndPLC(h5plist, "H5P_LINK_CREATE")
res <- .Call("_H5Pget_char_encoding", h5plist@ID, PACKAGE = "rhdf5")
res <- h5const2String("H5T_CSET", res)
res
}
#' Get and set whether to create missing intermediate groups
#'
#' @param h5plist An object of class [H5IdComponent-class] representing a link
#' creation property list.
#' @param create_groups A logical of length 1 specifying whether missing
#' groups should be created when a new object is created. Default is `TRUE`.
#'
#' @examples
#' pid <- H5Pcreate("H5P_LINK_CREATE")
#'
#' ## by default intermediate groups are not created
#' H5Pget_create_intermediate_group(pid)
#'
#' ## Change the setting so groups will be created
#'
#' H5Pget_create_intermediate_group(pid)
#'
#' ## tidy up
#' H5Pclose(pid)
#'
#' @name H5P_create_intermediate_group
NULL
#' @rdname H5P_create_intermediate_group
#' @export
H5Pset_create_intermediate_group <- function(h5plist, create_groups = TRUE) {
h5checktypeAndPLC(h5plist, "H5P_LINK_CREATE")
if (!is.logical(create_groups)) {
stop("The 'create_groups' argument should be either TRUE or FALSE")
}
crt_intermed_group <- as.integer(create_groups)
res <- .Call(
"_H5Pset_create_intermediate_group",
h5plist@ID,
crt_intermed_group,
PACKAGE = "rhdf5"
)
invisible(res)
}
#' @rdname H5P_create_intermediate_group
#' @export
H5Pget_create_intermediate_group <- function(h5plist) {
h5checktypeAndPLC(h5plist, "H5P_LINK_CREATE")
res <- .Call(
"_H5Pget_create_intermediate_group",
h5plist@ID,
PACKAGE = "rhdf5"
)
res
}
####################################################
## Dataset Creation Properties
####################################################
#' Get and set the type of storage used to store the raw data for a dataset
#'
#' Possible options for the `layout` argument are:
#' * `H5D_COMPACT`
#' * `H5D_CONTIGUOUS`
#' * `H5D_CHUNKED`
#' * `H5D_VIRTUAL`
#'
#' The names of the layout types can also be obtained via `h5const("H5D")`.
#'
#' @param h5plist An object of class [H5IdComponent-class] representing a dataset creation property list.
#' @param layout A character giving the name of a dataset layout type.
#'
#' @name H5P_layout
NULL
#' @rdname H5P_layout
#' @export
H5Pset_layout <- function(h5plist, layout = h5default("H5D")) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
layout <- h5checkConstants("H5D", layout)
res <- .Call("_H5Pset_layout", h5plist@ID, layout, PACKAGE = "rhdf5")
invisible(res)
}
#' @rdname H5P_layout
#' @export
H5Pget_layout <- function(h5plist) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
res <- .Call("_H5Pget_layout", h5plist@ID, PACKAGE = "rhdf5")
res <- h5const2String("H5D", res)
res
}
#' Get and set the size of the chunks used to store a chunked layout dataset
#'
#' @details Note that a necessary side effect of running this function is that the
#' layout of the dataset will be changes to `H5D_CHUNKED` if it is not already set to this.
#'
#' @param h5plist An object of class [H5IdComponent-class] representing a dataset creation property list.
#' @param dim The chunk size used to store the dataset. This argument should be an integer vector of the same length as
#' the number of dimensions of the dataset the dataset creation property list will be applied to.
#'
#' @seealso [H5Pset_layout()]
#'
#' @name H5P_chunk
NULL
#' @rdname H5P_chunk
#' @export
H5Pset_chunk <- function(h5plist, dim) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
if (!is.null(dim) && !h5plist@native) {
dim <- rev(as.integer(dim))
}
res <- .Call("_H5Pset_chunk", h5plist@ID, dim, PACKAGE = "rhdf5")
invisible(res)
}
#' @rdname H5P_chunk
#' @export
H5Pget_chunk <- function(h5plist) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
res <- .Call("_H5Pget_chunk", h5plist@ID, PACKAGE = "rhdf5")
res
}
#' Add the deflate compression filter to the chunk processing pipeline.
#'
#' Valid values for the compression level range from 0 (no compression) to 9
#' (best compression, slowest speed). Note that applying this function with
#' `level = 0` does not mean the filter is removed. It is still part of the
#' filter pipeline, but no compression is performed. The filter will still need
#' to be available on any system that reads a file created with this setting
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#' creation property list.
#' @param level Integer giving the compression level to use. Valid values are
#' from 0 to 9.
#'
#' @export
H5Pset_deflate <- function(h5plist, level) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
level <- as.integer(level)
res <- .Call("_H5Pset_deflate", h5plist@ID, level, PACKAGE = "rhdf5")
invisible(res)
}
#' Set the fill value for an HDF5 dataset
#'
#' `H5Pset_fill_value` sets the fill value for a dataset in the dataset creation property list.
#'
#' @param h5plist An object of class [H5IdComponent-class] representing a
#' dataset creation property list.
#' @param value The default fill value of the dataset. A vector of length 1.
#'
#' @seealso [H5P_fill_time],[H5Pfill_value_defined]
#'
#' @name H5P_fill_value
NULL
#' @rdname H5P_fill_value
#' @export
H5Pset_fill_value <- function(h5plist, value) {
if (length(value) > 1L) {
stop("'value' must be a vector of length 1.")
}
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
storage.mode <- storage.mode(value)
tid <- switch(
storage.mode,
double = h5constants$H5T["H5T_IEEE_F64LE"],
integer = h5constants$H5T["H5T_STD_I32LE"],
logical = h5constants$H5T["H5T_STD_I8LE"],
character = {
tid <- H5Tcopy("H5T_C_S1")
on.exit(H5Tclose(tid))
size <- nchar(value, type = "bytes")
H5Tset_size(tid, size)
H5Tset_strpad(tid, strpad = "NULLPAD")
if (Encoding(value) == "UTF-8") {
cset <- "UTF-8"
} else {
cset <- "ASCII"
}
H5Tset_cset(tid, cset = cset)
tid
},
{
stop(
"datatype ",
storage.mode,
" not supported. Try 'double', 'integer', or 'character'."
)
}
)
res <- .Call("_H5Pset_fill_value", h5plist@ID, tid, value, PACKAGE = "rhdf5")
invisible(res)
}
#' Determine whether a property list has a fill value defined
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#' creation property list.
#'
#' @returns `TRUE` if the fill value is defined, `FALSE` if not. Will return
#' `NULL` if there is a problem determining the status of the fill value.
#'
#' @details Note that the return value for this function is slightly different
#' from the C version. The C API provides three return types and can, in the
#' case that a fill value is defined, differentiate whether the value is the
#' HDF5 library default or has been set by the application.
#'
#' @export
H5Pfill_value_defined <- function(h5plist) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
res <- .Call("_H5Pfill_value_defined", h5plist@ID, PACKAGE = "rhdf5")
res
}
#' Set the time when fill values are written to a dataset
#'
#' @param h5plist An object of class [H5IdComponent-class] representing a
#' dataset creation property list.
#' @param fill_time When the fill values should be written. Possible options
#' can be listed with `h5const("H5D_FILL_TIME")`.
#'
#' @name H5P_fill_time
NULL
#' @rdname H5P_fill_time
#' @export
H5Pset_fill_time <- function(h5plist, fill_time = h5default("H5D_FILL_TIME")) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
fill_time <- h5checkConstants("H5D_FILL_TIME", fill_time)
res <- .Call("_H5Pset_fill_time", h5plist@ID, fill_time, PACKAGE = "rhdf5")
invisible(res)
}
#' @rdname H5P_fill_time
#' @export
H5Pget_fill_time <- function(h5plist) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
res <- .Call("_H5Pget_fill_time", h5plist@ID, PACKAGE = "rhdf5")
res <- h5const2String("H5D_FILL_TIME", res)
res
}
H5Pset_alloc_time <- function(
h5plist,
alloc_time = h5default("H5D_ALLOC_TIME")
) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
alloc_time <- h5checkConstants("H5D_ALLOC_TIME", alloc_time)
res <- .Call("_H5Pset_alloc_time", h5plist@ID, alloc_time, PACKAGE = "rhdf5")
invisible(res)
}
H5Pget_alloc_time <- function(h5plist) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
res <- .Call("_H5Pget_alloc_time", h5plist@ID, PACKAGE = "rhdf5")
res <- h5const2String("H5D_ALLOC_TIME", res)
res
}
#' Query dataset filter properties.
#'
#' Return information about the filter pipeline applied to a dataset creation
#' property list.
#'
#' * `H5Pall_filters_avail()` checks whether all filters required to process a
#' dataset are available to **rhdf5**. This can be required if reading files
#' created with other HDF5 software.
#' * `H5Pget_nfilters()` returns the number of
#' filters in the dataset chunk processing pipeline.
#' * `H5Pget_filter()`
#' provides details of a specific filter in the pipeline. This includes the
#' filter name and the parameters provided to it e.g. compression level.
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#' creation property list.
#' @param idx Integer of length 1. This argument selects which filter to return
#' information about. Indexing is R-style 1-based.
#' @rdname H5P_filters
#' @export
H5Pall_filters_avail <- function(h5plist) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
res <- .Call("_H5Pall_filters_avail", h5plist@ID, PACKAGE = "rhdf5")
return(res)
}
#' @rdname H5P_filters
#' @export
H5Pget_nfilters <- function(h5plist) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
res <- .Call("_H5Pget_nfilters", h5plist@ID, PACKAGE = "rhdf5")
res
}
#' @rdname H5P_filters
#' @export
H5Pget_filter <- function(h5plist, idx) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
idx <- as.integer(idx)
if (idx < 1 || idx > H5Pget_nfilters(h5plist)) {
stop(
"'idx' argument is outside the range of filters set on this property list.",
call. = FALSE
)
}
res <- .Call("_H5Pget_filter", h5plist@ID, idx - 1L, PACKAGE = "rhdf5")
return(res)
}
#' Add a filter to the dataset filter pipeline.
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#' creation property list.
#' @param filter_id Integer of length 1, giving the ID of the filter to be used.
#' @param is_mandatory Logical of length 1. Filters can be either optional or
#' mandatory. If this argument is set to `FALSE` the filter won't be applied
#' to a chunk in the case of failure, but the data will still be written.
#' Setting to `TRUE` will result in a failure when writing the dataset if the
#' filter fails for some reason.
#' @param cd_values Integer vector giving parameters to be supplied to the
#' filter. No guidance is given for the number of values supplied here, it is
#' specific to each filter and the user is expected to know appropriate
#' options for the requested filter.
#' @export
H5Pset_filter <- function(h5plist, filter_id, is_mandatory = FALSE, cd_values) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
filter_id <- as.integer(filter_id)
is_mandatory <- as.logical(is_mandatory)
cd_values <- as.integer(cd_values)
res <- .Call(
"_H5Pset_filter",
h5plist@ID,
filter_id,
is_mandatory,
cd_values,
PACKAGE = "rhdf5"
)
return(res)
}
#' Add the shuffle filter to the chunk processing pipeline.
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#' creation property list.
#'
#' @returns Returns (invisibly) an integer vector of length 1. The only
#' element of this vector will be non-negative if the filter was set
#' successfully and negative otherwise.
#'
#' @export
H5Pset_shuffle <- function(h5plist) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
res <- .Call("_H5Pset_shuffle", h5plist@ID, PACKAGE = "rhdf5")
invisible(res)
}
#' Add the N-Bit filter to the chunk processing pipeline.
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#' creation property list.
#'
#' @returns Returns (invisibly) an integer vector of length 1. The only
#' element of this vector will be non-negative if the filter was set
#' successfully and negative otherwise.
#'
#' @export
H5Pset_nbit <- function(h5plist) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
res <- .Call("_H5Pset_nbit", h5plist@ID, PACKAGE = "rhdf5")
invisible(res)
}
#' Add the SZIP compression filter to the chunk processing pipeline.
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#' creation property list.
#' @param options_mask,pixels_per_block Integer vectors of length 1, setting parameters
#' of the SZIP algorithm. See <https://portal.hdfgroup.org/display/HDF5/H5P_SET_SZIP> for more details.
#'
#' @references <https://portal.hdfgroup.org/display/HDF5/Szip+Compression+in+HDF+Products>
#'
#' @export
H5Pset_szip <- function(h5plist, options_mask, pixels_per_block) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_CREATE")
options_mask <- as.integer(options_mask)
pixels_per_block <- as.integer(pixels_per_block)
res <- .Call(
"_H5Pset_szip",
h5plist@ID,
options_mask,
pixels_per_block,
PACKAGE = "rhdf5"
)
invisible(res)
}
####################################################
## Dataset Access Properties
####################################################
#' Set parameters for the raw data chunk cache
#'
#' @param h5plist Object of class [H5IdComponent-class] representing a dataset
#' access property list.
#' @param rdcc_nslots Integer defining the number of chunk slots in the raw data
#' chunk cache for this dataset.
#' @param rdcc_nbytes Integer setting the total size of the raw data chunk cache
#' for this dataset in bytes. In most cases increasing this number will
#' improve performance, as long as you have enough free memory. The default
#' size is 1 MB
#' @param rdcc_w0 Numeric value defining the chunk preemption policy. Must be between
#' `0` and `1` inclusive.
#'
#' @name H5P_chunk_cache
NULL
#' @rdname H5P_chunk_cache
#' @export
H5Pset_chunk_cache <- function(h5plist, rdcc_nslots, rdcc_nbytes, rdcc_w0) {
h5checktypeAndPLC(h5plist, "H5P_DATASET_ACCESS")
rdcc_nslots <- as.integer(rdcc_nslots)
rdcc_nbytes <- as.integer(rdcc_nbytes)
rdcc_w0 <- as.double(rdcc_w0)
res <- .Call(
"_H5Pset_chunk_cache",
h5plist@ID,
rdcc_nslots,
rdcc_nbytes,
rdcc_w0,
PACKAGE = "rhdf5"
)
invisible(res)
}
####################################################
## Object Creation Properties
####################################################
#' Set whether to record timestamps for operations performed on an HDF5 object.
#'
#' @details Objects created using high-level **rhdf5** functions like
#' [h5createDataset()] will have this setting turned off. This was done to
#' ensure otherwise identical files returned the same md5 hash. This differs
#' from the default setting in HDF5, which is for objects to record the times
#' operations were performed on them.
#'
#' @param h5plist An [H5IdComponent-class] object representing an object
#' creation property list.
#' @param track_times `logical` specifying whether times associated with an
#' object should recorded.
#'
#' @name H5Pobject_track_times
NULL
#' @rdname H5Pobject_track_times
#' @export
H5Pset_obj_track_times <- function(h5plist, track_times = TRUE) {
if (!is.logical(track_times) || is.na(track_times)) {
stop("Argument 'track_times' must be either TRUE or FALSE")
}
res <- .Call(
"_H5Pset_obj_track_times",
h5plist@ID,
as.integer(track_times),
PACKAGE = "rhdf5"
)
invisible(res)
}
#' @rdname H5Pobject_track_times
#' @export
H5Pget_obj_track_times <- function(h5plist) {
res <- .Call("_H5Pget_obj_track_times", h5plist@ID, PACKAGE = "rhdf5")
return(res)
}
####################################################
## Generic Property Operations (Advanced)
####################################################
H5Pequal <- function(h5plistclass1, h5plistclass2) {
h5checktype(h5plistclass1, "plistclass")
h5checktype(h5plistclass2, "plistclass")
res <- .Call(
"_H5Pequal",
h5plistclass1@ID,
h5plistclass2@ID,
PACKAGE = "rhdf5"
)
as.logical(res)
}
H5Pclose_class <- function(h5plistclass) {
h5checktype(h5plistclass, "plistclass")
invisible(.Call("_H5Pclose_class", h5plistclass@ID, PACKAGE = "rhdf5"))
}