Trigger.py revision 1ddd9d3bb4633c4fe48ebb8658d6c6449c7fab44 
1#    Copyright 2015-2015 ARM Limited
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14#
15
16"""Trigger is a representation of the following:
17
18    - Event(s) (:mod:`trappy.base.Base`)
19    - An associated value
20        - scalar
21        - vector
22    - A set of filters
23        - value based
24        - function based
25"""
26
27import types
28from trappy.utils import listify
29import pandas as pd
30
31
32class Trigger(object):
33    """Trigger is an event-value relationship which
34    accepts a run object to "generate" qualified data
35
36    :param run: A trappy Run object
37    :type run: :mod:`trappy.run.Run`
38
39    :param template: A trappy Event to act as a trigger
40    :type template: trappy.Base
41
42    :param filters: Key value filter pairs
43    :type filters: dict
44
45    The filter can either have a function:
46    ::
47
48        def function_based_filter(elem):
49            if condition:
50                return True
51            else:
52                return False
53
54    or a value/list of values
55    ::
56
57        f = {}
58        f["data_column_a"] = function_based_filter
59        f["data_column_b"] = value
60
61    :param value: Value can be a string or a numeric
62    :type value: str, int, float
63
64    :param pivot: This is the column around which the data will be
65        pivoted
66    :type pivot: str
67    """
68
69    def __init__(self, run, template, filters, value, pivot):
70
71        self.template = template
72        self._filters = filters
73        self._value = value
74        self._pivot = pivot
75        self.run = run
76
77    def generate(self, pivot_val):
78        """Generate the trigger data for a given pivot value
79        and a run index
80
81        :param pivot_val: The pivot to generate data for
82        :type pivot_val: hashable
83        """
84
85        trappy_event = getattr(self.run, self.template.name)
86        data_frame = trappy_event.data_frame
87
88        mask = (data_frame[self._pivot] == pivot_val)
89        for key in self._filters:
90
91            operator = self._filters[key]
92
93            if isinstance(operator, types.FunctionType):
94                mask = mask & (data_frame[key].apply(operator))
95            else:
96                value = operator
97                mask = apply_filter_kv(key, value, data_frame, mask)
98
99        data_frame = data_frame[mask]
100
101        if isinstance(self._value, str):
102            return data_frame[value]
103        else:
104            return pd.Series(self._value, index=data_frame.index)
105
106
107def apply_filter_kv(key, value, data_frame, mask):
108    """Internal function to apply a key value
109    filter to a data_frame and update the initial
110    condition provided in mask.
111
112    :param value: The value to checked for
113
114    :param data_frame: The data to be filtered
115    :type data_frame: :mod:`pandas.DataFrame`
116
117    :param mask: Initial Condition Mask
118    :type mask: :mod:`pandas.Series`
119
120    :return: A **mask** to index the data frame
121    """
122
123    value = listify(value)
124    if key not in data_frame.columns:
125        return mask
126    else:
127        for val in value:
128            mask = mask & (data_frame[key] == val)
129        return mask
130