Ellipsoid: Shape Statistics in Python

What and Where is the Use Case?

This use case is designed to demonstrate the functionality of python APIs for shape statistics tools of ShapeWorks. These APIs include reading particle files and computing eigenvectors, eigenvalues, and PCA loadings

The use case is located at: Examples/Python/ellipsoid_pca.py

Running the Use Case

To run the use case, run RunUseCase.py (in Examples/Python/) with proper tags. The tags control the type of input data and the optimization method. See Getting Started with Use Cases for the full list of tags.

Before you run the ellipsoid_pca use case, make sure you have the run the ellipsoid use case at least once. The ellipsoid_pca use case reads the particle files generated by the ellipsoid use case and calculates the shape statistics.

Run the following command to run this use case.

$ cd /path/to/shapeworks/Examples/Python
$ python RunUseCase.py ellipsoid_pca 

This calls ellipsoid_pca.py (in Examples/Python/) to perform the following.

  • Loads the existing (pre-trained) ellipsoid shape model
  • Performs shape statistics using the python API and saves relevant data
  • Plots the shape statistics metrics similar to ShapeWorks Studio.

Grooming Data

Since this use case directly loads an existing shape model, there is no grooming involved.

Optimizing Shape Model

Since this use case directly loads an existing shape model, there is no optimization involved.

Analyzing Shape Model

The ParticleShapeStatistics() of ShapeWorks python API analyzes the optimized particle-based shape model by calculating the principal components of the shape model, eigenvalues, eigenvectors, and PCA loadings. This tool also estimates the variance explained by each mode and generates plots for PCA metrics similar to ShapeWorks Studio.

# Read the particle files from a pre-trained shape model
particle_data = sw.ParticleSystem(<list of local point files>)

To perform PCA:

shape_statistics = sw.ParticleShapeStatistics()
shape_statistics.PCA(particleSystem = particle_data,domainsPerShape=1)

Using shape_statistics object, you can now extract the following entities: * Calculate principal components : principalComponentProjections() * Extract the loadings: pcaLoadings() * Eigen Values: eigenValues() * Eigen Vectors: eigenVectors() * Number of shapes in the model: sampleSize() * Dimension of each shape: numDims() * Variance explained by each mode: percentVarByMode()