API: Web and Command Line Parameters¶

General API Parameters¶

The bycon package supports number of parameters for filtering and querying the data which includes and extends standard Beacon parameters and can - depending on the parameter and the current scope - in general be invoked through HTTP requests and as command line arguments.

Only parameters defined in config/argument_definitions.yaml will be interpreted.

Parameters are listed in snake_case format although for command line arguments (and also optionally web requests) camelCase versions are required (see the cmdFlags).

Definitions¶

`user_name`¶

type: string
pattern: ^\w+$
cmdFlags: --userName
description: faking a user name

`test_mode`¶

type: boolean
cmdFlags: -t,--testMode
description: test setting, i.e. returning some random documents
default: False

`skip`¶

type: integer
cmdFlags: --skip
description: pages to be skipped
default: 0

`limit`¶

type: integer
cmdFlags: -l,--limit
description: limit number of documents; a value of 0 sets to unlimited
default: 200
local: 0

`requested_granularity`¶

type: string
pattern: ^\w+$
description: The requested granularity of the beacon
cmdFlags: --requestedGranularity
default: record

`request_entity_path_id`¶

type: string
cmdFlags: --requestEntityPathId
description:

data entry point, equal to the first REST path element in Beacon
this only is used for command-line tests instead of the REST path value seen by the stack in web server mode

`response_entity_path_id`¶

type: string
cmdFlags: --responseEntityPathId
description:

optional data delivery entry point, for {id} paths
for command line (see above), but also potentially for selecting a special response entity in byconaut services (e.g. indviduals in /sampletable/)

`include_resultset_responses`¶

type: string
cmdFlags: --includeResultsetResponses
description:

include resultset responses, e.g. HIT, MISS
kind of a holdover from Beacon pre-v1 but HIT & ALL might have some use in networks
default: HIT

`dataset_ids`¶

type: array
items:
- type: string
cmdFlags: -d,--datasetIds
description: dataset ids

`cohort_ids`¶

type: array
items:
- type: string
cmdFlags: --cohortIds
description: cohort ids

`filters`¶

type: array
items:
- type: string
cmdFlags: --filters
description: prefixed filter values, comma concatenated; or objects in POST

`filter_precision`¶

type: string
cmdFlags: --filterPrecision
description: either start or exact for matching filter values
default: exact

`filter_logic`¶

type: string
cmdFlags: --filterLogic
description: Global for either OR or AND (translated to the MongoDB $and etc.). The Beacon protocol only knows AND.
default: AND

`include_descendant_terms`¶

type: boolean
cmdFlags: --includeDescendantTerms
description: global treatment of descendant terms
default: True

`assembly_id`¶

type: string
pattern: ^\w+?[\w\-\.]*?\w*?$
db_key: assembly_id
cmdFlags: --assemblyId
description: assembly id; currently not used in bycon's version

`reference_name`¶

type: string
db_key: location.sequence_id
pattern: ^\w+.*?\w?$
cmdFlags: --referenceName
description: chromosome

`mate_name`¶

type: string
db_key: adjoined_sequences.sequence_id
pattern: ^\w+.*?\w?$
cmdFlags: --mateName
description: chromosome

`reference_bases`¶

type: string
db_key: reference_sequence
pattern: ^[ACGTN]+$
cmdFlags: --referenceBases
description: reference bases

`alternate_bases`¶

type: string
db_key: sequence
pattern: ^[ACGTN]+$
cmdFlags: --alternateBases
description: alternate bases

`variant_type`¶

type: string
db_key: variant_state.id
pattern: ^\w+[\w \-\:]\w+?$
cmdFlags: --variantType
description: variant type, e.g. DUP

`start`¶

type: array
db_key: location.start
items:
- type: integer
- pattern: ^\d+?$
cmdFlags: --start
description: genomic start position

`end`¶

type: array
db_key: location.end
items:
- type: integer
- pattern: ^\d+?$
cmdFlags: --end
description: genomic end position

`mate_start`¶

type: integer
db_key: adjoined_sequences.start
pattern: ^\d+?$
cmdFlags: --mateStart
description: genomic start position of fusion partner breakpoint region

`mate_end`¶

type: integer
db_key: adjoined_sequences.end
pattern: ^\d+?$
cmdFlags: --MateEnd
description: genomic end position of fusion partner breakpoint region

`variant_min_length`¶

type: integer
db_key: info.var_length
pattern: ^\d+?$
cmdFlags: --variantMinLength
description: The minimal variant length in bases e.g. for CNV queries.

`variant_max_length`¶

type: integer
db_key: info.var_length
pattern: ^\d+?$
cmdFlags: --variantMaxLength
description: The maximum variant length in bases e.g. for CNV queries.

`gene_id`¶

type: array
items:
- type: string
- pattern: ^\w+?(\w+?(\-\w+?)?)?$
db_key: None
cmdFlags: --geneId
description: gene id

`aminoacid_change`¶

type: string
db_key: molecular_attributes.aminoacid_changes
pattern: ^\w+?$
examples: V600E,M734V,G244A
cmdFlags: --aminoacidChange
description: Aminoacid alteration in 1 letter format

`genomic_allele_short_form`¶

type: string
db_key: identifiers.genomicHGVS_id
pattern: ^\w+.*\w$
examples: NC_000017.11:g.7674232C>G
cmdFlags: --genomicAlleleShortForm
description: Genomic HGVSId descriptor

`variant_query_digests`¶

type: array
db_key: None
items:
- type: string
- pattern: ^(?:chro?)?([12]?[\dXY]):(\d+?(?:-\d+?)?)(?:--(\d+?(?:-\d+?)?))?(?::([\w\:\>]+?))?$
cmdFlags: --variantQueryDigests
examples: 9:9000001-21975098--21967753-24000000:DEL
description: EXPERIMENTAL Variant query digest-style short form

`variant_multi_pars`¶

type: array
db_key: None
items:
- type: object
cmdFlags: --variantMultiPars
description: EXPERIMENTAL List of multiple variant queries, for POST

`variant_internal_id`¶

type: string
db_key: variant_internal_id
pattern: ^\w[\w\:\-\,]+?\w$
examples: 11:52900000-134452384:EFO_0030067
cmdFlags: --variantInternalId
description: An id value used for all variant instances of the same composition; a kind of digest

`accessid`¶

type: string
db_key: id
pattern: ^\w[\w\-]+?\w$
examples: b59857bc-0c4a-4ac8-804b-6596c6566494
cmdFlags: --accessid
description: An accessid for retrieving handovers etc.

`file_id`¶

type: string
pattern: ^\w[\w\-]+?\w$
examples: 90e19951-1443-4fa8-8e0b-6b5d8c5e45cc
cmdFlags: --fileId
description: A file id e.g. as generated by the uploader service

`id`¶

type: string
db_key: id
pattern: ^\w[\w\:\-\,]+?\w$
examples: pgxvar-5bab576a727983b2e00b8d32,pgxind-kftx25eh
cmdFlags: --id
description: An id; this parameter only makes sense for specific REST entry types

`ids`¶

type: array
items:
- type: string
- pattern: ^\w[\w:-]+\w$
cmdFlags: --ids
description: One or more ids; this parameter only makes sense for specific REST entry types

`biosample_ids`¶

type: array
items:
- type: string
- pattern: ^\w[\w:-]+\w$
byc_entity: biosample
cmdFlags: --biosampleIds
description: biosample ids

`analysis_ids`¶

type: array
items:
- type: string
- pattern: ^\w[\w:-]+\w$
byc_entity: analysis
cmdFlags: --analysisIds
description: analysis ids

`individual_ids`¶

type: array
items:
- type: string
- pattern: ^\w[\w:-]+\w$
byc_entity: individual
cmdFlags: --individualIds
description: subject ids

`variant_ids`¶

type: array
items:
- type: string
- pattern: ^\w[\w:-]+\w$
byc_entity: genomicVariant
cmdFlags: --variantIds
description: variant ids

`debug_mode`¶

type: boolean
cmdFlags: --debugMode
description: debug setting
default: False

`show_help`¶

type: boolean
cmdFlags: --showHelp
description: specific help display
default: False

`test_mode_count`¶

type: integer
cmdFlags: --testModeCount
description: setting the number of documents reurned in test mode
default: 5

`output`¶

type: string
cmdFlags: --output
description: For defining a special output format, mostly for byconaut services use. Examples:

cnvstats, for analyses, to present some CNV statistics
pgxseg, using the .pgxseg variant file format
text, for some services to deliver a text table instead of JSON
in byconaut for the target database when copying...

`include_handovers`¶

type: boolean
default: True
cmdFlags: --includeHandovers
description: only used for web requests & testing

`method`¶

type: string
cmdFlags: --method
description: special method
default: None

`group_by`¶

type: string
cmdFlags: --groupBy
description: group parameter e.g. for subset splitting
default: text

`mode`¶

type: string
cmdFlags: -m,--mode
description: mode, e.g. file type

`update`¶

type: boolean
cmdFlags: -u,--update
description: update existing records - might be deprecated; only used for publications
default: False

`force`¶

type: boolean
cmdFlags: --force
description: force mode, e.g. for update or insert (cmd line)
default: False

`inputfile`¶

type: string
cmdFlags: -i,--inputfile
description: a custom file to specify input data, usually tab-delimited with special header

`outputdir`¶

type: string
cmdFlags: --outputdir
description: output directory where supported (cmd line)

`outputfile`¶

type: string
cmdFlags: -o,--outputfile
description: output file where supported (cmd line)

`min_number`¶

type: integer
cmdFlags: --minNumber
description: minimal number, e.g. for collations, where supported
default: 0

`delivery_keys`¶

type: array
items:
- type: string
cmdFlags: --deliveryKeys
description: delivery keys to force only some parameters in custom exporters

`collation_types`¶

type: array
items:
- type: string
cmdFlags: --collationTypes
description: selected collation types, e.g. "EFO"

`selected_beacons`¶

type: array
items:
- type: string

`genome_binning`¶

type: string
default: 1Mb
cmdFlags: --genomeBinning
description: one of the predefined genome binning keys - default 1Mb

`cyto_bands`¶

type: string
pattern: ^(?:chro?)?([12]?[\dXY])([pq](generated?:(?:ter)|(?:cen)|(?:[1-4](generated?:\d(?:\.\d\d*?)?)?)?))?\-?([pq](generated?:(?:cen)|(?:ter)|(?:[1-4](generated?:\d(?:\.\d\d*?)?)?)?))?$
db_key: None
cmdFlags: --cytoBands
description: cytobands, e.g. 8q21q24.1

`chro_bases`¶

type: string
pattern: ^(chro?)?([12]?[\dXY])\:(\d+?)(\-(\d+?))?$
db_key: None
cmdFlags: --chroBases
description: only for the cytoband converter ... e.g. 8:0-120000000

`city`¶

type: string
cmdFlags: -c,--city
description: only for the geolocations...

`geo_latitude`¶

type: number
cmdFlags: --geoLatitude
description: only for the geolocations...

`geo_longitude`¶

type: number
cmdFlags: --geoLongitude
description: only for the geolocations...

`geo_distance`¶

type: integer
cmdFlags: --geoDistance
description: only for the geolocations...

`plot_pars`¶

type: string
cmdFlags: --plotPars
description: plot parameters in form par=value concatenated by ::

`plot_type`¶

type: string
cmdFlags: --plotType
description: plot type (histoplot, samplesplot, arrayplot - more?)
default: None

Services: Plot Parameters¶

The byconServices package inside bycon provides a number of plotting functions which can be used to visualize the data in the database. Generally plot functionality is focussed on generating CNV visualizations for per-sample and aggregated CNV data (e.g. frequencyplots). Additionally some geographic map projectins are provided e.g. for samples and metadata.

More information can be found on these pages:

plot documentation on this page

Plot Types¶

`histoplot`¶

description: The default option, used to plot histograms of the CNV frequencies per data collection ("collation") or aggregated sample data.
data_key: interval_frequencies_bundles
data_type: collations

`histoheatplot`¶

description: A "heatmap" style version of the histogram plot, where a single gain/loss frequency result is transformed into a small heat color strip.
data_key: interval_frequencies_bundles
data_type: collations

`histosparkplot`¶

description: A version of the histogram with predefined parameters for representing a small and unlabeled plot, e.g. for use in hover previews. As in the normal histogram parameters can be overridden.
data_key: interval_frequencies_bundles
data_type: collations
mods:
- plot_chro_height: 0
- plot_title_font_size: 0
- plot_area_height: 18
- plot_margins: 0
- plot_axislab_y_width: 0
- plot_grid_stroke: 0
- plot_footer_font_size: 0
- plot_width: 480
- plot_area_opacity: 0
- plot_dendrogram_width: 0
- plot_labelcol_width: 0
- plot_axis_y_max: 80
modded: histoplot

`histocircleplot`¶

description: A version circular of the histogram.
data_key: interval_frequencies_bundles
data_type: collations
mods:
- plot_width: 640
- plot_chro_height: 16
- plot_axislab_y_width: 0
- plot_area_opacity: 0
- plot_dendrogram_width: 0
- plot_labelcol_width: 0

`samplesplot`¶

description: A plot of the called CNV segments per sample, with the samples ordered by their clustering (i.e. similarity of binned CNV data).
data_key: analyses_variants_bundles
data_type: samples

`geomapplot`¶

description: A leaflet based plot of geolocations.
data_key: geolocs_list
data_type: geolocs

Plot Parameters¶

`plot_id`¶

default: genomeplot

`plot_title`¶

description: title above the plot

`plot_group_by`¶

description: group samples in histograms by a filter type (NCIT, PMID...)
default: ``

`plot_filter_empty_samples`¶

description: By setting to true samples w/o data can be removed e.g. from sample plots
type: boolean
default: False

`force_empty_plot`¶

description: By setting to true a plot strip will be forced even if there are no CNV samples
type: boolean
default: False

`plot_cluster_results`¶

description: By setting to false clustering can be suppressed
type: boolean
default: True

`plot_samples_cluster_type`¶

description: Selection of which measurees are used to generate the clustering matrix

intcoverage uses the ~2x3k (gain, loss) 1MB intervals
chrostats only uses the CNV coverage per chromosomal arm (separately for gains and losses)
default: intcoverage
oneOf: chrostats,intcoverage

`plot_cluster_metric`¶

default: ward
oneOf: average,centroid,complete,median,single,ward,weighted

`plot_dup_color`¶

default: #FFC633

`plot_hldup_color`¶

default: #FF6600

`plot_del_color`¶

default: #33A0FF

`plot_hldel_color`¶

default: #0033CC

`plot_loh_color`¶

default: #0066FF

`plot_snv_color`¶

default: #FF3300

`plot_chros`¶

type: array
items: string
default: 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22

`plot_width`¶

description:

width of the plot image, in px
the plot area width is determined through
- plot_width - 2 *plot_margins - plot_labelcol_width - plot_axislab_y_width - plot_dendrogram_width
  type: integer
  default: 1024

`plot_area_height`¶

description: height of the plot area (applies only to histogram plots)
type: integer
default: 100

`plot_axis_y_max`¶

description:

frequency value the maximum of the Y-axis corresponds to
use this to e.g. spread values if a max. of less than 100 is expected
type: integer
default: 100

`plot_samplestrip_height`¶

description: height of a single sample strip
type: integer
default: 12

`plot_margins`¶

description: outer plot margins, in px
type: integer
default: 25

`plot_labelcol_width`¶

description:

width of the space for left text labels (e.g. sample ids, collation labels)
defaults to 0 when only one item
type: integer
default: 220

`plot_axislab_y_width`¶

description: width of the space for histogram percentage markers
type: integer
default: 30

`plot_dendrogram_width`¶

description:

width of the cluster tree
defaults to 0 when no clustering is being performed
type: integer
default: 50

`plot_dendrogram_color`¶

description: color of the cluster tree stroke
default: #333333

`plot_dendrogram_stroke`¶

description: thickness of the cluster tree stroke
type: number
default: 0.5

`plot_chro_height`¶

description: height (well, width...) of the chromosomes in the ideogram strip
type: integer
default: 14

`plot_region_gap_width`¶

type: integer
default: 3

`plot_canvas_color`¶

description: color of the document background
default: #ffffff

`plot_area_color`¶

description: color of the plot area background
default: #eef6ff

`plot_area_opacity`¶

description: opacity of the plot background
type: number
default: 0.8

`plot_heat_intensity`¶

description: factor for frequency heatmap value brightness
type: number
default: 1

`plot_grid_stroke`¶

type: integer
default: 1

`plot_grid_color`¶

description: color of grid lines
default: #c0e3ee

`plot_grid_opacity`¶

type: float
default: 0.8

`plot_font_color`¶

default: #000000

`plot_font_size`¶

description: font size, in px
type: integer
default: 10

`plot_title_font_size`¶

description: title font size, in px
type: integer
default: 16

`plot_labelcol_font_size`¶

description: label font size (left column), in px
type: integer
default: 12

`plot_label_y_font_size`¶

description: font size for Y-axis labels (percents ...)
type: integer
default: 8

`plot_label_y_font_color`¶

description: font color for Y-axis labels (percents ...)
default: #666666

`plot_label_y_values`¶

type: array
items: integer
default: 25,50,75

`plot_label_y_unit`¶

type: string
default: %

`circ_start_gap`¶

description: in degrees; top (usually) gap providing separation & space for labels
type: integer
default: 20

`circ_start_angle`¶

description: in degrees; start of plot circle from 12 o'clock position
type: integer
default: 0

`plot_probe_y_factor`¶

description: relative y-scaling of the probes in array-/probeplots
type: integer
default: 1

`plot_probe_label_y_values`¶

type: array
items: number
default: 1,2,3,4,5,6,7,8,9

`plot_probedot_size`¶

type: integer
default: 1

`plot_probedot_opacity`¶

type: integer
default: 222

`plot_region_labels`¶

description:

placeholder for markers / labels in the
format is 8:120000000-124000000:Region+of+Interest
comma-concatenation for multiple values
label is optional
type: array

`plot_regionlabel_color`¶

default: #ddceff

`plot_gene_symbols`¶

description:

label a gene's position by its symbol (CDKN2A, MYC, ERBB2...)
comma-concatenation for multiple values
type: array

`plot_cytoregion_labels`¶

description:

label a cytoband's position (8q24, 1p12p11, 17q...)
comma-concatenation for multiple values
type: array

`plot_cytoregion_color`¶

default: #ffe3ee

`plot_marker_font_color`¶

description: font color for gene and region markers
default: #dd3333

`plot_marker_font_size`¶

type: integer
default: 10

`plot_marker_label_padding`¶

description: text padding of markers versus background/box
type: integer
default: 4

`plot_marker_lane_padding`¶

type: integer
default: 2

`plot_footer_font_size`¶

type: integer
default: 10

`plot_footer_font_color`¶

default: #999999

`cytoband_shades`¶

type: object
default:
- gpos100: {'0%': 'rgb(39,39,39)', '100%': 'rgb(0,0,0)'}
- gpos75: {'0%': 'rgb(87,87,87)', '100%': 'rgb(39,39,39)'}
- gpos50: {'0%': 'rgb(196,196,196)', '100%': 'rgb(111,111,111)'}
- gpos25: {'0%': 'rgb(223,223,223)', '100%': 'rgb(196,196,196)'}
- gneg: {'0%': 'white', '100%': 'rgb(223,223,223)'}
- gvar: {'0%': 'rgb(196,196,196)', '100%': 'rgb(111,111,111)'}
- stalk: {'0%': 'rgb(39,39,39)', '100%': 'rgb(0,0,0)'}
- acen: {'0%': 'rgb(163,55,247)', '100%': 'rgb(138,43,226)'}

`histoval_directions`¶

type: object
default:
- gain_frequency: 1
- gain_hlfrequency: 1
- loss_frequency: -1
- loss_hlfrequency: -1

`histoval_colorkeys`¶

type: object
default:
- gain_frequency: plot_dup_color
- gain_hlfrequency: plot_hldup_color
- loss_frequency: plot_del_color
- loss_hlfrequency: plot_hldel_color

`tiles_source`¶

default: https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

`attribution`¶

default: Map data © <a href="https://www.openstreetmap.org/">OpenStreetMap</a> contributors, <a href="https://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA</a>

`init_latitude`¶

default: 30

`init_longitude`¶

default: 9

`zoom`¶

default: 1

`head`¶

default: <meta charset="utf-8"> <link rel="stylesheet" href="https://unpkg.com/leaflet@1.8.0/dist/leaflet.css" integrity="sha512-hoalWLoI8r4UszCkZ5kL8vayOGVae1oxXe/2A4AO6J9+580uKHDO3JdHb7NzwwzK5xr/Fs0W40kiNHxM9vyTtQ==" crossorigin="" />

`map_w_px`¶

default: 800

`map_h_px`¶

default: 512

`marker_type`¶

default: marker

`bubble_stroke_color`¶

default: #dd6633

`bubble_stroke_weight`¶

default: 1

`bubble_fill_color`¶

default: #cc9966

`bubble_opacity`¶

default: 0.4

`marker_scale`¶

default: 2

`marker_max_r`¶

default: 1000

`zoom_min`¶

default: 2

`zoom_max`¶

default: 14

API: Web and Command Line Parameters¶

General API Parameters¶

Definitions¶

user_name¶

test_mode¶

skip¶

limit¶

requested_granularity¶

request_entity_path_id¶

response_entity_path_id¶

include_resultset_responses¶

dataset_ids¶

cohort_ids¶

filters¶

filter_precision¶

filter_logic¶

include_descendant_terms¶

assembly_id¶

reference_name¶

mate_name¶

reference_bases¶

alternate_bases¶

variant_type¶

start¶

end¶

mate_start¶

mate_end¶

variant_min_length¶

variant_max_length¶

gene_id¶

aminoacid_change¶

genomic_allele_short_form¶

variant_query_digests¶

variant_multi_pars¶

variant_internal_id¶

accessid¶

file_id¶

id¶

ids¶

biosample_ids¶

analysis_ids¶

individual_ids¶

variant_ids¶

debug_mode¶

show_help¶

test_mode_count¶

output¶

include_handovers¶

method¶

group_by¶

mode¶

update¶

force¶

inputfile¶

outputdir¶

outputfile¶

min_number¶

delivery_keys¶

collation_types¶

selected_beacons¶

genome_binning¶

cyto_bands¶

chro_bases¶

city¶

geo_latitude¶

geo_longitude¶

geo_distance¶

plot_pars¶

plot_type¶

Services: Plot Parameters¶

Plot Types¶

histoplot¶

histoheatplot¶

histosparkplot¶

histocircleplot¶

samplesplot¶

geomapplot¶

Plot Parameters¶

plot_id¶

plot_title¶

`user_name`¶

`test_mode`¶

`skip`¶

`limit`¶

`requested_granularity`¶

`request_entity_path_id`¶

`response_entity_path_id`¶

`include_resultset_responses`¶

`dataset_ids`¶

`cohort_ids`¶

`filters`¶

`filter_precision`¶

`filter_logic`¶

`include_descendant_terms`¶

`assembly_id`¶

`reference_name`¶

`mate_name`¶

`reference_bases`¶

`alternate_bases`¶

`variant_type`¶

`start`¶

`end`¶

`mate_start`¶

`mate_end`¶

`variant_min_length`¶

`variant_max_length`¶

`gene_id`¶

`aminoacid_change`¶

`genomic_allele_short_form`¶

`variant_query_digests`¶

`variant_multi_pars`¶

`variant_internal_id`¶

`accessid`¶

`file_id`¶

`id`¶

`ids`¶

`biosample_ids`¶

`analysis_ids`¶

`individual_ids`¶

`variant_ids`¶

`debug_mode`¶

`show_help`¶

`test_mode_count`¶

`output`¶

`include_handovers`¶

`method`¶

`group_by`¶

`mode`¶

`update`¶

`force`¶

`inputfile`¶

`outputdir`¶

`outputfile`¶

`min_number`¶

`delivery_keys`¶

`collation_types`¶

`selected_beacons`¶

`genome_binning`¶

`cyto_bands`¶

`chro_bases`¶

`city`¶

`geo_latitude`¶

`geo_longitude`¶

`geo_distance`¶

`plot_pars`¶

`plot_type`¶

`histoplot`¶

`histoheatplot`¶

`histosparkplot`¶

`histocircleplot`¶

`samplesplot`¶

`geomapplot`¶

`plot_id`¶

`plot_title`¶

`plot_group_by`¶

`plot_filter_empty_samples`¶

`force_empty_plot`¶

`plot_cluster_results`¶

`plot_samples_cluster_type`¶

`plot_cluster_metric`¶