API reference: Transforms

The transform engine and the dataset transform factories.

TransformSequence

TransformSequence

TransformSequence()

Bases: object

Source code in standard_transform/base.py

def __init__(self):
    self._transforms = []

invert

invert(pts_tf, as_int=False) -> np.ndarray

Invert points post-transform back into the original coordinate system

Parameters:

Name	Type	Description	Default
pts_tf	array - like	Points in the post-transform coordinate system	required
as_int	bool	Return locations as integers, by default False	False

Returns:

Type	Description
array - like	Points in the original coordinate system

Source code in standard_transform/base.py

def invert(self, pts_tf, as_int=False) -> np.ndarray:
    """Invert points post-transform back into the original coordinate system

    Parameters
    ----------
    pts_tf : array-like
        Points in the post-transform coordinate system
    as_int : bool, optional
        Return locations as integers, by default False

    Returns
    -------
    array-like
        Points in the original coordinate system
    """
    if isinstance(pts_tf, pd.Series):
        return self.column_invert(pts_tf, as_int=as_int)
    else:
        return self.list_invert(pts_tf, as_int=as_int)

apply_project

apply_project(projection, pts, as_int=False) -> np.ndarray

Apply transform and extract one dimension (e.g. depth)

Parameters:

Name	Type	Description	Default
projection	str or int	Which dimension to project out of the transformed data. One of "x","y", or "z" (or 0,1,2 equivalently).	required
pts	ndarray or Series	Either an n x 3 array or pandas Series object with 3-element arrays as elements.	required
as_int	bool	Return locations as integers, by default False	False

Returns:

Type	Description
array	N-length array

Source code in standard_transform/base.py

def apply_project(self, projection, pts, as_int=False) -> np.ndarray:
    """Apply transform and extract one dimension (e.g. depth)

    Parameters
    ----------
    projection : str or int
        Which dimension to project out of the transformed data. One of "x","y", or "z" (or 0,1,2 equivalently).
    pts : np.ndarray or pd.Series
        Either an n x 3 array or pandas Series object with 3-element arrays as elements.
    as_int : bool, optional
        Return locations as integers, by default False

    Returns
    -------
    np.array
        N-length array
    """
    proj_map = {
        "x": 0,
        "y": 1,
        "z": 2,
        0: 0,
        1: 1,
        2: 2,
    }
    # If a single point is passed, then return a single number not an array.
    if len(np.array(pts).shape) == 1 and not isinstance(pts, pd.Series):

        def output_fn(x):
            return x[0]
    else:

        def output_fn(x):
            return x

    if projection not in proj_map:
        raise ValueError('Projection must be one of "x", "y", or "z"')
    return output_fn(
        np.array(np.atleast_2d(self.apply(pts, as_int=as_int)))[
            :, proj_map.get(projection)
        ]
    )

apply_dataframe

apply_dataframe(
    col,
    df,
    projection=None,
    return_array=False,
    as_int=False,
) -> "Union[np.ndarray, list]"

Apply transformation on a dataframe position column (or prefix of a split position column).

Parameters:

Name	Type	Description	Default
col	str	Column name or prefix of a split position column. e.g. pt_position for pt_position_x, pt_position_y, pt_position_z. Whether or not column is split is auto-determined.	required
df	DataFrame	Dataframe with data	required
projection	str	If specified as 'x', 'y', or 'z' return only one element, by default None.	None
as_int	bool	If True, cast values to integers, by default False	False

Source code in standard_transform/base.py

def apply_dataframe(
    self, col, df, projection=None, return_array=False, as_int=False
) -> "Union[np.ndarray, list]":
    """Apply transformation on a dataframe position column (or prefix of a split position column).

    Parameters
    ----------
    col : str
        Column name or prefix of a split position column. e.g. `pt_position` for `pt_position_x`, `pt_position_y`, `pt_position_z`.
        Whether or not column is split is auto-determined.
    df : pd.DataFrame
        Dataframe with data
    projection : str, optional
        If specified as 'x', 'y', or 'z' return only one element, by default None.
    as_int : bool, optional
        If True, cast values to integers, by default False
    """
    pts = get_dataframe_points(pt_col=col, df=df)
    if projection:
        out = self.apply_project(projection, pts, as_int=as_int)
        if return_array:
            return out
        else:
            return out.tolist()
    else:
        out = self.apply(pts, as_int)
        if return_array:
            return out
        else:
            return out.tolist()

apply_skeleton

apply_skeleton(
    sk, inplace=False
) -> "meshparty.skeleton.Skeleton"

Apply transformation to a meshparty Skeleton

.. deprecated:: Transforming morphology objects is moving to Ossify (https://csdashm.com/ossify/), where the transformation is passed to the object. Use :meth:apply on sk.vertices for coordinate arrays.

Parameters:

Name	Type	Description	Default
sk	Skeleton	Skeleton to transform	required
inplace	bool	If True, transform vertices in place, by default False	False

Returns:

Type	Description
Skeleton	Skeleton with transformed vertices

Source code in standard_transform/base.py

def apply_skeleton(self, sk, inplace=False) -> "meshparty.skeleton.Skeleton":
    """Apply transformation to a meshparty Skeleton

    .. deprecated::
        Transforming morphology objects is moving to Ossify
        (https://csdashm.com/ossify/), where the transformation is passed to the
        object. Use :meth:`apply` on ``sk.vertices`` for coordinate arrays.

    Parameters
    ----------
    sk : meshparty.Skeleton
        Skeleton to transform
    inplace : bool, optional
        If True, transform vertices in place, by default False

    Returns
    -------
    Skeleton
        Skeleton with transformed vertices
    """
    warn_object_transform_deprecated("TransformSequence.apply_skeleton")
    if not inplace:
        sk = sk.copy()
    sk.vertices = self.apply(sk._rooted.vertices)
    return sk

apply_meshwork_vertices

apply_meshwork_vertices(
    nrn, inplace=False
) -> "meshparty.meshwork.Meshwork"

Apply transformation to mesh and skeleton vertices of a meshparty Meshwork

.. deprecated:: Transforming morphology objects is moving to Ossify (https://csdashm.com/ossify/), where the transformation is passed to the object. Use :meth:apply on coordinate arrays.

Parameters:

Name	Type	Description	Default
nrn	Meshwork	Object to transform	required
inplace	bool	If True, transform vertices in place, by default False	False

Returns:

Type	Description
Skeleton	Skeleton with transformed vertices

Source code in standard_transform/base.py

def apply_meshwork_vertices(
    self, nrn, inplace=False
) -> "meshparty.meshwork.Meshwork":
    """Apply transformation to mesh and skeleton vertices of a meshparty Meshwork

    .. deprecated::
        Transforming morphology objects is moving to Ossify
        (https://csdashm.com/ossify/), where the transformation is passed to the
        object. Use :meth:`apply` on coordinate arrays.

    Parameters
    ----------
    nrn : meshparty.meshwork.Meshwork
        Object to transform
    inplace : bool, optional
        If True, transform vertices in place, by default False

    Returns
    -------
    Skeleton
        Skeleton with transformed vertices
    """
    warn_object_transform_deprecated("TransformSequence.apply_meshwork_vertices")
    if not inplace:
        nrn = nrn.copy()
    curr_mask = nrn.mesh.node_mask
    nrn.reset_mask()
    nrn.mesh.vertices = self.apply(nrn.mesh.vertices)
    nrn.skeleton.vertices = self.apply(nrn.skeleton.vertices)
    nrn.apply_mask(curr_mask)
    return nrn

apply_meshwork_annotations

apply_meshwork_annotations(
    nrn, anno_dict, inplace=False
) -> "meshparty.meshwork.Meshwork"

Apply transformations to annotations in a meshwork

.. deprecated:: Transforming morphology objects is moving to Ossify (https://csdashm.com/ossify/), where the transformation is passed to the object. Use :meth:apply on coordinate arrays.

Parameters:

Name	Type	Description	Default
nrn	Meshwork	Object to transform	required
anno_dict	dict	Dictionary whose keys are annotation tables in the meshwork and whose values are the columns to transform (string or list of strings)	required
inplace	bool	If True, transform vertices in place, by default False	False

Returns:

Type	Description
meshwork	Object with transformed annotation positions.

Source code in standard_transform/base.py

def apply_meshwork_annotations(
    self, nrn, anno_dict, inplace=False
) -> "meshparty.meshwork.Meshwork":
    """Apply transformations to annotations in a meshwork

    .. deprecated::
        Transforming morphology objects is moving to Ossify
        (https://csdashm.com/ossify/), where the transformation is passed to the
        object. Use :meth:`apply` on coordinate arrays.

    Parameters
    ----------
    nrn : meshwork.Meshwork
        Object to transform
    anno_dict : dict
        Dictionary whose keys are annotation tables in the meshwork and whose values are the columns to transform (string or list of strings)
    inplace : bool, optional
        If True, transform vertices in place, by default False

    Returns
    -------
    meshwork
        Object with transformed annotation positions.
    """
    warn_object_transform_deprecated("TransformSequence.apply_meshwork_annotations")
    if not inplace:
        nrn = nrn.copy()
    for tbl in anno_dict:
        vs = anno_dict[tbl]
        if not is_list_like(vs):
            vs = [vs]
        for v in vs:
            nrn.anno[tbl]._data[v] = self.apply(nrn.anno[tbl]._data[v])
    return nrn

identity_transform

identity_transform

identity_transform() -> TransformSequence

Returns the same points provided

Source code in standard_transform/base.py

def identity_transform() -> TransformSequence:
    "Returns the same points provided"
    return TransformSequence()

Factory functions

minnie_transform

minnie_transform(
    resolution="nm", version=None
) -> TransformSequence

Transform for the minnie65 dataset into oriented microns.

Parameters:

Name	Type	Description	Default
resolution	str or array - like	Units of the input points: "nm" (default), "vx" (native voxel size), or an explicit [x, y, z] resolution.	'nm'
version	str	Transform version; by default the latest. See :func:available_versions.	None

Source code in standard_transform/datasets.py

def minnie_transform(resolution="nm", version=None) -> TransformSequence:
    """Transform for the minnie65 dataset into oriented microns.

    Parameters
    ----------
    resolution : str or array-like, optional
        Units of the input points: ``"nm"`` (default), ``"vx"`` (native voxel size),
        or an explicit ``[x, y, z]`` resolution.
    version : str, optional
        Transform version; by default the latest. See :func:`available_versions`.
    """
    return _build_transform("minnie65", version, _resolution_vector(resolution, "minnie65"))

v1dd_transform

v1dd_transform(
    resolution="nm", version=None
) -> TransformSequence

Transform for the v1dd dataset into oriented microns. See :func:minnie_transform.

Source code in standard_transform/datasets.py

def v1dd_transform(resolution="nm", version=None) -> TransformSequence:
    """Transform for the v1dd dataset into oriented microns. See :func:`minnie_transform`."""
    return _build_transform("v1dd", version, _resolution_vector(resolution, "v1dd"))

Version discovery

available_versions

available_versions(dataset)

List the available transform and streamline versions for a dataset.

Parameters:

Name	Type	Description	Default
dataset	str	Dataset name, one of "minnie65" or "v1dd".	required

Returns:

Type

Description

dict

{"transform": {"latest": <label>, "versions": {<label>: <introduced_in>}}, "streamline": {"latest": ..., "versions": {...}, "transform_versions": {<label>: <transform version the streamline is built in>}}}. The two tracks are versioned independently -- each label is the package release in which that definition became the default -- but every streamline pins the transform version whose oriented frame its data lives in.

Source code in standard_transform/datasets.py

def available_versions(dataset):
    """List the available transform and streamline versions for a dataset.

    Parameters
    ----------
    dataset : str
        Dataset name, one of ``"minnie65"`` or ``"v1dd"``.

    Returns
    -------
    dict
        ``{"transform": {"latest": <label>, "versions": {<label>: <introduced_in>}},
        "streamline": {"latest": ..., "versions": {...}, "transform_versions":
        {<label>: <transform version the streamline is built in>}}}``. The two tracks
        are versioned independently -- each label is the package release in which that
        definition became the default -- but every streamline pins the transform version
        whose oriented frame its data lives in.
    """
    if dataset not in _TRANSFORM_VERSIONS:
        raise ValueError(
            f"Unknown dataset {dataset!r}. Available: {sorted(_TRANSFORM_VERSIONS)}."
        )
    return {
        "transform": {
            "latest": _TRANSFORM_LATEST[dataset],
            "versions": {
                v: e["introduced_in"] for v, e in _TRANSFORM_VERSIONS[dataset].items()
            },
        },
        "streamline": {
            "latest": _STREAMLINE_LATEST[dataset],
            "versions": {
                v: e["introduced_in"] for v, e in _STREAMLINE_VERSIONS[dataset].items()
            },
            # Each streamline version is built in a specific transform version's frame.
            "transform_versions": {
                v: e["transform_version"]
                for v, e in _STREAMLINE_VERSIONS[dataset].items()
            },
        },
    }