.. _validation:

Validation
==========

By default, parameters for tracks are validated to catch errors at creation
time rather than upload time.

In this example, we set `fake_param`. Note that track object is created with no
errors...

.. testcode::

    import os
    import trackhub

    hub, genomes_file, genome, trackdb = trackhub.default_hub(
        hub_name="quickstart",
        genome="hg38",
        email="you@email.com")

    track1 = trackhub.Track(
        name="signal1",
        source=os.path.join(trackhub.helpers.data_dir(), 'sine-hg38-0.bedgraph.bw'),
        fake_param='asdf',
        tracktype='bigWig -2 2',
    )
    trackdb.add_tracks(track1)

...but when we render the track either by printing it directly, or indirectly
by rendering any of its parents, we get validation errors:

.. testcode::

    print(trackdb)

.. testoutput::

    Traceback (most recent call last):
    trackhub.track.ParameterError: The following parameters are unknown for track type bigWig -2 2: {'fake_param': 'asdf'}

If we specify a correct parameter name, but the value is incorrect, we get
a ValidationError (`maxHeightPixels` should be a colon-separated values, not an
integer):

.. testcode::

    track2 = trackhub.Track(
        name="signal1",
        source=os.path.join(trackhub.helpers.data_dir(), 'sine-hg38-0.bedgraph.bw'),
        maxHeightPixels=15,
        tracktype='bigWig -2 2',
    )
    trackdb.add_tracks(track2)
    print(track2)

.. testoutput::

    Traceback (most recent call last):
    trackhub.validate.ValidationError: Value 15 failed ColSV3 validation; Example value(s): 'a:b:c' or '0:10:100'

Sometimes the validation is too picky, or perhaps you're using a beta version
of the Genome Browser with additional features that trackhub does not yet know
about. In that case, we can disable the validation by setting
`settings.VALIDATE` to False:

.. testcode::

    trackhub.settings.VALIDATE = False
    print(trackdb)


.. testoutput::
    :options: +NORMALIZE_WHITESPACE

    track signal1
    bigDataUrl signal1.bigWig
    shortLabel signal1
    longLabel signal1
    type bigWig -2 2
    fake_param asdf

    track signal1
    bigDataUrl signal1.bigWig
    shortLabel signal1
    longLabel signal1
    type bigWig -2 2
    maxHeightPixels 15

Updating parameters
-------------------
The track hub specification changes. In order to stay up-to-date with these
changes, the `trackhub.parse` module can be used to parse the HTML of the Track
Database Definition page and create the corresponding `Param` objects.

The general workflow is to run:

.. code-block:: bash

    python trackhub/parse.py > parsed_results.py

And then use a diff tool (`meld`, `vim -d`, etc) to manually evaluate the
difference between the existing `parsed_params.py` module and the output
generated by `trackhub/parse.py`. In general, mostly only the validators will
be different, although there are some params that are not defined in the
database documnet and had to be added manually.

After making the necessary changes, please either open an issue or create
a pull request on `the GitHub repository <https://github.com/daler/trackhub>`_.