analysis.compression_metrics.polymer_trace

Methods to calculate metrics from polymer trace data.

Functions

fit_pca_to_polymer_trace(polymer_trace)	Fits PCA to the polymer trace and returns the fitted object.
get_2d_polymer_trace(polymer_trace[, ...])	Get the 2D projection of the polymer trace.
get_angle_between_vectors(vec1, vec2[, signed])	Calculate the signed angle between two vectors.
get_asymmetry_of_peak(polymer_trace, **options)	Calculate the scaled distance of the projection of the peak from the end-to-end axis midpoint.
get_average_distance_from_end_to_end_axis(...)	Calculate the average perpendicular distance of polymer trace points from the end-to-end axis.
get_bending_energy_from_trace(polymer_trace, ...)	Calculate the bending energy per monomer of a polymer trace.
get_chirality(polymer_trace, **options)	Calculate the chirality of a polymer trace.
get_compression_ratio(polymer_trace, **options)	Calculate the compression ratio of a polymer trace.
get_contour_length_from_trace(polymer_trace, ...)	Calculate the sum of inter-monomer distances in the trace.
get_end_to_end_axis_distances_and_projections(...)	Calculate distances of the polymer trace points from the end-to-end axis.
get_normalized_tangent_vectors(polymer_trace)	Calculate the normalized tangent vectors for a polymer trace.
get_pca_polymer_trace_projection(polymer_trace)	Calculate the PCA projection of the polymer trace.
get_sum_bending_energy(fiber_energy, **options)	Calculate the sum of bending energy from the given fiber energy array.
get_third_component_variance(polymer_trace, ...)	Calculate the 3rd PCA component given the x,y,z positions of a fiber.
get_total_fiber_twist(polymer_trace, **options)	Calculate the total twist of a polymer trace using the normal vectors.
get_total_fiber_twist_2d(trace_2d[, signed, ...])	Calculate the total twist for 2D traces.
get_total_fiber_twist_pca(polymer_trace[, ...])	Calculate the total twist using PCA projections of the polymer trace in the 2nd and 3rd dimension.
get_total_fiber_twist_project(polymer_trace, ...)	Calculate the total twist using projections of the polymer trace in the 2nd and 3rd dimension.
get_twist_angle(polymer_trace, **options)	Calculate the twist angle of the polymer trace.

get_end_to_end_axis_distances_and_projections(polymer_trace: ndarray) → tuple[ndarray, ndarray, ndarray]

Calculate distances of the polymer trace points from the end-to-end axis.

Here, the end-to-end axis is defined as the line joining the first and last fiber point.

Parameters:

polymer_trace – Array containing the x,y,z positions of the polymer trace.

Returns:

• perp_distances – Perpendicular distances of the polymer trace from the end-to-end axis.

• scaled_projections – Length of fiber point projections along the end-to-end axis, scaled by axis length. Can be negative.

• projection_positions – Positions of points on the end-to-end axis that are closest from the respective points in the polymer trace. The distance from projection_positions to the trace points is the shortest distance from the end-to-end axis.

get_average_distance_from_end_to_end_axis(polymer_trace: ndarray, **options: dict[str, Any]) → float

Calculate the average perpendicular distance of polymer trace points from the end-to-end axis.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• **options – Additional options as key-value pairs. Unused.

Returns:

Average perpendicular distance of polymer trace points from the end-to-end axis.

get_asymmetry_of_peak(polymer_trace: ndarray, **options: dict[str, Any]) → float

Calculate the scaled distance of the projection of the peak from the end-to-end axis midpoint.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• **options – Additional options as key-value pairs. Unused.

Returns:

Scaled distance of the projection of the peak from the axis midpoint.

get_pca_polymer_trace_projection(polymer_trace: ndarray) → ndarray

Calculate the PCA projection of the polymer trace.

Parameters:

polymer_trace – Array containing the x,y,z positions of the polymer trace.

Returns:

PCA projection of the polymer trace.

get_contour_length_from_trace(polymer_trace: ndarray, **options: dict[str, Any]) → float

Calculate the sum of inter-monomer distances in the trace.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• **options – Additional options as key-value pairs. Unused.

Returns:

Sum of inter-monomer distances in the trace.

get_bending_energy_from_trace(polymer_trace: ndarray, **options: dict[str, Any]) → float

Calculate the bending energy per monomer of a polymer trace.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• **options –

  Additional options as key-value pairs:

  bending_constant: float

  Bending constant of the fiber in pN nm.

Returns:

Bending energy per monomer of the polymer trace.

get_2d_polymer_trace(polymer_trace: ndarray, compression_axis: int = 0) → ndarray

Get the 2D projection of the polymer trace.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• compression_axis – The axis along which the polymer trace is compressed.

Returns:

The 2D projection of the polymer trace.

get_normalized_tangent_vectors(polymer_trace: ndarray) → ndarray

Calculate the normalized tangent vectors for a polymer trace.

Parameters:

polymer_trace – Array containing the x,y,z positions of the polymer trace.

Returns:

The normalized tangent vectors for the polymer.

get_twist_angle(polymer_trace: ndarray, **options: dict[str, Any]) → float

Calculate the twist angle of the polymer trace.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• **options – Additional options as key-value pairs. Unused.

Returns:

Twist angle of the polymer trace in degrees.

get_chirality(polymer_trace: ndarray, **options: dict[str, Any]) → float

Calculate the chirality of a polymer trace.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• **options – Additional options as key-value pairs. Unused.

Returns:

Chirality of the polymer trace.

get_total_fiber_twist(polymer_trace: ndarray, **options: dict[str, Any]) → float

Calculate the total twist of a polymer trace using the normal vectors.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• **options –

  Additional options as key-value pairs:

  signed: bool

  Whether to return the signed or unsigned total twist.

Returns:

Total twist of the polymer trace.

get_total_fiber_twist_project(polymer_trace: ndarray, **options: dict[str, Any]) → float

Calculate the total twist using projections of the polymer trace in the 2nd and 3rd dimension.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• **options –

  Additional options as key-value pairs:

  compression_axis: int

  Axis along which the polymer trace is compressed.

  signed: bool

  Whether to return the signed or unsigned total twist.

  tolerance: float

  Tolerance for vector length.

Returns:

Sum of angles between PCA projection vectors.

get_total_fiber_twist_pca(polymer_trace: ndarray, tolerance: float = 1e-06) → float

Calculate the total twist using PCA projections of the polymer trace in the 2nd and 3rd dimension.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• tolerance – Tolerance for vector length.

Returns:

Sum of angles between PCA projection vectors.

get_angle_between_vectors(vec1: ndarray, vec2: ndarray, signed: bool = False) → float

Calculate the signed angle between two vectors.

Parameters:

• vec1 – The first vector.

• vec2 – The second vector.

• signed – True to get signed angle between vectors, False otherwise.

Returns:

Angle between vec1 and vec2.

get_total_fiber_twist_2d(trace_2d: ndarray, signed: bool = False, tolerance: float = 1e-06) → float

Calculate the total twist for 2D traces.

The 2D twist is defined as the sum of (signed) angles between consecutive vectors in the 2D projection along the compression axis.

Parameters:

• trace_2d – Array containing the x,y positions of the polymer trace.

• signed – True to calculate signed total twist, False otherwise.

• tolerance – Tolerance for vector length.

Returns:

Sum of angles between trace vectors.

fit_pca_to_polymer_trace(polymer_trace: ndarray) → PCA

Fits PCA to the polymer trace and returns the fitted object.

Parameters:

polymer_trace – Array containing the x,y,z positions of the polymer trace.

Returns:

PCA object fit to the polymer trace.

get_third_component_variance(polymer_trace: ndarray, **options: dict[str, Any]) → float

Calculate the 3rd PCA component given the x,y,z positions of a fiber.

This component reflects non-coplanarity/out-of-planeness of the fiber.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• **options – Additional options as key-value pairs. Unused.

Returns:

Variance explained by the third principal component.

get_sum_bending_energy(fiber_energy: ndarray, **options: dict[str, Any]) → float

Calculate the sum of bending energy from the given fiber energy array.

Parameters:

• fiber_energy – Array containing fiber energy values.

• **options – Additional options as key-value pairs. Unused.

Returns:

Sum of bending energy.

get_compression_ratio(polymer_trace: ndarray, **options: dict[str, Any]) → float

Calculate the compression ratio of a polymer trace.

The compression ratio is defined as 1 minus the ratio of the length of the end-to-end vector to the contour length of the polymer trace.

Parameters:

• polymer_trace – Array containing the x,y,z positions of the polymer trace.

• **options – Additional options as key-value pairs. Unused.

Returns:

The compression ratio of the polymer trace.