Welcome to g3d’s documentation!

Introduction

g3d is a binary file format for storing genomic 3D structure data, g3d is short for genomic 3D format.

We have one github repository hosts the g3d toolsets:

  1. g3dv - the online g3d visualization platform
  2. g3dtools - the command line tool to generate or query .g3d file
  3. g3djs - the JavaScript API for reading `.g3d`file

If you have any question, please contact us by submit an Issue request.

Visualization

A frontend library based on Vue.js display .g3d file using three.js engine.

Features:

  1. Single mesh mode, all meshes mode
  2. Customization (color, line width etc)
  3. Walk mode
  4. Clickable label to highight
  5. Screenshot (w/ and w/o label)
  6. Performance (high FPS)

Start from a g3d file

Prepare your 3D genomic structure data in .g3d format, you can then put it on a web server for remote access or just save on your local drive.

Open the g3dv website at: https://g3dv.now.sh/

_images/g3dv_1.png

Click the Remote file or Local file tab to switch from using a file from web server or a local file from your hard drive.

We have provide example file and region for your to take a quick look, just click the Example button and then the Go button, the 3D structure for the default region will be displayed:

_images/g3dv_2.png

If you want to see whole chromosome structure, choose Whole Chromosome as display region, submit again:

_images/g3dv_3.png

The display will update:

_images/g3dv_4.png

By default, only one 3D model will be displayed, either from maternal or paternal, or from one chromosome. One the display scene, the right part shows the configuration menu for single mode:

_images/single_on.png

The Show all checkbox toggles single model mode or multiple models mode:

_images/single_off.png

Display configurations

The Background color can be changed if you move mouse over to the Background menu item, click the palette to change the color you liked:

_images/bgc.png

The label for each chromosome or region will be displayed by default:

_images/label_on.png

You can make them invisible by uncheck the Show label menu item:

_images/label_off.png

Single model mode

While at single model mode, there is a dropdown menu for selection which region/chromosome to display, we can also change the color and scale:

_images/single_1.png

After adjusted region, color and scale:

_images/single_2.png

On single model mode, there is a walking camera provided to mimic the walk/run along with the reigon/chromosome:

_images/walk_1.png

By checking the Walk mode checkbox, the view will start to move/walk. The speed can be adjusted as well.

_images/walk_2.png

Multiple models mode

Multiple modeles mode displays all 3D models, both from paternal and maternal, and from all chromosomes/regions. There are two dropdown menus to change the color of each model, and toggle the display of each model. Also you can change the shape type to line, tube or ball.

_images/mul_1.png

The image below shows while we changed shape type to ball:

_images/mul_2.png

Screenshot

Use the screenshot button (shown below) to take a screenshot, the generated screenshot will be the same as the time when you clicked the button.

_images/screen.png

Try genomics 3D structure in AR mode

  • Please use your phone’s camera point the QR code in the image below, Safari will popup and try to open our website, and will ask if allow to use the camera, please Allow
_images/patt_qr.png
  • then point the camera again to the Marker part (St. Louis Arch), and you will see the 3D structure in AR.
_images/g3d_ar.jpg

g3dtools

A tool for operating .g3d (genome 3D structure) format.

Require: Python (Recommend version 3 and above).

example input, 6 columns bed-like text file:

chr7    16760000     -14.3866688728  -36.3919302029  19.8483965881   m
chr7    16760000     -24.9116268071  50.0521268287   9.91073185128   p
chr7    25160000     -10.1170055526  -34.8975763469  20.2401719179   m
chr7    25160000     -21.8210915649  27.1128556621   13.4856945965   p
chr7    33540000     -4.11059384846  -54.4940083464  4.21321135564   m
chr7    33540000     -12.0040359857  31.5960497183   26.6925954134   p
chr7    41940000     5.75342635105   -55.4976428728  8.65307697332   m
chr7    41940000     -23.7372022413  36.0614692267   31.919119243    p
chr7    50320000     -10.7099779927  -38.0214001171  25.8308473821   m
chr7    50320000     -28.5142098162  26.6468499001   28.8634805533   p
chr7    26200000     -11.5800097945  -37.9903257744  16.2461100893   m
chr7    26200000     -15.9552426623  27.016940724    17.5722080595   p
chr7    27260000     -14.1883124179  -44.7860807973  12.4104162757   m
chr7    27260000     -20.0857754297  30.9204143041   18.4774635708   p
chr7    28300000     -18.0160836669  -39.398544495   12.811858164    m
chr7    28300000     -14.9383020843  39.1464516779   17.3743509519   p
chr7    29360000     -11.8032470923  -47.3595095319  13.2828128833   m
chr7    29360000     -12.2445277916  41.2431968179   14.8844908717   p
chr7    30400000     -12.8674349856  -45.0752589744  9.15498568359   m

columns are:

  • chromosome
  • start position
  • X (coordinates in 3D)
  • Y
  • Z
  • haplotype (optional), m for maternal, p for paternal, s for shared, if omitted, s will be used

Generate a new .g3d file using the format listed above

g3dtools load ../test/test.g3d.bed.gz -o ../testOut/test -s 2,3,4,5,6,7,8,9,10

Generate a new .g3d file from .3dg format

Input a file with high resolution, let the tool calculate lower resolutions:

g3dtools 3dg ../test/GSM3271347_gm12878_01.impute3.round4.clean.3dg.txt.gz -o ../testOut/GSM3271347_gm12878_01.impute3.round4.clean -s 2,3,4,5,6,7,8,9,10

or prepare different resolution files in advance:

Query

By region:

g3dtools query testOut/test.g3d -c chr7 -s 27053397 -e 27373765

change resolution:

g3dtools query testOut/test.g3d -c chr7 -s 27053397 -e 27373765 -r 100000

when resolution not exists:

g3dtools query testOut/test.g3d -c chr7 -s 27053397 -e 27373765 -r 130000
[Query] Error, resolution 130000 not exists for this file,
available resolutions: [20000, 40000, 60000, 80000, 100000, 120000, 140000, 160000, 180000, 200000]

JavaScript API

Javascript API for reading .g3d genomic 3D structure files.

Installation

Requires Node.

npm install g3djs

Examples

Example code below to fetch data from a .g3d file hosted on a webserver.

import G3dFile from 'g3djs';

const url = 'https://wangftp.wustl.edu/~dli/tmp/test.g3d';
const file = new G3dFile({ url });
// get metadata
// metadata contains information about genome assembly, dataset name, resolutions etc.
file.readHeader().then(() => console.log(file.meta));

// get 3D data from a specific region, under a specific resolution
// parameters: chrom, start, end, resolution
file.readData('chr7', 27053397, 27373765, 20000).then(data => console.log(data));

// get data for a chromsome, 200000 is the resolution
file.readDataChromosome('chr7', 200000).then(data => console.log(data));

// get data for the genome, 200000 is the resolution
file.readDataGenome(200000).then(data => console.log(data));

Indices and tables