pana

cryocat.analysis.pana.analyze_rotations(tomogram, template, template_mask, input_angles, wedge_mask_tomo=None, wedge_mask_tmpl=None, output_file=None, cc_radius=3, angular_offset=None, starting_angle=None, c_symmetry=1, angles_order='zxz')

Perform template matching between a tomogram and a reference template.

This function rotates a reference template through a set of input Euler angles, computes the Fast Local Cross-Correlation Function (FLCF) between each rotated template and the target tomogram, and collects statistics for each rotation. Optionally, wedge masks can be applied to account for missing wedge artifacts, and a spherical correlation mask can be applied for localized measurements.

Parameters:

tomogramstr or numpy.ndarray

File path (.mrc or .em) to or a numpy array of a tomogram of interest.

templatestr or numpy.ndarray

File path to or an array of the reference template map.

template_maskstr or numpy.ndarray

File path to or an array of the binary mask for the template.

input_anglesstr or numpy.ndarray

File path to an angle list or a numpy array of euler angles.

wedge_mask_tomostr or numpy.ndarray, optional

File path to or a numpy array of the wedge mask for the tomogram.

wedge_mask_tmplstr or numpy.ndarray, optional

File path to or an array of the wedge mask for the template.

output_filestr, optional

Base path for saving output CSV and EM maps. If None, results are not written to disk.

cc_radiusint, optional

Radius (in voxels) of the spherical mask applied to compute masked cross-correlation. Default is 3.

angular_offsetfloat or array-like of shape (3,), optional

Euler angles (degrees) to offset all input angles before matching.

starting_anglefloat or array-like of shape (3,), optional

Euler angles (degrees) representing the reference orientation from which angular distances will be calculated. Default is (0, 0, 0).

c_symmetryint, optional

C symmetry of the structure. Default is 1 (no symmetry).

angles_order{“zxz”, …}, optional

Euler angle convention used for rotations. Default is “zxz”.

Returns:

res_tablepandas.DataFrame

Table containing per-rotation statistics, including: - ang_dist: Angular distance from starting_angle (degrees) - cone_dist: Cone angle difference (degrees) - inplane_dist: In-plane rotation difference (degrees) - common_voxels: Overlap between mask and rotated mask - ccc: Maximum cross-correlation coefficient - ccc_masked: Maximum masked CCC within cc_radius - z_score: Maximum z-score across the full cc map - z_score_masked: Maximum z-score within the spherical mask

final_ccc_mapndarray

3D array of the maximum CCC values observed across all rotations.

final_angles_mapndarray

3D array of rotation indices (of angle rotation list) corresponding to the highest CCC at each voxel.

final_ccc_map_maskedndarray

Masked CCC map showing only the central area of final_ccc_map.

Notes

• If the template and tomogram sizes differ, the smaller map is padded to match.

• The function keeps track of the highest CCC per voxel across all rotations.

cryocat.analysis.pana.check_existing_tight_mask_values(template_list, indices, parent_folder_path, angle_list_path, angles_order='zxz')

Check and populate “Tight mask overlap” values for given rows in template list.

This function verifies whether specified rows have “Tight mask overlap” values. If the values are missing, it attempts to find an analyzed row (with the same tight mask and degrees) from which the overlap values can be copied. If no such data is found, the function computes the overlap and saves it back to the output csvs.

Parameters:

template_liststr

Path to the CSV template list file.

indiceslist of int

List of row indices in template_list to check.

parent_folder_pathstr

Base directory where structure folders are located.

angle_list_pathstr

Path to the directory containing rotation angle list files.

angles_orderstr, optional

Rotation order to interpret the Euler angles when computing overlaps. Default is “zxz”.

cryocat.analysis.pana.compute_center_peak_stats_and_profiles(template_list, indices, parent_folder_path)

Compute statistics and line profiles for the cc peaks in a score map.

For each specified template index, this function: 1. Identifies the peak location and value.

2. Saves the 1D line profiles through the peak along x, y, and z axes. Saved as

   ‘<output_base>_peak_line_profiles.csv’ in the output folder.

3. Computes the drop in score from the peak to its immediate neighbors along

   each axis.

4. Calculates mean, median, and variance of scores in small areas where the peaks

   are centered (spherical of radius from 1 to 5 px).

5. Updates the template list CSV file with the computed statistics:

   • “Peak value”

   • “Drop x”, “Drop y”, “Drop z”

   • “Peak x”, “Peak y”, “Peak z”

   • “Mean r”, “Median r”, “Var r” for r = 1..5

Parameters:

template_liststr

Path to the CSV template list file.

indiceslist of int

List of row indices in template_list to process.

parent_folder_pathstr

Base directory containing structure folders.

cryocat.analysis.pana.compute_dist_maps_voxels(template_list, indices, parent_folder_path, morph_footprint=(2, 2, 2))

Compute a few morphology related measurements for areas with highest cc score.

For each specified rows in the template list, this function processes angular distance maps to find patches (i.e. connected components) within the search angle and have highest cross correlation score. Morphological properties computed include voxel count, solidity, and bounding box dimensions. The results are stored back into the template list CSV file.

Parameters:

template_liststr

Path to the CSV template list file.

indiceslist of int

Row indices in template_list to process.

parent_folder_pathstr

Base directory where structure folders are located.

morph_footprinttuple of int, optional

Size of the structuring element used for binary opening during morphological processing of labeled regions. Default is (2, 2, 2).

Notes

For “dist_all”, the threshold is set to ‘2.0 * degrees’; for the other maps,

the threshold is ‘degrees’.

• degrees here is the search increment angle used.

• the max angular distance (i.e. “dist_all”) given angular combinations within the “degrees” value is just slightly above 2*degrees.

• cc score decreases with increasing angular distance (given no symmetry), therefore only looking at places where the dist is no larger than search angles

Labeled connected components are analyzed to extract:

• Voxel count (VC) of components with highest cc score

• Solidity

• Morphologically opened voxel count (VCO)

• Bounding box dimensions (O x, O y, O z)

Labeled masks and morphologically opened masks are saved as .em files with _label and _label_open suffixes, respectively.

cryocat.analysis.pana.compute_peak_shapes(template_list, indices, parent_folder_path)

Compute and record peak shape statistics from scores maps for selected structures.

This function processes score maps for the given structures, evaluates the peak shapes using multiple thresholding methods, stores the results in the template list, and generates a visualization of the peaks and thresholds.

Parameters:

template_liststr

Path to the CSV file containing metadata for all templates and analyses.

indiceslist of int

List of row indices in the template list to process.

parent_folder_pathstr

Path to the root directory containing structure data and score maps.

Notes

• Only rows marked as ‘Done == True’ in the template list are processed.

• Structures named ‘“membrane”’ are skipped.

• peak shapes are measured using tmana.evaluate_scores_map with three thresholding methods: triangle, Gaussian, and hard threshold.

• The three principal dimensions (x, y, z) of each peak shape are stored in the template list under the columns: ‘TP x/y/z’, ‘GP x/y/z’, and ‘HP x/y/z’ (triangle, Gaussian, hard).

• The maximum peak value is stored under ‘Peak value’.

• A PNG plot visualizing the scores and peaks is saved in the corresponding output folder under the name ‘peaks.png’.

cryocat.analysis.pana.compute_sharp_mask_overlap(template_list, indices, angle_list_path, parent_folder_path, angles_order='zxz')

Compute the overlap between the original tight mask and rotated versions of it.

For each template specified by its index in the template list, this function loads the corresponding tight mask and set of rotation angles, rotates the mask accordingly, computes the overlap (intersection) with the original mask, and writes the results to a CSV file.

Parameters:

template_liststr

Path to the CSV template list file.

indiceslist of int

List of row indices in the CSV to process.

angle_list_pathstr

Path to the directory containing angle list files used for rotation.

parent_folder_pathstr

Base directory where folders for all structures are.

angles_orderstr, optional

The rotation order used to interpret the Euler angles (default is “zxz”).

cryocat.analysis.pana.correct_bbox(template_list, indices)

Increment specific bounding box-related columns by 1 for completed entries.

This function reads a CSV file containing template metadata and, for the specified row indices where the “Done” column is True, increments the values in several bounding box-related columns by 1 along each spatial dimension (“x”, “y”, “z”). The updated DataFrame is saved back to the same CSV file after all corrections.

Parameters:

template_liststr

Path to the CSV file containing metadata for all templates and analyses. The file must include the following columns: - “Dim x”, “Dim y”, “Dim z” - “O dist_all x”, “O dist_all y”, “O dist_all z” - “O dist_normals x”, “O dist_normals y”, “O dist_normals z” - “O dist_inplane x”, “O dist_inplane y”, “O dist_inplane z”

indicesiterable of int

List or array of row indices to process within the CSV file.

cryocat.analysis.pana.create_em_path(folder_path, structure_name, em_filename)

Constructs the full path to an .em file within a specific structure folder.

Parameters:

folder_pathstr

The base directory path.

structure_namestr

The name of the structure, used to create a subdirectory under folder_path.

em_filenamestr

The name of the .em file, without the file extension.

Returns:

em_pathstr

The full path to the .em file, including the .em extension.

cryocat.analysis.pana.create_output_base_name(tmpl_index)

Generates the base name for peak analysis output folders / files.

Includes the index of the row analyzed from the template list csv.

Parameters:

tmpl_indexint

The index of the row analyzed in the templatel list csv.

Returns:

output_basestr

Output file based name. It should be “id_<tmpl_index>”.

cryocat.analysis.pana.create_output_folder_name(tmpl_index)

Generates the name of the folder (not the full path) where the peak analysis results will be stored, given the index of the row from the template list csv.

Parameters:

tmpl_indexint

The index of the row analyzed in the templatel list csv.

Returns:

str

The name of result folder. It should be ‘id_<tmpl_index>_results’.

cryocat.analysis.pana.create_output_folder_path(folder_path, structure_name, folder_spec)

Constructs the full path of the output folder.

Parameters:

folder_pathstr

The path to the peak analysis base folder.

structure_namestr

The name of the structure.

folder_specint or else

Information about the output folder. If int (should be an index from the template list csv), the output folder name will be ‘id_<folder_spec>_results’. If not int, the output folder name will be ‘<folder_spec>’.

Returns:

output_pathstr

The full path to the output folder. Should be either ‘id_<folder_spec>_results’ or ‘<folder_spec>’.

cryocat.analysis.pana.create_structure_path(folder_path, structure_name)

Put together a path for the structure folder by combining a base folder path and the name of the structure.

Parameters:

folder_pathstr

The base directory path where the structure folder should be created. It should include a trailing slash if needed, otherwise the function will not insert a separator between folder_path and structure_name.

structure_namestr

The name of the structure of interest.

Returns:

structure_folderstr

Full path to the structure folder.

cryocat.analysis.pana.create_subtomo_name(structure_name, motl_name, tomo_id, boxsize)

Generate a standardized filename for a subtomogram. The generated file name is subtomo_<structure_name>_m<motl_name>_t<tomo_id>_s<boxsize>.em

Parameters:

structure_namestr

Name of the structure.

motl_namestr

Name of the motive list file containing particle information.

tomo_idstr

Tomogram id/number from which the subtomogram is extracted.

boxsizeint

Size of the subtomogram box in voxels.

Returns:

subtomo_namestr

The constructed filename for the subtomogram.

cryocat.analysis.pana.create_subtomograms_for_tm(template_list, parent_folder_path)

Generates subtomograms with highest ccc score from tomograms for each entry in template list csv.

Updates the template list with orientation and status info, and saves the updated list.

Parameters:

template_liststr

Path to the template list file with motl path info.

parent_folder_pathstr

Path to the base directory for peak analysis.

Returns:

temp_dfpandas.DataFrame

The updated DataFrame containing subtomogram metadata, including creation status, orientation angles, and filenames.

cryocat.analysis.pana.create_summary_pdf(template_list, indices, parent_folder_path)

Generate a detailed summary PDF for a set of peak analysis results.

This function reads metadata from a CSV file (template_list), retrieves volumetric map data, analysis results, and visualization slices for the specified indices, and compiles them into a structured multi-panel PDF report. Each report includes:

• Template and processing parameters (symmetry, wedge application, voxel size, etc.)

• Peak detection information (location, value, line profiles)

• Distance map statistics and solidity/volume coverage measures

• Scatter plots, histograms, and gradual rotation CCC analysis (if available)

• Cross-sectional heatmaps of masks, score maps, and angular distance maps

The output is saved as ‘id_<index>_summary.pdf’ in the corresponding output folder for each index.

Parameters:

template_liststr

Path to the CSV file containing metadata for all templates and analyses.

indiceslist of int

List of row indices from template_list to process.

parent_folder_pathstr

Base directory containing the structure folders, output folders, and map files.

Notes

• If the “Done” column is False for a given index, that entry is skipped.

• Gradual rotation histogram and CCC analysis are included if the corresponding ‘_gradual_angles_histograms.csv’ and ‘_gradual_angles_analysis.csv’ are found.

cryocat.analysis.pana.create_tomo_name(folder_path, tomo)

Generate a full file path for a tomogram with an .mrc extension.

Parameters:

folder_pathstr

Path to the directory containing the tomogram.

tomostr

Base name of the tomogram file (without extension).

Returns:

tomo_namestr

Full path to the tomogram file with .mrc extension.

cryocat.analysis.pana.create_wedge_names(wedge_path, tomo_number, boxsize, binning, filter=None)

Generate filenames for tomogram and template wedge masks with filtering info.

If no filter size is provided, it defaults to half of the box size.

Parameters:

wedge_pathstr

Directory path where the wedge files will be stored.

tomo_numberint

Number of the tomogram.

boxsizeint

Size of the subtomogram box in voxels.

binningint

Binning level applied to the tomogram.

filterint, optional, default=boxsize // 2

Size of the filter applied during processing.

Returns:

tomo_wedgestr

Filename for the filtered tomogram wedge mask.

tmpl_wedgestr

Filename for the filtered template wedge mask.

cryocat.analysis.pana.cut_the_best_subtomo(tomogram, motl_path, subtomo_shape, output_file)

Extract the highest-scoring subtomogram from a tomogram.

Loads a tomogram and its corresponding particle motive list, identifies the entry with the highest score, and extracts the aligned subtomogram around that position. Optionally writes the result to a file.

Parameters:

tomogramstr

Path to the tomogram file to extract from.

motl_pathstr

Path to the motive list with extracted particle information (.csv or compatible format).

subtomo_shapetuple of int

Shape of the subtomogram to extract, in (x, y, z) order.

output_filestr or None

Path to save the extracted subtomogram. If None, the file is not saved.

Returns:

subvolume_shnumpy.ndarray

The extracted and shifted subtomogram.

anglesnumpy.ndarray

The Euler angles (phi, theta, psi) rotation associated with the best subtomogram.

cryocat.analysis.pana.generate_ctf(wl, slice_idx, slice_weight, binning)

Generate a CTF filter for a weighted volume that is subset of a full volume.

This function computes defocus and phase shift-specific CTF filters for a template.

It does so by: 1. computing the frequency array of a tomogram;

2. interpolating the CTF based on the full sized frequency array and defocus / pshift values;

3. fourier cropping the full size CTF values to fit the size of a template, to keep only the lower frequencies;

4. applying the CTF values to the given slice_weight array.

Parameters:

wlpandas.DataFrame

Wedge list dataframe containing metadata and microscope parameters for one tomogram.

slice_idxarray-like of int

Indices of the frequency components (aka. points in fourier space) to which the CTF filter should be applied.

slice_weightndarray

A 3D array representing the frequency domain weighting (missing wedge + bandpass) of each tilt. The shape is assumed to be (depth, height, width) or (zyx).

binningint or float

The binning factor of the tomogram. Used to scale the pixel size.

Returns:

ctf_filtndarray

The computed CTF filter applied on top of the weighted filter input (i.e. bandpass and missing wedge), in fourier space. Same shape as slice_weight.

Notes

• If pshift is not provided in wl, it defaults to zeros.

cryocat.analysis.pana.generate_exposure(wedgelist, slice_idx, slice_weight, binning)

Generate an exposure-based filter to account for frequency-dependent signal attenuation due to electron dose in cryo-electron tomography.

This function models the decay of signal at different spatial frequencies based on cumulative electron exposure per tilt. The filter is computed per tilt exposure using an empirical decay function and returned as a 3D volume matching the input slice weights.

Parameters:

wedgelistpandas.DataFrame

Metadata table containing at least the following columns: - “exposure”: float, cumulative electron exposure per tilt (in mathrm{e^- / AA^2}) - “pixelsize”: float, unbinned pixel size (in \(\mathrm{\AA}\))

slice_idxlist of numpy.ndarray

Indices of the frequency components (aka. points in fourier space) to which the exposure filter should be applied.

slice_weightnumpy.ndarray

A 3D array representing the frequency domain weighting (missing wedge + bandpass) of each tilt. The shape is assumed to be (depth, height, width) or (zyx).

binningint

The binning factor of the tomogram. Used to scale the pixel size.

Returns:

exp_filtnumpy.ndarray

3D exposure filter of the same shape as slice_weight. Each voxel contains a multiplicative factor representing attenuation based on frequency and dose.

Notes

The attenuation function follows the empirical dose-dependent decay model:

\[\exp\Bigg(-\frac{\mathrm{exposure}}{2 \, (a \, f^b + c)}\Bigg)\]

where f is the spatial frequency in \(\mathrm{\AA}^{-1}\) and a, b, c are empirical constants. See this paper for more info.

cryocat.analysis.pana.generate_wedge_masks(template_size, tile_size, wedgelist, tomo_number, binning=1, low_pass_filter=None, high_pass_filter=None, ctf_weighting=False, exposure_weighting=False, output_template=None, output_tile=None)

Generates wedge masks for both template and subtomo tile volumes.

This function computes frequency-space masks that account for the missing wedge artifacts based on a provided wedge list. Optionally applies low-pass and high-pass filters to the masks. CTF and exposure filtering may also be applied on top of the wedge masks.

Parameters:

template_sizeint or array-like

The size of the template. Could be a single int (assume cubic shape) or a tuple, list or numpy.ndarray of length of 3.

tile_sizetuple of int

The size of the subtomo or tile. Could be a single int (assume cubic shape) or a tuple, list or numpy.ndarray of length of 3.

wedgeliststr or pandas.DataFrame

Path to the STOPGAP wedge list file (.star) or a preloaded DataFrame. The list should contain entries specifying the missing wedge parameters per tomogram.

tomo_numberint

The tomogram number to select from the wedge list.

binningint, optional

Binning factor used in tomogram. Default is 1 (no binning).

low_pass_filterint, optional

If provided, applies a low-pass filter in Fourier space with the given cutoff in Fourier pixels.

high_pass_filterint, optional

If provided, applies a high-pass filter in Fourier space with the given cutoff in Fourier pixels.

ctf_weightingbool, optional

If True, applies CTF weighting. Default is False.

exposure_weightingbool, optional

If True, applies exposure weighting. Default is False.

output_templatestr, optional

Path to save the resulting template wedge mask. Can use create_wedge_names to generate this path.

output_tilestr, optional

Path to save the resulting tile wedge mask. Can use create_wedge_names to generate this path.

Returns:

filter_template_tndarray

The wedge-weighted and filtered Fourier mask for the template volume.

filter_tile_tndarray

The wedge-weighted and filtered Fourier mask for the tile volume.

cryocat.analysis.pana.generate_wedgemask_slices_template(wedgelist, template_filter)

Generate missing wedge masks and weights for a template in Fourier space.

This function simulates the sampling of a 3D template volume in Fourier space, given a set of tilt angles. It computes:

• Which voxels are covered based on tilt range.

• A normalized weight to compensate for unequal coverage of tilts, due to rotation interpolation artifacts (some voxels may be covered by >1 tilt).

• A binary template mask that shows active voxels after bandpass & missing wedge filters.

Parameters:

wedgelistpandas.DataFrame

A table with a column tilt_angle (in degrees) representing the tilt angles of the acquisition. This should only contain info for one tomogram.

template_filterndarray

A 3D frequency-filtered template in numpy array. The dimensions have to be equal, aka. a cube shape.

Returns:

active_slices_idxlist of tuple of ndarrays

A list of index tuples ‘[(zs, ys, xs)]’ for each tilt, indicating where the projection intersects the bandpassed Fourier space. Each value inside the tuple is an array indicating where all active points is on each dimension. len(active_slices_idx) = len(wedgelist).

wedge_slices_weightsndarray

A 3D array of the same shape as template_filter, containing weights that normalize the contribution of each voxel based on how frequently it was sampled. Voxels that are not sampled receive a weight of 0.

wedge_slicesndarray

A binary 3D mask of the same shape as template_filter with 1s at all voxels that were sampled by at least one tilt.

Notes

• Since the wedge mask is manually built and assume zero frequency component in center of array, shifting of the mask from center of array to top-left corner is needed for later operations in fourier space.

• Rotating the ray at specified degrees (not a continuous range) to match the real tilting scheme better (star-shaped).

cryocat.analysis.pana.generate_wedgemask_slices_tile(wedgelist, tile_filter)

Generate missing wedge masks and weights for a subtomo or a tile from tomogram in Fourier space.

This function simulates the sampling of a 3D tile volume in Fourier space, given a set of tilt angles. It computes:

• Which voxels are covered based on tilt range.

• A normalized weight to compensate for unequal coverage of tilts, due to rotation interpolation artifacts (some voxels may be covered by >1 tilt).

• A binary tile mask that shows active voxels after bandpass & missing wedge filters.

Parameters:

wedgelistpandas.DataFrame

A table with a column tilt_angle (in degrees) representing the tilt angles of the acquisition. This should only contain info for one tomogram.

tile_filterndarray

A 3D frequency-filtered tile in numpy array. The dimensions have to be equal, aka. a cube shape. The array itself is not used for its values, only its shape.

Returns:

wedge_slicesndarray

A binary 3D mask of the same shape as tile_filter with 1s at all voxels that were sampled by at least one tilt.

cryocat.analysis.pana.get_indices(template_list, conditions, sort_by=None)

Get the indices of a filtered and optionally sorted template list csv file.

Parameters:

template_liststr

Path to the template list csv file.

conditionsdict

Dictionary where keys are template list column names and values are the values to filter by. Only rows matching all conditions are retained.

sort_bystr, optional

Column name to sort the filtered DataFrame by. If None, no sorting is applied.

Returns:

pandas.Index

Index of the filtered (and optionally sorted) rows in the template list DataFrame.

cryocat.analysis.pana.get_mask_stats(template_list, indices, parent_folder_path)

Compute and update mask statistics for specified rows in a template list.

Loads info about soft and tight (sharp) masks to computes volume-related statistics, including nonzero voxel counts, mask element bounding box dimensions, and solidity. Updates the CSV with these values: specifically:

• ‘Voxels’: Number of nonzero voxels in the soft mask.

• ‘Voxels TM’: Number of nonzero voxels in the tight mask.

• ‘Dim x’, ‘Dim y’, ‘Dim z’: Dimensions of the bounding box enclosing the tight mask.

• ‘Solidity’: Solidity metric of the tight mask (volume / convex hull volume).

Parameters:

template_liststr

Path to the CSV template list file.

indiceslist of int

List of row indices in the CSV to process.

parent_folder_pathstr

Base directory where folders for all structures are.

cryocat.analysis.pana.get_shape_stats(template_list, indices, shape_type, parent_folder_path)

Compute and save shape statistics for specific shapes in a template list.

This function reads path from a CSV file, loads corresponding tight masks, labels connected components, computes geometric and morphological properties for each labeled region, and saves the results to CSV files.

Parameters:

template_liststr or path-like

Path to the CSV file containing metadata for all templates and analyses.

indicesarray_like of int

Rows in template_list for which statistics should be computed.

shape_typestr

A descriptive label for the type of shape used for analysis. This string is appended to the output CSV filename.

parent_folder_pathstr or path-like

Path to the root directory containing the structure and mask files.

Notes

The following region properties are computed for each labeled region:

• ‘label’ : integer label ID

• ‘area’ : voxel count

• ‘area_bbox’ : bounding box volume

• ‘area_convex’ : convex hull volume

• ‘equivalent_diameter_area’ : diameter of a sphere with same volume

• ‘euler_number’ : topological Euler characteristic

• ‘feret_diameter_max’ : maximum caliper distance

• ‘inertia_tensor’ : 3×3 inertia tensor matrix

• ‘solidity’ : ratio of area to convex hull area

Output files are named in the format:

‘<structure_path>/<output_folder>/id_<index>_shape_stats_<shape_type>.csv’

cryocat.analysis.pana.get_sharp_mask_stats(input_mask)

Get the boxsize of the nonzero element inside the sharp mask and the total volume of the nonzero element.

Parameters:

input_maskstr or numpy.ndarray

Input mask specified either by its path or already loaded as 3D numpy.ndarray. The nonzero element in this mask has sharp edges, i.e.: the values inside the mask are either 1 or 0.

Returns:

n_voxelsint

The number of voxels of where the input_mask is not zero.

mask_bbtuple of int

The bounding box size in (x, y, z) of the nonzero element.

cryocat.analysis.pana.get_soft_mask_stats(input_mask)

Get the boxsize of the element (> 0.5) inside the soft mask and the total volume of the nonzero element.

Parameters:

input_maskstr or numpy.ndarray

Input mask specified either by its path or already loaded as 3D numpy.ndarray. The nonzero element in this mask has soft edges, i.e.: the values inside the mask are between 0 and 1.

Returns:

n_voxelsint

The number of voxels of where the input_mask is bigger than 0.5.

mask_bbtuple of int

The bounding box size in (x, y, z) of the element that has values bigger than 0.5.

cryocat.analysis.pana.plot_scores_and_peaks(peak_files, plot_title=None, output_file=None)

Plot heatmaps of peak cross-sections for multiple peak-related data arrays.

This function visualizes peak data from a list of files or arrays by generating heatmaps for three orthogonal 2D slices (X, Y, Z) centered at the main peak. All peaks are normalized to the same value range based on the first peak file.

Parameters:

peak_fileslist of array_like or list of str

List of 3D arrays or file paths containing peak-related data. Each entry is processed using tmana.create_starting_parameters_2D to extract peak-centered slices.

plot_titlestr, optional

Title for the entire figure. If None, no title is added.

output_filestr, optional

Path to save the figure as an image file. If None, the figure is not saved.

cryocat.analysis.pana.recompute_dist_maps(template_list, indices, parent_folder_path, angle_list_path)

Recompute angular distance maps for specified entries in a template list.

This function reads a CSV file containing template metadata, and for each specified index where the “Done” flag is True, it recalculates angular distance maps using corresponding angle files. The updated maps are written to disk.

Parameters:

template_liststr

Path to the CSV file containing metadata for all templates and analyses.

indicesiterable of int

List or array of row indices in the CSV file to process.

parent_folder_pathstr

Base path to the parent folder where structure and output folders are.

angle_list_pathstr

Base path to the directory containing angle list files referenced in the CSV.

cryocat.analysis.pana.rename_folders(template_list, indices, parent_folder_path)

Rename output folders for specified dataset entries and update metadata.

This function updates the output folder names for given indices in a template list CSV file. Each folder is renamed to a new standardized name generated from its index, and the corresponding entry in the CSV file is updated to reflect the change.

Parameters:

template_liststr

Path to the CSV file containing metadata for all templates and analyses.

indicesiterable of int

List or array of row indices in template_list to process.

parent_folder_pathstr

Base directory containing all structure folders.

Notes

• Uses ‘create_structure_path’ to locate the parent folder for each structure.

• Uses ‘create_output_folder_name’ to generate a new standardized folder name based on the index.

cryocat.analysis.pana.rename_scores_angles(template_list, indices, parent_folder_path)

Rename score and angle-related output files for specified dataset entries.

This function updates the filenames of score and angular analysis files for given indices in a template list CSV file. The files are renamed to a new standardized base name derived from the entry’s index. File renaming is done in the filesystem without altering the CSV metadata.

Parameters:

template_liststr

Path to the CSV file containing metadata for all templates and analyses.

indicesiterable of int

List or array of row indices in template_list to process.

parent_folder_pathstr

Base directory containing all structure folders.

Notes

• The base name pattern of the old files depends on the value of the ‘Compare’ column:

  • "tmpl" → "tt_" + Map type

  • "subtomo" → "ts_t<tomogram_number>_" + Map type

  • other → "td_<Compare>_" + Map type

• The following files are renamed with new base name for each entry:

  • ‘<base>.csv’

  • ‘<base>_scores.em’

  • ‘<base>_angles.em’

  • ‘<base>_angles_dist_all.em’

  • ‘<base>_angles_dist_normals.em’

  • ‘<base>_angles_dist_inplane.em’

cryocat.analysis.pana.rotate_image(image, alpha, fill_mode='constant', fill_value=0.0)

Rotate an ndarray image by a specified angle.

Uses ‘skimage.transform.rotate’ to rotate the input image without resizing the output. Pixels outside the boundaries of the input are filled according to the specified mode and fill value.

Some descriptions are from scikit-image page.

Parameters:

imagendarray

nD NumPy array representing the image to rotate.

alphafloat

Angle of rotation in degrees. Positive values rotate counterclockwise.

fill_mode{‘constant’, ‘edge’, ‘symmetric’, ‘reflect’, ‘wrap’}, optional

Points outside the boundaries of the input are filled according to the given mode. Default is ‘constant’.

fill_valuefloat, optional

Value used to fill points outside the boundaries when fill_mode is ‘constant’. Default is 0.0.

Returns:

ndarray

Rotated image as a NumPy array with the same shape as the input.

cryocat.analysis.pana.run_analysis(template_list, indices, angle_list_path, wedge_path, parent_folder_path, cc_radius_tol=10)

Run peak analysis based on a list with parameters and save results.

This function iterates over the provided indices of a template list CSV, loads the corresponding tomogram, template, and mask files, and then calls analyze_rotations to perform rotation-based cross-correlation analysis. The results (score maps, angle maps, CSV stats) are written to an output folder for each index. It also generates angular distance maps for the resulting angle maps. The function updates the CSV in-place to record progress, ensuring partial results are saved in case of interruption.

Parameters:

template_liststr or path-like

Path to a CSV file containing info about peak analysis to perform. The CSV must include at least the following columns: - Structure - Template - Mask - Angles - Compare (compare method; “tmpl”: tmpl vs. tmpl, “subtomo”: subtomo vs. sutomo, or else) - Tomo map (i.e. subtomo) - Tomogram - Apply wedge (bool) - Boxsize - Binning - Phi, Theta, Psi (starting Euler angles in degrees) - Apply angular offset (bool) - Degrees (search angle increment / offset magnitude) - Symmetry (C symmetry)

indicessequence of int

List or array of row indices (0-based) in template_list to process.

angle_list_pathstr or path-like

Base directory path where the angle list files are stored. The angle file name from the CSV’s “Angles” column is appended to this path.

wedge_pathstr or path-like

Base directory containing wedge mask files. Used only if “Apply wedge” is set for the current row.

parent_folder_pathstr or path-like

Root folder containing all structure subfolders, templates, tomograms, and masks referenced in template_list.

cc_radius_tolfloat, optional

Radius (in voxels) of the spherical mask used for computing local cross-correlation scores in analyze_rotations. Default is 10.

Notes

• Writes output files for each processed index:

  • ‘<output_base>_scores.em’ (cross-correlation coefficient map)

  • ‘<output_base>_angles.em’ (best-angle index map)

  • CSV file with per-angle statistics

• Writes angular distance maps via ‘tmana.create_angular_distance_maps’

• Updates template_list CSV in place:

  • “Output folder” set for each processed index

  • “Done” flag set to True

• Creates any necessary output directories.

• For rows with "Compare" == "tmpl", the tomogram is the same as the template.

• For "Compare" == "subtomo", a tomogram is loaded from the specified file, and wedge masks may be applied if "Apply wedge" is true.

• starting_angle is read directly from "Phi", "Theta", "Psi" columns.

• If "Apply angular offset" is true, angular_offset is set to half of Degrees for all three Euler components; otherwise it is [0, 0, 0].

• Symmetry (c_symmetry) is passed to analyze_rotations to account for cyclic symmetry in angular distance calculations.

cryocat.analysis.pana.run_angle_analysis(template_list, indices, wedge_path, parent_folder_path, angular_range=359, write_output=False, cc_radius_tol=10)

Perform a gradual rotation angular peak analysis.

This function systematically evaluates the effect of varying Euler angles (3 kinds of rotations: full angular distance, cone rotation, and in-plane rotation) on the cross-correlation between a tomogram (or template) and a reference template. It iterates through a specified angular range 1 deg by 1 deg, computes correlation metrics, and optionally saves detailed analysis results and histograms.

Parameters:

template_liststr

Path to a CSV file containing metadata and file paths for templates, tomograms, masks, and analysis parameters.

indiceslist of int

List of row indices in template_list to process.

wedge_pathstr

Directory path containing wedge mask files.

parent_folder_pathstr

Root directory containing structure and template data.

angular_rangeint, optional

Number of degrees to test in the rotation range. Default is 359, meaning all integer angles from 0 to 358 will be analyzed. 359 makes a full circle.

write_outputbool, optional

If True, saves the computed angular analysis results and histograms as CSV files in the corresponding output directory. Default is False.

cc_radius_tolint, optional

Radius (in voxels) of the spherical mask applied to the cross-correlation map when evaluating local correlation. Default is 10.

Notes

• A histogram of CCC values across the angular range is also computed for each rotation type.

• Output files are:

  • ‘<output_base>_gradual_angles_analysis.csv’: Table containing detailed rotation metrics for all tested angles and rotation types

  • ‘<output_base>_gradual_angles_histograms.csv’: Histograms of CCC values for each rotation type