Filtering functions

Discussion

Functions are aggregated information items that can be used in Filtration procedures as well as filtering properties. Difference between application of an enumerated property and application of a function is in parameters: the function requires proper settings for them.

Up to now all functions behave as multiset property: even if result is True value, there is no reason to keep False value of rest of variants in dataset.

The list and format of function parameters are specific for the function. Each parameter value must be data structure in JSON format. So the Front End application needs to handle each function in a specific way.

The logic of function usage is as following:

  • API requests ds_stat and dtree_stat deliver on the client Property Status structure for all applicable functions. Thus the Front End gets information of placement of functions in list of filtering properties, and so called environment information for each function.

  • The user can select function and set its parameters to build condition; the Front End needs to support this process with use of environment information

  • When parameters a set, the request statfunc delivers on the client Property Status structure for this function, with information about available value variants. Thus the user can make proper selection of variants and complete the condition (see Condition descriptor for details of condition format).

Since work with functions is a complex one, there might be additional requirements for Front End application to provide support of necessary "short cuts":

  • function environment should be used to set "standard" configurations of function parameters;

  • in cases when list of function values is expected (for example if value is single True), these values should be pre-selected in interface without extra user click

Most part of currently available functions implement functionality dealing with zygosity properties of variants. See Notes on Zygosity for explanations

Examples are given in form of Python dialect used in Decision Tree Syntax Reference.

Function reference

GeneRegion()

sub-type: "region"

Parameter:

locus, location string

Environment properties: none

Values: ["True"]

Function allows the user to define simple string representation for the following options:

  • chromosome

  • position or diapason of positions

  • optional gene or list of genes

These options are put into string with ':` as separator. (Separator for list of genes is ',').

Examples:

GeneRegion(locus = "chr1:6424820") in {True}
GeneRegion("chr1:6424820-6424920") in {True}
GeneRegion("chr1::ESPN,HES2") in {True}

Additional interface requirement:

The user interface needs to keep check for "True" value selection on.

Inheritance_mode()

sub-type: "inheritance-z"

Parameters:

problem_group, optional [ list of id for samples in case ]

Environment properties:

“family”: [ list of id for all samples in case, first is proband ]
“affected”: [ list of id, default problem group ]
“available”: [ list of all available values ]

Values:

["Homozygous Recessive", "X-linked", "Autosomal Dominant", "Compensational"]

Function selects variants with Standard Zygosity Scenarios if problem group is defined.

Examples

Inheritance_mode() in {"Homozygous Recessive", "X-linked"}
Inheritance_mode(problem_group = ["bgm9001a1", "bgm9001u2"]) in {"Compensational"}

Notes:

  • default problem group is preset

  • function value X-linked is actual only if case includes a male sample

Additional interface requirement:

There should be an easy way to reset value of problem group to default one.

Facts useful for debug purposes

  • for fixed problem group variant sets of types "Homozygous Recessive" and "X-linked" never intersect; variants from chromosome X present in the first set only if there is no a male sample in case

  • for different problem groups variant sets of type "Autosomal Dominant" never intersect; the same is true for type "Compensational"

Custom_Inheritance()

sub-type: "custom-inheritance-z"

Parameters:

scenario, scenario structure

Environment properties:

“family”: [ list of id for all samples in case, first is proband ]
“affected”: [ list of id, default problem group ]

Values: ["True"]

The function selects variants by a fixed Zygosity Scenario.

In terms of functionality it is an extension of Inheritance_Mode() function.

Example

Custom_Inheritance(scenario =
    {“2”: ["bgm9001a1", "bgm9001u2"], “1-0”: ["bgm9001u1"]}}) in {True}

Additional interface requirements:

There should be an easy way to reset scenario to one of standard scenarios with default problem group.

The user interface needs to keep check for "True" value selection on.

Compound_Heterozygous()

sub-type: "comp-hets"

Parameters:

approx, optional gene approximation variant, string
state, optional decision tree state label, string

Environment properties:

"trio-variants": [ list of id for subject samples of trio, strings ]
"approx-modes": [ list of available gene approximation variants, strings ]
labels: [ list of available decision tree state labels, strings ]
Values:

list equals to trio-variants environment property

The function detects compound heterozygous variants for all trio presenting in the case of dataset. Function is available only if (at least one, usually one) trio is included in case, i.e. environment property trio-variants is nonempty.

Special notation: if proband is subject of trio, "Proband" is used as identifier of trio, otherwise trio is identified by id of its subject.

Default value for approx parameter is the first item in approx-modes environment property.

The parameter state can be either null or value from labels environment property.

In common context labels is empty, and state parameter can be only null or undefined. So the detection procedure is run on the current state of variants filtering process.

Different situation can happen only in case of decision tree, and only if there is а definition of label in code before function evaluation. In this case detection procedure is run on labeled state (decision tree point) of filtering process.

Examples

Compound_Heterozygous() in {Proband}
Compound_Heterozygous(approx = "rough", state = "label1") in {Proband, bgm4321u3}

Additional interface requirements:

In case if proband has trio in case, user interface needs to keep check for "Proband" value selection on.

Compound_Request()

sub-type: "comp-request"

Parameters:

request, compound request structure
approx, optional gene approximation variant, string
state, optional decision tree state label, string

Environment properties:

“family”: [ list of id for all samples in case, first is proband ]
“affected”: [ list of id, default problem group ]
"approx-modes": [ list of available gene approximation variants, strings ]
labels: [ list of available decision tree state labels, strings ]

Values: ["True"]

The function evaluates compound request.

In terms of functionality it is a wide extension of Compound_Heterozygous() function

All comments on parameters approx and state, environment properties approx-modes and labels from function Compound_Heterozygous() are actual in this context.

Example

Compound_Request(request = [
    [1, {“2-1”: ["bgm9001a1", "bgm9001u2"], “0”: ["bgm9001u1"]],
    [1, {“2-1”: ["bgm9001a1", "bgm9001u1"], “0”: ["bgm9001u2"]]]) in {True}

The example demonstrates realization of Compound_Heterozygous() functionality for trio ["bgm9001a1", "bgm9001u1", "bgm9001u2"].

Additional interface requirements:

There should be an easy way to setup any scenario in request sequence to form of any of Standard Zygosity Scenarios applied to default problem group of the case. (See details in discussion of Inheritance_mode())

The user interface needs to keep check for "True" value selection on.