ParticleChromo3D+: a Web Server for ParticleChromo3D Algorithm for 3D Chromosome Structure Reconstruction

Access on: http://ParticleChromo3D.online

---

OluwadareLab, University of Colorado, Colorado Springs

---

Build Status :

Test Status :
Also checks coverage stats

---

Developers:
              David Vadnais
              Department of Computer Science
              University of Colorado, Colorado Springs
              Email: dvadnais@uccs.edu

Contact:
              Oluwatosin Oluwadare, PhD
              Department of Computer Science
              University of Colorado, Colorado Springs
              Email: ooluwada@uccs.edu

---

0. Pip install:

NOTE: This usage is underconstruction.
We released a pypi package.

Simply run : pip install ParticleChromo3D

Then :

from ParticleChromo3D import Ps
import numpy as np

fout = Ps.strip_file("exampleIfs/chr22_matrix.txt")

# this will all get moved into a self contained function soon
theseAlphas = np.array([0.1, 2.0, 0.1]) * 100
theAlphas = ( np.array(range(int(theseAlphas[0]), int(theseAlphas[1]), int(theseAlphas[2]))) / 100)

outputOfSwarm = Ps.Full_List(fout, "this_pdb", theseAlphas)[0]

bestSpearm = outputOfSwarm[1]
bestCost = outputOfSwarm[2]
bestAlpha = theAlphas[outputOfSwarm[4]]
bestPearsonRHO = outputOfSwarm[0]

print(f"Convert factor:: {bestAlpha}")
print(f"SSE at best spearman : {bestCost}")
print(f"Best Spearman correlation Dist vs. Reconstructed Dist  : {bestSpearm}")
print(f"Best Pearson correlation Dist vs. Reconstructed Dist: {bestPearsonRHO}")

Ps.Write_Log(
    "this_run.log", fout, bestAlpha, bestCost, bestSpearm, bestPearsonRHO
)

1. Content of folders:

• configs: Python Dependencies
  
• exampleIfs: Synthetic and Real Hi-C datasets examples.
  
• ParticleChromo3D: Source Code and utility's used.
  
• help: Example scripts to help a user get started with our tool.
  
• results: Output structures generated for all the experiments performed.
  
• website: front end code

2. Hi-C Data example data in this study:

The GM12878 cell Hi-C dataset, GEO Accession number GSE63525, was downloaded from GSDB with GSDB ID: OO7429SF

3. Input matrix file format:

Square Matrix Input format: The square matrix is a tab seperated N by N intra-chromosomal contact matrix derived from Hi-C data, where N is the number of regions of a chromosome.

Or convert using the convert endpoint after uploading the Sparse Matrix as a TSV (three-column) file format.

4. Dependencies Installation:

With Docker

Docker

Without Docker

See config/requirements.txt

5. Usage - Docker

Base usage

• Download latest image
  • Via the GitHub web interface here: https://github.com/OluwadareLab/ParticleChromo3D_Plus/actions
• Load the image with
  • docker image load -i particlechromo3d_image.tar.gz
• Run the container with
  • docker run -d -p 5001:5001 -p 8080:8080 -e SERVICE_EMAIL=${YOUR_SVC_EMAIL} -e HOSTNAME_BE=${YOUR_URL} -e SERVICE_EMAIL_KEY=${KEY} particlechromo3d:latest

Build/extend the image

In the base folder build the image with docker build -t particlechromo3d:latest .

Then run the container with docker run -d -p 5001:5001 -p 8080:8080 -e SERVICE_EMAIL=${YOUR_SVC_EMAIL} -e HOSTNAME_BE=${YOUR_URL} -e SERVICE_EMAIL_KEY=${KEY} particlechromo3d:latest

Volumes (Persisting Data)

Working with volumes:

# Manage your volume
docker volume create ${VOLUME_NAME}
docker volume inspect ${VOLUME_NAME}
docker volume ls
docker volume rm ${VOLUME_NAME}

# Run using a volume
docker run -d -p 5001:5001 -p 8080:8080  -e SERVICE_EMAIL=${YOUR_SVC_EMAIL} -e HOSTNAME_BE=${YOUR_URL} -e SERVICE_EMAIL_KEY=${KEY} particlechromo3d:latest

7. Usage - Direct:

In lieu of using docker ParticleChromo3D/Ps.py can be run directly through:

git clone git@github.com:OluwadareLab/ParticleChromo3D_Plus.git
cd ParticleChromo3D_Plus/config
pip install -r requirements.txt

python ParticleChromo3D/Ps.py ${INPUT_MATRIX}
# example Windows: python .\ParticleChromo3D\Ps.py exampleIfs\chr20_matrix.txt
# example Linux: python ParticleChromo3D/Ps.py exampleIfs/chr20_matrix.txt

Use python Ps.py --help to find out more about the run options.

Unit Test: We use pytest in the root level for unit testing. Simply install pytest and run pytest.

Coverage: pytest --cov=ParticleChromo3D --cov-report=term --cov-report=html

8. Publication:

Vadnais, David, and Oluwatosin Oluwadare. "ParticleChromo3D+: A Web Server for ParticleChromo3D Algorithm for 3D Chromosome Structure Reconstruction." Current Issues in Molecular Biology 45.3 (2023): 2549-2560.

Vadnais, D., Middleton, M. & Oluwadare, O. ParticleChromo3D: a Particle Swarm Optimization algorithm for chromosome 3D structure prediction from Hi-C data. BioData Mining 15, 19 (2022). https://doi.org/10.1186/s13040-022-00305-x

9. Rust:

Rust support is explained in the readme in ParticleChromo3D_rust. The package can be found here

TODO:

• Do a speed test comparison
• Release a python package
• Add workflows for testing rust build