swectral.SpecExp#

class swectral.SpecExp(report_directory, log_loading=False, *, _space_wait_timeout=6, _reserve_free_pct=5.0)[source]#

SpecExp is the experiment data manager for SpecPipe batch processing, modeling, and model evaluation. The SpecPipe pipeline module uses SpecExp for data loading. Create and configure a SpecExp instance before designing SpecPipe testing pipelines.

Attributes:

report_directorystr

Root directory where reports are stored.

log_loadingbool

Whether configuration logging is enabled. Default is True.

groupslist of str

Experiment groups. Each item is a group name.

imageslist of tuple

Raster image loading data. Each tuple contains:

image_id : str
group : str
image_name : str
mask_of : str
image_path : str

images_datalist of tuple

Raster images for sample spectral data. Same structure as images.

images_masklist of tuple

Raster images serving as masks. Same structure as images.

rois_from_filelist of tuple

Regions of interest (ROIs) loaded from ROI files. Each tuple contains:

roi_id : str
group : str
image_name : str
roi_name : str
roi_type : str
coord_lists : list of list of tuple of 2 (float or int)
roi_file_name : str
roi_file_path : str

rois_from_coordslist of tuple

ROIs added from coordinate lists (without file info). Each tuple contains:

roi_id : str
group : str
image_name : str
roi_name : str
roi_type : str
coord_lists : list of list of tuple of 2 (float or int)

roislist of tuple

All regions of interest. Same structure as rois_from_coords.

rois_samplelist of tuple

ROIs serving as samples. Same structure as rois_from_coords.

rois_masklist of tuple

ROIs serving as masks. Same structure as rois_from_coords.

standalone_specslist of tuple

Standalone spectral data. Each tuple contains:

spectrum_id : str
group : str
use_type : str
sample_name : str
spectral_data : list of (float or int)

standalone_specs_samplelist of tuple

Training sample spectral data. Same structure as standalone_specs.

sample_labelslist of tuple

Custom sample labels. Each tuple contains:

sample_id : str
label : str
group : str

sample_targetslist of tuple

Target values of samples for modeling. Each tuple contains:

sample_id : str
label : str
target_value : str, bool, int, or float
group : str
validation_group : str
test_mask : int
train_mask : int

create_timestr

Creation date and time of this SpecExp isntance.

Methods

`add_groups`(group_name_list)	Add experiment groups by list of group names.
`ls_groups`()	List added groups.
`rm_group`(group_name)	Remove a group from this SpecExp instance by name, simultaneously removing associated image paths, ROI files, and added ROIs.
`add_images_by_name`([image_name, ...])	Add paths of raster images to an experiment group by searching name pattern(s) in the specified directory.
`add_images_by_path`([path, group, mask_of])	Add paths of raster images to an experiment group by image path(s).
`ls_images`([image_name, group, mask_of, ...])	List added image items based on image name and group.
`rm_images`([image_name, group, mask_of, globbing])	Remove raster images from this SpecExp instance by group, image name(s) and mask target(s), simultaneously removing associated ROIs.
`add_rois_by_suffix`([roi_filename_suffix, ...])	Load ROIs from files by searching for a suffix pattern in the names of associated images and add them to this SpecExp instance.
`add_rois_by_file`(path, image_name, group[, ...])	Load ROIs from specified files, such as ENVI '.xml' ROI files or shapefiles ('.shp') from QGIS/ArcGIS, and add them to this SpecExp instance.
`add_roi_by_coords`(roi_name, coord_lists, ...)	Add a (multi-)polygon ROI to a raster image using vertex coordinates.
`ls_rois`([roi_name_list, roi_type, ...])	List added ROI items based on filtering conditions.
`rm_rois`([roi_name, roi_type, ...])	Remove Regions of Interest (ROIs) from this SpecExp instance based on provided filters.
`roi_subset_augmentation`(n_sub, resolution, ...)	Perform spatial subset augmentation on the ROI data.
`add_standalone_specs`(spec_data, group[, ...])	Add one-dimensional standalone spectra to a group.
`load_standalone_specs`(csv_file_path)	Load or reload standalone spectra from a CSV file.
`ls_standalone_specs`([sample_name, group, ...])	List added standalone spectra based on filtering conditions.
`rm_standalone_specs`([sample_name, group, ...])	Remove added standalone spectra from this SpecExp instance.
`ls_sample_labels`([return_dataframe])	List added sample labels.
`sample_labels_from_df`(labels_dataframe)	Load sample labels from a pandas DataFrame into this SpecExp instance.
`sample_labels_to_csv`([path])	Save sample labels to a CSV file.
`sample_labels_from_csv`([label_csv_path])	Load sample labels from a CSV file into the current SpecExp instance.
`ls_sample_targets`([return_dataframe])	List sample target values.
`sample_targets_from_df`(target_value_dataframe)	Load sample target values from a dataframe.
`sample_targets_to_csv`([path, include_header])	Save sample target values to a CSV file.
`sample_targets_from_csv`([path, ...])	Load sample target values from a CSV file.
`save_data_config`([copy, ...])	Save the current configuration of this SpecExp instance to a file in the root of the report directory.
`load_data_config`([config_file_path])	Load SpecExp configurations from a dill file.

Examples

Create a SpecExp instance from a directory path:

>>> exp = SpecExp("/experiment")

__init__(report_directory, log_loading=False, *, _space_wait_timeout=6, _reserve_free_pct=5.0)[source]#

Methods

`__init__`(report_directory[, log_loading, ...])
`add_groups`(group_name_list)	Add experiment groups by list of group names.
`add_images_by_name`([image_name, ...])	Add paths of raster images to an experiment group by searching name pattern(s) in the specified directory.
`add_images_by_path`([path, group, mask_of])	Add paths of raster images to an experiment group by image path(s).
`add_roi_by_coords`(roi_name, coord_lists, ...)	Add a (multi-)polygon ROI to a raster image using vertex coordinates.
`add_rois_by_file`(path, image_name, group[, ...])	Load ROIs from specified files, such as ENVI '.xml' ROI files or shapefiles ('.shp') from QGIS/ArcGIS, and add them to this SpecExp instance.
`add_rois_by_suffix`([roi_filename_suffix, ...])	Load ROIs from files by searching for a suffix pattern in the names of associated images and add them to this SpecExp instance.
`add_specs`(spec_data, group[, use_type, ...])	Add one-dimensional standalone spectra to a group.
`add_standalone_specs`(spec_data, group[, ...])	Add one-dimensional standalone spectra to a group.
`labels_from_csv`([label_csv_path])	Load sample labels from a CSV file into the current SpecExp instance.
`labels_from_df`(labels_dataframe)	Load sample labels from a pandas DataFrame into this SpecExp instance.
`labels_to_csv`([path])	Save sample labels to a CSV file.
`load_config`([config_file_path])	Load SpecExp configurations from a dill file.
`load_data_config`([config_file_path])	Load SpecExp configurations from a dill file.
`load_specs`(csv_file_path)	Load or reload standalone spectra from a CSV file.
`load_standalone_specs`(csv_file_path)	Load or reload standalone spectra from a CSV file.
`ls_groups`()	List added groups.
`ls_images`([image_name, group, mask_of, ...])	List added image items based on image name and group.
`ls_labels`([return_dataframe])	List added sample labels.
`ls_rois`([roi_name_list, roi_type, ...])	List added ROI items based on filtering conditions.
`ls_rois_from_coords`([roi_name_list, ...])	List Regions of Interest added using vertex coordinates.
`ls_rois_from_file`([roi_name_list, roi_type, ...])	List file-added Regions of Interest.
`ls_rois_mask`([roi_name_list, roi_type, ...])	List Regions of Interest as masks.
`ls_rois_sample`([roi_name_list, roi_type, ...])	List Regions of Interest as samples.
`ls_sample_labels`([return_dataframe])	List added sample labels.
`ls_sample_targets`([return_dataframe])	List sample target values.
`ls_specs`([sample_name, group, use_type, ...])	List added standalone spectra based on filtering conditions.
`ls_standalone_specs`([sample_name, group, ...])	List added standalone spectra based on filtering conditions.
`ls_targets`([return_dataframe])	List sample target values.
`rm_group`(group_name)	Remove a group from this SpecExp instance by name, simultaneously removing associated image paths, ROI files, and added ROIs.
`rm_images`([image_name, group, mask_of, globbing])	Remove raster images from this SpecExp instance by group, image name(s) and mask target(s), simultaneously removing associated ROIs.
`rm_rois`([roi_name, roi_type, ...])	Remove Regions of Interest (ROIs) from this SpecExp instance based on provided filters.
`rm_specs`([sample_name, group, use_type, ...])	Remove added standalone spectra from this SpecExp instance.
`rm_standalone_specs`([sample_name, group, ...])	Remove added standalone spectra from this SpecExp instance.
`roi_subset_augmentation`(n_sub, resolution, ...)	Perform spatial subset augmentation on the ROI data.
`sample_labels_from_csv`([label_csv_path])	Load sample labels from a CSV file into the current SpecExp instance.
`sample_labels_from_df`(labels_dataframe)	Load sample labels from a pandas DataFrame into this SpecExp instance.
`sample_labels_to_csv`([path])	Save sample labels to a CSV file.
`sample_targets_from_csv`([path, ...])	Load sample target values from a CSV file.
`sample_targets_from_df`(target_value_dataframe)	Load sample target values from a dataframe.
`sample_targets_to_csv`([path, include_header])	Save sample target values to a CSV file.
`save_config`([copy, _space_wait_timeout, ...])	Save the current configuration of this SpecExp instance to a file in the root of the report directory.
`save_data_config`([copy, ...])	Save the current configuration of this SpecExp instance to a file in the root of the report directory.
`show_image`(image_name, group, rgb_band_index)	Display a raster image with associated ROIs in RGB preview.
`targets_from_csv`([path, target_dtype, ...])	Load sample target values from a CSV file.
`targets_from_df`(target_value_dataframe)	Load sample target values from a dataframe.
`targets_to_csv`([path, include_header])	Save sample target values to a CSV file.

Attributes

`create_time`
`groups`
`images`
`images_data`
`images_mask`
`log_loading`
`report_directory`
`rois`
`rois_from_coords`
`rois_from_file`
`rois_mask`
`rois_sample`
`sample_labels`
`sample_targets`
`standalone_specs`
`standalone_specs_sample`

property report_directory#

property sample_labels#

property sample_targets#

property log_loading#

property create_time#

property groups#

property images#

property images_data#

property images_mask#

property rois_from_file#

property rois_from_coords#

property rois#

property rois_sample#

property rois_mask#

property standalone_specs#

property standalone_specs_sample#

add_groups(group_name_list)[source]#

Add experiment groups by list of group names.

Parameters:

group_listlist of str: List of group names to add. Groups can be experiment groups or groups of certain features to test.

Return type:

None

Examples

>>> exp = SpecExp("/experiment")
>>> exp.add_groups(['group1', 'group2'])

ls_groups()[source]#

List added groups.

Returns:

list of str: List of group names.

Return type:

list

Examples

>>> exp = SpecExp("/experiment")
>>> exp.add_groups(['group1', 'group2'])
>>> exp.ls_groups()

The result is the same as:

>>> exp.groups

rm_group(group_name)[source]#

Remove a group from this SpecExp instance by name, simultaneously removing associated image paths, ROI files, and added ROIs.

Parameters:

group_namestr: Group to remove.

Return type:

None

Examples

>>> exp = SpecExp("/experiment")
>>> exp.add_groups(['group1', 'group2'])

>>> exp.rm_group('group2')

add_images_by_name(image_name=None, image_directory='', group='', mask_of='')[source]#

Add paths of raster images to an experiment group by searching name pattern(s) in the specified directory.

Parameters:

image_namestr or list of str or None, optional: Image name(s) or pattern(s) of image names in the given directory. For multiple patterns or names, please provide them in a list. Unix-like filename pattern is supported for image names. Image names must be unique within each group for the same type, or the existed duplicated record will be overwritten. The default is None.
image_directorystr, optional: Directory path of the images to add. If empty string empty string, the current working directory is used. The default is empty string.
groupstr: Group of the added raster images.
mask_ofbool: If the given image is a binary raster mask of a spectral image, specify the name of the target image it corresponds to. If not, this is default to empty string.

Return type:

None

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")

Add single image:

>>> exp.add_images_by_name("image.tif", "/rasters", "group1")

Add single image using default current working directory:

>>> exp.add_images_by_name("image.tif", group="group1")

Add multiple images:

>>> exp.add_images_by_name(["image1.tif", "image2.tif"], "/rasters", "group1")

Add by pattern:

>>> exp.add_images_by_name("*.tif", "/rasters", "group1")
>>> exp.add_images_by_name(["*.tif", "*.tiff"], "/rasters", "group1")

Add raster mask:

>>> exp.add_images_by_name("image_mask.tif", "/rasters", "group1", mask_of="image1")

add_images_by_path(path=None, group='', mask_of='')[source]#

Add paths of raster images to an experiment group by image path(s).

Parameters:

pathstr or list of str or None, optional: Absolute path or list of absolute paths of the image files. The default is None. The implemention of image_full_path is preferred if image_name and image_directory are simultaneously provided.
groupstr: Group of the added raster images.
mask_ofbool: If the given image is a binary raster mask of a spectral image, specify the name of the target image it corresponds to. If not, this is default to empty string.

Return type:

None

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")

Add single image:

>>> exp.add_images_by_path("/image.tif", "group1")

Add multiple images:

>>> exp.add_images_by_path(["/image1.tif", "/image2.tif"], "group1")

ls_images(image_name=None, group='', mask_of=None, *, print_result=True, return_dataframe=False)[source]#

List added image items based on image name and group. When a parameter is not specified, the corresponding filter is not applied.

Parameters:

image_namestr or list of str or None, optional

Name or list of names of the image(s) to filter.

If a string, only images with that exact name are matched.
If a list of strings, any image matching one of the names is included.
If None, no filtering by image name is applied.

Default is None.

groupstr, optional

Name of the group to filter images by.

If empty string, no filtering by group is applied.

Default is an empty string.

mask_ofstr or list of str or None, optional

Name(s) of the target image(s) if filtering for raster masks.

For sample images, provide an empty string.
For masks of a single image, provide the target image name as a string.
For masks of multiple images, provide a list of target image names.
If None, no filtering by mask association is applied.

Default is None.

print_resultbool, optional

Whether to print the matched image items to the console. Default is True.

return_dataframebool, optional

Whether to return the results as a pandas DataFrame. Default is False.

Returns:

pandas.DataFrame or None

If return_dataframe=True, returns a pandas DataFrame containing matched image items. Each row corresponds to one image. Columns:

IDstr
Unique identifier for the image.

Groupstr
Group to which the image belongs.

Imagestr
Name of the image file.

Typestr
Type of the image item, e.g., 'sample' or 'mask'.

Pathstr
Full path to the image file.

If return_dataframe=False, returns None and prints the result to console.

Return type:

Optional[DataFrame]

Examples

Prepare a SpecExp instance and add a group and image:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image.tif", "group1")

List all added images:

>>> exp.ls_images()

Filter images by name or group:

>>> exp.ls_images("image.tif")
>>> exp.ls_images(group="group1")

Retrieve image item dataframe:

>>> df = exp.ls_images(return_dataframe=True)

show_image(image_name, group, rgb_band_index, display_size=(12, 9), roi_name=None, roi_color='red', roi_linewidth=3, *, display_roi=True, normalize=True, output_path=None, dpi=150, show_image=True)[source]#

Display a raster image with associated ROIs in RGB preview.

Parameters:

image_namestr

Name of the image to display.

groupstr

Group to which the image belongs.

rgb_band_indextuple of 3 int

Indices of the Red, Green, and Blue bands for RGB display. Example: (R_index, G_index, B_index)

display_sizetuple of 2 (float or int), optional

Size of the preview plot in inches (width, height). Default is (12, 9).

roi_namestr or None, optional

Name of the ROI to display. If None, all ROIs associated with the image are displayed. Default is None.

roi_colorstr or tuple of 3 float, optional

Color of the ROI frame.

If str, standard color names (e.g., “red”) are accepted.
If tuple, specify RGB values as float numbers in the range 0-1, e.g., (1.0, 0.0, 0.0) for red.

Default is “red”.

roi_linewidthint or float, optional

Line width of the ROI frame in the plot. Default is 3.

display_roibool, optional

Whether to display ROI frames on the image. Default is True.

normalizebool, optional

Whether to normalize image values for RGB display. Default is True.

output_pathstr or None, optional

Path to save the RGB preview image. If None, no file is saved. Default is None.

dpiint, optional

Dots per inch (DPI) for the output image. Default is 150.

show_imagebool, optional

Whether to display the image in the console. Default is True.

Returns:

None: This function does not return a value. The image is displayed in console and saved to file depending on the parameters.

Return type:

None

Examples

Prepare a SpecExp instance and add images:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image.tif", "group1")

Basic usage:

>>> exp.show_image("image.tif", "group1", rgb_band_index=(192, 124, 64))

Save output to a PNG image file:

>>> exp.show_image(
...     "image.tif",
...     "group1",
...     rgb_band_index=(192, 124, 64),
...     output_path="/image_rgb.png"
... )

rm_images(image_name=None, group='', mask_of=None, globbing=True)[source]#

Remove raster images from this SpecExp instance by group, image name(s) and mask target(s), simultaneously removing associated ROIs. If a criterion is not provided, matched images will be removed regardless of the criterion.

Parameters:

image_namestr or list of str, or None, optional

Name(s) of the image(s) to remove.

If str, remove a single image.
If list of str, remove multiple images.
If None, all images matching the other criteria are removed.

Default is None.

groupstr, optional

Name of the group to which the images belong. If empty string or not provided, images are removed regardless of group. Default is “”.

mask_ofstr or list of str, or None, optional

Name(s) of the target images if masks should be removed.

If str, remove masks associated with a single image.
If list of str, remove masks associated with multiple images.
If None, no mask filtering is applied.

Default is None.

globbingbool, optional

Whether Unix-like filename patterns (globbing) are enabled.

True (default): patterns like “image*” are allowed.
False: filenames must match exactly.

Return type:

None

Examples

Prepare a SpecExp instance and add images:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name(["image1.tif", "image2.tif"], "group1")

Remove all images:

>>> exp.rm_images()

Remove a single image by name:

>>> exp.rm_images("image1.tif")

Remove multiple images by name:

>>> exp.rm_images(["image1.tif", "image2.tif"])

Remove images by group:

>>> exp.rm_images(group="group2")

Remove images by name pattern:

>>> exp.rm_images("image*")

add_rois_by_suffix(roi_filename_suffix='', search_directory='', group='', as_mask=False, *, include_roiname=None, exclude_roiname=None)[source]#

Load ROIs from files by searching for a suffix pattern in the names of associated images and add them to this SpecExp instance.

Parameters:

roi_filename_suffixstr, optional

Suffix pattern to match ROI files to the names of added images. If empty string, all ROI files with arbitrary suffixes are considered. Default is empty string.

search_directorystr, optional

Directory path in which to search for ROI files. If empty string, current working directory is used. Default is empty string.

groupstr

Name of the image group to which ROIs will be added. Must be one of the groups in SpecExp.groups.

as_maskbool, optional

If True, added ROIs are labeled as masks. If False, added ROIs are labeled as sample ROIs. Default is False.

include_roinamestr or list of str or None, optional

Inclusion filter for ROI names.

If str, ROIs containing that substring are included.
If list of str, ROIs containing any of the substrings are included.
If None, all ROIs are included.

Default is None.

exclude_roinamestr or list of str or None, optional

Exclusion filter for ROI names.

If str, ROIs containing that substring are excluded.
If list of str, ROIs containing any of the substrings are excluded.
If None, no ROIs are excluded.

Default is None.

Return type:

None

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")

Add ROIs matching a suffix pattern:

>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Add ROIs using a glob pattern:

>>> exp.add_rois_by_suffix("*.xml", group="group1")

Exclude a specific ROI name:

>>> exp.add_rois_by_suffix("*.xml", group="group1", exclude_roiname='name_to_exclude')

Exclude multiple ROI names:

>>> exp.add_rois_by_suffix("*.xml", group="group1", exclude_roiname=['name_to_exclude1', 'name_to_exclude2'])

Only include ROIs by specific ROI name pattern:

>>> exp.add_rois_by_suffix("*.xml", group="group1", include_roiname='_sample')

Add ROI as masks to the associated images:

>>> exp.add_rois_by_suffix("_mask.xml", group="group1", as_mask=True)

add_rois_by_file(path, image_name, group, as_mask=False, *, include_roiname=None, exclude_roiname=None)[source]#

Load ROIs from specified files, such as ENVI ‘.xml’ ROI files or shapefiles (‘.shp’) from QGIS/ArcGIS, and add them to this SpecExp instance.

Parameters:

pathstr or list of str

Path or list of paths to ROI files to load.

image_namestr

Name of the belonging raster image for the ROI(s). If empty, ROIs are associated automatically with matching images.

groupstr

Name of the experiment group to which the ROIs belong. Must be one of the groups in SpecExp.groups.

as_maskbool, optional

If True, added ROIs are labeled as masks. If False, added ROIs are labeled as sample ROIs. Default is False.

include_roinamestr or list of str or None, optional

Inclusion filter for ROI names:

If str, ROIs containing that substring are included.
If list of str, ROIs containing any of the substrings are included.
If None, all ROIs are included.

Default is None.

exclude_roinamestr or list of str or None, optional

Exclusion filter for ROI names:

If str, ROIs containing that substring are excluded.
If list of str, ROIs containing any of the substrings are excluded.
If None, no ROIs are excluded.

Default is None.

Return type:

None

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")

Add a single ROI file:

>>> exp.add_rois_by_file("/image1_roi.xml", group="group1")

Exclude a single ROI name:

>>> exp.add_rois_by_file("/image1_roi.xml", group="group1", exclude_roiname='name_to_exclude')

Exclude multiple ROI names:

>>> exp.add_rois_by_file("/image1_roi.xml", group="group1", exclude_roiname=['name_to_exclude1', 'name_to_exclude2'])

Include ROIs by specific ROI name pattern:

>>> exp.add_rois_by_file("/image1_roi.xml", group="group1", include_roiname='_sample')

Add ROI as mask of the corresponding image:

>>> exp.add_rois_by_file("/image1_roi_mask.xml", group="group1", as_mask=True)

add_roi_by_coords(roi_name, coord_lists, image_name, group, as_mask=False, print_update=True, *, _roi_id=None, _skip_meta_validation=False, _use_external_update=False)[source]#

Add a (multi-)polygon ROI to a raster image using vertex coordinates. The ROI can consist of multiple polygons. Each polygon is defined as a list of (x, y) vertex coordinate pairs and must be closed.

Parameters:

roi_namestr

Name of the ROI to add.

coord_listslist of list of tuple of 2 (float or int)

Coordinates of the ROI polygons. Structure:

[
    [ (x1, y1), (x2, y2), ..., (xn, yn), (x1, y1) ],  # Polygon 1
    [ (x1, y1), (x2, y2), ..., (xm, ym), (x1, y1) ],  # Polygon 2
    ...
]

Each inner list represents a polygon (for multipart geometries), and each tuple is a vertex coordinate.

image_namestr

Name of the raster image to which the ROI belongs.

groupstr

Name of the experiment group of the ROI. Must be one of the existing SpecExp.groups.

as_maskbool, optional

If True, the added ROI is labeled as a mask. If False, the added ROI is labeled as a sample. Default is False.

print_updatebool, optional

If True, prints the ROI update report. Set to False to suppress the update report. Defaults to True.

Return type:

None

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")

Add ROI by vertex coordinates:

>>> coordinates = [[(100, 100), (200, 100), (200, 200), (100, 200), (100, 100)]]
>>> exp.add_roi_by_coords(
...     roi_name="test_roi",
...     group="group1",
...     image_name="image1.tif",
...     coord_lists=coordinates
... )

ls_rois(roi_name_list=None, roi_type='', roi_file_name_list=None, source_type='', image_name='', group='', *, print_result=True, return_dataframe=False)[source]#

List added ROI items based on filtering conditions. If a filter criterion is not provided, the corresponding filter is not applied.

Parameters:

roi_name_listlist of str or None, optional

List of ROI names to filter by. If None, no filtering by ROI name is applied. Default is None.

roi_typestr, optional

Use type of ROI. Accepted values are:

"sample"
"mask"

If empty, no filtering by ROI type is applied. Default is “”.

roi_file_name_listlist of str or None, optional

List of ROI source file names to filter by. If None, no filtering by ROI file name is applied. Default is None.

source_typestr, optional

Source type of ROI addition. Accepted values are:

"file" : ROIs loaded from files
"coords" : ROIs added from coordinate lists

If empty, no filtering by source type is applied. Default is “”.

image_namestr, optional

Name of the associated raster image. If empty, no filtering by image name is applied. Default is “”.

groupstr, optional

Name of the experiment group. If empty, no filtering by group is applied. Default is “”.

print_resultbool, optional

Whether to print the matched ROI items to the console. Default is True.

return_dataframebool, optional

Whether to return the matched ROI items as a pandas DataFrame. Default is False.

Returns:

pandas.DataFrame or None

If return_dataframe=True, returns a pandas DataFrame containing matched ROI items.

The DataFrame contains the following columns:

IDstr
unique identifier of the ROI.

Groupstr
group to which the ROI belongs.

Imagestr
name of the associated image.

ROI_namestr
name of the ROI.

ROI_typestr
use type of the ROI (“sample” or “mask”).

Coordinateslist of list of tuple of 2 (float or int)
vertex coordinates of the ROI polygons.

If ROIs were loaded from files, the following columns are additionally included:

ROI_source_filestr
name of the ROI source file.

ROI_file_pathstr
full path to the ROI source file.

If return_dataframe=False, returns None.

Return type:

Optional[DataFrame]

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

List all ROIs:

>>> exp.ls_rois()

List ROIs with filtering conditions:

>>> exp.ls_rois(roi_type="sample")
>>> exp.ls_rois(roi_name_list=["ROI1", "ROI2"])
>>> exp.ls_rois(source_type="coords")
>>> exp.ls_rois(group="group1")
>>> exp.ls_rois(group="group1", roi_type="sample")

Return results as a DataFrame:

>>> df = exp.ls_rois(return_dataframe=True)

ls_rois_from_file(roi_name_list=None, roi_type='', group='', image_name='', roi_file_name_list=None, *, print_result=True, return_dataframe=False)[source]#

List file-added Regions of Interest. For detailed use, see ‘ls_rois’.

Return type:: Optional[DataFrame]

See also

ls_rois

ls_rois_from_coords(roi_name_list=None, roi_type='', group='', image_name='', roi_file_name_list=None, *, print_result=True, return_dataframe=False)[source]#

List Regions of Interest added using vertex coordinates. For detailed use, see ls_rois.

Return type:: Optional[DataFrame]

See also

ls_rois

ls_rois_sample(roi_name_list=None, roi_type='', group='', image_name='', roi_file_name_list=None, source_type='', *, print_result=True, return_dataframe=False)[source]#

List Regions of Interest as samples. For detailed use, see ls_rois.

Return type:: Optional[DataFrame]

See also

ls_rois

ls_rois_mask(roi_name_list=None, roi_type='', group='', image_name='', roi_file_name_list=None, source_type='', *, print_result=True, return_dataframe=False)[source]#

List Regions of Interest as masks. For detailed use, see ls_rois.

Return type:: Optional[DataFrame]

See also

ls_rois

rm_rois(roi_name='', roi_type='', roi_source_file_name='', roi_source_file_path='', image_name='', group='')[source]#

Remove Regions of Interest (ROIs) from this SpecExp instance based on provided filters. All parameters act as filters. If a parameter is not specified or left empty, the corresponding filter criterion is not applied. Unix-like wildcard patterns like * and ? are supported for string parameters.

Parameters:

roi_namestr, optional: Name or name pattern of the ROI(s) to remove.
roi_typestr, optional: Type of ROI to remove. Allowed values are "sample" and "mask".
roi_source_file_namestr, optional: Name or name pattern of the source ROI file(s).
roi_source_file_pathstr, optional: Path or path pattern of the source ROI file(s).
image_namestr, optional: Name or name pattern of the associated image(s).
groupstr, optional: Name or name pattern of the belonging experiment group(s).

Return type:

None

Examples

Prepare a SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Remove all ROIs:

>>> exp.rm_rois()

Remove ROIs by condition:

>>> exp.rm_rois(roi_type="mask")
>>> exp.rm_rois(group="group1")
>>> exp.rm_rois(image_name="image1.tif")
>>> exp.rm_rois(roi_source_file_name="image1_roi.xml")

roi_subset_augmentation(n_sub, resolution, coverage_ratio, n_processor=-1, random_state=None)[source]#

Perform spatial subset augmentation on the ROI data.

This method can only be applied on completely configured SpecExp instance.

The method generates multiple synthetic spatial subsets from the original ROIs and automatically updates the related data. The generated sub-ROIs shares the same target value as the original sample ROI.

Parameters:

n_subint

The number of augmented synthetic data points (subsets) to generate for each sample ROI.

resolutionint or float

The side length of the square grid cells used for sampling. This effectively defines the spatial grain of the augmentation.

Note: Combining a large ROI with a very fine resolution (small value) significantly increases the number of grid cells to be processed, leading to longer computation times. It is recommended to scale the resolution proportionally to the ROI size and the desired ‘n_sub’ to maintain an efficient balance between spatial variability and performance.

coverage_ratiofloat

The target fraction of the total original ROI area to retain in each augmented sample. Must be a value between 0.0 and 1.0.

n_processorint, optional

Number of processors to use during pipeline execution.

Default is -1, which does not apply parallel execution on Windows and applies parallel execution using (maximum available CPUs - 1) processors on other operating systems.

Set to -2 to force (maximum available CPUs - 1) processors on Windows.

Windows note: when using n_processor > 1 or n_processor = -2 on Windows, all excecutable code in the working script must be placed within:

if __name__ == '__main__':

random_stateint, optional

Seed for the internal NumPy random number generator to ensure reproducibility. Default is None.

Return type:

None

Examples

>>> exp.roi_subset_augmentation(
...     n_sub=5,
...     resolution=2,
...     coverage_ratio=0.3,
...     random_state=42
... )

add_standalone_specs(spec_data, group, use_type='sample', sample_name_list=None, *, silent_run=False, save_backup=True, return_updates=False)[source]#

Add one-dimensional standalone spectra to a group.

Parameters:

spec_dataarray_like (n_samples, n_bands)

Spectral values of one-dimensional spectra.

Can be provided as a list of lists, where each inner list contains the spectral values of one spectrum.

groupstr

Name of the belonging group.

use_typestr, optional

Use-type label of the spectra. Set to "sample" to treat the spectra as samples. The default is "sample".

sample_name_listlist of str, optional

Names of the spectra. If not provided, spectra are named automatically.

silent_runbool, optional

Whether to suppress console output. The default is False.

save_backupbool, optional

Whether to save backup files. If False, data are saved without creating a backup.

return_updatesbool, optional

Whether to return an update report. If True, a summary of the updates is returned.

Returns:

dict of pandas.DataFrame or None

If return_updates=True, returns a dictionary containing update reports:

updated_itemspandas.DataFrame: DataFrame containing the updated spectral items.
added_itemspandas.DataFrame: DataFrame containing the newly added spectral items.

If return_updates=False, returns None.

Return type:

Optional[dict[str, DataFrame]]

Notes

This method is also available as add_specs.

Examples

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")

>>> exp.add_standalone_specs(
...     [[1, 2, 3, 4], [1, 3, 3, 3]],
...     group="group1",
...     sample_name_list=["sample1", "sample2"]
... )

add_specs(spec_data, group, use_type='sample', sample_name_list=None, *, silent_run=False, save_backup=True, return_updates=False)#

Add one-dimensional standalone spectra to a group.

Parameters:

spec_dataarray_like (n_samples, n_bands)

Spectral values of one-dimensional spectra.

Can be provided as a list of lists, where each inner list contains the spectral values of one spectrum.

groupstr

Name of the belonging group.

use_typestr, optional

Use-type label of the spectra. Set to "sample" to treat the spectra as samples. The default is "sample".

sample_name_listlist of str, optional

Names of the spectra. If not provided, spectra are named automatically.

silent_runbool, optional

Whether to suppress console output. The default is False.

save_backupbool, optional

Whether to save backup files. If False, data are saved without creating a backup.

return_updatesbool, optional

Whether to return an update report. If True, a summary of the updates is returned.

Returns:

dict of pandas.DataFrame or None

If return_updates=True, returns a dictionary containing update reports:

updated_itemspandas.DataFrame: DataFrame containing the updated spectral items.
added_itemspandas.DataFrame: DataFrame containing the newly added spectral items.

If return_updates=False, returns None.

Return type:

Optional[dict[str, DataFrame]]

Notes

This method is also available as add_specs.

Examples

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")

>>> exp.add_standalone_specs(
...     [[1, 2, 3, 4], [1, 3, 3, 3]],
...     group="group1",
...     sample_name_list=["sample1", "sample2"]
... )

load_standalone_specs(csv_file_path)[source]#

Load or reload standalone spectra from a CSV file.

The CSV file should contain a table of spectral data with metadata. Expected table columns:

[‘ID’, ‘Group’, ‘Use_type’, ‘Sample_name’, ‘Band_1’, ‘Band_2’, …].

Both ‘ID’ and ‘Sample_name’ values must be unique.

Parameters:

csv_file_pathstr: Path to the CSV file containing standalone spectra.

Return type:

None

Notes

This method is also available as load_specs.

Examples

Prepare SpecExp instance and load spectra:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.load_standalone_specs("/specs.csv")

load_specs(csv_file_path)#

Load or reload standalone spectra from a CSV file.

The CSV file should contain a table of spectral data with metadata. Expected table columns:

[‘ID’, ‘Group’, ‘Use_type’, ‘Sample_name’, ‘Band_1’, ‘Band_2’, …].

Both ‘ID’ and ‘Sample_name’ values must be unique.

Parameters:

csv_file_pathstr: Path to the CSV file containing standalone spectra.

Return type:

None

Notes

This method is also available as load_specs.

Examples

Prepare SpecExp instance and load spectra:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.load_standalone_specs("/specs.csv")

ls_standalone_specs(sample_name='', group='', use_type='', *, exact_match=True, print_result=True, return_dataframe=False)[source]#

List added standalone spectra based on filtering conditions. If a filter criterion is not provided, the corresponding filter is not applied.

Parameters:

sample_namestr, optional: Name of the sample to filter by. If None, no filtering by sample name is applied. Default is None.
groupstr, optional: Name of the group to filter by. If None, no filtering by group is applied. Default is None.
use_typestr, optional: Use type of the spectra to filter by. If None, no filtering by use type is applied. Default is None.
exact_matchbool, optional: If False, all items with sample names containing the given string will be included. Default is True.
print_resultbool, optional: If True, prints a simplified table of results to the console. Default is True.
return_dataframebool, optional: If True, returns a pandas DataFrame of the filtered spectra. Default is False.

Returns:

pandas.DataFrame or None

If return_dataframe=True, returns a pandas DataFrame of matched standalone spectra.

If return_dataframe=False, returns None.

Return type:

Optional[DataFrame]

Notes

This method is also available as ls_specs.

Examples

Prepare a SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_standalone_specs(
...     [[1, 2, 3, 4], [1, 3, 3, 3]],
...     group='group1',
...     sample_name_list=['sample1', 'sample2']
... )

List all standalone spectra:

>>> exp.ls_standalone_specs()

Filter by group:

>>> exp.ls_standalone_specs(group='group1')

Filter by partial sample name:

>>> exp.ls_standalone_specs(sample_name='1', exact_match=False)

Return results as a DataFrame:

>>> df = exp.ls_standalone_specs(return_dataframe=True)

ls_specs(sample_name='', group='', use_type='', *, exact_match=True, print_result=True, return_dataframe=False)#

List added standalone spectra based on filtering conditions. If a filter criterion is not provided, the corresponding filter is not applied.

Parameters:

sample_namestr, optional: Name of the sample to filter by. If None, no filtering by sample name is applied. Default is None.
groupstr, optional: Name of the group to filter by. If None, no filtering by group is applied. Default is None.
use_typestr, optional: Use type of the spectra to filter by. If None, no filtering by use type is applied. Default is None.
exact_matchbool, optional: If False, all items with sample names containing the given string will be included. Default is True.
print_resultbool, optional: If True, prints a simplified table of results to the console. Default is True.
return_dataframebool, optional: If True, returns a pandas DataFrame of the filtered spectra. Default is False.

Returns:

pandas.DataFrame or None

If return_dataframe=True, returns a pandas DataFrame of matched standalone spectra.

If return_dataframe=False, returns None.

Return type:

Optional[DataFrame]

Notes

This method is also available as ls_specs.

Examples

Prepare a SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_standalone_specs(
...     [[1, 2, 3, 4], [1, 3, 3, 3]],
...     group='group1',
...     sample_name_list=['sample1', 'sample2']
... )

List all standalone spectra:

>>> exp.ls_standalone_specs()

Filter by group:

>>> exp.ls_standalone_specs(group='group1')

Filter by partial sample name:

>>> exp.ls_standalone_specs(sample_name='1', exact_match=False)

Return results as a DataFrame:

>>> df = exp.ls_standalone_specs(return_dataframe=True)

rm_standalone_specs(sample_name='', group='', use_type='', sample_name_exact_match=True, silent_run=False)[source]#

Remove added standalone spectra from this SpecExp instance.

The removal can be filtered by sample name, group, and use-type. If a filter parameter is not specified or left empty, the corresponding filter criterion is not applied.

Parameters:

sample_namestr, optional: Name of the spectra to remove. Default is empty string.
groupstr, optional: Group name of the spectra to remove. Default is empty string.
use_typestr, optional: Use type of the spectra to remove (e.g., ‘sample’). Default is empty string.
sample_name_exact_matchbool, optional: If False, all spectra with names containing the given string are removed. Default is True.
silent_runbool, optional: If True, suppresses printing the removal report to the console. Default is False.

Return type:

None

Notes

This method is also available as rm_specs.

Examples

Prepare a SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_standalone_specs(
...     [[1, 2, 3, 4], [1, 3, 3, 3]],
...     group='group1',
...     sample_name_list=['sample1', 'sample2']
... )

Remove all standalone spectra:

>>> exp.rm_standalone_specs()

Remove spectra by group:

>>> exp.rm_standalone_specs(group='group1')

rm_specs(sample_name='', group='', use_type='', sample_name_exact_match=True, silent_run=False)#

Remove added standalone spectra from this SpecExp instance.

The removal can be filtered by sample name, group, and use-type. If a filter parameter is not specified or left empty, the corresponding filter criterion is not applied.

Parameters:

sample_namestr, optional: Name of the spectra to remove. Default is empty string.
groupstr, optional: Group name of the spectra to remove. Default is empty string.
use_typestr, optional: Use type of the spectra to remove (e.g., ‘sample’). Default is empty string.
sample_name_exact_matchbool, optional: If False, all spectra with names containing the given string are removed. Default is True.
silent_runbool, optional: If True, suppresses printing the removal report to the console. Default is False.

Return type:

None

Notes

This method is also available as rm_specs.

Examples

Prepare a SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_standalone_specs(
...     [[1, 2, 3, 4], [1, 3, 3, 3]],
...     group='group1',
...     sample_name_list=['sample1', 'sample2']
... )

Remove all standalone spectra:

>>> exp.rm_standalone_specs()

Remove spectra by group:

>>> exp.rm_standalone_specs(group='group1')

sample_labels_to_csv(path='')[source]#

Save sample labels to a CSV file.

Parameters:

pathstr, optional: Output CSV file path. If not provided, the labels are saved as ‘Sample_labels.csv’ in the report directory of this SpecExp instance.

Return type:

None

Notes

This method is also available as labels_to_csv.

Examples

Prepare a SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Save labels to the default path:

>>> exp.sample_labels_to_csv()

Save labels to a custom path:

>>> exp.sample_labels_to_csv("/labels.csv")

labels_to_csv(path='')#

Save sample labels to a CSV file.

Parameters:

pathstr, optional: Output CSV file path. If not provided, the labels are saved as ‘Sample_labels.csv’ in the report directory of this SpecExp instance.

Return type:

None

Notes

This method is also available as labels_to_csv.

Examples

Prepare a SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Save labels to the default path:

>>> exp.sample_labels_to_csv()

Save labels to a custom path:

>>> exp.sample_labels_to_csv("/labels.csv")

ls_sample_labels(return_dataframe=True)[source]#

List added sample labels.

Parameters:

return_dataframebool, optional

If True, returns the sample labels as a pandas DataFrame.

If False, prints the labels to the console and returns None.

Default is True.

Returns:

pandas.DataFrame or None

If return_dataframe=True, returns a pandas DataFrame of sample labels.

If return_dataframe=False, returns None.

Return type:

Optional[DataFrame]

Notes

This method is also available as ls_labels.

Examples

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

>>> exp.ls_sample_labels()

ls_labels(return_dataframe=True)#

List added sample labels.

Parameters:

return_dataframebool, optional

If True, returns the sample labels as a pandas DataFrame.

If False, prints the labels to the console and returns None.

Default is True.

Returns:

pandas.DataFrame or None

If return_dataframe=True, returns a pandas DataFrame of sample labels.

If return_dataframe=False, returns None.

Return type:

Optional[DataFrame]

Notes

This method is also available as ls_labels.

Examples

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

>>> exp.ls_sample_labels()

sample_labels_from_df(labels_dataframe)[source]#

Load sample labels from a pandas DataFrame into this SpecExp instance.

Parameters:

labels_dataframepandas.DataFrame

DataFrame containing sample labels.

Expected columns are [‘Sample_ID’, ‘Label’, ‘Group’]. Each combination of sample ID and group must be unique.

Return type:

None

Notes

This method is also available as labels_from_df.

Examples

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

>>> df = exp.ls_sample_labels()
>>> exp.sample_labels_from_df(df)

labels_from_df(labels_dataframe)#

Load sample labels from a pandas DataFrame into this SpecExp instance.

Parameters:

labels_dataframepandas.DataFrame

DataFrame containing sample labels.

Expected columns are [‘Sample_ID’, ‘Label’, ‘Group’]. Each combination of sample ID and group must be unique.

Return type:

None

Notes

This method is also available as labels_from_df.

Examples

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

>>> df = exp.ls_sample_labels()
>>> exp.sample_labels_from_df(df)

sample_labels_from_csv(label_csv_path='')[source]#

Load sample labels from a CSV file into the current SpecExp instance. The initial or current label CSV file can be created using SpecExp.sample_labels_to_csv().

Parameters:

label_csv_pathstr, optional

Path to the CSV file containing sample labels.

Expected columns are [‘Sample_ID’, ‘Label’, ‘Group’]. If not provided, the file Sample_labels.csv in the report directory of this SpecExp instance is used.

Return type:

None

Notes

This method is also available as labels_from_csv.

Examples

Prepare a SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Load labels from the default path:

>>> exp.sample_labels_to_csv()
>>> exp.sample_labels_from_csv()

Load labels from a custom path:

>>> exp.sample_labels_to_csv("/labels.csv")
>>> exp.sample_labels_from_csv("/labels.csv")

labels_from_csv(label_csv_path='')#

Load sample labels from a CSV file into the current SpecExp instance. The initial or current label CSV file can be created using SpecExp.sample_labels_to_csv().

Parameters:

label_csv_pathstr, optional

Path to the CSV file containing sample labels.

Expected columns are [‘Sample_ID’, ‘Label’, ‘Group’]. If not provided, the file Sample_labels.csv in the report directory of this SpecExp instance is used.

Return type:

None

Notes

This method is also available as labels_from_csv.

Examples

Prepare a SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Load labels from the default path:

>>> exp.sample_labels_to_csv()
>>> exp.sample_labels_from_csv()

Load labels from a custom path:

>>> exp.sample_labels_to_csv("/labels.csv")
>>> exp.sample_labels_from_csv("/labels.csv")

sample_targets_to_csv(path='', include_header=True)[source]#

Save sample target values to a CSV file.

If target values have not been specified, the target value column contains blank entries.

Parameters:

pathstr, optional: Output CSV file path. If not provided, the file “Sample_target_values.csv” in the report directory of this SpecExp instance is used.
include_headerbool, optional: If True, column headers are written as the first row of the CSV file. Default is True.

Return type:

None

Notes

This method is also available as targets_to_csv.

Examples

Prepare a SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Save target values to the default path:

>>> exp.sample_targets_to_csv()

Save target values to a custom path:

>>> exp.sample_targets_to_csv("/target.csv")

targets_to_csv(path='', include_header=True)#

Save sample target values to a CSV file.

If target values have not been specified, the target value column contains blank entries.

Parameters:

pathstr, optional: Output CSV file path. If not provided, the file “Sample_target_values.csv” in the report directory of this SpecExp instance is used.
include_headerbool, optional: If True, column headers are written as the first row of the CSV file. Default is True.

Return type:

None

Notes

This method is also available as targets_to_csv.

Examples

Prepare a SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Save target values to the default path:

>>> exp.sample_targets_to_csv()

Save target values to a custom path:

>>> exp.sample_targets_to_csv("/target.csv")

ls_sample_targets(return_dataframe=True)[source]#

List sample target values.

If no sample targets have been specified, a blank template dataframe is returned that can be filled and assigned back to the SpecExp instance.

Parameters:

return_dataframebool, optional

Whether to return the dataframe.

If False, a simplified view is printed to the console. Default is True.

Returns:

pandas.DataFrame or None

If return_dataframe=True, returns a pandas DataFrame of sample target values.

If return_dataframe=False, returns None.

Return type:

Optional[DataFrame]

Notes

This method is also available as ls_targets.

Examples

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

>>> exp.ls_sample_targets()

ls_targets(return_dataframe=True)#

List sample target values.

If no sample targets have been specified, a blank template dataframe is returned that can be filled and assigned back to the SpecExp instance.

Parameters:

return_dataframebool, optional

Whether to return the dataframe.

If False, a simplified view is printed to the console. Default is True.

Returns:

pandas.DataFrame or None

If return_dataframe=True, returns a pandas DataFrame of sample target values.

If return_dataframe=False, returns None.

Return type:

Optional[DataFrame]

Notes

This method is also available as ls_targets.

Examples

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

>>> exp.ls_sample_targets()

sample_targets_from_df(target_value_dataframe)[source]#

Load sample target values from a dataframe.

The current target dataframe can be retrieved using SpecExp.ls_sample_targets. A blank template dataframe can also be obtained using the same method, which can be filled and assigned back to the SpecExp instance using this method.

Parameters:

target_value_dataframepd.DataFrame

Dataframe containing sample target values. Expected columns:

[“Sample_ID”, “Label”, “Target_value”, “Group”, “Validation_group”, “Test”, “Train”]

And each row corresponds to a single sample.

The dataframe can be obtained from SpecExp.ls_sample_targets for editing or reloading.

Return type:

None

Notes

This method is also available as targets_from_df.

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Load or update target values from dataframe:

>>> df = exp.ls_sample_targets()
>>> exp.sample_targets_from_df(df)

targets_from_df(target_value_dataframe)#

Load sample target values from a dataframe.

Parameters:

target_value_dataframepd.DataFrame

Dataframe containing sample target values. Expected columns:

[“Sample_ID”, “Label”, “Target_value”, “Group”, “Validation_group”, “Test”, “Train”]

And each row corresponds to a single sample.

The dataframe can be obtained from SpecExp.ls_sample_targets for editing or reloading.

Return type:

None

Notes

This method is also available as targets_from_df.

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Load or update target values from dataframe:

>>> df = exp.ls_sample_targets()
>>> exp.sample_targets_from_df(df)

sample_targets_from_csv(path='', target_dtype=None, include_header=True)[source]#

Load sample target values from a CSV file.

The current target CSV file can be retrieved using SpecExp.sample_targets_to_csv. A blank template CSV can also be obtained using the same method, which can be edited and loaded back using this method.

Parameters:

pathstr

CSV file path.

Expected columns:

[“Sample_ID”, “Label”, “Target_value”, “Group”, “Validation_group”, “Test”, “Train”]

If not provided, the file Sample_target_values.csv in the report directory of this SpecExp instance is used.

target_dtypetype, str, or None, optional

Data type of the target values.

If None, pandas will infer the type automatically (see pandas.read_csv documentation). Default is None.

include_headerbool, optional

Whether the first row of the CSV file is treated as headers. Default is True.

Return type:

None

Notes

This method is also available as targets_from_csv.

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Use default path:

>>> exp.sample_targets_to_csv()
>>> exp.sample_targets_from_csv()

Use custom path:

>>> exp.sample_targets_to_csv("/target.csv")
>>> exp.sample_targets_from_csv("/target.csv")

targets_from_csv(path='', target_dtype=None, include_header=True)#

Load sample target values from a CSV file.

Parameters:

pathstr

CSV file path.

Expected columns:

[“Sample_ID”, “Label”, “Target_value”, “Group”, “Validation_group”, “Test”, “Train”]

If not provided, the file Sample_target_values.csv in the report directory of this SpecExp instance is used.

target_dtypetype, str, or None, optional

Data type of the target values.

If None, pandas will infer the type automatically (see pandas.read_csv documentation). Default is None.

include_headerbool, optional

Whether the first row of the CSV file is treated as headers. Default is True.

Return type:

None

Notes

This method is also available as targets_from_csv.

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")
>>> exp.add_groups("group1")
>>> exp.add_images_by_name("image1.tif", "group1")
>>> exp.add_rois_by_suffix("_roi.xml", group="group1")

Use default path:

>>> exp.sample_targets_to_csv()
>>> exp.sample_targets_from_csv()

Use custom path:

>>> exp.sample_targets_to_csv("/target.csv")
>>> exp.sample_targets_from_csv("/target.csv")

save_data_config(copy=True, *, _space_wait_timeout=1, _reserve_free_pct=0.1)[source]#

Save the current configuration of this SpecExp instance to a file in the root of the report directory.

The file path is (SpecExp.report_directory)/SpecExp_configuration/SpecExp_data_configuration_(creating-time).dill.

The copy name is SpecExp_data_configuration_(creating-time)_copy_at_(saving-time).dill

Parameters:

copybool, optional: Whether to create a simultaneous copy of the configuration file. Default is True.

Return type:

None

Notes

This method is also available as save_config.

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")

Save configuration with default behavior (copy enabled):

>>> exp.save_data_config()

Save configuration without creating a copy:

>>> exp.save_data_config(copy=False)

save_config(copy=True, *, _space_wait_timeout=1, _reserve_free_pct=0.1)#

Save the current configuration of this SpecExp instance to a file in the root of the report directory.

The file path is (SpecExp.report_directory)/SpecExp_configuration/SpecExp_data_configuration_(creating-time).dill.

The copy name is SpecExp_data_configuration_(creating-time)_copy_at_(saving-time).dill

Parameters:

copybool, optional: Whether to create a simultaneous copy of the configuration file. Default is True.

Return type:

None

Notes

This method is also available as save_config.

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")

Save configuration with default behavior (copy enabled):

>>> exp.save_data_config()

Save configuration without creating a copy:

>>> exp.save_data_config(copy=False)

load_data_config(config_file_path='')[source]#

Load SpecExp configurations from a dill file.

Parameters:

config_file_pathstr, optional

Path to the configuration dill file. Can be a file path or the file name in the report directory of this SpecExp instance.

If not provided or empty, the path will be:

(SpecExp.report_directory)/SpecExp_configuration/SpecExp_data_configuration_(SpecExp.create_time).dill

Default is empty string.

Return type:

None

Notes

This method is also available as load_config.

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")

Load configuration using default path:

>>> exp.save_data_config()
>>> exp.load_data_config()

Load configuration from a custom path:

>>> exp.load_data_config("/spec_exp_config.dill")

load_config(config_file_path='')#

Load SpecExp configurations from a dill file.

Parameters:

config_file_pathstr, optional

Path to the configuration dill file. Can be a file path or the file name in the report directory of this SpecExp instance.

If not provided or empty, the path will be:

(SpecExp.report_directory)/SpecExp_configuration/SpecExp_data_configuration_(SpecExp.create_time).dill

Default is empty string.

Return type:

None

Notes

This method is also available as load_config.

Examples

Prepare SpecExp instance:

>>> exp = SpecExp("/experiment")

Load configuration using default path:

>>> exp.save_data_config()
>>> exp.load_data_config()

Load configuration from a custom path:

>>> exp.load_data_config("/spec_exp_config.dill")