pycroglia.core.io package

Subpackages

Submodules

Export cell masks and skeleton branch surfaces to mesh and VTK volume formats.

Skeleton branch arrays from analysis are XY-cropped; they are embedded into each cell’s full (Z, Y, X) mask shape before marching cubes so outputs share one volume frame.

class pycroglia.core.io.geometry_export.GeometryExportSelection(skeleton_obj: 'bool' = False, skeleton_ply: 'bool' = False, skeleton_vtp: 'bool' = False, skeleton_vtk: 'bool' = False, mask_obj: 'bool' = False, mask_ply: 'bool' = False, mask_vtp: 'bool' = False, mask_vtk: 'bool' = False, mask_volume_vtk: 'bool' = False, mask_volume_vti: 'bool' = False)[source]

Bases: object

Parameters:
any_geometry_selected()[source]
Return type:

bool

mask_obj: bool = False
mask_ply: bool = False
mask_surface_formats()[source]

Cell mask surface mesh (marching-cubes PolyData): obj/ply/vtp/vtk.

Return type:

set[str]

mask_volume_formats()[source]

Boolean mask ImageData volumes: vtk and/or vti.

Return type:

set[str]

mask_volume_vti: bool = False
mask_volume_vtk: bool = False
mask_vtk: bool = False
mask_vtp: bool = False
skeleton_formats()[source]
Return type:

set[str]

skeleton_obj: bool = False
skeleton_ply: bool = False
skeleton_vtk: bool = False
skeleton_vtp: bool = False
pycroglia.core.io.geometry_export.export_geometry(out_root, cells_masks, cells, scale, zscale, selection)[source]

Write selected geometry under out_root/{fmt}/.

Directory layout

out_root/

obj/ cell_000_skeleton.obj, cell_000_surface.obj, … ply/ cell_000_skeleton.ply, cell_000_surface.ply, … vtp/ cell_000_skeleton.vtp, cell_000_surface.vtp, … vtk/ cell_000_skeleton.vtk, cell_000_surface.vtk, …

cell_000_boolean_mask.vtk

vti/ cell_000_boolean_mask.vti

returns:

List of human-readable messages for skipped cells or failures (non-fatal).

Parameters:
Return type:

list[str]

class pycroglia.core.io.output.AnalysisMetadata(file_path, gray_filter_value, min_size, erosion_radius, scale, z_scale, segmented_cell_indices, selected_cell_indices, rejected_cell_indices, skeletonization_method='slimskel3d')[source]

Bases: object

Metadata about the analysis pipeline parameters and cell indices.

Parameters:

  • file_path (str)

  • gray_filter_value (float)

  • min_size (int)

  • erosion_radius (int)

  • scale (float)

  • z_scale (float)

  • segmented_cell_indices (List[int])

  • selected_cell_indices (List[int])

  • rejected_cell_indices (List[int])

  • skeletonization_method (str)

file_path

Path to the source image file.

Type:

str

gray_filter_value

Threshold value used for the gray filter.

Type:

float

min_size

Minimum size for small object removal (pixels).

Type:

int

erosion_radius

Radius for the diamond erosion footprint.

Type:

int

scale

XY scale in μm.

Type:

float

z_scale

Z scale in μm.

Type:

float

segmented_cell_indices

List of all cell indices from segmentation.

Type:

List[int]

final_cell_indices

List of cell indices not rejected (kept after selection).

erosion_radius: int
file_path: str
gray_filter_value: float
min_size: int
rejected_cell_indices: List[int]
scale: float
segmented_cell_indices: List[int]
selected_cell_indices: List[int]
skeletonization_method: str = 'slimskel3d'
z_scale: float
class pycroglia.core.io.output.AnalysisSummary(file, avg_centroid_distance, total_territorial_volume, total_unoccupied_volume, percent_occupied_volume)[source]

Bases: object

Summary statistics for microglia analysis.

Parameters:

  • file (str)

  • avg_centroid_distance (float)

  • total_territorial_volume (float)

  • total_unoccupied_volume (float)

  • percent_occupied_volume (float)

file

Name of the analyzed file.

Type:

str

avg_centroid_distance

Average distance between cell centroids.

Type:

float

total_territorial_volume

Total volume of all cell territories.

Type:

float

total_unoccupied_volume

Volume not occupied by any cell territory.

Type:

float

percent_occupied_volume

Percentage of total volume that is occupied.

Type:

float

avg_centroid_distance: float
file: str
percent_occupied_volume: float
total_territorial_volume: float
total_unoccupied_volume: float
class pycroglia.core.io.output.AnalysisSummaryConfig(file_txt, avg_centroid_distance_txt, total_territorial_volume_txt, total_unoccupied_volume_txt, percent_occupied_volume_txt)[source]

Bases: object

Configuration for column headers in analysis summary output.

Parameters:

  • file_txt (str)

  • avg_centroid_distance_txt (str)

  • total_territorial_volume_txt (str)

  • total_unoccupied_volume_txt (str)

  • percent_occupied_volume_txt (str)

file_txt

Header text for file column.

Type:

str

avg_centroid_distance_txt

Header text for average centroid distance.

Type:

str

total_territorial_volume_txt

Header text for total territorial volume.

Type:

str

total_unoccupied_volume_txt

Header text for total unoccupied volume.

Type:

str

percent_occupied_volume_txt

Header text for percent occupied volume.

Type:

str

avg_centroid_distance_txt: str
classmethod default()[source]

Create default configuration with standard column headers.

Returns:

Configuration with default header texts.

Return type:

AnalysisSummaryConfig

file_txt: str
percent_occupied_volume_txt: str
total_territorial_volume_txt: str
total_unoccupied_volume_txt: str
class pycroglia.core.io.output.BranchLengthsXlsxOutput[source]

Bases: OutputWriter

XLSX output writer for per-cell branch lengths.

Creates a simple XLSX file where each row represents a cell (by index) and each column represents a branch length. No headers are written.

DEFAULT_FILE_EXTENSION = '.xlsx'
DEFAULT_NAME = 'Branch Lengths XLSX'
classmethod get_name()[source]

Return the display name of the writer.

Returns:

Name of the writer.

Return type:

str

write(file_path, data, meta)[source]

Write per-cell branch lengths to an XLSX file.

Parameters:

  • file_path (str) – Path where the XLSX file should be saved.

  • data (FullAnalysis) – Complete analysis results containing branch data.

  • meta (AnalysisMetadata)

class pycroglia.core.io.output.CellAnalysis(cell_territory_volume, cell_volume, ramification_index, number_of_endpoints, number_of_branches, avg_branch_length, max_branch_length, min_branch_length, branch_analysis, full_cell_analysis)[source]

Bases: object

Analysis results for an individual microglia cell.

Parameters:
cell_territory_volume

Volume of the cell’s territory.

Type:

float

cell_volume

Volume of the cell itself.

Type:

float

ramification_index

Measure of cell branching complexity.

Type:

float

number_of_endpoints

Count of branch endpoints.

Type:

int

number_of_branches

Count of branch points.

Type:

int

avg_branch_length

Average length of all branches.

Type:

float

max_branch_length

Length of the longest branch.

Type:

float

min_branch_length

Length of the shortest branch.

Type:

float

avg_branch_length: float
branch_analysis: dict[str, Any]
cell_territory_volume: float
cell_volume: float
full_cell_analysis: dict[str, Any]
max_branch_length: float
min_branch_length: float
number_of_branches: int
number_of_endpoints: int
ramification_index: float
class pycroglia.core.io.output.CellAnalysisConfig(cell_territory_volume_txt, cell_volume_txt, ramification_index_txt, number_of_endpoints_txt, number_of_branches_txt, avg_branch_length_txt, max_branch_length_txt, min_branch_length_txt)[source]

Bases: object

Configuration for column headers in per-cell analysis output.

Parameters:

  • cell_territory_volume_txt (str)

  • cell_volume_txt (str)

  • ramification_index_txt (str)

  • number_of_endpoints_txt (str)

  • number_of_branches_txt (str)

  • avg_branch_length_txt (str)

  • max_branch_length_txt (str)

  • min_branch_length_txt (str)

cell_territory_volume_txt

Header text for cell territory volume.

Type:

str

cell_volume_txt

Header text for cell volume.

Type:

str

ramification_index_txt

Header text for ramification index.

Type:

str

number_of_endpoints_txt

Header text for number of endpoints.

Type:

str

number_of_branches_txt

Header text for number of branches.

Type:

str

avg_branch_length_txt

Header text for average branch length.

Type:

str

max_branch_length_txt

Header text for maximum branch length.

Type:

str

min_branch_length_txt

Header text for minimum branch length.

Type:

str

avg_branch_length_txt: str
cell_territory_volume_txt: str
cell_volume_txt: str
classmethod default()[source]

Create default configuration with standard column headers.

Returns:

Configuration with default header texts.

Return type:

CellAnalysisConfig

max_branch_length_txt: str
min_branch_length_txt: str
number_of_branches_txt: str
number_of_endpoints_txt: str
ramification_index_txt: str
class pycroglia.core.io.output.ExcelOutput(summary_title=None, per_cell_title=None, summary_config=None, per_cell_config=None)[source]

Bases: OutputWriter

Excel output writer for microglia analysis results.

Creates Excel workbooks with separate sheets for summary statistics and per-cell analysis data.

Parameters:
DEFAULT_FILE_EXTENSION = '.xlsx'
DEFAULT_NAME = 'Multi Sheet Excel'
DEFAULT_PER_CELL_SHEET_TITLE = 'PerCell'
DEFAULT_SUMMARY_SHEET_TITLE = 'Summary'
classmethod get_name()[source]

Return the display name of the Excel writer.

Returns:

Name of the writer.

Return type:

str

write(file_path, data, meta)[source]

Write analysis data to an Excel file.

Parameters:
class pycroglia.core.io.output.FullAnalysis(summary, cells)[source]

Bases: object

Complete analysis results containing summary and per-cell data.

Parameters:
summary

Overall analysis summary statistics.

Type:

pycroglia.core.io.output.AnalysisSummary

cells

List of individual cell analysis results.

Type:

List[pycroglia.core.io.output.CellAnalysis]

cells: List[CellAnalysis]
summary: AnalysisSummary
class pycroglia.core.io.output.JSONOutput(summary_config=None, per_cell_config=None, indent=4)[source]

Bases: OutputWriter

JSON output writer for microglia analysis results.

Serializes analysis data to JSON format using configured field names for consistency with other output formats.

Parameters:
DEFAULT_FILE_EXTENSION = '.json'
DEFAULT_NAME = 'JSON File'
classmethod get_name()[source]

Return the display name of the JSON writer.

Returns:

Name of the writer.

Return type:

str

write(file_path, data, meta)[source]

Write analysis data to a JSON file.

Parameters:
class pycroglia.core.io.output.OutputWriter[source]

Bases: ABC

Abstract base class for writing analysis results to files.

abstractmethod classmethod get_name()[source]

Return the display name of the writer.

Returns:

Name of the writer.

Return type:

str

classmethod get_writers()[source]

Return all non-abstract subclasses of OutputWriter.

Returns:

List of OutputWriter subclasses.

Return type:

list

abstractmethod write(file_path, data, meta)[source]

Write analysis data to a file.

Parameters:

  • file_path (str) – Path where the output file should be saved.

  • data (FullAnalysis) – Complete analysis results to write.

  • meta (AnalysisMetadata) – Metadata associated with the analysis.

class pycroglia.core.io.readers.MultiChReader[source]

Bases: ABC

Abstract base class for multi-channel image readers.

abstractmethod read(ch, ch_interest)[source]

Reads the specified channels from the image file.

Parameters:

  • ch (int) – The number of channels in the image.

  • ch_interest (int) – The channel of interest to extract (1-based index).

Returns:

The extracted channel data.

Return type:

NDArray

class pycroglia.core.io.readers.TiffReader(path)[source]

Bases: MultiChReader

Reader for TIFF image files.

Parameters:

path (str)

VALID_EXTENSIONS

Valid file extensions [‘.tif’, ‘.tiff’].

Type:

list

EXTENSION_ERROR_CODE

Error code for invalid extensions (1001).

Type:

int

path

Path of the file.

Type:

str

EXTENSION_ERROR_CODE = 1001
VALID_EXTENSIONS = ['.tif', '.tiff']
read(ch, ch_interest)[source]

Reads the contents of the file and returns the specified channels.

Parameters:

  • ch (int) – The number of channels.

  • ch_interest (int) – The channel extracted from the file.

Returns:

The file data.

Return type:

NDArray

Raises:
validate_channels(ch, ch_interest)[source]

Validates the channel and channel of interest values.

Parameters:

  • ch (int) – The number of channels.

  • ch_interest (int) – The channel extracted from the file.

Raises:
Return type:

None

validate_path()[source]

Validates the path of the file.

Raises:
Return type:

None

pycroglia.core.io.readers.create_channeled_reader(path)[source]

Creates a MultiChReader instance based on the file extension.

Parameters:

path (str) – Path to the image file.

Returns:

An instance of TiffReader or LsmReader.

Return type:

MultiChReader

Raises:

PycrogliaException(1005) – If the file extension is not supported.

Module contents