locan.data.locdata.LocData#

class locan.data.locdata.LocData(references=None, dataframe=None, indices=None, meta=None)[source]#

Bases: object

This class carries localization data, aggregated properties and meta data.

Data consist of individual elements being either localizations or other LocData objects. Both, localizations and Locdata objects have properties. Properties come from the original data or are added by analysis procedures.

Parameters:

references – A LocData reference or an array with references to LocData objects referring to the selected localizations in dataset.
dataframe – Dataframe with localization data.
indices – Indices for dataframe in references that makes up the data. indices refers to index label, not position.
meta – Metadata about the current dataset and its history.

Variables:

references (LocData | list[LocData] | None) – A LocData reference or an array with references to LocData objects referring to the selected localizations in dataframe.
dataframe (pandas.DataFrame) – Dataframe with localization data.
indices (slice | list[int] | None) – Indices for dataframe in references that makes up the data.
meta (locan.data.metadata_pb2.Metadata) – Metadata about the current dataset and its history.
properties (dict[str, Any]) – List of properties generated from data.
coordinate_keys (list[str]) – The available coordinate properties.
uncertainty_keys (list[str]) – The available uncertainty properties.
dimension (int) – Number of coordinates available for each localization (i.e. size of coordinate_keys).

Methods

`__init__`([references, dataframe, indices, meta])
`concat`(locdatas[, meta])	Concatenate LocData objects.
`from_chunks`(locdata[, chunks, chunk_size, ...])	Divide locdata in chunks of localization elements.
`from_collection`(locdatas[, meta])	Create new LocData object by collecting LocData objects.
`from_coordinates`([coordinates, ...])	Create new LocData object from a sequence of localization coordinates.
`from_dataframe`([dataframe, meta])	Create new LocData object from DataFrame with localization data.
`from_selection`(locdata[, indices, meta])	Create new LocData object from selected elements in another LocData.
`print_meta`()	Print Locdata.metadata.
`print_summary`()	Print a summary containing the most common metadata keys.
`projection`(coordinate_labels)	Reduce dimensions by projecting all localization coordinates onto selected coordinates.
`reduce`([reset_index])	Clean up references.
`reset`([reset_index])	Reset hulls and properties.
`update`(dataframe[, reset_index, meta])	Update the dataframe attribute in place.
`update_alpha_shape`(alpha)	Compute the alpha shape for specific alpha and update self.alpha_shape.
`update_alpha_shape_in_references`(alpha)	Compute the alpha shape for each element in locdata.references and update locdata.dataframe.
`update_convex_hulls_in_references`()	Compute the convex hull for each element in locdata.references and update locdata.dataframe.
`update_inertia_moments_in_references`()	Compute inertia_moments for each element in locdata.references and update locdata.dataframe.
`update_oriented_bounding_box_in_references`()	Compute the oriented bounding box for each element in locdata.references and update locdata.dataframe.
`update_properties_in_references`([properties])	Add properties for each element in self.references and update self.dataframe.

Attributes

`alpha_shape`	Return an object representing the alpha-shape of all localizations.
`bounding_box`	Return an object representing the axis-aligned minimal bounding box.
`centroid`	Return coordinate values of the centroid (being the property values for all coordinate labels).
`convex_hull`	Return an object representing the convex hull of all localizations.
`coordinate_keys`
`coordinates`	Return all coordinate values.
`count`	A counter for counting LocData instantiations (class attribute).
`data`	Return all elements either copied from the reference or referencing the current dataframe.
`inertia_moments`	Inertia moments are returned as computed by `locan.data.properties.inertia_moments()`.
`oriented_bounding_box`	Return an object representing the oriented minimal bounding box.
`region`	Return the region that supports all localizations.
`uncertainty_keys`

property alpha_shape: AlphaShape | None#

Return an object representing the alpha-shape of all localizations.

Type:: Hull object

property bounding_box: BoundingBox | None#

Return an object representing the axis-aligned minimal bounding box.

Type:: Hull object

property centroid: ndarray[Any, dtype[float64]]#

Return coordinate values of the centroid (being the property values for all coordinate labels).

Type:: npt.NDArray[np.float64]

classmethod concat(locdatas, meta=None)[source]#

Concatenate LocData objects.

Parameters:

locdatas (Iterable[LocData]) – Locdata objects to concatenate.
meta (UnionType[Metadata, dict[str, Any], str, bytes, PathLike[Any], BinaryIO, None]) – Metadata about the current dataset and its history.

Returns:

A new LocData instance with dataframe representing the concatenated data.

Return type:

LocData

property convex_hull: ConvexHull | None#

Return an object representing the convex hull of all localizations.

Type:: Hull object

property coordinate_keys: list[str]#

property coordinates: ndarray[Any, dtype[float64]]#

Return all coordinate values.

Type:: npt.NDArray[float]

count = 0#

A counter for counting LocData instantiations (class attribute).

Type:: int

property data: DataFrame#

Return all elements either copied from the reference or referencing the current dataframe.

Type:: pandas.DataFrame

classmethod from_chunks(locdata, chunks=None, chunk_size=None, n_chunks=None, order='successive', drop=False, meta=None)[source]#

Divide locdata in chunks of localization elements.

Parameters:

locdata (LocData) – Locdata to divide.
chunks (Optional[Sequence[tuple[int, ...]]]) – Localization chunks as defined by a list of index-tuples. One of chunks, chunk_size or n_chunks must be different from None.
chunk_size (Optional[int]) – Number of consecutive localizations to form a single chunk of data. One of chunks, chunk_size or n_chunks must be different from None.
n_chunks (Optional[int]) – Number of chunks. One of chunks, chunk_size or n_chunks must be different from None.
order (Literal['successive', 'alternating']) – The order in which to select localizations. One of ‘successive’ or ‘alternating’.
drop (bool) – If True the last chunk will be eliminated if it has fewer localizations than the other chunks.
meta (UnionType[Metadata, dict[str, Any], str, bytes, PathLike[Any], BinaryIO, None]) – Metadata about the current dataset and its history.

Returns:

A new LocData instance with references and dataframe elements representing the individual chunks.

Return type:

LocData

classmethod from_collection(locdatas, meta=None)[source]#

Create new LocData object by collecting LocData objects.

Parameters:

locdatas (Iterable[LocData]) – Locdata objects to collect.
meta (UnionType[Metadata, dict[str, Any], str, bytes, PathLike[Any], BinaryIO, None]) – Metadata about the current dataset and its history.

Returns:

A new LocData instance with dataframe representing the concatenated data.

Return type:

LocData

classmethod from_coordinates(coordinates=None, coordinate_labels=None, meta=None)[source]#

Create new LocData object from a sequence of localization coordinates.

Parameters:

coordinates (Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]], None]) – Sequence of tuples with localization coordinates with shape (n_loclizations, dimension)
coordinate_labels (Optional[Sequence[str]]) – The available coordinate properties.
meta (UnionType[Metadata, dict[str, Any], str, bytes, PathLike[Any], BinaryIO, None]) – Metadata about the current dataset and its history.

Returns:

A new LocData instance with dataframe representing the oncatenated data.

Return type:

LocData

classmethod from_dataframe(dataframe=None, meta=None)[source]#

Create new LocData object from DataFrame with localization data.

Parameters:

dataframe (Optional[DataFrame]) – Localization data.
meta (UnionType[Metadata, dict[str, Any], str, bytes, PathLike[Any], BinaryIO, None]) – Metadata about the current dataset and its history.

Returns:

A new LocData instance with dataframe representing the concatenated data.

Return type:

LocData

classmethod from_selection(locdata, indices=None, meta=None)[source]#

Create new LocData object from selected elements in another LocData.

Parameters:

locdata – Locdata object from which to select elements.
indices – Index labels for elements in locdata that make up the new data. Note that contrary to usual python slices, both the start and the stop are included (see pandas documentation). Indices refer to index value not position in list.
meta – Metadata about the current dataset and its history.

Returns:

A new LocData instance with dataframe representing the selected data.

Return type:

LocData

Note

No error is raised if indices do not exist in locdata.

property inertia_moments: InertiaMoments | None#: Inertia moments are returned as computed by locan.data.properties.inertia_moments().

property oriented_bounding_box: OrientedBoundingBox | None#

Return an object representing the oriented minimal bounding box.

Type:: Hull object

print_meta()[source]#: Print Locdata.metadata. :rtype: None

See also

locan.data.metadata_utils.metadata_to_formatted_string()

print_summary()[source]#

Print a summary containing the most common metadata keys.

Return type:: None

projection(coordinate_labels)[source]#

Reduce dimensions by projecting all localization coordinates onto selected coordinates.

Parameters:: coordinate_labels (str | list[str]) – The coordinate labels to project onto.
Return type:: LocData
Returns:: LocData

reduce(reset_index=False)[source]#

Clean up references.

This includes to update Locdata.dataframe and set LocData.references and LocData.indices to None.

Parameters:: reset_index (bool) – Flag indicating if the index is reset to integer values. If True the previous index values are discarded.
Returns:: The modified object
Return type:: Self

property region: Region | None#

Return the region that supports all localizations.

Type:: RoiRegion object

reset(reset_index=False)[source]#

Reset hulls and properties. This is needed after the dataframe attribute has been modified in place.

Note

Should be used with care because metadata is not updated accordingly. The region property is not changed. Better to just re-instantiate with LocData.from_dataframe() or use locdata.update().

Parameters:: reset_index (bool) – Flag indicating if the index is reset to integer values. If True the previous index values are discarded.
Returns:: The modified object
Return type:: Self

property uncertainty_keys: list[str]#

update(dataframe, reset_index=False, meta=None)[source]#

Update the dataframe attribute in place.

Use this function rather than setting locdata.dataframe directly in order to automatically update the attributes for dimension, hulls, properties, and metadata.

Parameters:

dataframe (Optional[DataFrame]) – Dataframe with localization data.
reset_index (bool) – Flag indicating if the index is reset to integer values. If True the previous index values are discarded.
meta (locan.data.metadata_pb2.Metadata | dict | str | bytes | os.PathLike | BinaryIO | None) – Metadata about the current dataset and its history.

Returns:

The modified object

Return type:

Self

update_alpha_shape(alpha)[source]#

Compute the alpha shape for specific alpha and update self.alpha_shape.

Parameters:: alpha (float) – Alpha parameter specifying a unique alpha complex.
Returns:: The modified object
Return type:: Self

update_alpha_shape_in_references(alpha)[source]#

Compute the alpha shape for each element in locdata.references and update locdata.dataframe.

Parameters:: alpha (float) – Alpha parameter specifying a unique alpha complex.
Returns:: The modified object
Return type:: Self

update_convex_hulls_in_references()[source]#

Compute the convex hull for each element in locdata.references and update locdata.dataframe.

Returns:: The modified object
Return type:: Self

update_inertia_moments_in_references()[source]#

Compute inertia_moments for each element in locdata.references and update locdata.dataframe.

Returns:: The modified object
Return type:: Self

update_oriented_bounding_box_in_references()[source]#

Compute the oriented bounding box for each element in locdata.references and update locdata.dataframe.

Returns:: The modified object
Return type:: Self

update_properties_in_references(properties=None)[source]#

Add properties for each element in self.references and update self.dataframe.

Parameters:: properties – new property values for each reference or function to compute property for LocData object.
Return type:: Self