# dash_bioIdeogram Examples and Reference

see Ideogram in action.

## Ideogram

An example of a default Ideogram component without any extra properties.

Select which chromosomes to display on the ideogram below:
×1
×2
×3
×4
×5
×6
×7
×8
×9
×10
×11
×12
×13
×14
×15
×16
×17
×18
×19
×20
×21
×22
×
You have not selected a chromosome.

    library(dashBio)
    library(readr)

    app <- Dash$new()

    chromosomes <- c(as.character(seq(1:22)), "X", "Y")

    listOfOptions <- lapply(chromosomes, function(x) {
        list(label = x, value = x)
    })

    app$layout(htmlDiv(list(
        'Select which chromosomes to display on the ideogram below:',
        dccDropdown(
            id='my-default-displayed-chromosomes',
            options = listOfOptions,
            multi=TRUE,
            value = listOfOptions
        ),
      dashbioIdeogram(
            id='my-default-ideogram'
      ),
      htmlDiv(id='my-default-ideogram-rotated')
    )))

    app$callback(
        output = list(id = 'my-default-ideogram', property = 'chromosomes'),
        params = list(input(id = 'my-default-displayed-chromosomes', property = 'value')),
        update_ideogram <- function(value) {
            return(value)
        }
    )

    app$callback(
        output(id = "my-default-ideogram-rotated", property = "children"),
        params = list(input(id = "my-default-ideogram", property = "rotated")),
        update_ideogram_rotated <- function(rot) {
            if (rot == TRUE) {
                return("You have selected a chromosome.")
            }
            else {
                return("You have not selected a chromosome.")
            }
        }
    )

    app$run_server()

## Customization

### Height/Width

Change the size of the chromosomes in your ideogram.

    library(dashBio)

    dashbioIdeogram(
        id = "ideogram-size",
        chrHeight = 800,
        chrWidth = 200
    )

### Annotations

Display annotations that are loaded from a JSON file.

    library(dashBio)

    dashbioIdeogram(
        id = "ideogram-annotations",
        chromosomes = list("X", "Y"),
        annotationsPath = "https://eweitz.github.io/ideogram/data/annotations/SRR562646.json"
    )

### Rotatability

Disable rotation of the chromosome upon clicking on it.

    library(dashBio)

    dashbioIdeogram(
        id = "ideogram-rotation",
        rotatable = FALSE
    )

### Orientation

Display chromosomes horizontally or vertically.

    library(dashBio)

    dashbioIdeogram(
        id = "ideogram-orientation",
        rotatable = "horizontal"
    )

### Brush

Highlight a region of the chromosome by adding a brush.

    library(dashBio)

    dashbioIdeogram(
        id = "ideogram-brush",
        orientation = "horizontal",
        chromosomes = list("X"),
        brush = "chrX:1-10000000"
    )

## Ideogram Properties

> Our recommended IDE for writing Dash apps is Dash Enterprise's Data Science Workspaces, which has typeahead support for Dash Component Properties. Find out if your company is using Dash Enterprise.

`id` (character; required): The ID used to identify this component in Dash callbacks and used to identify Ideogram instances.

`style` (named list; optional): The component's inline styles.

`className` (character; optional): The CSS class of the component wrapper.

`accessToken` (character; optional): OAuth 2.0 access token. Enables authentication and authorization. This can be useful for controlling access to private annotation data.

`ancestors` (named list; optional): A map associating ancestor labels to colors. Used to color chromosomes from different ancestors in polyploid genomes.

`annotations` (list where each item is a named list; optional): A list of annotation objects. Annotation objects can also have a name, color, shape, and track index. At the moment there is more keys specified and the docs need updating.

`annotations` is a list where each item is a named list with keys:

- `chr` (character; optional)

- `color` (character; optional)

- `index` (numeric; optional)

- `name` (character; optional)

- `shape` (character; optional)

- `start` (numeric; optional)

- `stop` (numeric; optional)

`annotationHeight` (numeric; optional): Not used if annotationsLayout is set to "overlay". The height of histogram bars or the size of annotations tracks symbols.

`annotationsColor` (character; default `'#F00'`): The color of each annotation.

`annotationsLayout` (a value equal to: 'tracks', 'histogram' or 'overlay'; default `'tracks'`): Layout of ideogram annotations. One of "tracks", "histogram", or "overlay". "tracks": display annotations in tracks beside each chromosome. "histogram": display annotations in a histogram. Clusters annotations by location. Each cluster/bin is shown as a bar, the height of which represents the number of annotations on genomic range. "overlay": display annotations directly over chromosomes.

`annotationsPath` (character; optional): An absolute or relative URL directing to a JSON file containing annotation objects (JSON).

`annotationsData` (character; optional): Use this prop in a dash callback to return annotationData when hovered. It is read-only, i.e., it cannot be used with dash.dependencies.Output but only with dash.dependencies.Input.

`annotationTracks` (unnamed list of named lists; optional): A list of objects with metadata for each track, e.g., id, display name, color, shape.

`assembly` (character; optional): Default: latest RefSeq assembly for specified organism. The genome assembly to display. Takes assembly name (e.g., "GRCh37"), RefSeq accession (e.g., "GCF_000306695.2"), or GenBank accession (e.g., "GCA_000005005.5").

`barWidth` (numeric; default `3`): Pixel width of histogram bars. Only used if annotationsLayout is set to "histogram".

`brush` (character; optional): Genomic coordinate range (e.g., "chr1:104325484-119977655") for a brush on a chromosome. Useful when ideogram consists of one chromosome and you want to be able to focus on a region within that chromosome, and create an interactive sliding window to other regions.

`brushData` (named list; optional): A dash callback that is activated when the 'brush' prop is used. It will return an dictionary like so: {'start': <value>, 'end': <value>, 'extent': <value>} where start is the left most edge, end is right most edge, and extent is the total width of the brush. It is read-only, i.e., it cannot be used with dash.dependencies.Output but only with dash.dependencies.Input.

`brushData` is a named list with keys:

- `end` (character; optional)

- `extent` (character; optional)

- `start` (character; optional)

`chrHeight` (numeric; default `400`): The pixel height of the tallest chromosome in the ideogram.

`chrMargin` (numeric; default `10`): The pixel space of margin between each chromosome.

`chrWidth` (numeric; default `10`): The pixel width of each chromosome.

`chromosomes` (unnamed list of characters | named list; optional): A list of the names of chromosomes to display. Useful for depicting a subset of the chromosomes in the genome, e.g., a single chromosome. If Homology (between two different species): Ex: chromosomes={ 'human': ['1'], 'mouse': ['4'] } General case to specify specific chromosomes: Ex: chromosomes=['1', '2'].

`chromosomeScale` (a value equal to: 'absolute' or 'relative'; optional): Used when comparing multiple genomes. "absolute": chromosomes will be scaled by base pairs in each genome. "relative": first chromosome in each genome is of equal length; subsequent chromosomes will be scaled relative to the first chromosome.

`container` (character; optional): CSS styling and the id of the container holding the Ideogram in react-ideogram.js, this is where all the d3 magic happens.

`dataDir` (character; default `'https://unpkg.com/ideogram/dist/data/bands/native/'`): Absolute or relative URL of the directory containing data needed to draw banded chromosomes. You will need to set up your own database to grab data from a custom database.

`demarcateCollinearChromosomes` (logical; optional): Whether to demarcate colllinear chromosomes. Puts a dark border around the perimeter of each track-chromosomes block in track sets for chromosomes arranged in collinear geometry.

`geometry` (a value equal to: 'collinear' or 'parallel'; optional): The arrangement of chromosomes. "collinear": arrange all chromosomes in one line. "parallel": arrange chromosomes to be parallel to one another.

`heatmaps` (list where each item is a named list; optional): Array of heatmap objects. Each heatmap object has a key string and a thresholds array. The key property specifies the annotations key value to depict in the heatmap. The thresholds property specifies a list of two-element "threshold" lists, where the first element is the threshold value and the second is the threshold color. The threshold values are a list of ranges to use in coloring the heatmap. Threshold values are specified in ascending order.

`heatmaps` is a list where each item is a named list with keys:

- `key` (character; optional)

- `thresholds` (unnamed list of unnamed lists; optional)

`histogramScaling` (a value equal to: 'absolute' or 'relative'; optional): Scaling of histogram bars height Only used if annotationsLayout is set to "histogram". One of "absolute" or "relative". "absolute": sets bar height relative to tallest bar in all chromosomes. "relative": sets bar height relative to tallest bar in each chromosome.

`homology` (named list; optional): Used to compare two chromosomes. The keys "chrOne" and "chrTwo" represent one chromosome each. Organism is the taxID or name. Start is an array, containing start one and start two, in this order. Stop is an array, containing stop one, and stop two, in this order. Ex: homology={ "chrOne": { organism": "9606", "start": [50000, 155701383], "stop": [900000, 156030895] }, "chrTwo": { organism": "10090", "start": [10001, 50000000], "stop": [2781479, 57217415] } }.

`homology` is a named list with keys:

- `chrOne` (named list; optional)

  `chrOne` is a named list with keys:

  - `organism` (character; required)

  - `start` (unnamed list of numerics; optional)

  - `stop` (unnamed list of numerics; optional)

- `chrTwo` (named list; optional)

  `chrTwo` is a named list with keys:

  - `organism` (character; required)

  - `start` (unnamed list of numerics; optional)

  - `stop` (unnamed list of numerics; optional)

`filterable` (logical; optional): Whether annotations should be filterable or not.

`fullChromosomeLabels` (logical; optional): Whether to include abbreviation species name in chromosome label. Used for homology.

`legend` (list where each item is a named list; optional)

`legend` is a list where each item is a named list with keys:

- `name` (character; optional)

- `rows` (list where each item is a named list; optional)

  `rows` is a list where each item is a named list with keys:

  - `color` (character; optional)

  - `name` (character; optional)

  - `shape` (a value equal to: 'circle', 'triangle' or 'rectangle'; optional)

`organism` (character | numeric; default `'human'`): Organism(s) to show chromosomes for. Supply organism's name as a string (e.g., "human") or organism's NCBI Taxonomy ID (taxid, e.g., 9606) to display chromosomes from a single organism, or an array of organisms' names or taxids to display chromosomes from multiple species.

`orientation` (a value equal to: 'vertical' or 'horizontal'; optional): The orientation of chromosomes on the page.

`perspective` (a value equal to: 'comparative'; optional): Use perspective: 'comparative' to enable annotations between two chromosomes, either within the same organism or different organisms. Used for homology.

`ploidy` (numeric; default `1`): The ploidy - number of chromosomes to depict for each chromosome set.

`ploidyDesc` (unnamed list of named lists; optional): Description of ploidy in each chromosome set in terms of ancestry composition.

`rangeSet` (unnamed list of named lists; optional): List of objects describing segments of recombination among chromosomes in a chromosome set.

`resolution` (numeric; optional): The resolution of cytogenetic bands to show for each chromosome. The quantity refers to an approximate value in bands per haploid set (bphs). One of 450, 550, or 850.

`rotatable` (logical; default `TRUE`): Whether chromosomes are rotatable on click.

`rotated` (logical; optional): Dash callback that returns TRUE if rotated, and FALSE if not.

`rows` (numeric; default `1`): Number of rows to arrange chromosomes into. Useful for putting ideogram into a small container, or when dealing with genomes that have many chromosomes.

`sex` (a value equal to: 'male' or 'female'; optional): The biological sex of the organism. Useful for omitting chromosome Y in female animals. Currently only supported for organisms that use XY sex-determination.

`showAnnotTooltip` (logical; default `TRUE`): Whether to show a tooltip upon mousing over an annotation.

`showBandLabels` (logical; default `FALSE`): Whether to show cytogenetic band labels, e.g., 1q21.

`showChromosomeLabels` (logical; default `TRUE`): Whether to show chromosome labels, e.g., 1, 2, 3, X, Y.

`showFullyBanded` (logical; default `TRUE`): Whether to show fully banded chromosomes for genomes that have sufficient data. Useful for showing simpler chromosomes of cytogenetically well-characterized organisms, e.g., human, beside chromosomes of less studied organisms, e.g., chimpanzee.

`showNonNuclearChromosomes` (logical; default `FALSE`): Whether to show non-nuclear chromosomes, e.g., for mitochondrial (MT) and chloroplast (CP) DNA.

`loading_state` (named list; optional): Object that holds the loading state object coming from dash-renderer.

`loading_state` is a named list with keys:

- `component_name` (character; optional): Holds the name of the component that is loading.

- `is_loading` (logical; optional): Determines if the component is loading or not.

- `prop_name` (character; optional): Holds which property is loading.

## Example Data

- UCSC Table Browser