cytopy.data.geometry¶

For the purpose of cytometry analysis we often think of a population of cells as having a particular phenotype that can be identified by sub-setting cells in one or two dimensional space. This results in geometric objects that define a population. This module houses the functionality around those geometric objects.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Classes:

`PolygonGeom`(args, *kwargs)	Polygon shape.
`PopulationGeometry`(args, *kwargs)	Geometric shape generated by non-threshold generating Gate
`ThresholdGeom`(args, *kwargs)	Threshold shape.

Functions:

`create_convex_hull`(x_values, y_values)	Given the x and y coordinates of a cloud of data points, generate a convex hull, returning the x and y coordinates of its vertices.
`create_polygon`(x, y)	Given a list of x coordinated and a list of y coordinates, generate a shapely Polygon
`ellipse_to_polygon`(centroid, width, height, …)	Convert an ellipse to a shapely Polygon object.
`inside_ellipse`(data, center, width, height, …)	Return mask of two dimensional matrix specifying if a data point (row) falls within an ellipse
`inside_polygon`(df, x, y, poly[, njobs])	Return rows in dataframe who’s values for x and y are contained in some polygon coordinate shape
`polygon_overlap`(poly1, poly2[, threshold])	Compare the area of two polygons and give the fraction overlap.
`probablistic_ellipse`(covariances, conf)	Given the covariance matrix of a mixture component, calculate a elliptical shape that represents a probabilistic confidence interval.

class cytopy.data.geometry.PolygonGeom(*args, **kwargs)¶

Polygon shape. Inherits from PopulationGeometry.

x_values¶

X-axis coordinates

Type: list

y_values¶

Y-axis coordinates

Type: list

Methods:

transform_to_linear()

x,y coordinates are transformed to their equivalent value in linear space according to the transform defined.

transform_to_linear()¶

x,y coordinates are transformed to their equivalent value in linear space according to the transform defined. If transform is None, coordinates are returned as saved.

Returns
Return type: numpy.ndarray, numpy.ndarray

class cytopy.data.geometry.PopulationGeometry(*args, **kwargs)¶

Geometric shape generated by non-threshold generating Gate

x¶

Name of the X-dimension e.g. CD3, FSC-A etc

Type: str

y¶

Name of the Y-dimension e.g. CD3, FSC-A etc

Type: str

transform_x¶

Transformation method applied to the x-axis

Type: str

transform_y¶

Transformation method applied to the y-axis

Type: str

transform_x_kwargs¶

Transformation keyword arguments for transform method applied to the x-axis

Type: dict

transform_y_kwargs¶

Transformation keyword arguments for transform method applied to the y-axis

Type: str

class cytopy.data.geometry.ThresholdGeom(*args, **kwargs)¶

Threshold shape. Inherits from PopulationGeometry.

x_threshold¶

Threshold applied to the X-axis

Type: float

y_threshold¶

Threshold applied to the Y-axis

Type: float

Methods:

transform_to_linear()

Thresholds are transformed to their equivalent value in linear space according to the transform defined.

transform_to_linear()¶

Thresholds are transformed to their equivalent value in linear space according to the transform defined. If transform is None, thresholds are returned as saved.

Returns
Return type: float, float

cytopy.data.geometry.create_convex_hull(x_values: numpy.array, y_values: numpy.array)¶

Given the x and y coordinates of a cloud of data points, generate a convex hull, returning the x and y coordinates of its vertices.

Parameters

x_values (numpy.ndarray) –
y_values (numpy.ndarray) –

Returns

Return type

numpy.ndarray, numpy.ndarray

cytopy.data.geometry.create_polygon(x: list, y: list)¶

Given a list of x coordinated and a list of y coordinates, generate a shapely Polygon

Parameters

x (list) –
y (list) –

Returns

Return type

Polygon

cytopy.data.geometry.ellipse_to_polygon(centroid: (<class 'float'>, <class 'float'>), width: float, height: float, angle: float, ellipse: Optional[matplotlib.patches.Ellipse] = None)¶

Convert an ellipse to a shapely Polygon object.

Parameters

centroid ((float, float)) –
width (float) –
height (float) –
angle (float) –
ellipse (Ellipse (optional)) –

Returns

Return type

Polygon

cytopy.data.geometry.inside_ellipse(data: numpy.array, center: tuple, width: int, height: int, angle: int) → object¶

Return mask of two dimensional matrix specifying if a data point (row) falls within an ellipse

Parameters

data (numpy.ndarray) – two dimensional matrix (x,y)
center (tuple) – x,y coordinate corresponding to center of elipse
width (int or float) – semi-major axis of eplipse
height (int or float) – semi-minor axis of elipse
angle (int or float) – angle of ellipse

Returns

numpy array of indices for values inside specified ellipse

Return type

numpy.ndarray

cytopy.data.geometry.inside_polygon(df: pandas.core.frame.DataFrame, x: str, y: str, poly: shapely.geometry.polygon.Polygon, njobs: int = - 1)¶

Return rows in dataframe who’s values for x and y are contained in some polygon coordinate shape

Parameters

df (Pandas.DataFrame) – Data to query
x (str) – name of x-axis plane
y (str) – name of y-axis plane
poly (shapely.geometry.Polygon) – Polygon object to search
njobs (int) – Number of jobs to run in parallel, by default uses all available cores

Returns

Masked DataFrame containing only those rows that fall within the Polygon

Return type

Pandas.DataFrame

cytopy.data.geometry.polygon_overlap(poly1: shapely.geometry.polygon.Polygon, poly2: shapely.geometry.polygon.Polygon, threshold: float = 0.0)¶

Compare the area of two polygons and give the fraction overlap. If fraction overlap does not exceed given threshold or the polygon’s do not overlap, return 0.0

Parameters

poly1 (Polygon) –
poly2 (Polygon) –
threshold (float (default = 0.0)) –

Returns

Return type

float

cytopy.data.geometry.probablistic_ellipse(covariances: numpy.array, conf: float)¶

Given the covariance matrix of a mixture component, calculate a elliptical shape that represents a probabilistic confidence interval.

Parameters

covariances (np.array) – Covariance matrix
conf (float) – The confidence interval (e.g. 0.95 would give the region of 95% confidence)

Returns

Width, Height and Angle of ellipse

Return type

float and float and float