Package 'TrajectoryGeometry'

Description

This function takes a single cell trajectory and analyses it starting from successively later points in pseudotime, with the rationale that a more consistent directionality will be followed after the branch point.

Usage

analyseBranchPoint(
  attributes,
  pseudotime,
  randomizationParams,
  statistic,
  start = (max(pseudotime) - min(pseudotime)) * 0.25,
  stop = (max(pseudotime) - min(pseudotime)) * 0.75,
  step = (max(pseudotime) - min(pseudotime)) * 0.05,
  nSamples = 1000,
  nWindows = 10,
  d = ncol(attributes),
  N = 1
)

Arguments

Value

This returns a list of results for analyseSingleCellTrajectory, named by trajectory starting point. Each result from analyseSingleCellTrajectory is a list which contains an entry for each sampled path. Each of these entries is a list containing information comparing the sampled path in question to random paths. The entries consist of: pValue - the p-value for the path and statistic in question; sphericalData - a list containing the projections of the path to the sphere, the center of that sphere and the statistic for distance to that center; randomDistances - the corresponding distances for randomly chosen; paths; randomizationParams - the choice of randomization parameters

Examples

chol_branch_point_results = analyseBranchPoint(chol_attributes[,seq_len(3)],
                         chol_pseudo_time[!is.na(chol_pseudo_time)],
                         randomizationParams = c('byPermutation',
                                         'permuteWithinColumns'),
                         statistic = "mean",
                         start = 0,
                         stop = 50,
                         step = 5,
                         nSamples = 10,
                         N = 1)

Description

This function analyses a single cell trajectory by sampling multiple paths and comparing each path to random paths. It takes vector of pseudotime values, and a matrix of attribute values (cell x attribute). It also optionally takes the number of pseudotime windows to sample a single cell from. This defaults to 10. The function returns a list of Answers for each comparison of a sampled path to a random path.

Usage

analyseSingleCellTrajectory(
  attributes,
  pseudotime,
  randomizationParams,
  statistic,
  nSamples = 1000,
  nWindows = 10,
  d = ncol(attributes),
  N = 1000
)

Arguments

Value

This returns a list, where each entry is itself a list containing information comparing a sampled path to random paths. These entries consist of: pValue - the p-value for the path and statistic in question; sphericalData - a list containing the projections of the path to the sphere, the center of that sphere and the statistic for distance to that center; randomDistances - the corresponding distances for randomly chosen; paths; randomizationParams - the choice of randomization parameters

Examples

chol_answers = analyseSingleCellTrajectory(chol_attributes[,seq_len(3)],
                                         chol_pseudo_time_normalised,
                                         nSamples = 10,
                                         randomizationParams =
                                                     c('byPermutation',
                                                   'permuteWithinColumns'),
                                         statistic = "mean",
                                         N = 1)
hep_answers = analyseSingleCellTrajectory(hep_attributes[,seq_len(3)],
                                         hep_pseudo_time_normalised,
                                         nSamples = 10,
                                         randomizationParams =
                                                   c('byPermutation',
                                                   'permuteWithinColumns'),
                                         statistic = "mean",
                                         N = 1)

Description

Results of running analyseSingleCellTrajectory() on a trajectory describing the development of cholangiocytes from hepatoblasts.

Usage

chol_answers

Format

A list

Results of running analyseSingleCellTrajectory() on a trajectory describing the development of cholangiocytes from hepatoblasts.

Source

Single-cell data has been obtained from GEO (GSE90047) and the script used for upstream processing is available at https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

PCA projections derived from normalised gene expression values for single cells, and filtered for cells which feature in a trajectory from hepatoblast to cholangiocyte. The columns are the PCs and the rows are the cells.

Usage

chol_attributes

Format

A matrix

PCA projections derived from normalised gene expression values for single cells, and filtered for cells which feature in a trajectory from hepatoblast to cholangiocyte. The columns are the PCs and the rows are the cells.

Source

Single-cell data has been obtained from GEO (GSE90047) and the script used for upstream processing is available at https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

Results of running analyseBranchPoint() on a trajectory describing the development of cholangiocytes from hepatoblasts.

Usage

chol_branch_point_results

Format

A list

Results of running analyseBranchPoint() on a trajectory describing the development of cholangiocytes from hepatoblasts.

Source

Single-cell data has been obtained from GEO (GSE90047) and the script used for upstream processing is available at https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

A vector of pseudotime values for a trajectory describing the development of cholangiocytes from hepatoblasts. Pseudotime values have been inferred using the SlingShot package. The vector is named according to cell ID.

Usage

chol_pseudo_time

Format

A vector

A vector of pseudotime values for a trajectory describing the development of cholangiocytes from hepatoblasts. Pseudotime values have been inferred using the SlingShot package. The vector is named according to cell ID.

Source

Single-cell data has been obtained from GEO (GSE90047) and the script used for upstream processing is available at https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

A vector of pseudotime values, normalised to range from 0 to 100, for a trajectory describing the development of cholangiocytes from hepatoblasts. Pseudotime values have been inferred using the SlingShot package. The vector is named according to cell ID.

Usage

chol_pseudo_time_normalised

Format

A vector

A vector of pseudotime values, normalised to range from 0 to 100, for a trajectory describing the development of cholangiocytes from hepatoblasts. Pseudotime values have been inferred using the SlingShot package. The vector is named according to cell ID.

Source

Single-cell data has been obtained from GEO (GSE90047) and the script used for upstream processing is available at https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

Find a circle on the unit 2-sphere

Usage

circleOnTheUnitSphere(center, radius, N = 36)

Arguments

Details

Given a point on the unit 2-sphere and a radius given as a spherical distance, this finds the circle.

It's not clear to me this should be exported, but it's handy to do this for testing and debugging.

Value

This returns an approximation to the the circle as a N+1 x 3 matrix

Examples

pole = c(1,0,0)
radius = pi / 4
circle = circleOnTheUnitSphere(pole,radius)

Description

A path of n points in dimension d is an n x d matrix. This particular path is relatively crooked.

Usage

crooked_path

Format

A 14 x 3 matrix

This path changes direction after the 5th point.

Source

This was created by code in createSyntheticData.R available from https://github.com/AnnaLaddach/TrajectoryGeometryData The second author wishes to categorically deny that this variable is named after the course of his own life.

Description

The point on the unit sphere minimizing mean spherical distance to the projection of crooked_path

Usage

crooked_path_center

Format

A vector of length 3

A unit vector of length 3 minimizing mean spherical distance to the points of the projection of crooked_path.

Source

Synthetic data.

Description

The projection of the last 8 points on crooked_path onto the unit sphere as seen from the the 6th. This is a collection of 8 unit points in dimension 3.

Usage

crooked_path_projection

Format

An 8 x 3 matrix

The projection of crooked_path[7:14,] onto the unit sphere as seen from crooked_path[6,] .

Source

This was created by code in createSyntheticData.R available from https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

The mean spherical distance from the points of the projection of crooked_path to the point minimizing this mean distance.

Usage

crooked_path_radius

Format

Numeric

The mean spherical distance from the points of the projection of crooked_path to the point minimizing this mean distance.

Source

This was created by code in createSyntheticData.R available from https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

This function compares two single cell trajectories (representative of different lineages within the same dataset), and finds the minimum euclidean distance between the first and the second trajectory at each point in pseudotime. Please note, attributes can either be values for single cells, or attributes which have been smoothed over pseudotime. Likewise the pseudotime values should be for single cells, or for smoothed attributes over pseudotime

Usage

distanceBetweenTrajectories(attributes1, pseudotime1, attributes2)

Arguments

Value

results - a dataframe containing pseudotime values (for the first trajectory), and distances (the minimimum euclidian distance between the two trajectories at that point in pseudotime).

Examples

distances = distanceBetweenTrajectories(chol_attributes,
                                 chol_pseudo_time[!is.na(chol_pseudo_time)],
                                 hep_attributes)

Description

This function takes a set of points on the d-1 sphere in d-space and finds a center for these. Depending on choice of statistic, this center is a point on the sphere which minimizes either the median distance, the mean distance or the maximum distance of the center to the given points. "Distance" here is taken to mean angle between the points, i.e., arccos of their dot product.

Usage

findSphereClusterCenter(points, statistic, normalize = FALSE)

Arguments

Value

This returns a point in dimension d given as a vector.

Examples

projection = projectPathToSphere(straight_path)
center = findSphereClusterCenter(projection,'mean')

Description

This function takes a point (typically a center) and a set of points and finds the spherical distance between the given point and each of the others. If requested, it will first normalize all of them.

Usage

findSphericalDistance(center, points, normalize = FALSE)

Arguments

Value

This returns a vector of n spherical distances in radians.

Examples

distances = findSphericalDistance(straight_path_center,
    straight_path_projection)

Description

This function takes a path and produces N random paths of the same dimension and length based on it. This can be done either by permuting the entries in path or by taking steps from the initial point of path. Exact behaviour is controlled by randomizationParams.

Usage

generateRandomPaths(
  path,
  from = 1,
  to = nrow(path),
  d = ncol(path),
  randomizationParams,
  N
)

Arguments

Value

This function returns a list of random paths. Each path is a matrix.

Examples

randomizationParams = c('byPermutation','permuteWithinColumns')
randomPaths = generateRandomPaths(crooked_path,from=6,to=nrow(crooked_path),
              d=ncol(crooked_path),randomizationParams=randomizationParams,
              N=10)

Description

This function generates a random unit vector in in dimension d.

Usage

generateRandomUnitVector(d)

Arguments

Value

A unit vector in dimension d.

Examples

randomUnitVector = generateRandomUnitVector(5)

Description

This function takes a list of paths and a choice of statistic (median, mean or max) and returns that statistic for the appropriate center for each path. Each path is an n x d matrix. In use, it is assumed that these will be the randomized paths. It is therefore assumed that they are already of the correct dimensions.

Usage

getDistanceDataForPaths(paths, statistic)

Arguments

Value

This returns a vector of n distances.

Examples

paths =
    generateRandomPaths(path=straight_path,randomizationParam='bySteps',N=5)
distance = getDistanceDataForPaths(paths=paths,statistic='max')

Description

It handles the case in which from, to and d are all given by the dimensions of the path

Usage

getSphericalData(path, statistic)

Arguments

Value

This function returns a list whose elements are the projections of the path to the sphere, the center for those projections, the median, mean or max distance from the center to those projections and the name of the statistic used.

Examples

sphericalData = getSphericalData(straight_path,'max')

Description

This finds the lengths of the steps along a path

Usage

getStepLengths(path, from = 1, to = nrow(path), d = ncol(path))

Arguments

Value

This function returns the length of each step in a path.

Examples

stepLengths = getStepLengths(path=crooked_path)
stepLengths = getStepLengths(path=crooked_path,from=4)

Description

Results of running analyseSingleCellTrajectory() on a trajectory describing the development of hepatocytes from hepatoblasts.

Usage

hep_answers

Format

A list

Results of running analyseSingleCellTrajectory() on a trajectory describing the development of hepatocytes from hepatoblasts.

Source

Single-cell data has been obtained from GEO (GSE90047) and the script used for upstream processing is available at https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

PCA projections derived from normalised gene expression values for single cells, and filtered for cells which feature in a trajectory from hepatoblast to hepatocyte. The columns are the PCs and the rows are the cells.

Usage

hep_attributes

Format

A matrix

PCA projections derived from normalised gene expression values for single cells, and filtered for cells which feature in a trajectory from hepatoblast to hepatocyte. The columns are the PCs and the rows are the cells.

Source

Single-cell data has been obtained from GEO (GSE90047) and the script used for upstream processing is available at https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

A vector of pseudotime values for a trajectory describing the development of hepatocytes from hepatoblasts. Pseudotime values have been inferred using the SlingShot package. The vector is named according to cell ID.

Usage

hep_pseudo_time

Format

A vector

A vector of pseudotime values for a trajectory describing the development of hepatocytes from hepatoblasts. Pseudotime values have been inferred using the SlingShot package. The vector is named according to cell ID.

Source

Single-cell data has been obtained from GEO (GSE90047) and the script used for upstream processing is available at https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

A vector of pseudotime values, normalised to range from 0 to 100, for a trajectory describing the development of hepatocytes from hepatoblasts. Pseudotime values have been inferred using the SlingShot package. The vector is named according to cell ID.

Usage

hep_pseudo_time_normalised

Format

A vector

A vector of pseudotime values for a trajectory describing the development of hepatocytes from hepatoblasts. Pseudotime values have been inferred using the SlingShot package. The vector is named according to cell ID.

Source

Single-cell data has been obtained from GEO (GSE90047) and the script used for upstream processing is available at https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

Given a vector in R3, this normalizes it and then uses it as the first basis vector in an orthonormal basis. We'll use this to find circles around points on the sphere.

Usage

orthonormalBasis(x)

Arguments

Value

This function returns an orthonormal basis in the the form of a 3 x 3 matrix in which the first vector is parallel to v

Examples

anOrthonormalBasis = orthonormalBasis(c(1,1,1))

Description

This a path which prepends small oscillations to straight path. Its purpose is to illustrate instability of spherical projection near the beginning of a path.

Usage

oscillation

Format

A matrix

This a path which prepends small oscillations to straight path. Its purpose is to illustrate instability of spherical projection near the beginning of a path.

Source

This was created by code in createSyntheticData.R available from https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

This function measures the progress of a path in a specified direction. This direction will typically be the center of its projection onto the sphere as revealed using your favorite statistic.

Usage

pathProgression(path, from = 1, to = nrow(path), d = ncol(path), direction)

Arguments

Value

This returns a numeric given the signed distance projection of the path along the line through its starting point in the given direction.

Examples

progress =
    pathProgression(straight_path,direction=straight_path_center)
progress =
    pathProgression(crooked_path,from=6,direction=crooked_path_center)

Description

This function takes a path and returns a list containing its projection to the sphere, the center for that projection, the spherical distance from the center to the points of the projection and the name of the statistic used.

Usage

pathToSphericalData(path, from, to, d, statistic)

Arguments

Value

This function returns a list whose elements are the projections of the path to the sphere, the center for those projections, the median, mean or max distance from the center to those projections and the name of the statistic used.

Examples

sphericalData = pathToSphericalData(straight_path,from=1,
                                    to=nrow(straight_path), d=3,
                                    statistic='median')

Description

This function assumes you have a path in dimension 3 and you have found the projection for the portion under consideration, the center for its projection and the circle (i.e., radius) for the appropriate statistic. Scales the path to keep it comparable to the sphere and plots all this in your favorite color. It can be called repeatedly to add additional paths in different colors.

Usage

plotPathProjectionCenterAndCircle(
  path,
  from = 1,
  to = nrow(path),
  projection,
  center,
  radius,
  color,
  circleColor = "white",
  pathPointSize = 8,
  projectionPointSize = 8,
  scale = 1.5,
  newFigure = TRUE
)

Arguments

Value

This returns 0.

Examples

plotPathProjectionCenterAndCircle(path=straight_path,
                                 projection=straight_path_projection,
                                 center=straight_path_center,
                                 radius=straight_path_radius,
                                 color='red',
                                 newFigure=TRUE)

Description

This function takes a path in d dimensional space and projects it onto the d-1 sphere. It takes as additional arguments the starting and ending points under consideration and the dimension to be considered.

Usage

projectPathToSphere(path, from = 1, to = nrow(path), d = ncol(path))

Arguments

Value

This returns a projection of the path onto the d-1 sphere in the form of a (to - from) x d matrix.

Examples

projection1 = projectPathToSphere(straight_path)
projection2 = projectPathToSphere(crooked_path,from=6)

Description

This function takes vector of pseudotime values, and a matrix of attribute values (cell x attribute). It also optionally takes the number of pseudotime windows to sample a single cell from. This defaults to 10. The function returns a matrix of sampled attribute values which form the coordinates of the sampled path. The matrix of attribute values should consist of numeric values relevant to a pseudotime trajectory i.e. gene expression values or PCA projections. The vector of pseudotime values should be named according to cell names. Simarly the row names of the matrix of attribute values should be cell names. Row names for the returned matrix of the sampled path give the window number a cell was sampled from.

Usage

samplePath(attributes, pseudotime, nWindows = 10)

Arguments

Value

sampledPath - A path consisting of a matrix of attributes of sampled cells. The rownames refer to the pseudotime windows cell was sampled from.

Examples

samplePath(chol_attributes, chol_pseudo_time_normalised)
samplePath(hep_attributes, hep_pseudo_time_normalised)

Description

PCA projections derived from normalised gene expression values for single cells. The columns are the PCs and the rows are the cells.

Usage

single_cell_matrix

Format

A matrix

PCA projections derived from normalised gene expression values for single cells. The columns are the PCs and the rows are the cells.

Source

Single-cell data has been obtained from GEO (GSE90047) and the script used for upstream processing is available at https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

A path of n points in dimension d is an n x d matrix. This particular path is relatively straight.

Usage

straight_path

Format

A 14 x 3 matrix

The path is roughly in the (1,0,0) direction.

Source

This was created by code in createSyntheticData.R available from https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

The point on the unit sphere minimizing mean spherical distance to the projection so straight_path

Usage

straight_path_center

Format

A vector of length 3

A unit vector of length 3 minimizing distance to the points of the projection of straight_path.

Source

This was created by code in createSyntheticData.R available from https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

The projection of straight_path onto the unit sphere. This is a collection of 13 unit points in dimension 3

Usage

straight_path_projection

Format

A 13 x 3 matrix

The projection of straight_path[2:14,] onto the unit sphere as seen from straight_path[1,] .

Source

This was created by code in createSyntheticData.R available from https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

The mean spherical distance from the points of the projection of straight_path to the point minimizing this mean distance.

Usage

straight_path_radius

Format

Numeric

The mean spherical distance from the points of the projection of straight_path to the point minimizing this mean distance.

Source

This was created by code in createSyntheticData.R available from https://github.com/AnnaLaddach/TrajectoryGeometryData

Description

This is the core function of this package. It takes a path, and a choice of statistical measure and computes a statistical significance for the directionality of that path.

Usage

testPathForDirectionality(
  path,
  from = 1,
  to = nrow(path),
  d = ncol(path),
  randomizationParams,
  statistic,
  N
)

Arguments

Value

This returns a list giving whose entries are: pValue - the p-value for the path and statistic in question; sphericalData - a list containing the projections of the path to the sphere, the center of that sphere and the statistic for distance to that center; randomDistances - the corresponding distances for randomly chosen; paths; randomizationParams - the choice of randomization parameters

Examples

randomizationParams = c('byPermutation','permuteWithinColumns')
p = testPathForDirectionality(path=straight_path,
                              randomizationParams=randomizationParams,
                              statistic='median',N=100)
q = testPathForDirectionality(path=crooked_path,from=6,
                              randomizationParams=randomizationParams,
                              statistic='median',N=100)

Description

This function creates plots and extracts statistics for analysing branch points. It returns plots and underlying data for visualising distance metrics and -log10 transformed pvalues (comparison to random trajectories) for trajectories with different starting points.

Usage

visualiseBranchPointStats(branchPointData, average = "mean")

Arguments

Value

a list containing: branchPointValues - dataframe containing data underlying distance plot in long format pValues- dataframe containing data underlying p-value plot in long format distancePlot - ggplot object, violin plots of distance metric for sampled paths for different trajectory different starting points pValue - ggplot object, line plot of -log10 transformed p-values for comparing sampled paths to random paths for different trajectory starting points

Examples

cholBranchPointStats = visualiseBranchPointStats(chol_branch_point_results)

Description

This function creates plots and extracts statistics for comparisons of metrics for sampled paths to random paths. It can also create plots for comparing two sets of sampled paths by providing the traj2Data argument.

Usage

visualiseTrajectoryStats(
  traj1Data,
  metric,
  average = "mean",
  traj2Data = list()
)

Arguments

Value

a list containing: stats - output of wilcox test (paired if comparing sampled to random paths, unpaired if comparing sampled paths for two different trajectories) values - dataframe containing plotted data in long format plot - ggplot object

Examples

cholResultDistance = visualiseTrajectoryStats(chol_answers, "distance")
hepResultDistance = visualiseTrajectoryStats(hep_answers, "distance")
distanceComparison = visualiseTrajectoryStats(chol_answers, "distance",
    traj2Data = hep_answers)