trainCombinedModel

Trains up a residual model to remove an uninteresting signal from an experiment.

BNF

<combined-training-input-configuration> ::=
   {<combined-settings-section> , <data-section>,
     <combined-head-section>, <verbosity-section>}

<combined-head-section> ::=
  "heads" : [<combined-head-list>]

<combined-head-list> ::=
    <combined-individual-head>
  | <combined-individual-head>, <combined-head-list>

<combined-individual-head> ::=
    {"num-tasks" : <integer>,
     "profile-loss-weight" : <number>,
     <counts-loss-section>,
     "head-name" : <string>,
     "use-bias-counts" : <boolean>}

<combined-settings-section> ::=
    "settings" : {<combined-settings-contents>}

<combined-settings-contents> ::=
    {"output-prefix" : "<string>",
     "epochs" : <integer>,
     "early-stopping-patience" : <integer>,
     "batch-size" : <integer>,
     "learning-rate" : <number>,
     "learning-rate-plateau-patience" : <integer>,
     "transformation-model" : <transformation-combined-settings>,
     "max-jitter" : <integer>,
     "architecture" : <combined-architecture-specification> }

<transformation-combined-settings> ::=
    {"transformation-model-file" : <file-name> }

<combined-architecture-specification> ::=
    <combined-bpnet-architecture-specification>

<combined-bpnet-architecture-specification> ::=
    {"architecture-name" : "bpnet",
     "input-length" : <number>,
     "output-length" : <number>,
     "model-name" : <string>,
     "model-args" : <string>,
     "filters" : <number>,
     "layers" : <number>,
     "input-filter-width" : <number>,
     "output-filter-width" : <number>}

Parameter Notes

Most of the parameters for the combined model are the same as for a solo model, and they are described at trainSoloModel.

use-bias-counts: Selects if you want to add the counts prediction from the transformation model, and the appropriateness of this flag will depend on the nature of your bias. If the bias is a constant background signal, then it makes sense to subtract the bias contribution to the counts. However, if your bias is multiplied by the underlying biology, then you probably shouldn’t add in the bias counts since they won’t affect the actual experiment.
transformation-model-file: The name of the Keras model file generated by trainTransformationModel.
input-length: The input size of the residual model, not the solo model. The solo model, having already been created, knows its own input length. If the solo model’s input length is smaller than the input-length setting in this config file, the sequence input to the solo model will automatically be cropped down to match.

HISTORY

Before BPReveal 3.0.0, the solo model had to have the same input length as the residual model. An auto-cropdown feature was implemented by Melanie Weilert to remove this restriction.

API

bpreveal.trainCombinedModel.main(config): Build and train a combined model.

Schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "trainCombinedModel",
    "description": "Schema for trainCombinedModel.py",
    "type": "object",
    "properties": {
        "train-data": {"type": "string"},
        "val-data": {"type": "string"},
        "settings": {
            "type": "object",
            "properties": {
                "output-prefix": {"type": "string"},
                "epochs": {"type": "integer"},
                "max-jitter": {"type": "integer"},
                "early-stopping-patience": {"type": "integer"},
                "batch-size": {"type": "integer"},
                "learning-rate": {"type": "number"},
                "learning-rate-plateau-patience": {"type": "integer"},
                "transformation-model": {
                    "type": "object",
                    "properties": {
                        "transformation-model-file": {"type": "string"}
                    },
                    "required": ["transformation-model-file"]
                },
                "architecture": {
                    "type": "object",
                    "properties": {
                        "architecture-name": {"type": "string", "enum": ["bpnet"]},
                        "input-length": {"type": "integer"},
                        "output-length": {"type": "integer"},
                        "model-name": {"type": "string"},
                        "model-args": {"type": "string"},
                        "filters": {"type": "integer"},
                        "layers": {"type": "integer"},
                        "input-filter-width": {"type": "integer"},
                        "output-filter-width": {"type": "integer"}},
                    "required": ["architecture-name", "input-length", "output-length",
                        "model-name", "filters", "layers", "input-filter-width",
                        "output-filter-width"]}
            },
            "required": ["output-prefix", "epochs", "max-jitter",
                "early-stopping-patience", "batch-size", "learning-rate",
                "learning-rate-plateau-patience", "transformation-model",
                "architecture"],
            "not": {"required": ["profile-architecture", "counts-architecture"]}
        },
        "heads": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "num-tasks": {"type": "integer"},
                    "profile-loss-weight": {"type": "number"},
                    "head-name": {"type": "string"},
                    "counts-loss-weight": {"type": "number"},
                    "counts-loss-frac-target": {"type": "number"},
                    "use-bias-counts": {"type": "boolean"}
                },
                "anyOf": [
                    {"required": ["counts-loss-weight"]},
                    {"required": ["counts-loss-frac-target"]}
                ],
                "required": ["num-tasks", "profile-loss-weight",
                             "head-name", "use-bias-counts"]
            }
        },
        "verbosity": {"$ref": "/schema/base#/definitions/verbosity"}
    },
    "required": ["heads", "train-data", "val-data", "settings",  "verbosity"]
}