Hub Track Database Definition (v3)

There are a number of different filters available for bigBed data. See the Filters Quick Start guide for more info.

filterValues.<fieldName> is used to enable filtering by specified values within a field. It can be used on fields that can contain one text value or a list of comma-separated values of text, like "classA,classB". Usually these are category names. The option requires at least one value to filter on.

Every individual possible value that can ever occur in the field must be passed in a comma separated list. You will then be able to select those values as categories, choosing to display only items that belong to one, any, or at least one of the selected values. By default, the user can select multiple values from this list and the filter lets pass any features with at least one of these values (multiple).

In order to choose the default selection behavior, the optional parameter filterType.<fieldName> may be used. If this parameter is not passed, by default the selection will be set to "one or more match" which is the same as having filterType.fieldName multiple. If the user should only be able to select a single value, single can be passed instead. Another option, multipleListAnd, means that the user can select multiple categories, but the filter will let pass only features where all of these categories are present.

Both single and multiple have "list" options. These options split the bigBed field values by commas, meaning that they should only be used when items can contain multiple values at once in the desired filter field. For example, if my data is classifying variants, and they can only be a SNV, insertion, or deletion, I will want to use single and multiple. However, if instead the filter will be on a field classifying functional impact, there can be many values for each item. For example, variant rs11541299, which is both a synonymous variant and a coding sequence variant. In this case, I would want to use one of the "list" options. Most simply singleList or multipleList, or one of the additional varieties of multipleList depending on the desired options.

multipleListOr and multipleListAnd both still let the user override the type of combination manually in the user interface with a radio button. If you specify multipleListOnlyOr or multipleListOnlyAnd then the radiobutton is suppressed and the user cannot choose between the options anymore. This can be used in cases where by the nature of the field, it makes little sense to offer the OR or AND search.

You can also choose which values to have selected by default using the filterValuesDefault.<fieldName> parameter. It can take a comma separated list just like filterValues.<fieldName>, and any items included will be automatically selected. Not that the values need to be present in both settings.

The labels in the menu shown to the user can be configured to display a different name/label than the one present in the bigBed field. This can be helpful when the data values are written in short form, but you want a longer more descriptive name to show up in the UI. The format for this substitution is as follows:

filterValues.fieldName fieldValue1|alternativeName1,fieldValue2|alternativeName2...

E.g. if the value in the bigBed field is AML, a setting like Acute Myeloid Leukemia|AML will show Acute Myeloid Leukemia in the user interface but will lead to the value AML being searched in the bigBed field. This can reduce the size of the bigBed file a lot. See example below for more information.

Notes:

• Currently, all values must be stated individually
• Value names must match exactly
• By default, all bed tracks that are at least bed5 will have a score filter. Enabling any of the filter*.<fieldName> filter settings will disable that default filter
• In order for filters to work, the track must be type bigBed N + or type type bigBed N . a "+" (for bigBed+ tracks) or a "." (for non-extended bigBed tracks) is required
• Filters are not supported in bed3 or bed4 files, even bed 3+x. The file must be at least a bed5
• There should not be any white spaces between declared items after commas, e.x. "itemOne,itemTwo,itemThree"
• The default label can be customized with the filterLabel.<fieldName> parameter
• When using filter values in a field that incudes commas, an additional comma can be used to escape it. E.x. "fieldOne,fieldTwo,,fieldTwo,fieldThree"

Examples:

    filterValues.OddEven Odd,Even

In this simple example, we are applying filterValues.<fieldName> to the OddEven field, which designates either "Even" or "Odd". We can then filter the data using the OddEven field with a drop-down menu displayed on the track controls page to just evens or odds. As there is no filterType, the user can also show both evens and odds at the same time.

    filterValues.OddEven Odd,Even
    filterType.OddEven singleList

In this follow up example, we are passing the filterType.fieldName singleList parameter, which means that only one item in the OddEven field can be chosen, in this case "Odd" or "Even". This removes the default that allows multiple selections.

    filterValues.OddEven Odd,Even
    filterType.OddEven singleList
    filterValuesDefault.OddEven Odd

In this third example, we have added the filterValuesDefault.fieldName parameter as well. Now the default filter when the hub is loaded will have the Odd value preselected.

    filterValues.annotationType DNA-BR,AS,BS,BSi

In this example the filter is being applied to multiple values in the annotationType field. We can then select from these values in the annotationType field with a drop-down menu displayed on the track settings page, and display only items that match our selections. The selection choices will let us match one, all, or any combination of the supplied values.

    filterValues.annotationType DNA-BR|DNA-binding region,AS|active site,BS|beta strand,BSi|binding site

In this follow up to the previous question, we have changed the name of the items that show up in the drop down menu to be more descriptive than the dense file format values. This means that if we wanted to only see items with annotationType of DNA-BR, we would select DNA-binding region from the interface menu.