# 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()`