DOCSEARCHbyAlgolia
Submit Docs

Ideogram.js

repository·master·Indexed 43 days ago

https://github.com/eweitz/ideogram

A JavaScript library for chromosome visualization on the web. Ideogram.js allows developers to draw and animate genome-wide datasets for various eukaryotes, supporting complex biological features such as ploidy, recombination, and homology. It provides integration support for Angular, React, Vue, R, and Jupyter Notebooks, and supports multiple annotation layouts including tracks, heatmaps, histograms, and overlays.

Tokens
8.4K
Snippets
26
Records
39
Agent score
55%

What's inside Ideogram

  1. Understand Ideogram native annotation formats

    master

    Ideogram.js supports native annotation formats that are distinguished implicitly by their data layout rather than explicit configuration properties. These formats are defined by two dimensions: Density and Origin.

    Density

    • Dense: Each genomic feature (e.g., a gene) contains annotation data for all tracks.
    • Sparse: Each genomic feature contains annotation data for only one specific track.

    Origin

    • Client: Annotation properties are passed as parameters within the Ideogram configuration.
    • Server: Annotation properties are provided as keys within the annotation data file itself.

  2. Configure annotation layouts with annotationsLayout

    master

    The annotationsLayout option determines how genomic annotations are visually presented relative to the chromosomes.

    Available options:

    • 'tracks' (Default): Displays annotations in tracks beside each chromosome. Useful for categorizing data (e.g., pathogenic vs. benign).
    • 'span': Similar to tracks, but lays out annotations in spanning tracks beside each chromosome.
    • 'heatmap': Plots individual annotations in a heatmap beside each chromosome. Requires use with the heatmaps option.
    • 'heatmap-2d': Displays a two-dimensional z-heatmap beside a single chromosome to visualize raw data summarized by the heatmap layout.
    • 'histogram': Clusters annotations by location into bins, where the bar height represents the number of annotations in that genomic range. Ideal for summarizing large datasets (1000+ features).
    • 'overlay': Draws annotations directly over the chromosomes. This is the most space-efficient method.
    // Example: Using histogram layout
var ideogram = new Ideogram({
  organism: 'human',
  annotationsLayout: 'histogram',
  barWidth: 3
});

  3. Choose an annotation format based on use case

    master

    Ideogram supports four broad annotation formats. Choose the format that best balances your requirements for configuration complexity, data transfer speed, and information density.

    FormatControlConfigurationTransferInformationUsabilityDeveloper capacityExample scenario
    Sparse clientDynamicComplexFastLowInteractive and glanceableFront-endClinical variation
    Sparse serverStaticSimpleFastLowEasy and glanceableBack-endClinical variation
    Dense clientDynamicComplexSlowHighInteractive and richFront-endGene expression research
    Dense serverStaticSimpleSlowHighEasy and richBack-endGene expression research

  4. Format of Ideogram annotation sets

    master

    Ideogram.js uses a compact JSON format to load sets of annotations. To minimize file size, the format uses a schema-on-read approach where a top-level keys array defines the meaning of elements within the annotation arrays. Annotations are grouped by chromosome (chr) to avoid repeating chromosome names for every entry.

    Required Fields: Every annotation array must contain at least three elements:

    1. name
    2. start (position)
    3. length

    Optional Fields: Annotations may include integer values representing:

    • Track index: The ordinal position of the track where the annotation should appear.
    • Filter index: An index mapping to an array of filter objects (containing metadata like label and a string identifier) used for DOM selection or URL filtering.
    {
  "keys": ["name", "start", "length", "expression-level", "gene-type"],
  "annots": [
    {
      "chr": "1",
      "annots": [
        ["MTOR", 11106535, 155972, 5, 5],
        ["F5", 169514166, 72422, 4, 2]
      ]
    },
    {
      "chr": "2",
      "annots": [
        ["APOB", 21001429, 42644, 2, 5],
        ["CASP8", 201233443, 54268, 6, 5]
      ]
    }
  ]
}

  5. Install Ideogram

    master

    You can install Ideogram using several methods depending on your project environment:

    CDN (Direct Link)

    For simple web pages, link directly to the latest release via jsDelivr:

    <script src="https://cdn.jsdelivr.net/npm/ideogram@1.53.0/dist/js/ideogram.min.js"></script>

    npm

    For modern JavaScript applications, install via npm:

    npm install ideogram

    Then import it into your application:

    import Ideogram from 'ideogram';

    Local Clone

    To explore examples locally, clone the repository into your web server's document root:

    git clone https://github.com/eweitz/ideogram.git
    npm install ideogram

  6. Install and run the Ideogram Angular example

    master

    To run the basic Ideogram integration example in an Angular environment, clone the repository, navigate to the Angular example directory, install dependencies, and start the development server.

    1. Clone the repository.
    2. Navigate to examples/angular.
    3. Run npm install to install dependencies.
    4. Run ng serve to start the Angular application.
    5. Open your browser to http://localhost:4200 to view the running example.
    git clone origin https://github.com/eweitz/ideogram
cd ideogram/examples/angular
npm install
ng serve

  7. Instantiate Ideogram with the Ideogram class

    master

    To create a chromosome visualization, instantiate the Ideogram class by passing a configuration object to its constructor. This object defines the organism, genome assembly, orientation, and any annotation data to be displayed.

    var ideogram = new Ideogram({
  organism: 'human',
  annotations: [{
    name: 'BRCA1',
    chr: '17',
    start: 43044294,
    stop: 43125482
  }]
});

  8. Run Ideogram in Jupyter

    master

    To run the Ideogram demonstration in a Jupyter environment, clone the repository, navigate to the Jupyter examples directory, and launch the notebook server. Once the notebook is open in your browser, open ideogram.pynb and execute the cells by clicking 'Run' twice.

    git clone origin https://github.com/eweitz/ideogram
cd ideogram/examples/jupyter
jupyter notebook

  9. Run the Ideogram React example

    master

    To run the basic integration example of Ideogram with React, clone the repository, navigate to the React example directory, install dependencies, and start the development server.

    git clone https://github.com/eweitz/ideogram
cd ideogram/examples/react
npm install
npm start

  10. Basic Usage of Ideogram

    master

    To initialize an Ideogram instance, create a new Ideogram object and provide a configuration object. At a minimum, you should specify the organism (e.g., 'human') and an array of annotations.

    Annotations are defined by a name, a chromosome (chr), a start position, and a stop position.

    Ideogram supports various annotation types including histograms, heatmaps, overlays, and spanning annotations, which can be layered in tracks.

    <head>
  <script src="https://cdn.jsdelivr.net/npm/ideogram@1.53.0/dist/js/ideogram.min.js"></script>
</head>
<body>
<script>
  var ideogram = new Ideogram({
    organism: 'human',
    annotations: [{
      name: 'BRCA1',
      chr: '17',
      start: 43044294,
      stop: 43125482
    }]
  });
</script>
</body>

  11. Integrate Ideogram with Frameworks and Data Science Platforms

    master

    Ideogram is designed to be embedded as a reusable component. Beyond vanilla JavaScript, it provides integration support for:

    • JavaScript Frameworks: Angular, React, and Vue.
    • Data Science Platforms: R and Jupyter Notebook.

    Specific examples for these integrations can be found in the repository's examples/ directory.

  12. Install and run the Ideogram Vue example

    master

    To run the basic Ideogram integration example for Vue, clone the repository, navigate to the Vue example directory, install dependencies, and start the development server.

    1. Clone the repository.
    2. Navigate to ideogram/examples/vue.
    3. Run npm install to install dependencies.
    4. Run npm run dev to start the server.
    5. Open your browser to http://localhost:8080 to view the running example.
    git clone https://github.com/eweitz/ideogram
cd ideogram/examples/vue
npm install
npm run dev