objectExtract: Object Extraction
In IFC: Tools for Imaging Flow Cytometry
View source: R/objectExtract.R
objectExtract R Documentation
Object Extraction
Description
Extracts / Decompress objects stored in RIF or CIF Files.
Usage
objectExtract(ifd, param, verbose = FALSE, bypass = FALSE, ...)
Arguments
ifd
list of sub elements of IFD data information extracted by getIFD. This argument can't be missing.
param
object of class 'IFC_param', containing extraction parameters defined by objectParam.
This argument is not mandatory but it may allow to save time for repeated image export on same file.
If this argument is missing, objectExtract will use named arguments in '...' as input to objectParam to control object extraction.
However, if 'param' is provided, '...' will be ignored.
verbose
whether to display information (use for debugging purpose). Default is FALSE.
bypass
whether to bypass checks on 'ifd' and 'param'. Default is FALSE.
...
Arguments passed on to objectParam
infoobject of class 'IFC_info', rich information extracted by getInfo.
This argument is not mandatory but it may allow to save time for repeated image export on same file.
If missing, the default, 'info' will be extracted thanks to '...'.
modecolor mode export. Either "rgb", "gray" or "raw". Default is "raw".
Note that "raw" is only possible when 'export' is "matrix".
exportformat mode export. Either "file", "matrix", "base64". Default is "matrix".
write_toused when export is "file" or "base64" to compute respectively exported file name or base64 id attribute.
Exported file extension and base64 MIME type will be deduced from this pattern. Allowed export are ".bmp", ".jpg", ".jpeg", ".png", ".tif", ".tiff".
Note that ".bmp" are faster but not compressed producing bigger data.
Placeholders, if found, will be substituted:
-%d: with full path directory,
-%p: with first parent directory,
-%e: with extension (without leading .),
-%s: with shortname (i.e. basename without extension),
-%o: with object_id,
-%c: with channel_id.
A good trick is to use:
-"%d/%s/%s_%o_%c.tiff", when 'export' is "file",
-"%o_%c.bmp", when 'export' is "base64".
Note that if missing and 'export' is not "file", 'write_to' will be set to "%o_%c.bmp".
base64_idwhether to add id attribute to base64 exported object. Default is FALSE.
Only applied when export is "base64".
base64_attattributes to add to base64 exported object. Default is "".
Only applied when export is "base64". For example, use "class='draggable'".
Note that id (if 'base64_id' is TRUE) and width and height are already used.
overwriteonly apply when 'export' is "file" whether to overwrite file or not. Default is FALSE.
compositecharacter vector of image composite. Default is "", for no image composite.
Should be like "1.05/2.4/4.55" for a composition of 5 perc. of channel 1, 40 perc. of channel 2 and 50 perc. of channel 55.
Note that channels should have been acquired and final image composition should be 100 perc., otherwise an error is thrown.
Note that each composite will be appended after 'selection'.
selectionphysical channels to extract.
Note that this parameter will be ordered.
Default is "all" to extract all acquired channels.
Use "none" to only extract composite.
random_seeda list of elements to pass to set.seed or a single value, interpreted as an integer, or NULL to be used when 'add_noise' is set to TRUE. Default is NULL.
Note that NA_integer_ or list(seed = NA_integer_) can be used to not call set.seed at all.
sizea length 2 integer vector of final dimensions of the image, height 1st and width 2nd. Default is c(0,0) for no change.
force_widthwhether to use information in 'info' to fill size. Default is TRUE.
When set to TRUE, width of 'size' argument will be overwritten.
removalremoval method: Either "none", "raw", "clipped", "masked", "MC".
-"none", to keep image as is, no mask extraction will be performed resulting in faster extraction,
-"raw", to keep image as is, it provides a convenient way to retrieve "raw" value for the mask,
-"clipped", to remove clipped object from image,
-"masked", to only keep masked object from image,
-"MC", to keep MC masked object from image.
This parameter will be repeated with rep_len() from base for every physical channel that needs to be extracted according to 'selection' and 'composite' parameters.
add_noiseif TRUE adds normal noise to background using Rcpp. Default is TRUE.
Note that it is better to set it to FALSE when 'removal' is "masked" or "MC". Doing so will allow to place masked object in a zero filled background,
otherwise background will still be filled with noise.
This parameter will be repeated with rep_len() from base for every physical channel that needs to be extracted according to 'selection' and 'composite' parameters.
full_rangeonly apply when 'mode' is not "raw", if 'full_range' is TRUE, then object range will be considered as 0 to 4095, it is like "raw" 'mode' but resulting in [0,4095] normalization to [0,1]. Default is FALSE.
This parameter will be repeated with rep_len() from base for every physical channel that needs to be extracted according to 'selection' and 'composite' parameters.
force_rangeonly apply when 'mode' is not "raw", if 'force_range' is TRUE, then range will be adjusted to object range in [-4095,+inf] resulting in normalization to [0,1]. Default is FALSE.
This parameter will be repeated with rep_len() from base for every physical channel that needs to be extracted according to 'selection' and 'composite' parameters.
Note that this parameter takes the precedence over 'full_range'.
spatial_correctiononly apply on RIF file, whether to apply spatial correction. Default is FALSE.
Details
When a mask is detected, 'add_noise', 'full_range' and 'force_range' are set to FALSE and range used will be forced to [0,3].
Range of image is controlled by 'Images' information from supplied 'info' or as extracted by getInfo and will be returned as 'channels' by objectParam.
In case 'mode' is not "raw", 'channels$xmin', 'channels$xmax', 'channels$gamma' will be used for object extraction by objectExtract unless any of 'force_range' or 'full_range' is TRUE.
Experimental (as of v0.2.0.501): once returned by objectParam, those 'channels$xmin' and 'channels$xmax' can be manually adjusted to ]0,1[ so as to be used as 'probs' argument to quantile to allow quantile normalization during object extraction (objectExtract) afterwards.
Value
A list (for every extracted objects) of list (for every exported channels) depending on 'param$export' parameter:
-"matrix", a matrix when 'param$mode' is set to "raw" or "gray" OR an array when 'param$mode' is "rgb",
-"base64", a data-uri string,
-"file", an invisible file path corresponding to the location of exported file(s).
Note
'...' will be used to compute 'param' only if 'param' is not provided.
/!\ When 'param' is not provided, if not any of 'fileName', 'info' can be found in '...', then attr(ifd, "fileName_image") will be used as 'fileName' input parameter to pass to objectParam.
Source
For image decompression, Lee Kamentsky's code porting from https://github.com/ome/bioformats/blob/4146b9a1797501f0fec7d6cfe69124959bff96ee/components/formats-bsd/src/loci/formats/in/FlowSightReader.java
cited in https://linkinghub.elsevier.com/retrieve/pii/S1046-2023(16)30291-2
BSD implementations of Bio-Formats readers and writers
Copyright (C) 2005 - 2017 Open Microscopy Environment:
- Board of Regents of the University of Wisconsin-Madison
- Glencoe Software, Inc.
- University of Dundee
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Examples
if(requireNamespace("IFCdata", quietly = TRUE)) {
## use a cif file
file_cif <- system.file("extdata", "example.cif", package = "IFCdata")
cif_offs <- getOffsets(fileName = file_cif, fast = TRUE)
## extract infomation
info <- getInfo(fileName = file_cif, from = "analysis")
## retrieve number of objects stored
nobj <- as.integer(info$objcount)
## randomly subset the offsets of at most 5 "img" objects
sel = sample(0:(nobj-1), min(5, nobj))
sub_offs <- subsetOffsets(cif_offs, objects = sel, image_type = "img")
## read IFDs from these "img" objects
IFDs <- getIFD(fileName = file_cif, offsets = sub_offs)
## extract raw data of these"img" objects to matrix
raw = objectExtract(ifd = IFDs, info = info, mode = "raw",
export = "matrix")
## extract base64 "rgb" colorized version of these "img" objects to base64
b64 = objectExtract(ifd = IFDs, info = info, mode = "rgb",
export = "base64", base64_id = TRUE,
write_to = "example_%o_%c.bmp")
## use DisplayGallery to show the first "img" objects and play with ... extra parameters
## force_range, add_noise, selection, composite, see objectParam
DisplayGallery(info = info, offsets = cif_offs, objects = sel,
base64_id = TRUE, write_to = "example_%o_%c.bmp",
force_range = c(FALSE,TRUE,FALSE,TRUE), add_noise = FALSE,
selection = c(1,2,4,6), composite = "1.7/4.3")
} else {
message(sprintf('Please run `install.packages("IFCdata", repos = "%s", type = "source")` %s',
'https://gitdemont.github.io/IFCdata/',
'to install extra files required to run this example.'))
}
IFC documentation built on Sept. 14, 2023, 1:08 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
View source: R/objectExtract.R
| objectExtract | R Documentation |
Object Extraction
Description
Extracts / Decompress objects stored in RIF or CIF Files.
Usage
objectExtract(ifd, param, verbose = FALSE, bypass = FALSE, ...)
Arguments
ifd |
list of sub elements of IFD data information extracted by |
param |
object of class 'IFC_param', containing extraction parameters defined by |
verbose |
whether to display information (use for debugging purpose). Default is |
bypass |
whether to bypass checks on |
... |
Arguments passed on to
|
Details
When a mask is detected, 'add_noise', 'full_range' and 'force_range' are set to FALSE and range used will be forced to [0,3].
Range of image is controlled by 'Images' information from supplied 'info' or as extracted by getInfo and will be returned as 'channels' by objectParam.
In case 'mode' is not "raw", 'channels$xmin', 'channels$xmax', 'channels$gamma' will be used for object extraction by objectExtract unless any of 'force_range' or 'full_range' is TRUE.
Experimental (as of v0.2.0.501): once returned by objectParam, those 'channels$xmin' and 'channels$xmax' can be manually adjusted to ]0,1[ so as to be used as 'probs' argument to quantile to allow quantile normalization during object extraction (objectExtract) afterwards.
Value
A list (for every extracted objects) of list (for every exported channels) depending on 'param$export' parameter:
-"matrix", a matrix when 'param$mode' is set to "raw" or "gray" OR an array when 'param$mode' is "rgb",
-"base64", a data-uri string,
-"file", an invisible file path corresponding to the location of exported file(s).
Note
'...' will be used to compute 'param' only if 'param' is not provided.
/!\ When 'param' is not provided, if not any of 'fileName', 'info' can be found in '...', then attr(ifd, "fileName_image") will be used as 'fileName' input parameter to pass to objectParam.
Source
For image decompression, Lee Kamentsky's code porting from https://github.com/ome/bioformats/blob/4146b9a1797501f0fec7d6cfe69124959bff96ee/components/formats-bsd/src/loci/formats/in/FlowSightReader.java
cited in https://linkinghub.elsevier.com/retrieve/pii/S1046-2023(16)30291-2
BSD implementations of Bio-Formats readers and writers
Copyright (C) 2005 - 2017 Open Microscopy Environment:
- Board of Regents of the University of Wisconsin-Madison
- Glencoe Software, Inc.
- University of Dundee
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
Examples
if(requireNamespace("IFCdata", quietly = TRUE)) {
## use a cif file
file_cif <- system.file("extdata", "example.cif", package = "IFCdata")
cif_offs <- getOffsets(fileName = file_cif, fast = TRUE)
## extract infomation
info <- getInfo(fileName = file_cif, from = "analysis")
## retrieve number of objects stored
nobj <- as.integer(info$objcount)
## randomly subset the offsets of at most 5 "img" objects
sel = sample(0:(nobj-1), min(5, nobj))
sub_offs <- subsetOffsets(cif_offs, objects = sel, image_type = "img")
## read IFDs from these "img" objects
IFDs <- getIFD(fileName = file_cif, offsets = sub_offs)
## extract raw data of these"img" objects to matrix
raw = objectExtract(ifd = IFDs, info = info, mode = "raw",
export = "matrix")
## extract base64 "rgb" colorized version of these "img" objects to base64
b64 = objectExtract(ifd = IFDs, info = info, mode = "rgb",
export = "base64", base64_id = TRUE,
write_to = "example_%o_%c.bmp")
## use DisplayGallery to show the first "img" objects and play with ... extra parameters
## force_range, add_noise, selection, composite, see objectParam
DisplayGallery(info = info, offsets = cif_offs, objects = sel,
base64_id = TRUE, write_to = "example_%o_%c.bmp",
force_range = c(FALSE,TRUE,FALSE,TRUE), add_noise = FALSE,
selection = c(1,2,4,6), composite = "1.7/4.3")
} else {
message(sprintf('Please run `install.packages("IFCdata", repos = "%s", type = "source")` %s',
'https://gitdemont.github.io/IFCdata/',
'to install extra files required to run this example.'))
}
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.