SarcGraph Class

Public Methods

class sarcgraph.sg.SarcGraph(config=None, **kwargs)

Bases: object

Zdiscs and sarcomeres segmentation and tracking.

Parameters:

• config (Config, optional) – Configuration settings for the application. If not provided, default settings are used, and any additional settings can be passed via keyword arguments.

• **kwargs – Additional settings to override the defaults or values in the provided Config object.

print_config()

load_data(file_path=None)

Loads a video/image file.

Parameters:

file_path (str, optional) – A direct path to a video/image file to load.

Returns:

All frames in the raw format in gray scale.

Return type:

numpy.ndarray

save_data(data, file_name)

Saves a numpy array or a pandas dataframe based on the type of data.

Parameters:

• data (Union[np.ndarray, List, pd.DataFrame])

• file_name (str)

filter_frames(frames)

Convolves each image with Laplacian and Gaussian filters.

Parameters:

frames (np.ndarray) – A 2D image or a stack of 2D images.

Returns:

A stack of filtered images.

Return type:

np.ndarray

zdisc_segmentation(**kwargs)

Perform z-disc segmentation using various inputs and optional processing functions. - Pre-filtered frames can be provided by specifying ‘filtered_frames’. - Raw frames can be provided by specifying ‘raw_frames’; overrides ‘filtered_frames’. - An input file path can be provided by specifying ‘input_file’; overrides ‘raw_frames’ and ‘filtered_frames’. - Processing functions can be provided as a list of callable functions by specifying ‘processing_functions’.

Any configuration parameters can also be updated to customize the behavior of the segmentation and processing.

Parameters:

**kwargs (dict) – Arbitrary keyword arguments including: - ‘input_file’: Path to the input file to load raw frames. - ‘raw_frames’: Array-like structure with raw frames for processing. - ‘filtered_frames’: Array-like structure with pre-filtered frames for processing. - ‘processing_functions’: List of function references to apply additional processing. - Any configuration parameters to update.

Returns:

The processed z-disc information after segmentation.

Return type:

pd.DataFrame

zdisc_tracking(**kwargs)

Track detected Z-Discs in video data, similar to zdisc_segmentation, but with an additional tracking step. If ‘segmented_zdiscs’ is provided, it directly proceeds to tracking; otherwise, it first runs the z-discs segmentation process.

This function shares similar inputs to zdisc_segmentation with the addition of an optional ‘segmented_zdiscs’ DataFrame parameter.

Parameters:

**kwargs (dict, optional) – Shared keyword arguments with zdisc_segmentation, plus: - segmented_zdiscs: pd.DataFrame, optional Pre-segmented zdiscs information. If provided, it should contain at least the following columns: ‘frame’, ‘x’, ‘y’, ‘p1_x’, ‘p1_y’, ‘p2_x’, ‘p2_y’.

Returns:

Tracked zdiscs information; adds ‘particle’ column for each tracked zdisc.

Return type:

pd.DataFrame

Notes

• For details on shared parameters and segmentation process, refer to

sarcgraph.sg.SarcGraph.zdisc_segmentation().

See also

sarcgraph.sg.SarcGraph.zdisc_segmentation()

sarcomere_detection(**kwargs)

Detect sarcomeres in a video/image using dynamic keyword arguments. Sarcomere detection can be initiated with tracked zdisc information, or by first running zdisc tracking.

Parameters:

**kwargs (dict) –

Keyword arguments dynamically passed. Relevant keys are: ‘input_file’ : str

The address of an image or a video file to be loaded.

’raw_frames’np.ndarray

Raw input frames as a numpy array.

’filtered_frames’np.ndarray

Pre-filtered frames for processing.

’segmented_zdiscs’pd.DataFrame

Information of all detected zdiscs in every frame.

’tracked_zdiscs’pd.DataFrame

Information of tracked zdiscs. Must be non-empty and include the following columns: ‘frame’, ‘x’, ‘y’, ‘p1_x’, ‘p1_y’, ‘p2_x’, ‘p2_y’, ‘particle’. If provided and valid, sarcomere detection is initiated immediately.

Additional configuration parameters relevant for sarcomere detection and tracking can also be provided via kwargs.

Returns:

A tuple containing: - A DataFrame with detected sarcomeres information including

’frame’, ‘sarc_id’, ‘zdiscs’, ‘x’, ‘y’, ‘length’, ‘width’, and ‘angle’.

• A list of Graph objects representing connected sarcomeres (myofibrils).

Return type:

Tuple[pd.DataFrame, List[nx.Graph]]

Notes

• If ‘tracked_zdiscs’ is not provided, this function will internally call zdisc_tracking to generate tracked zdiscs from the provided keyword arguments. It is assumed that zdisc_tracking can handle error checking and appropriate defaults for its parameters.

• For a detailed description of the Trackpy package check: http://soft-matter.github.io/trackpy/v0.5.0/tutorial.html

• For a detailed description of the OPTICS algorithm check: https://scikit-learn.org/stable/modules/generated/sklearn.cluster.OPTICS.html

See also

sarcgraph.sg.SarcGraph.zdisc_segmentation(), sarcgraph.sg.SarcGraph.zdisc_tracking()

Private Methods

class sarcgraph.sg.SarcGraph(config=None, **kwargs)

Zdiscs and sarcomeres segmentation and tracking.

Parameters:

• config (Config, optional) – Configuration settings for the application. If not provided, default settings are used, and any additional settings can be passed via keyword arguments.

• **kwargs – Additional settings to override the defaults or values in the provided Config object.

print_config()

load_data(file_path=None)

Loads a video/image file.

Parameters:

file_path (str, optional) – A direct path to a video/image file to load.

Returns:

All frames in the raw format in gray scale.

Return type:

numpy.ndarray

save_data(data, file_name)

Saves a numpy array or a pandas dataframe based on the type of data.

Parameters:

• data (Union[np.ndarray, List, pd.DataFrame])

• file_name (str)

filter_frames(frames)

Convolves each image with Laplacian and Gaussian filters.

Parameters:

frames (np.ndarray) – A 2D image or a stack of 2D images.

Returns:

A stack of filtered images.

Return type:

np.ndarray

zdisc_segmentation(**kwargs)

Perform z-disc segmentation using various inputs and optional processing functions. - Pre-filtered frames can be provided by specifying ‘filtered_frames’. - Raw frames can be provided by specifying ‘raw_frames’; overrides ‘filtered_frames’. - An input file path can be provided by specifying ‘input_file’; overrides ‘raw_frames’ and ‘filtered_frames’. - Processing functions can be provided as a list of callable functions by specifying ‘processing_functions’.

Any configuration parameters can also be updated to customize the behavior of the segmentation and processing.

Parameters:

**kwargs (dict) – Arbitrary keyword arguments including: - ‘input_file’: Path to the input file to load raw frames. - ‘raw_frames’: Array-like structure with raw frames for processing. - ‘filtered_frames’: Array-like structure with pre-filtered frames for processing. - ‘processing_functions’: List of function references to apply additional processing. - Any configuration parameters to update.

Returns:

The processed z-disc information after segmentation.

Return type:

pd.DataFrame

zdisc_tracking(**kwargs)

Track detected Z-Discs in video data, similar to zdisc_segmentation, but with an additional tracking step. If ‘segmented_zdiscs’ is provided, it directly proceeds to tracking; otherwise, it first runs the z-discs segmentation process.

This function shares similar inputs to zdisc_segmentation with the addition of an optional ‘segmented_zdiscs’ DataFrame parameter.

Parameters:

**kwargs (dict, optional) – Shared keyword arguments with zdisc_segmentation, plus: - segmented_zdiscs: pd.DataFrame, optional Pre-segmented zdiscs information. If provided, it should contain at least the following columns: ‘frame’, ‘x’, ‘y’, ‘p1_x’, ‘p1_y’, ‘p2_x’, ‘p2_y’.

Returns:

Tracked zdiscs information; adds ‘particle’ column for each tracked zdisc.

Return type:

pd.DataFrame

Notes

• For details on shared parameters and segmentation process, refer to

sarcgraph.sg.SarcGraph.zdisc_segmentation().

See also

sarcgraph.sg.SarcGraph.zdisc_segmentation()

sarcomere_detection(**kwargs)

Detect sarcomeres in a video/image using dynamic keyword arguments. Sarcomere detection can be initiated with tracked zdisc information, or by first running zdisc tracking.

Parameters:

**kwargs (dict) –

Keyword arguments dynamically passed. Relevant keys are: ‘input_file’ : str

The address of an image or a video file to be loaded.

’raw_frames’np.ndarray

Raw input frames as a numpy array.

’filtered_frames’np.ndarray

Pre-filtered frames for processing.

’segmented_zdiscs’pd.DataFrame

Information of all detected zdiscs in every frame.

’tracked_zdiscs’pd.DataFrame

Information of tracked zdiscs. Must be non-empty and include the following columns: ‘frame’, ‘x’, ‘y’, ‘p1_x’, ‘p1_y’, ‘p2_x’, ‘p2_y’, ‘particle’. If provided and valid, sarcomere detection is initiated immediately.

Additional configuration parameters relevant for sarcomere detection and tracking can also be provided via kwargs.

Returns:

A tuple containing: - A DataFrame with detected sarcomeres information including

’frame’, ‘sarc_id’, ‘zdiscs’, ‘x’, ‘y’, ‘length’, ‘width’, and ‘angle’.

• A list of Graph objects representing connected sarcomeres (myofibrils).

Return type:

Tuple[pd.DataFrame, List[nx.Graph]]

Notes

• If ‘tracked_zdiscs’ is not provided, this function will internally call zdisc_tracking to generate tracked zdiscs from the provided keyword arguments. It is assumed that zdisc_tracking can handle error checking and appropriate defaults for its parameters.

• For a detailed description of the Trackpy package check: http://soft-matter.github.io/trackpy/v0.5.0/tutorial.html

• For a detailed description of the OPTICS algorithm check: https://scikit-learn.org/stable/modules/generated/sklearn.cluster.OPTICS.html

See also

sarcgraph.sg.SarcGraph.zdisc_segmentation(), sarcgraph.sg.SarcGraph.zdisc_tracking()