LocusZoom

LocusZoom allows you to combine different data layers (e.g., association data and LD information) within a single data layer layout using data_operations. This is essential when a single plot element depends on information from multiple sources.

Data operations consist of two main types:

1. Fetch operations: Used to retrieve data. You can specify dependencies using the syntax some_request(dependency_name). For example, ld(assoc) tells LocusZoom to wait until the assoc data is retrieved before requesting ld data. LocusZoom automatically parallelizes requests that have no dependencies.
2. Joins (Data functions): Used to merge multiple sets of records into a single list. You can use built-in joins like left_match, inner_match, and full_outer_match, or register custom functions in LocusZoom.DataFunctions.

Note: Everything listed in data_layer.namespace automatically triggers a retrieval request. You only need to explicitly modify fetch.from if you need to define dependencies (e.g., ld(assoc)).

{
    namespace: { 'assoc': 'mystudy', 'ld': 'some_ld' },
    data_operations: [
        {
            type: 'fetch',
            from: ['assoc', 'ld(assoc)'],
        },
        {
            type: 'left_match',
            name: 'assoc_plus_ld',
            requires: ['assoc', 'ld'],
            // Specify field names for the join
            params: ['assoc:position', 'ld:position2'], 
        },
    ]
}

LocusZoom allows different data layers to communicate so that selecting an element in one panel highlights related elements in another. This is achieved through a match directive.

1. Opt-in: Add a match object to your layer configuration.
2. Broadcasting: A layer with match.send will broadcast the value of a specific field when an element is selected.
3. Receiving: A layer with match.receive will examine its data points. If a point's specified field matches the broadcast value, it is tagged with the internal field lz_is_match.
4. Rendering: Use the lz_is_match field in your layout directives (e.g., color, size, shape) to visually distinguish matched points.

Note: For performance, only one field can be broadcast at a time, and only a single value is broadcast across all layers.

To trigger matching from outside the plot, you can manually update the plot state using plot.applyState({lz_match_value: your_value_here}).

{
  ...options,
  // A layer can send and receive to respond to its own events
  match: { send: '{{namespace[access]}}target', receive: '{{namespace[access]}}target' },
  color: [
    {
      field: 'lz_is_match', // Use the internal tag to trigger custom rendering
      scale_function: 'if',
      parameters: {
        field_value: true,
        then: '#ff0000',
      },
    },
  ],
}

When an adapter requests data, it follows a specific sequence of methods to construct the query, handle caching, and transform the raw response into a format suitable for rendering. Developers can override these methods to customize how data is fetched and processed.

The execution order is roughly:

1. getData(plot_state, ...dependent_data): The entry point.
2. _buildRequestOptions(plot_state, ...dependent_data): Prepares request parameters.
3. _getCacheKey(request_options): Determines the cache identifier.
4. _performRequest(request_options): Executes the network request.
5. _getURL(request_options): Generates the target URL.
6. _normalizeResponse(raw_response, options): Parses and transforms raw data (e.g., converting columnar to row-based formats).
7. _annotateRecords(records, options): Performs user-specified cleanup like field renaming, filtering, or adding calculated fields.
8. _postProcessResponse(records, options): Final transformation, typically used for adding field prefixes (e.g., assoc:id).

getData(plot_state, ...dependent_data)
    _buildRequestOptions(plot_state, ...dependent_data)
    _getCacheKey(request_options)
    _performRequest(request_options)
        _getURL(request_options)
    // Parse JSON, convert columnar data to rows, etc
    _normalizeResponse(raw_response, options)
        cache.add(records)
    // User-specified cleanup of the parsed response fields.
    _annotateRecords(records, options)
    // Usually not overridden: applies prefixes and simplifies fields
    _postProcessResponse(records, options)

Once data is retrieved, it often needs to be transformed into the row-based format ([{field: value}]) expected by LocusZoom data layers.

_normalizeResponse(raw_response, options)

Use this to convert non-standard responses into a standard format.

• Columnar to Row conversion: If your source provides data in a column-oriented format (e.g., {a_field: [1], other_field: [1]}), this method can transform it into the required row-based format ([{a_field: 1, other_field: 1}]). Note that the default adapter attempts to do this automatically for some sources.

_annotateRecords(records, options)

Use this for high-level data manipulation after parsing. Common use cases include:

• Renaming fields: e.g., changing pValue to log_pvalue.
• Filtering: Removing records based on specific criteria.
• Calculated fields: Generating new fields on the fly, such as creating a variant marker field by concatenating chromosome:position_ref/alt if the API doesn't provide it.
• Toggling datasets: Using plot.state to decide which subset of data to return from a single large response (useful for creating cheap toggles via the set_state toolbar widget).