{
"info": {
"author": "Frederik Faye",
"author_email": "frederikfaye@gmail.com",
"bugtrack_url": null,
"classifiers": [
"License :: OSI Approved :: Apache Software License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3"
],
"description": "# DeepCalo\n### Python 3 package for doing deep supervised learning on ATLAS data, using Keras\nAuthor: Frederik Faye, The Niels Bohr Institute, 2019\n\n## What is DeepCalo?\nThis package allows you to build, train and tune convolutional neural network (CNN) models using Keras with any backend.\n\nYou can also integrate models for processing non-image data, such as scalars and sequences.\nThe models that can be built have been designed specifically with the ATLAS detector in mind, but you can also just use the framework and all its nice features for any Keras-based project.\n\n## Why should you use it?\n* All hyperparameters are set through a single Python dictionary, making it very easy to experiment with different models.\n* A lot of advanced features are supported (such as cyclic learning rate schedules, grouped convolutions, DropBlock regularization, squeeze and excite modules, non-standard optimizers such as Yogi and Padam, and much more), and it is easy to add new ones.\n* Extensive logging is automatically created for each run of a model, including hyperparameters, plots of model architectures, and weights of the model during training, making it easy to keep track of what you have tried, and what came of it.\n\n### Table of Content\n- [Installation](#installation)\n- [Dependencies](#dependencies)\n- [Usage](#usage)\n - [Quick start](#quickstart)\n - [Using ATLAS data](#atlasdata)\n- [Model architectures](#archs)\n - [CNN](#arch_cnn)\n - [Network in network](#arch_network_in_network)\n - [Top](#arch_top)\n - [Scalar net](#arch_scalar_net)\n - [FiLM generator](#arch_film_gen)\n - [Track net](#arch_track_net)\n - [Gate net](#arch_gate_net)\n - [Combined](#arch_combined)\n- [Documentation](#docs)\n - [`data`](#doc_data)\n - [`params`](#doc_params)\n - [Keys concerning submodels](#doc_submodels)\n - [`dirs`](#doc_dirs)\n- [Known issues](#knownissues)\n- [Todo](#todo)\n\n\n## Installation\n```bash\npip install deepcalo\n```\n\n\n## Dependencies\n```python\nnumpy, pandas, matplotlib, h5py, joblib, tqdm, keras, tensorflow, scikit-optimize, keras-contrib, keras-drop-block\n```\n\nIf you want to be able to plot the graph of your model, please install `pydot` and `graphviz` (if possible, use `conda install python-graphviz` for `graphviz`).\n\n\n## Usage\n\n\n### Quick start\nThe main functionality lies in the so-called model container, which can be imported as\n```python\nfrom deepcalo import ModelContainer\n```\nSee the [documentation](#docs) below for all the details. However, often an example is a better way of learning. Some examples are found in the *demos* folder.\n\nDownload and run the MNIST tutorial:\n```bash\npython mnist_tutorial.py --exp_dir ./my_mnist_experiment/ -v 1\n```\nThis will train a tiny CNN for a single epoch to discriminate between the digits of the MNIST dataset, which should reach $`>95\\%`$ test accuracy after its first epoch.\n\nOpen the script to see what is going on; the important part is the hyperparameter section. Try playing around with the parameters to see if you can find a network that does better! Also have a look at the contents of the *logs* folder in the experiment directory (`./my_mnist_experiment/`) to see some of the nice logging features this framework has to offer.\n\nThere are a lot more hyperparameters to play around with. See the [documentation](#doc_params) for what is possible.\n\n\n### Using ATLAS data\nIn the *demos* folder, you will also find the more realistic examples of `run_model.py` and `hp_search.py`. The former shows how to run a single model (much like the MNIST example), while the latter shows how to use this package for doing hyperparameter optimization (using the Bayesian optimization of [scikit-optimize](https://github.com/scikit-optimize/scikit-optimize)).\n\nBoth use actual ATLAS simulation data to do energy regression. The data used herein can be downloaded from the lxplus (CERNBox) directory */eos/user/l/lehrke/Data/Data* (which should be visible to all current CERN members).\n\nThe scripts uses the function `deepcalo.utils.load_atlas_data` function, which is tailored to these datasets. If need be, you can modify this function to work with your data, however note that this framework uses the `'channels_last'` format, which is the standard in Keras.\n\n\n## Model architectures\nThe following is a quick tour of the different out-of-the-box models available. Each model is made for a different kind of input, e.g., images, scalar variables, tracks, or the output from other models.\n\nAll models except the [top](#arch_top) are optional to use. However, models are tied to their input in such a way that if for instance a `tracks` dataset is present in the suppplied [data](#doc_data), the [track net](#arch_track_net) will be integrated into the [combined model](#arch_combined).\n\nYou can find information about how to set the hyperparameters of these models in the [documentation](#doc_params), where each model has its own section.\n\n\n### CNN\nBelow, an illustration of the default CNN architecture can be seen. It is comprised of blocks. For all but the first block, a block begins with downsampling and the number of feature maps being doubled.\n\nThe tuple underneath the input denotes the size of the input (here height, width, channels).\n\nNote that normalization, the activation function, downsampling and global average pooling can all be turned on or off.\n\nThe output of the CNN is passed on to either the [top](#arch_top), or to the [network in network](#arch_network_in_network).\n\n
\n \n
\n\n\n### Network in network\n\nThis model takes the outputted feature maps of the [CNN](#arch_cnn) (without global average pooling applied), and applies a [Network in Network](https://arxiv.org/abs/1312.4400) to it, which consists of a series of $`1\\times 1`$ convolutions, typically followed by global average pooling.\n\nThis makes it possible to make CNN architectures without a dense top (e.g. the [AllConv Net](https://arxiv.org/abs/1412.6806)). For instance, if you want to train a CNN with a network in network classifier to be able to distinguish between five categories, make the final $`1 \\times 1`$ convolution in the network in network submodel output five feature maps, apply global average pooling, and set the [top](#arch_top) to have no units (`units:[]`) and `final_activation:'softmax'`.\n\n
\n \n
\n\n\n### Top\nThe top model is a simple, dense neural network that takes as input the concatenated outputs of other models, and gives a final output, which can be any 1D size $`\\geq 1`$.\n\n
\n \n
\n\n\n### Scalar net\nThe scalar net is again a simple, dense network that processes any scalar variables you may want to include. Its output can be connected to either the [top](#arch_top), the [FiLM generator](#arch_film_gen), or both.\n\n
\n \n
\n\n\n### FiLM generator\nThe FiLM generator is a nice way of conditioning the CNN with scalar variables. You can read a good introduction to the technique [here](https://distill.pub/2018/feature-wise-transformations/).\n\nThe FiLM generator can take inputs from both the [scalar net](#arch_scalar_net) and the [track net](#arch_track_net). Its output modulates the [CNN](#arch_cnn).\n\n
\n \n
\n\n\n### Track net\n\nThis model takes the (varying) number of track vectors for a datapoint as input and spits out a fixed size representation of that datapoint, which is then passed on to the [top](#arch_top), the [FiLM generator](#arch_film_gen), or both.\n\nAs the order in which we give our model the track vectors for a datapoint carries no information, the permutation invariant method of [Deep Sets](https://arxiv.org/abs/1703.06114) has been used.\n\nThe $`T`$ in the shape of $`X_{\\mathrm{track}}`$ is the largest number of track vectors of any datapoint in the dataset, where zero-padding has been used if the actual number of tracks for a given datapoint is smaller than $`T`$.\n\nNote that right now, the aggregation part of the track net is a simple sum, as in the [Deep Sets](https://arxiv.org/abs/1703.06114) paper.\n\n
\n \n
\n\n\n### Gate net\nThe [CNN](#arch_cnn) architecture can be expanded to include images, that contain cell information other than just the energy, by using the gate net. This was originally motivated by the inclusion of when in time each cell determined its signal to be, in order to help mitigate out-of-time pileup, but images containing other cell information can be included instead; for instance, the noise of each cell has proven useful for energy regression.\n\nThe cell images containing the extra cell information is collected in an image tensor $`X_{\\mathrm{gate-img}}`$ of the same resolution and dimension as the standard cell image tensor $`X_{\\mathrm{img}}`$.\n$`X_{\\mathrm{gate-img}}`$ is first passed through a gating mechanism (the gate net), which outputs a real number between zero and one for each pixel in each channel. These numbers are then merged with $`X_{\\mathrm{img}}`$, either by element-wise multiplication and then concatenation along the channel axis, or just by element-wise multiplication. The idea is that the element-wise multiplication allows the network to modulate the values of $`X_{\\mathrm{img}}`$ according to the information stored in $`X_{\\mathrm{gate-img}}`$.\nThe resulting, merged tensor is then given as the input to the [CNN](#arch_cnn) (in the stead of $`X_{\\mathrm{img}}`$).\n\n
\n \n
\n\n\n### Combined\nIn the final illustration below, you can see how the models all fit together.\n\n
\n \n
\n\n#### Good hyperparameter configurations\nSee https://indico.cern.ch/event/800614/contributions/3327152/attachments/1799540/2936007/presentation_cnn.pdf for some slightly outdated results on energy regression using the above described networks with good hyperparameters.\n\n\n## Documentation\nThe heart of DeepCalo is the `ModelContainer` class, found in `deepcalo.model_container`, which is documented below.\n\n```python\nclass ModelContainer:\n \"\"\"\n A class for organizing the creation, training and evaluation of models.\n \"\"\"\n\n def __init__(self, data, params, dirs, save_figs=True, verbose=True):\n```\n### Arguments\n\n\n#### data : *dict*\nDictionary of training, validation and (optionally) test data, organized according to the type of data.\n\n This dictionary must have either two or three keys, being `train` and `val`, or `train`, `val`, and `test`. Each of these keys points to another *dict* containing different kinds of data. The keys of these dictionaries can be any or all of `'images'`, `'scalars'`, `'tracks'`, `'sample_weights'` and `'targets'`. The documentation for what each of these keys refers to is given below. Note that `'images'`, `'scalars'` and `'tracks'` are considered inputs, and at least one of them must be non-empty.\n\n Note that the shapes of the datasets contained in `data` are used in the model creation (but a single datapoint is enough to do so).\n\n**images** : *dict of ndarrays*\n- If `'images'` is a key in `data[set_name]` and `data[set_name]['images']` is non-empty (where `set_name` can be either `'train'`, `'val'` or `'test'`), a [CNN](#arch_cnn) will be created and used to process these images.\n\n To allow you to keep track of different types of images (intended to be used for different kinds of things), the value corresponding to the `'images'` key of `data` is also a *dict*.\n\n Say you have two different kinds of images that you would like to have processed by the CNN. Let's call them `'low_res_imgs'` and `'high_res_imgs'` (i.e., these are the keys in the `data[set_name]['images']` dictionary), each being 4D numpy array with shape $`(N,H,W,C)`$, where $`H`$ and $`W`$ are different for the two types of images. You can then use the `upsampling` functionality (see [`params`](#doc_params)) to upsample them to a common resolution, so that they can be processed together in the CNN.\n\n If you want to include and process [gate images](#arch_gate_net), these should be named the exact same as the cells they correspond to, with `'gate_'` preprended; using the example from above, the `data[set_name]['images']` dictionary would then have the four keys `'low_res_imgs'`, `'gate_low_res_imgs'`, `'high_res_imgs'` and `'gate_high_res_imgs'`. Only if images are named in this manner will a submodel for processing the gate images be created and used.\n\n**scalars** : *ndarray*\n- If `'scalars'` is a key in `data[set_name]` and `data[set_name]['scalars']` is non-empty (where `set_name` can be either `'train'`, `'val'` or `'test'`), a [scalar net](#arch_scalar_net) will be created and used to process these scalars.\n\n The scalars should come in the form of a $`(N,S)`$ numpy array, where $`N`$ is the number of datapoints in the set, and where $`S`$ is the number of scalars.\n\n**tracks** : *ndarray*\n- If `'tracks'` is a key in `data[set_name]` and `data[set_name]['tracks']` is non-empty (where `set_name` can be either `'train'`, `'val'` or `'test'`), a [track net](#arch_track_net) will be created and used to process these tracks.\n\n The track vectors should come in the form of a numpy array of shape $`(N,T,F)`$, where $`N`$ is the number of datapoints, $`T`$ is the maximum number of tracks, and where $`F`$ is the length of each track vector, i.e., the number of features.\n\n As each datapoint can have a variable number of track vectors associated with it, datapoints with $`t\n#### params : *dict*\n\nThis dictionary contains all the hyperparameters used in constructing, training and evaluating the model. Default parameters can be gotten from the function `deepcalo.utils.get_default_params`.\n\nWhen a dictionary key is referenced below, what is actually meant is the\nvalue corresponding to that key. For instance, although the key `'epochs'`\nis of course a *str*, the documentation below concerns itself with the value\nof this key, which in this case is an *int*.\n\n**epochs** : *int*\n- Number of epochs to train for. If `use_earlystopping` is set to\n`True`, training may stop prior to completing the chosen number of\nepochs.\n\n**batch_size** : *int*\n- Mini-batch size. Note that if several GPUs are used, the mini-batch\n will be evenly divided among them.\n\n**loss** : *str*\n- Any Keras loss function name. See `get_loss_function` in\n`model_building_functions.py` for implemented custom loss functions,\nas well as how to implement your own.\n\n**metrics** : *list of strs or None*\n- Can be the name of any metric recognized by Keras. This (or these)\nmetric(s) will be shown during training, as well as in the final\nevaluation.\nNote that if a *hp_search* is carried out, the last entry of the list\nwill be the evaluation function used by the Gaussian process\nhyperparameter search. If an empty list or `None`, the `loss` will be\nthe evaluation function used by the Gaussian process hyperparameter search.\n\n**optimizer** : *str or config dict*\n- Which optimizer to use. Any Keras optimizer, as well as the Padam\nand Yogi optimizers from keras_contrib, can be used.\n\n If you don't want to simply use the defaults parameters of the\n chosen optimizer, instead give a *config dict*. See [Explanation of\n *str or config dict*](#doc_config_dict).\n\n**lr_finder** : *dict*\n- Dictionary of learning rate finder (from [Smith, 2015](https://arxiv.org/abs/1506.01186)) parameters.\n * The `'use'` key is a *bool* deciding whether or not to use the\n learning rate finder as implemented in `custom_classes.py`.\n * The `'scan_range'` is a *list* containing the minimum and maximum\n learning rate to be scanned over.\n * The `'epochs'` key is an *int* setting the number of epochs to use in the scan.\n 1-4 epochs is typically enough, depending on the size of the training set.\n * The `'scale'` can be either `'linear'` (default) or `'log'`, resulting in the\n learning rates being scanned linearly or logarithmically, respectively.\n * If `'prompt_for_input'` is `True`, the user will be asked to input a\n range within which the cyclical learning rate schedule (see below)\n should vary in between upon completing the learning rate finder\n scan.\n\n**lr_schedule** : *dict*\n- Dictionary of learning rate schedule parameters.\n * The `'name'` key can be either `None` (when no learning rate schedule\n will be used), `'CLR'` ([Smith, 2015](https://arxiv.org/abs/1506.01186)),\n `'OneCycle'` ([Smith et al., 2017](https://arxiv.org/abs/1708.07120)) or `'SGDR'` ([Loshchilov and Hutter, 2017](https://arxiv.org/abs/1608.03983)).\n * The `'range'` key should be a list with two floats, the first one being the minimum learning rate, and the second being the maximum learning rate.\n * The `'step_size_factor'` key differs in meaning for the possible learning rate schedules: If $`s`$ is the `'step_size_factor'` value and $`k`$ is the number of mini-batch updates per epoch $`e`$, then for\n - `'CLR'`, the step size of the cycle (i.e., the number of mini-batch updates per half a cycle) is given by $`ks`$,\n - `'OneCycle'`, the step size $`k\\times e/s`$, means that $`s`$ is the number of half cycles, including the cooldown to one hundredth the base learning rate. E.g., if $`s=2.25`$, the last $`\\frac{0.25}{2.25}`$ of the total number of mini-batch updates will be used for the cooldown,\n - `'SGDR'`, $`s`$ is simply the initial number of epochs in a cycle.\n\n Note that `cyclical_momentum==True` in `'OneCycle'` will only work with optimizers that have a `momentum` attribute (such as `'SGD'`).\n\n Besides the above mentioned, keyword arguments specific to each learning rate schedule class can be passed by using the `'kwargs'` key, which should have a dictionary of keyword arguments as its value.\n\n**auto_lr** : *bool*\n- Whether to use the function `get_auto_lr` in\n`model_building_functions.py` that automatically sets a good learning\nrate based on the chosen optimizer and the batch size, taking the\nlearning rate to be propertional to the square root of the batch\nsize. The constant of proportionality varies from optimizer to\noptimizer, and probably from problem to problem - use the learning\nrate finder to find out which constant is suitable for your problem.\n\n**use_earlystopping** : *bool*\n- Use the Keras EarlyStopping callback with `min_delta=0.001` and\n`patience=150` (these can be changed in `model_container.py`).\n\n**restore_best_weights** : *bool*\n- Restore the best weights found during training before evaluating.\n\n**pretrained_model** : *dict*\n- Dictionary of parameters for using (parts of) pretrained models.\n * The `'use'` key is a boolean deciding whether or not to load\n pretrained weights.\n * The `'weights_path'` is the path to the weights\n of the pretrained network. If `'params_path'` is `None`, the\n parameters for the pretrained network is assumed to be in the parent\n folder of the `'weights_path'`.\n * `'layers_to_load'` is a *list* with the Keras names of the layers (or\n submodels) whose weights should be transferred from the pretrained\n model to the one at hand. These names must refer to the same\n structure in both the pretrained model and in the model at hand.\n * `'freeze_loaded_layers'` can be either a boolean (when, if `True`,\n all layers listed in `'layers_to_load'` will be frozen, or not, if\n `False`) or a *list* of *bool*s with the same length as\n `'layers_to_load'` (when the first boolean in\n `'freeze_loaded_layers'` answers whether to freeze the first layer\n given by `'layers_to_load'` or not, etc.).\n\n**n_gpus** : *int*\n- Number of GPUs used in training. Can typically be inferred from the visible GPUs.\n\n**data_generator** : *dict*\n- Parameters concerning a DataGenerator, which is helpful if your data does not fit in memory, as it loads data in batches. Its current implementation, which is designed to work in conjunction with `deepcalo.utils.load_atlas_data`, can be seen in `deepcalo.data_generator`.\n\n * The `'use'` key is a *bool* deciding whether to use a DataGenerator.\n * The `'n_workers'` key is an *int* that sets the number of CPU workers to use for preparing batches.\n * The `'max_queue_size'` key is an *int* that sets the upper limit to how many batches can be ready at any one time.\n * The `'path'` key is a *str* that gives the path to the dataset.\n * The `'n_points'` key is a *dict* with the keys `'train'` and `'val'` (or `'train'`, `'val'` and `'test'`), whose corresponding values is an *int* given the number of datapoints in each set.\n * The `'load_kwargs'` key is a *dict* containing arguments to be passed to the `__init__` of the `DataGenerator` class.\n\n**usampling** : *dict*\n- Dictionary of parameters for upsampling input images inside the\nnetwork. This can be useful if the ability to downsample (which\nintroduces translational invariance) is important but the input\nimages are small.\n * The `'use'` key is a boolean deciding whether to upsample or not.\n `'wanted_size'` refers to the size that all images should be\n upsampled to before being concatenated.\n * The `'interpolation'` argument is passed to the Keras layer `UpSample2D`.\n\n After upsampling, the cell image tensor is normalized so as to\n maintain the same amount of energy overall, but now spread out over\n the upsampling pixels.\n\n\n##### Keys concerning all submodels:\n**initialization** : *str or config dict*\n- Initialization of the parameters of the submodel. Can be any\ninitializer recognized by Keras.\n\n If you don't want to simply use the defaults parameters of the\n chosen initializer, instead give a *config dict*. See [Explanation\n of *str or config dict*](#doc_config_dict).\n\n**normalization** : *str or config dict or None*\n- Normalization layer. If not `None`, the chosen normalization layer is\nplaced after every dense or convolutional layer in the submodel,\ni.e., before an activation function.\n\n Can be any of `'batch'`, `'layer'`, `'instance'` or `'group'`.\n Note that the last three are implemented through a group\n normalization layer (which encompass the layer and instance\n normalization). This means that the name of the normalization\n layer when using `keras.utils.plot_model` will be the name of a\n group normalization layer when using any of the last three.\n\n If you don't want to simply use the defaults parameters of the\n chosen normalization layer, instead give a *config dict*. See\n [Explanation of *str or config dict*](#doc_config_dict).\n\n**activation** : *str or config dict or None*\n- Activation function of all dense or convolutional layers in the\nsubmodel, except for the very last one, if a `final_activation`\nvariable is present.\n\n Can be any of `'relu'`, `'leakyrelu'`, `'prelu'`, `'elu'` or\n `'swish'`.\n See `get_activation` in `model_building_functions.py` for examples\n of implementations of custom activation functions.\n\n Is placed right after every normalization layer\n in the submodel, or - if `normalization` is `None`, right after\n every dense or convolutional layer in the submodel.\n\n If you don't want to simply use the defaults parameters of the\n chosen activation, instead give a *config dict*. See [Explanation of\n *str or config dict*](#doc_config_dict).\n\n**layer_reg** : *dict with None or strs or config dicts as values*\n- Layer regularization to be applied to all dense or convolutional\nlayers in the submodel. This dict collects `kernel_regularizer`s,\n`bias_regularizer`s, `activity_regularizer`s, `kernel_constraint`s\nand `bias_constraint`s to be applied.\n\n If you don't want to simply use the defaults parameters of the\n chosen regularizer, instead give a *config dict*. See [Explanation\n of *str or config dict*](#doc_config_dict).\n\n An example of what is allowed:\n ```python\n {'kernel_regularizer':'l2',\n 'bias_regularizer':{'class_name':'l1',\n 'config':{'l':1e-5}},\n 'activity_regularizer':None,\n 'kernel_constraint':{'class_name':'max_norm',\n 'config':{'max_value':3}},\n 'bias_constraint':'max_norm'}\n ```\n\n Any of these keys can be left out to invoke the default value of\n `None`. If the *dict* is empty, no layer regularization will be\n applied.\n\n**dropout** : *float or dict or None*\n- Arguments to be passed to either dropout layers, in the case of\ndense layers (pass the rate as a float), or dropblock layers, in the\ncase of convolutional layers (pass a dict to be unpacked into the\ndropblock layers - see the [dropblock documentation](https://github.com/MLearing/Keras-DropBlock/blob/master/keras_drop_block/drop_block.py) for what to pass).\nThe dropout or dropblock layers will be inserted immediately after\neach dense or convolutional layer.\nIf `None`, no dropout or dropblock layers will be added.\n\n##### Keys concerning submodel `top`:\nSubmodel for collecting inputs (e.g. from other submodels) and giving\nthe output of the full model.\n\nSee \"Keys concerning all submodels\" for keys `initialization`,\n`activation`, `normalization`, `layer_reg` and `dropout`.\n\n**units** : *list of ints*\n- List with the number of hidden units in each dense layer in the top\nas elements.\nThis includes the output neuron(s), so the last element in `units`\nshould be the number of desired outputs.\nIf the input to the top has the same shape as the target, it is also possible\nfor `units` to be an empty list, when the final output will be the\n`final_activation` (see below) applied to the input to `top`.\n\n**final_activation** : *str*\n- Activation function to apply to the last dense layer. E.g. for\nbinary classification, use `'sigmoid'`, and use `'linear'` or `None`\n(or `'relu'` to enforce non-negativity) for regression.\n\n##### Keys concerning submodel `cnn`:\nSubmodel for processing images. Will only be used if `img_names` is not None.\n\nSee \"Keys concerning all submodels\" for keys `initialization`,\n`activation`, `normalization`, `layer_reg` and `dropout`.\n\n**cnn_type** : *str*\n- The type of CNN that will be constructed. To use the CNN illustrated\n[here](#arch_cnn), set to `'simple'`. Set to `'res'` to use residual\nblocks, as in [He et al., 2016](https://arxiv.org/abs/1603.05027).\nSetting cnn_type to some other string is a good way to implement\nother types of CNNs, which are then integrated into the framework.\nFor instance, to use the ResNet18 of keras_contrib, set to `'res18'` - see `model_building_functions.py` under `get_cnn` for how this is\ndone.\n\n**conv_dim** : *int*\n- One of `2` or `3`. Whether to use 2D or 3D convolutions.\n\n**block_depths** : *list* of *int*s\n- List with number of convolutional layers for each block as elements.\nSee the illustration [here](#arch_cnn) for what constitutes a block.\n\n Note that is `cnn_type` is `'res'`, two convolutional layers are\n used per *int*, e.g. a `block_depth` value of `[1,2,2,2,2]` will\n result in a CNN with 18 convolutional layers, wheres the CNN would\n only have 9 convolutional layers if `cnn_type` had been `'simple'`.\n\n**n_init_filters** : *int*\n- How many filters should be used in the first convolutional layer.\n\n**init_kernel_size** : *int* or *tuple*\n- Kernel size of the first convolutional layer.\n\n If and *int* is given and `conv_dim` is `2`, a kernel size of\n `(init_kernel_size,init_kernel_size)` is used. If `conv_dim` is\n instead `3`, a kernel size of `(init_kernel_size,init_kernel_size,2)`\n is used.\n If a tuple is given, its length must equal `conv_dim`.\n\n**rest_kernel_size** : *int or tuple*\n- Kernel size of all but the first convolutional layer.\n\n If and *int* is given and `conv_dim` is `2`, a kernel size of\n `(init_kernel_size,init_kernel_size)` is used. If `conv_dim` is\n instead `3`, a kernel size of `(init_kernel_size,init_kernel_size,2)`\n is used.\n If a tuple is given, its length must equal `conv_dim`.\n\n**cardinality** : *int*\n- As in [Xie et al., 2016](https://arxiv.org/abs/1611.05431), i.e., grouped convolutions (without the bottleneck using $`1\\times 1 `$ convolutions) will be used instead of the normal convolutions when `cardinality > 1`. Only supported for 2D convolutions.\n\n**use_squeeze_and_excite** : *bool*\n- Whether to use the squeeze and excite block from [Hu et al., 2017](https://arxiv.org/abs/1709.01507). For the `'simple'` `cnn_type` it will be inserted after the activation function (which comes after the normalization layer). For the `'res'` `cnn_type` it will be inserted right before the addition of the skip-connection.\n\n**squeeze_and_excite_ratio** : *int*\n- Ratio to use in squeeze and excite module (see [Hu et al., 2017](https://arxiv.org/abs/1709.01507)), if `use_squeeze_and_excite` is `True`. The ratio should never be less than the number of incoming channels, meaning that one should set `n_init_filters >= ratio` if `use_squeeze_and_excite` is `True`.\n\n**globalavgpool** : *bool*\n- Whether to use global average pooling in the end of the CNN.\n\n**downsampling** : *str or None*\n- One of `None` (no downsampling is used), `'avgpool'` (with\n`pool_size=2`), `'maxpool'` (with `pool_size=2`), or `'strided'`\n(when strided convolutions with stride and kernel size of 2 is used\nto downsample).\n\n When one dimension is more than 1.5 times larger than another\n dimension, that (larger) dimension will be downsampling such that it\n is reduced by a factor of 3, instead of 2. This can be changed in\n `get_downsampling` in `model_building_functions.py`.\n\n**min_size_for_downsampling** : *int*\n- The minimum that any dimension over which convolutions are made (so\nexcluding samples and channels dimensions) must be if downsampling\nis to take place. This is to prevent downsampling down to too small\nimages.\n\n E.g., if 2D downsampling is attempted on a `(None,7,6,4)` image\n tensor while `min_size_for_downsampling` is `6`, the downsampling\n goes through and the result would be `(None,3,3,4)`. If, on the\n other hand, `min_size_for_downsampling` was `7`, the third dimension\n of the image tensor would be too small, and no downsampling would\n take place.\n\n##### Keys concerning submodel `network_in_network`:\nSubmodel for applying network in network ($`1\\times 1`$ convolutions) to the\noutput of the `cnn`. Will only be used if `img_names` is not None.\n\nSee \"Keys concerning all submodels\" for keys `initialization`,\n`activation`, `normalization`, `layer_reg` and `dropout`.\n\n**use** : *bool*\n- Whether to use the network in network model.\n\n**units** : *list of ints*\n- List with the number of filters for each convolutional layer as elements.\n\n**globalavgpool** : *bool*\n- Whether to use global average pooling in the end of the `network_in_network`.\n\n##### Keys concerning submodel `scalar_net`:\nSubmodel for processing scalar variables. Will only be used if `scalar_names` is not None.\n\nSee \"Keys concerning all submodels\" for keys `initialization`,\n`activation`, `normalization`, `layer_reg` and `dropout`.\n\n**units** : *list of ints*\n- List with the number of hidden units in each dense layer as\nelements. If empty, the input is passed on without any processing.\n\n**connect_to** : *list of strs*\n- Which other submodels should receive the output of `scalar_net` as\n(part of) their input. Can contain either `'top'` and/or\n`'FiLM_gen'`. It can in principle also be empty, but you should\nrather turn off the use of scalar variables by setting\n`scalar_names` to `None`.\n\n##### Keys concerning submodel `FiLM_gen`:\nSubmodel for modulating the feature maps of the `cnn` submodel, called\na FiLM generator. See [this](https://distill.pub/2018/feature-wise-transformations/) for an overview. Will only be used if the `connect_to` list of either of `scalar_net` or `track_net` contains `FiLM_gen` (and those submodels are used).\n\nSee \"Keys concerning all submodels\" for keys `initialization`,\n`activation`, `normalization`, `layer_reg` and `dropout`.\n\n**use** : *bool*\n- Whether to use the FiLM generator.\n\n**units** : *list of ints*\n- List with the number of hidden units in each dense layer as\nelements.\n\n##### Keys concerning submodel `track_net`:\nSubmodel for processing tracks. Will only be used if `use_tracks` is `True`.\nUses Deep Sets, see [Zaheer et al., 2017](https://arxiv.org/abs/1703.06114).\n\nSee \"Keys concerning all submodels\" for keys `initialization`,\n`activation`, `normalization`, `layer_reg` and `dropout`.\n\n**phi_units** : *list of ints*\n- List with the number of hidden units in each dense layer of the phi\nnetwork (see [Zaheer et al., 2017](https://arxiv.org/abs/1703.06114)) as elements.\nIf empty, the input is passed on to the rho network.\n\n**rho_units** : *list of ints*\n- List with the number of hidden units in each dense layer of the rho\nnetwork (see [Zaheer et al., 2017](https://arxiv.org/abs/1703.06114)) as elements.\nIf empty, the input is passed on without further processing.\n\n**connect_to** : *list of strs*\n- Which other submodels should receive the output of `track_net` as\n(part of) their input. Can contain either `'top'` and/or\n`'FiLM_gen'`. It can in principle also be empty, but you should\nrather turn off the use of tracks by setting `use_tracks` to\n`False`.\n\n##### Keys concerning submodel `gate_net`:\nSubmodel for processing to-be-gated images. Will only be used if any images in\nthe passed data dict starts with `gate_`.\n\nSee \"Keys concerning all submodels\" for keys `initialization`,\n`activation`, `normalization`, `layer_reg` and `dropout`.\n\n**units** : *list of ints*\n- List with the number of hidden units in each dense layer as\nelements. If empty, the input is passed on to `final_activation`.\n\n**use_res** : *bool*\n- Whether to use a residual connection over the dense layers given by\n`units`.\n\n**final_activation** : *str or config dict*\n- Activation function to apply to the last dense layer, or to the\ninput itself, in case `units` is empty.\n\n The output of the chosen activation function should be in the range\n [0;1].\n Custom activations `'gauss'`, ``'gauss_f'`, `'pgauss'` and\n `'pgauss_f'` have been implemented to use here. The \"p\" stands for\n \"parametric\", while the \"f\" stands for \"flipped\".\n\n**final_activation_init** : *list*\n- List of initial weights for parametric activation functions\n'pgauss'` and `'pgauss_f'`. These contain a single parameter, namely\nthe width of the Gaussian, and so `final_activation_init` should\ncontain a single float, e.g., `final_activation_init` could be\n`[0.5]`.\n\n If you don't want to simply use the defaults parameters of the\n chosen activation, instead give a *config dict*. See [Explanation of\n *str or config dict*](#doc_config_dict).\n\n##### Explanation of *str or config dict*:\nSay you want to use the `RandomNormal` initializer of Keras to\ninitialize the weights of some submodel. If you want to use the\ndefault value of the parameters of this class (`mean=0.0, stddev=0.05,\nseed=None`), you can simply give the *str* `'RandomNormal'` as the\nvalue for the `initialization` key described above.\nHowever, if you want to pass some other parameters to the class, you\ncan instead give a *config dict* as the value for the\n`initialization` key. A *config dict* must have two keys,\n`'class_name'` and `'config'`. The value corresponding to the\n`'class_name'` key should be a *str*, e.g. `'RandomNormal'`, while the\nvalue corresponding to the `'config'` key should be a dict containing\nthe keyword arguments you wish to pass to the class (an empty `'config'`\ndict will use the default values).\n\nYou could for example give the following as the value corresponding to\nthe `initialization` key:\n`{'class_name':'RandomNormal', 'config':{'stddev':1.0}}`\n\nSee the docs for `layer_reg` above for additional examples.\n\nFor a more technical definition of the *config dict*: It is what is\nreturned from `keras.utils.serialize_keras_object(keras_object)`\nwhere `keras_object` is the class instance you wish to create.\n\nIn most cases, aliases are set up such that multiple names for the\nsame class are valid, e.g. if you want to use batch normalization as\nnormalization in some submodel, you can pass any of `'batch'`,\n`'BatchNormalization'`, `'batch_norm'`, etc, as the `'class_name'`.\n\n\n#### dirs : *dict*\nDictionary of directories to put logs in. Should contain the keys `'log'` (the directory to put all the other directories in), `'fig'` (for saving figures), `'saved_models'` (for saving models and/or weights of the models during training) and `'lr_finder'` (for storing the results of the learning rate finder, if used).\n\n The function `deepcalo.utils.create_directories` will return such a dictionary (and create its contained directories).\n\n#### save_figs : *bool*\nWhether to save plots of the model and its submodels.\n\n#### verbose : *bool*\nVerbose output. Set to `2` to disable the progress bar for each epoch.\n\n### Methods\n#### get_model\nCreates the model, as defined by `params`, which it takes as its sole input.\n\n#### train\nTrains the model constructed by `get_model`.\n\n#### evaluate\nEvaluates the model constructed by `get_model`, typically at the end of training using the validation or the test set.\n\n\n## Known issues\n* Model weights produced with `multi_gpu_model` cannot be loaded using single GPU, see https://github.com/keras-team/keras/issues/9562\n\n\n## Todo\n* Implement a linear schedule for DropBlock, as https://github.com/miguelvr/dropblock/blob/master/dropblock/scheduler.py\n\n\n",
"description_content_type": "text/markdown",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://gitlab.com/ffaye/deepcalo",
"keywords": "",
"license": "",
"maintainer": "",
"maintainer_email": "",
"name": "deepcalo",
"package_url": "https://pypi.org/project/deepcalo/",
"platform": "",
"project_url": "https://pypi.org/project/deepcalo/",
"project_urls": {
"Homepage": "https://gitlab.com/ffaye/deepcalo"
},
"release_url": "https://pypi.org/project/deepcalo/0.2.0/",
"requires_dist": [
"numpy (>=1.15.4)",
"keras (>=2.2.4)",
"h5py (>=2.8.0)",
"joblib (>=0.13.0)",
"tqdm (>=4.28.1)",
"scikit-optimize (>=0.5.2+48.g692c21d)",
"keras-contrib (>=2.0.8)",
"keras-drop-block (>=0.4.0)"
],
"requires_python": "",
"summary": "Package for doing deep supervised learning on ATLAS data.",
"version": "0.2.0"
},
"last_serial": 5764337,
"releases": {
"0.1.0": [
{
"comment_text": "",
"digests": {
"md5": "ad4e09d49b3878d56a02251c677eec6f",
"sha256": "3a84b3557b898747d3fc6ca801b15078e3667a9a3d6b80f420dfa45d6e49f32d"
},
"downloads": -1,
"filename": "deepcalo-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad4e09d49b3878d56a02251c677eec6f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 48022,
"upload_time": "2019-04-19T22:46:12",
"url": "https://files.pythonhosted.org/packages/c4/56/7b3b7a9ae75e6593eea601a246a040eddc2a6baa495d77790bead0cb22e6/deepcalo-0.1.0-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "199f816deb89ef04ea9597010d812bbe",
"sha256": "d92430caac8bca5c9b7a8726b8381df74687b35eefa535cd4f555482ae0e69df"
},
"downloads": -1,
"filename": "deepcalo-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "199f816deb89ef04ea9597010d812bbe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 64441,
"upload_time": "2019-04-19T22:46:14",
"url": "https://files.pythonhosted.org/packages/66/a6/ec8ed7d4552d373fbbbcf482d03317050ba84cc993222dbaa1c94191482d/deepcalo-0.1.0.tar.gz"
}
],
"0.1.1": [
{
"comment_text": "",
"digests": {
"md5": "643334c2e4e819edb21b04aa3fdd7408",
"sha256": "a70a2d0c15f3734741648e0d6ec9abebbccf8cee95b368a566487bc3e6f79e1e"
},
"downloads": -1,
"filename": "deepcalo-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "643334c2e4e819edb21b04aa3fdd7408",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 48022,
"upload_time": "2019-04-20T08:13:04",
"url": "https://files.pythonhosted.org/packages/88/df/86e5219cfbf4d942789824cc82889a1a3cec35091c5ed1f0424221647f89/deepcalo-0.1.1-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "e583af466166173d2806dd0fcf5303d9",
"sha256": "0548679a0251c2bb33cbd85d5eb6f16c74dc1ea902dfc21570d1bd99acb095a7"
},
"downloads": -1,
"filename": "deepcalo-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "e583af466166173d2806dd0fcf5303d9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 64450,
"upload_time": "2019-04-20T08:13:06",
"url": "https://files.pythonhosted.org/packages/91/43/308340e7a709aa9d50835a028ca949a6843eee395eda038aa8514f80b1b2/deepcalo-0.1.1.tar.gz"
}
],
"0.1.2": [
{
"comment_text": "",
"digests": {
"md5": "f43b6a130a90165f6547e53ec87f6e9a",
"sha256": "9ae84eec298ffd240a3298eed87bec6de6dc6b48a25c3dd711b83f5276cc7d48"
},
"downloads": -1,
"filename": "deepcalo-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f43b6a130a90165f6547e53ec87f6e9a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 45767,
"upload_time": "2019-04-29T13:46:33",
"url": "https://files.pythonhosted.org/packages/6f/bf/003f49c3cd8c60606001634de360fd290483b5e0c39015227a03b4af1567/deepcalo-0.1.2-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "eab7b2c39ffa212a6cb60b972ac8723a",
"sha256": "6765ada7bcef77d7e1bfe37842eed4b99328404e64f4307fb2c4d1cb15e8d7c6"
},
"downloads": -1,
"filename": "deepcalo-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "eab7b2c39ffa212a6cb60b972ac8723a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 62205,
"upload_time": "2019-04-29T13:46:38",
"url": "https://files.pythonhosted.org/packages/2c/bf/68af61a45ce019b67ada0380fe509e0bff4c51e3b9fa5b4e119c4a0238c9/deepcalo-0.1.2.tar.gz"
}
],
"0.1.3": [
{
"comment_text": "",
"digests": {
"md5": "0a322795f3d870956f47e7ad08a2bfbd",
"sha256": "28ddcdf1f1cf35ef728e3b74e1c82b835bced8484a6c45036441c9a49c8c6469"
},
"downloads": -1,
"filename": "deepcalo-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0a322795f3d870956f47e7ad08a2bfbd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 45765,
"upload_time": "2019-04-30T11:35:13",
"url": "https://files.pythonhosted.org/packages/fa/83/f638d845ff293a8b6c11104a2c00cfa9e890823aec156a94aa8aa4ee86d3/deepcalo-0.1.3-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "b34184ca9a1df8590ffef82f97984b6d",
"sha256": "9d3b39b82964cccaf88ad5106c7e2cf7e40f4c0565af3783ed27c398024c467a"
},
"downloads": -1,
"filename": "deepcalo-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "b34184ca9a1df8590ffef82f97984b6d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 62192,
"upload_time": "2019-04-30T11:35:19",
"url": "https://files.pythonhosted.org/packages/fd/21/93c5d91ac0d512c120e54e32c0320c4d64c7ead625da4663100e6d9f65dd/deepcalo-0.1.3.tar.gz"
}
],
"0.1.4": [
{
"comment_text": "",
"digests": {
"md5": "18f09ec550a5abdec91f1506a327a5d2",
"sha256": "45c9af032ed4c6546aa13163408567704c6d192a5f83c73f00d3d523e86c071d"
},
"downloads": -1,
"filename": "deepcalo-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "18f09ec550a5abdec91f1506a327a5d2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 49723,
"upload_time": "2019-05-09T09:02:31",
"url": "https://files.pythonhosted.org/packages/d8/ad/f73b00aa0f83d00ab0687eb20162225e48c90b84c855033545e5dc3ac34b/deepcalo-0.1.4-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "ff65c5a616e0502bad01708cbd5305af",
"sha256": "47596d64dfbda4fff53e5b5d5c842d3ca291c4ba915801eec233ab842347a825"
},
"downloads": -1,
"filename": "deepcalo-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "ff65c5a616e0502bad01708cbd5305af",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 65353,
"upload_time": "2019-05-09T09:02:33",
"url": "https://files.pythonhosted.org/packages/ae/c5/a886450a355237df59c3a604a37ee58295c0734f8f681d393c6a7796f31a/deepcalo-0.1.4.tar.gz"
}
],
"0.1.5": [
{
"comment_text": "",
"digests": {
"md5": "670b8b9eafd3f4dde52696692d0868c4",
"sha256": "b4853a8f7adb5cc9a5ab01eab67eb9e1a9a45bff47129ed3bbae01258ba3012b"
},
"downloads": -1,
"filename": "deepcalo-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "670b8b9eafd3f4dde52696692d0868c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 50884,
"upload_time": "2019-05-14T14:38:35",
"url": "https://files.pythonhosted.org/packages/4e/87/54b4b1cfa0cda7604d606a8e0f81beed0456145e47b6cbf6c6790e4aebf1/deepcalo-0.1.5-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "d5dba03f98d034c3bee9779665b8ea63",
"sha256": "e6ac37839f330ebc2d1d8d2d535fe2e6f30b0b8a6de38927745e8fe20e43b8b7"
},
"downloads": -1,
"filename": "deepcalo-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "d5dba03f98d034c3bee9779665b8ea63",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 66498,
"upload_time": "2019-05-14T14:38:37",
"url": "https://files.pythonhosted.org/packages/2e/38/cb198e7fda5a64b35ae04aa0d3cce50a4fffb797755cd3aa27cd01a63516/deepcalo-0.1.5.tar.gz"
}
],
"0.2.0": [
{
"comment_text": "",
"digests": {
"md5": "3d3ad35eab2b404d94d6146f5c3850f7",
"sha256": "c4c77de281b70b6c945e832bf981e6fb48fd0e9d484de8eb588a4609b139127c"
},
"downloads": -1,
"filename": "deepcalo-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d3ad35eab2b404d94d6146f5c3850f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 52766,
"upload_time": "2019-08-31T13:23:29",
"url": "https://files.pythonhosted.org/packages/fa/8a/716627e0c24415090bdfdd265947c2051f40cd0a1c140e4e2dd1cf2ee7a3/deepcalo-0.2.0-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "efd0c4bf183a6265d60d23668fb0334c",
"sha256": "33ed447ca7482c56576209b489b168e7ef359793a64dc5083b8a2d19e1d3e30f"
},
"downloads": -1,
"filename": "deepcalo-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "efd0c4bf183a6265d60d23668fb0334c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 69651,
"upload_time": "2019-08-31T13:23:31",
"url": "https://files.pythonhosted.org/packages/25/66/add91052c3c8a61503519d51552846c855768323ca16a376993a089485a2/deepcalo-0.2.0.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "3d3ad35eab2b404d94d6146f5c3850f7",
"sha256": "c4c77de281b70b6c945e832bf981e6fb48fd0e9d484de8eb588a4609b139127c"
},
"downloads": -1,
"filename": "deepcalo-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d3ad35eab2b404d94d6146f5c3850f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 52766,
"upload_time": "2019-08-31T13:23:29",
"url": "https://files.pythonhosted.org/packages/fa/8a/716627e0c24415090bdfdd265947c2051f40cd0a1c140e4e2dd1cf2ee7a3/deepcalo-0.2.0-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "efd0c4bf183a6265d60d23668fb0334c",
"sha256": "33ed447ca7482c56576209b489b168e7ef359793a64dc5083b8a2d19e1d3e30f"
},
"downloads": -1,
"filename": "deepcalo-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "efd0c4bf183a6265d60d23668fb0334c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 69651,
"upload_time": "2019-08-31T13:23:31",
"url": "https://files.pythonhosted.org/packages/25/66/add91052c3c8a61503519d51552846c855768323ca16a376993a089485a2/deepcalo-0.2.0.tar.gz"
}
]
}
![](\"images/cnn_arch.png\")
\n![](\"images/network_in_network_arch.png\")
\n![](\"images/top_arch.png\")
\n![](\"images/scalar_net_arch.png\")
\n![](\"images/film_gen_arch.png\")
\n![](\"images/track_net_arch.png\")
\n![](\"images/gate_net_arch.png\")
\n![](\"images/combined_arch.png\")
\n