Skip to main content

3D shape analysis using deep learning

Project description

Project Status: Active – The project has reached a stable, usable state and is being actively developed. Python Version PyPI Downloads Wheel Development Status Tests Coverage Status Code style: black

Cellshape logo by Matt De Vries


Cellshape-cluster is an easy-to-use tool to analyse the cluster cells by their shape using deep learning and, in particular, deep-embedded-clustering. The tool provides the ability to train popular graph-based or convolutional autoencoders on point cloud or voxel data of 3D single cell masks as well as providing pre-trained networks for inference.

To install

pip install cellshape-cluster

Usage

Basic usage:

import torch
from cellshape_cloud import CloudAutoEncoder
from cellshape_cluster import DeepEmbeddedClustering

autoencoder = CloudAutoEncoder(
    num_features=128, 
    k=20, 
    encoder_type="dgcnn"
)

model = DeepEmbeddedClustering(autoencoder=autoencoder, 
                               num_clusters=10,
                               alpha=1.0)

points = torch.randn(1, 2048, 3)

recon, features, clusters = model(points)

To load a trained graph-based autoencoder and perform deep embedded clustering:

import torch
from torch.utils.data import DataLoader

import cellshape_cloud as cloud
import cellshape_cluster as cluster
from cellshape_cloud.vendor.chamfer_distance import ChamferDistance

dataset_dir = "path/to/pointcloud/dataset/"
autoencoder_model = "path/to/autoencoder/model.pt"
num_features = 128
k = 20
encoder_type = "dgcnn"
num_clusters = 10
num_epochs = 1
learning_rate = 0.00001
gamma = 1
divergence_tolerance = 0.01
output_dir = "path/to/output/"


autoencoder = CloudAutoEncoder(
    num_features=128, 
    k=20, 
    encoder_type="dgcnn"
)

checkpoint = torch.load(autoencoder_model)

autoencoder.load_state_dict(checkpoint['model_state_dict']

model = DeepEmbeddedClustering(autoencoder=autoencoder, 
                               num_clusters=10,
                               alpha=1.0)

dataset = cloud.PointCloudDataset(dataset_dir)

dataloader = DataLoader(dataset, batch_size=batch_size, shuffle=False) # it is very important that shuffle=False here!
dataloader_inf = DataLoader(dataset, batch_size=1, shuffle=False) # it is very important that batch_size=1 and shuffle=False here!

optimizer = torch.optim.Adam(
    model.parameters(),
    lr=learning_rate * 16 / batch_size,
    betas=(0.9, 0.999),
    weight_decay=1e-6,
)

reconstruction_criterion = ChamferDistance()
cluster_criterion = nn.KLDivLoss(reduction="sum")

train(
    model,
    dataloader,
    dataloader_inf,
    num_epochs,
    optimizer,
    reconstruction_criterion,
    cluster_criterion,
    update_interval,
    gamma,
    divergence_tolerance,
    output_dir
)

Parameters

  • autoencoder: CloudAutoEncoder or VoxelAutoEncoder.
    Instance of autoencoder class from cellshape-cloud or cellshape-voxel
  • num_clusters: int.
    The number of clusters to use in deep embedded clustering algorithm.
  • alpha: float.
    Degrees of freedom for the Student's t-distribution. Xie et al. (ICML, 2016) let alpha=1 for all experiments.

For developers

  • Fork the repository
  • Clone your fork
git clone https://github.com/USERNAME/cellshape-cluster 
  • Install an editable version (-e) with the development requirements (dev)
cd cellshape-cluster
pip install -e .[dev] 
  • To install pre-commit hooks to ensure formatting is correct:
pre-commit install
  • To release a new version:

Firstly, update the version with bump2version (bump2version patch, bump2version minor or bump2version major). This will increment the package version (to a release candidate - e.g. 0.0.1rc0) and tag the commit. Push this tag to GitHub to run the deployment workflow:

git push --follow-tags

Once the release candidate has been tested, the release version can be created with:

bump2version release

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cellshape-cluster-0.0.13rc0.tar.gz (11.2 kB view details)

Uploaded Source

Built Distribution

cellshape_cluster-0.0.13rc0-py3-none-any.whl (11.7 kB view details)

Uploaded Python 3

File details

Details for the file cellshape-cluster-0.0.13rc0.tar.gz.

File metadata

  • Download URL: cellshape-cluster-0.0.13rc0.tar.gz
  • Upload date:
  • Size: 11.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.10.5

File hashes

Hashes for cellshape-cluster-0.0.13rc0.tar.gz
Algorithm Hash digest
SHA256 421fd05d82c8c8a84a11928ffa8afd75b0c9225f2644734dbf0621f600dac070
MD5 8bfaf381d30d48053411a1850f5655c1
BLAKE2b-256 3a9d10703e945477257f9ec5fff443ef4f42a135e2838bcfea2f94e49982e757

See more details on using hashes here.

File details

Details for the file cellshape_cluster-0.0.13rc0-py3-none-any.whl.

File metadata

File hashes

Hashes for cellshape_cluster-0.0.13rc0-py3-none-any.whl
Algorithm Hash digest
SHA256 dde4035dd8374836e0bfcc9c30941f3740a5e5b86810e9ad81be29cc3243e3f4
MD5 5b0d90cb47ff23aedce2af10be05aba2
BLAKE2b-256 ba4adbdf70565fefe8481f03a73da50ec470d6b329b1c09c62a323b028aabeac

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page