ear-analytics-core 5.0.0__tar.gz

ear_analytics_core-5.0.0/LICENSE

@@ -0,0 +1,277 @@
+Eclipse Public License - v 2.0
+
+    THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE
+    PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION
+    OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.
+
+1. DEFINITIONS
+
+"Contribution" means:
+
+  a) in the case of the initial Contributor, the initial content
+     Distributed under this Agreement, and
+
+  b) in the case of each subsequent Contributor:
+     i) changes to the Program, and
+     ii) additions to the Program;
+  where such changes and/or additions to the Program originate from
+  and are Distributed by that particular Contributor. A Contribution
+  "originates" from a Contributor if it was added to the Program by
+  such Contributor itself or anyone acting on such Contributor's behalf.
+  Contributions do not include changes or additions to the Program that
+  are not Modified Works.
+
+"Contributor" means any person or entity that Distributes the Program.
+
+"Licensed Patents" mean patent claims licensable by a Contributor which
+are necessarily infringed by the use or sale of its Contribution alone
+or when combined with the Program.
+
+"Program" means the Contributions Distributed in accordance with this
+Agreement.
+
+"Recipient" means anyone who receives the Program under this Agreement
+or any Secondary License (as applicable), including Contributors.
+
+"Derivative Works" shall mean any work, whether in Source Code or other
+form, that is based on (or derived from) the Program and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship.
+
+"Modified Works" shall mean any work in Source Code or other form that
+results from an addition to, deletion from, or modification of the
+contents of the Program, including, for purposes of clarity any new file
+in Source Code form that contains any contents of the Program. Modified
+Works shall not include works that contain only declarations,
+interfaces, types, classes, structures, or files of the Program solely
+in each case in order to link to, bind by name, or subclass the Program
+or Modified Works thereof.
+
+"Distribute" means the acts of a) distributing or b) making available
+in any manner that enables the transfer of a copy.
+
+"Source Code" means the form of a Program preferred for making
+modifications, including but not limited to software source code,
+documentation source, and configuration files.
+
+"Secondary License" means either the GNU General Public License,
+Version 2.0, or any later versions of that license, including any
+exceptions or additional permissions as identified by the initial
+Contributor.
+
+2. GRANT OF RIGHTS
+
+  a) Subject to the terms of this Agreement, each Contributor hereby
+  grants Recipient a non-exclusive, worldwide, royalty-free copyright
+  license to reproduce, prepare Derivative Works of, publicly display,
+  publicly perform, Distribute and sublicense the Contribution of such
+  Contributor, if any, and such Derivative Works.
+
+  b) Subject to the terms of this Agreement, each Contributor hereby
+  grants Recipient a non-exclusive, worldwide, royalty-free patent
+  license under Licensed Patents to make, use, sell, offer to sell,
+  import and otherwise transfer the Contribution of such Contributor,
+  if any, in Source Code or other form. This patent license shall
+  apply to the combination of the Contribution and the Program if, at
+  the time the Contribution is added by the Contributor, such addition
+  of the Contribution causes such combination to be covered by the
+  Licensed Patents. The patent license shall not apply to any other
+  combinations which include the Contribution. No hardware per se is
+  licensed hereunder.
+
+  c) Recipient understands that although each Contributor grants the
+  licenses to its Contributions set forth herein, no assurances are
+  provided by any Contributor that the Program does not infringe the
+  patent or other intellectual property rights of any other entity.
+  Each Contributor disclaims any liability to Recipient for claims
+  brought by any other entity based on infringement of intellectual
+  property rights or otherwise. As a condition to exercising the
+  rights and licenses granted hereunder, each Recipient hereby
+  assumes sole responsibility to secure any other intellectual
+  property rights needed, if any. For example, if a third party
+  patent license is required to allow Recipient to Distribute the
+  Program, it is Recipient's responsibility to acquire that license
+  before distributing the Program.
+
+  d) Each Contributor represents that to its knowledge it has
+  sufficient copyright rights in its Contribution, if any, to grant
+  the copyright license set forth in this Agreement.
+
+  e) Notwithstanding the terms of any Secondary License, no
+  Contributor makes additional grants to any Recipient (other than
+  those set forth in this Agreement) as a result of such Recipient's
+  receipt of the Program under the terms of a Secondary License
+  (if permitted under the terms of Section 3).
+
+3. REQUIREMENTS
+
+3.1 If a Contributor Distributes the Program in any form, then:
+
+  a) the Program must also be made available as Source Code, in
+  accordance with section 3.2, and the Contributor must accompany
+  the Program with a statement that the Source Code for the Program
+  is available under this Agreement, and informs Recipients how to
+  obtain it in a reasonable manner on or through a medium customarily
+  used for software exchange; and
+
+  b) the Contributor may Distribute the Program under a license
+  different than this Agreement, provided that such license:
+     i) effectively disclaims on behalf of all other Contributors all
+     warranties and conditions, express and implied, including
+     warranties or conditions of title and non-infringement, and
+     implied warranties or conditions of merchantability and fitness
+     for a particular purpose;
+
+     ii) effectively excludes on behalf of all other Contributors all
+     liability for damages, including direct, indirect, special,
+     incidental and consequential damages, such as lost profits;
+
+     iii) does not attempt to limit or alter the recipients' rights
+     in the Source Code under section 3.2; and
+
+     iv) requires any subsequent distribution of the Program by any
+     party to be under a license that satisfies the requirements
+     of this section 3.
+
+3.2 When the Program is Distributed as Source Code:
+
+  a) it must be made available under this Agreement, or if the
+  Program (i) is combined with other material in a separate file or
+  files made available under a Secondary License, and (ii) the initial
+  Contributor attached to the Source Code the notice described in
+  Exhibit A of this Agreement, then the Program may be made available
+  under the terms of such Secondary Licenses, and
+
+  b) a copy of this Agreement must be included with each copy of
+  the Program.
+
+3.3 Contributors may not remove or alter any copyright, patent,
+trademark, attribution notices, disclaimers of warranty, or limitations
+of liability ("notices") contained within the Program from any copy of
+the Program which they Distribute, provided that Contributors may add
+their own appropriate notices.
+
+4. COMMERCIAL DISTRIBUTION
+
+Commercial distributors of software may accept certain responsibilities
+with respect to end users, business partners and the like. While this
+license is intended to facilitate the commercial use of the Program,
+the Contributor who includes the Program in a commercial product
+offering should do so in a manner which does not create potential
+liability for other Contributors. Therefore, if a Contributor includes
+the Program in a commercial product offering, such Contributor
+("Commercial Contributor") hereby agrees to defend and indemnify every
+other Contributor ("Indemnified Contributor") against any losses,
+damages and costs (collectively "Losses") arising from claims, lawsuits
+and other legal actions brought by a third party against the Indemnified
+Contributor to the extent caused by the acts or omissions of such
+Commercial Contributor in connection with its distribution of the Program
+in a commercial product offering. The obligations in this section do not
+apply to any claims or Losses relating to any actual or alleged
+intellectual property infringement. In order to qualify, an Indemnified
+Contributor must: a) promptly notify the Commercial Contributor in
+writing of such claim, and b) allow the Commercial Contributor to control,
+and cooperate with the Commercial Contributor in, the defense and any
+related settlement negotiations. The Indemnified Contributor may
+participate in any such claim at its own expense.
+
+For example, a Contributor might include the Program in a commercial
+product offering, Product X. That Contributor is then a Commercial
+Contributor. If that Commercial Contributor then makes performance
+claims, or offers warranties related to Product X, those performance
+claims and warranties are such Commercial Contributor's responsibility
+alone. Under this section, the Commercial Contributor would have to
+defend claims against the other Contributors related to those performance
+claims and warranties, and if a court requires any other Contributor to
+pay any damages as a result, the Commercial Contributor must pay
+those damages.
+
+5. NO WARRANTY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS"
+BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR
+IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF
+TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+PURPOSE. Each Recipient is solely responsible for determining the
+appropriateness of using and distributing the Program and assumes all
+risks associated with its exercise of rights under this Agreement,
+including but not limited to the risks and costs of program errors,
+compliance with applicable laws, damage to or loss of data, programs
+or equipment, and unavailability or interruption of operations.
+
+6. DISCLAIMER OF LIABILITY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS
+SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST
+PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE
+EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+7. GENERAL
+
+If any provision of this Agreement is invalid or unenforceable under
+applicable law, it shall not affect the validity or enforceability of
+the remainder of the terms of this Agreement, and without further
+action by the parties hereto, such provision shall be reformed to the
+minimum extent necessary to make such provision valid and enforceable.
+
+If Recipient institutes patent litigation against any entity
+(including a cross-claim or counterclaim in a lawsuit) alleging that the
+Program itself (excluding combinations of the Program with other software
+or hardware) infringes such Recipient's patent(s), then such Recipient's
+rights granted under Section 2(b) shall terminate as of the date such
+litigation is filed.
+
+All Recipient's rights under this Agreement shall terminate if it
+fails to comply with any of the material terms or conditions of this
+Agreement and does not cure such failure in a reasonable period of
+time after becoming aware of such noncompliance. If all Recipient's
+rights under this Agreement terminate, Recipient agrees to cease use
+and distribution of the Program as soon as reasonably practicable.
+However, Recipient's obligations under this Agreement and any licenses
+granted by Recipient relating to the Program shall continue and survive.
+
+Everyone is permitted to copy and distribute copies of this Agreement,
+but in order to avoid inconsistency the Agreement is copyrighted and
+may only be modified in the following manner. The Agreement Steward
+reserves the right to publish new versions (including revisions) of
+this Agreement from time to time. No one other than the Agreement
+Steward has the right to modify this Agreement. The Eclipse Foundation
+is the initial Agreement Steward. The Eclipse Foundation may assign the
+responsibility to serve as the Agreement Steward to a suitable separate
+entity. Each new version of the Agreement will be given a distinguishing
+version number. The Program (including Contributions) may always be
+Distributed subject to the version of the Agreement under which it was
+received. In addition, after a new version of the Agreement is published,
+Contributor may elect to Distribute the Program (including its
+Contributions) under the new version.
+
+Except as expressly stated in Sections 2(a) and 2(b) above, Recipient
+receives no rights or licenses to the intellectual property of any
+Contributor under this Agreement, whether expressly, by implication,
+estoppel or otherwise. All rights in the Program not expressly granted
+under this Agreement are reserved. Nothing in this Agreement is intended
+to be enforceable by any entity that is not a Contributor or Recipient.
+No third-party beneficiary rights are created under this Agreement.
+
+Exhibit A - Form of Secondary Licenses Notice
+
+"This Source Code may also be made available under the following
+Secondary Licenses when the conditions for such availability set forth
+in the Eclipse Public License, v. 2.0 are satisfied: {name license(s),
+version(s), and exceptions or additional permissions here}."
+
+  Simply including a copy of this Agreement, including this Exhibit A
+  is not sufficient to license the Source Code under Secondary Licenses.
+
+  If it is not possible or desirable to put the notice in a particular
+  file, then You may include the notice in a location (such as a LICENSE
+  file in a relevant directory) where a recipient would be likely to
+  look for such a notice.
+
+  You may add additional accurate notices of copyright ownership.

ear_analytics_core-5.0.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: ear-analytics-core
+Version: 5.0.0
+Summary: Core library for EAR analytics and Energy Models.
+Author-email: Oriol Vidal <oriol.vidal@eas4dc.com>, Jalal Lakhlili <jalal.lakhlili@eas4dc.com>
+License-Expression: EPL-2.0
+Keywords: data,hpc,analysis,ear
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pandas[output-formatting,performance,plot]
+Requires-Dist: importlib_resources
+Requires-Dist: rich
+Requires-Dist: pylatex
+Requires-Dist: returns
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Dynamic: license-file
+
+# ear_analytics_core
+A package to be used to work with EAR data.
+
+
+## Installation
+
+```bash
+pip install -U pip
+pip install build setuptools wheel
+python -m build
+pip install .
+```
+
+> You can change the destination path by exporting the variable [`PYTHONUSERBASE`](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONUSERBASE).
+> Tool's developers may want to use `pip install -e .` to install the package in editable mode, so there is no need to reinstall every time you want to test a new feature.

ear_analytics_core-5.0.0/README.md

@@ -0,0 +1,15 @@
+# ear_analytics_core
+A package to be used to work with EAR data.
+
+
+## Installation
+
+```bash
+pip install -U pip
+pip install build setuptools wheel
+python -m build
+pip install .
+```
+
+> You can change the destination path by exporting the variable [`PYTHONUSERBASE`](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONUSERBASE).
+> Tool's developers may want to use `pip install -e .` to install the package in editable mode, so there is no need to reinstall every time you want to test a new feature.

ear_analytics_core-5.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ear-analytics-core"
+authors = [
+  {name = "Oriol Vidal", email = "oriol.vidal@eas4dc.com"},
+  {name = "Jalal Lakhlili", email = "jalal.lakhlili@eas4dc.com"}
+]
+description = "Core library for EAR analytics and Energy Models."
+readme = "README.md"
+keywords = ["data", "hpc", "analysis", "ear"]
+license = "EPL-2.0"
+classifiers = [
+  "Programming Language :: Python :: 3",
+]
+version = "5.0.0"
+dependencies = [
+	"numpy",
+  "pandas[performance, plot, output-formatting]",
+  "importlib_resources",
+	"rich",
+  "pylatex",
+	"returns",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.optional-dependencies]
+docs = [
+  "sphinx"
+]
+tests = [
+  "pytest"
+]
+
+

ear_analytics_core-5.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ear_analytics_core-5.0.0/src/ear_analytics_core/__init__.py

@@ -0,0 +1,9 @@
+######################################################################
+# Copyright (c) 2024 Energy Aware Solutions, S.L
+#
+# This program and the accompanying materials are made
+# available under the terms of the Eclipse Public License 2.0
+# which is available at https://www.eclipse.org/legal/epl-2.0/
+#
+# SPDX-License-Identifier: EPL-2.0
+#######################################################################

ear_analytics_core-5.0.0/src/ear_analytics_core/console.py

@@ -0,0 +1,27 @@
+######################################################################
+# Copyright (c) 2024 Energy Aware Solutions, S.L
+#
+# This program and the accompanying materials are made
+# available under the terms of the Eclipse Public License 2.0
+# which is available at https://www.eclipse.org/legal/epl-2.0/
+#
+# SPDX-License-Identifier: EPL-2.0
+#######################################################################
+
+
+
+from rich.console import Console
+
+console = Console()
+
+
+def warning(*args, **kwargs):
+    console.print('[magenta][WARNING][/]', *args, **kwargs)
+
+
+def error(*args, **kwargs):
+    console.print('[bright_red][ERROR][/]', *args, **kwargs)
+
+
+def info(*args, **kwargs):
+    console.print('[cyan][INFO][/]', *args, **kwargs)

ear_analytics_core-5.0.0/src/ear_analytics_core/ear_data.py

@@ -0,0 +1,252 @@
+######################################################################
+# Copyright (c) 2024 Energy Aware Solutions, S.L
+#
+# This program and the accompanying materials are made
+# available under the terms of the Eclipse Public License 2.0
+# which is available at https://www.eclipse.org/legal/epl-2.0/
+#
+# SPDX-License-Identifier: EPL-2.0
+#######################################################################
+
+
+""" This module contains functions that can be applied
+to a DataFrame contained known EAR data. """
+
+import re
+import numpy as np
+import pandas as pd
+
+from returns.result import Result, Failure, Success
+
+from .utils import join_metric_node
+from .metrics import read_metrics_configuration, metric_regex
+from .console import warning
+
+
+def df_filter_invalid_gpu_cols(df: pd.DataFrame) -> pd.DataFrame:
+    """
+    Given a DataFrame containing EAR data, returns a copy of it without all
+    those invalid GPU columns.
+
+    An invalid GPU column is a column with data of a GPU x, for which EAR did
+    not report any GPUx_POWER_W reading.
+    """
+    # The regex is precompiled since it is searched multiple times.
+    gpu_colname_pattern = re.compile(r'GPU(\d)_POWER_W')
+
+    def return_gpupwr_index(gpupwr_colname: str) -> str:
+        """
+        Given a str of the form r'GPUx_POWER_W', returns the x part, if
+        found. Otherwise, returns None.
+
+        The regular expression pattern is taken from gpu_colname_pattern.
+        """
+        match = re.fullmatch(gpu_colname_pattern, gpupwr_colname)
+        if match:
+            try:
+                return match.group(1)
+            except IndexError:
+                return None
+        else:
+            return None
+
+    invalid_gpu_indices = filter(None,  # Filter all elements which are false
+                                 map(return_gpupwr_index,
+                                     df_get_invalid_gpupower_cols(df))
+                                 )
+
+    indices_or = '|'.join(invalid_gpu_indices)
+    filter_str = fr'GPU({indices_or})_\w+'
+    return df.drop(columns=df.filter(regex=filter_str).columns)
+
+
+def df_get_invalid_gpupower_cols(df: pd.DataFrame) -> pd.Index:
+    """
+    Given a pd.DataFrame with EAR data, returns those columns which are
+    actually invalid GPU Power data.
+
+    Invalid GPU power data is all those GPUx_POWER_W columns of the DataFrame
+    that are full of zero values.
+    """
+    return (df
+            .filter(regex=r'GPU\d_POWER_W')
+            .mask(lambda x: x != 0)  # All non-zero as nan
+            .dropna(axis=1, how='all')  # Drop nan columns
+            .columns
+            )
+
+
+def df_get_valid_gpu_data(df, gpu_metrics_regex):
+    """
+    Returns a DataFrame with only valid GPU data.
+
+    Valid GPU data is all those GPU columns of the DataFrame
+    that are not full of zeroes values.
+    """
+    return (df
+            .filter(regex=gpu_metrics_regex)
+            .mask(lambda x: x == 0)  # All 0s as nan
+            .dropna(axis=1, how='all')  # Drop nan columns
+            .mask(lambda x: x.isna(), other=0))  # Return to 0s
+
+
+def df_has_gpu_data(df, gpu_metrics_regex):
+    """
+    Returns whether the DataFrame df has valid GPU data.
+    """
+    return not df.pipe(df_get_valid_gpu_data, gpu_metrics_regex).empty
+
+
+def filter_invalid_gpu_series(df, gpu_metrics_regex):
+    """
+    Given a DataFrame with EAR data, filters those GPU
+    columns that not contain some of the job's GPUs used.
+    """
+    return (df
+            .drop(df  # Erase GPU columns
+                  .filter(regex=gpu_metrics_regex).columns, axis=1)
+            .join(df  # Join with valid GPU columns
+                  .pipe(df_get_valid_gpu_data, gpu_metrics_regex),
+                  validate='one_to_one'))  # Validate the join operation
+
+
+# TODO: This function is not called anywhere
+def df_gpu_node_metrics(df, conf_fn):
+    """
+    Given a DataFrame `df` with EAR data and a configuration filename `conf_fn`
+    Returns a copy of the DataFrame with new columns showing node-level GPU
+    metrics.
+    """
+    metrics_conf = read_metrics_configuration(conf_fn)
+
+    gpu_pwr_regex = metric_regex('gpu_power', metrics_conf)
+    gpu_freq_regex = metric_regex('gpu_freq', metrics_conf)
+    gpu_memfreq_regex = metric_regex('gpu_memfreq', metrics_conf)
+    gpu_util_regex = metric_regex('gpu_util', metrics_conf)
+    gpu_memutil_regex = metric_regex('gpu_memutil', metrics_conf)
+
+    gr_active_regex = metric_regex('dcgmi_gr_engine_active', metrics_conf)
+
+    return (df
+            .assign(
+                tot_gpu_pwr=lambda x: (x.filter(regex=gpu_pwr_regex)
+                                        .sum(axis=1)),  # Agg. GPU power
+
+                avg_gpu_pwr=lambda x: (x.filter(regex=gpu_pwr_regex)
+                                        .mean(axis=1)),  # Avg. GPU power
+
+                avg_gpu_freq=lambda x: (x.filter(regex=gpu_freq_regex)
+                                        .mean(axis=1)),  # Avg. GPU freq
+
+                avg_gpu_memfreq=lambda x: (x.filter(regex=gpu_memfreq_regex)
+                                           .mean(axis=1)),  # Avg. GPU mem freq
+
+                avg_gpu_util=lambda x: (x.filter(regex=gpu_util_regex)
+                                        .mean(axis=1)),  # Avg. % GPU util
+
+                avg_gpu_memutil=lambda x: (x.filter(regex=gpu_memutil_regex)
+                                           .mean(axis=1)),  # Avg %GPU mem util
+                avg_gr_engine_active=lambda x: (x.filter(regex=gr_active_regex)
+                                                .mean(axis=1))
+            ))
+
+
+def metric_agg_timeseries(df, metric):
+    """
+    TODO: Pay attention here because this function depends directly
+    on EAR's output.
+    """
+    return (df
+            .pivot_table(values=metric,
+                         index='TIMESTAMP', columns='NODENAME')
+            .bfill()
+            .ffill()
+            .pipe(join_metric_node)
+            .agg(np.sum, axis=1)
+            )
+
+
+def filter_batch_step(ear_df: pd.DataFrame) -> Result[pd.DataFrame, str]:
+    """
+    This function returns the DataFrame `ear_df` without any SLURM batch step
+    if it has some. It spects the DataFrame containing a column called
+    'STEPID'. If not encountered, returns a copy of the input argument.
+
+    Parameters
+    ----------
+    ear_df: A DataFrame containing EAR signature data. It must have a column
+            named 'STEPID'.
+
+    Return
+    ------
+    A Result type with a Success(pd.DataFrame) with the passed DataFrame
+    filtered or a Failure(str) indicating that the STEPID column does not exist
+    in the passed argument.
+    """
+    if 'STEPID' in ear_df.columns:
+        return Success(ear_df.loc[ear_df['STEPID'] != 4294967291])
+    else:
+        return Failure('STEPID not in data.')
+
+
+def filter_and_query(df, rules):
+    """
+    Returns the resulting DataFrame of applying filtering rules to the passed
+    dataframe `df`. The function first performs a pre-filtering of the
+    dataframe based on column labels and then uses the pd.DataFrame.query
+    method to query for specific row values.
+
+    Rules are configured in `rules` as a dict with the following
+    <key, value> pairs:
+        - 'filter': <A dictionary with a pd.DataFrame.filter's kwarg. This
+          key is optional and it is used to call the function to the passed
+          dataframe before querying.
+        - 'expr': 'A valid string to be passed to pd.DataFrame.query
+          function called on the filtered dataframe. This field is required
+          if and only if the next key is not found.
+        - 'criteria': 'A string with a valid query operation to be concatenated
+          with every column of the pre-filtered dataframe.'
+        - 'join': 'A string with conditional operator, e.g., and, or.'
+
+    (Optional) Pre-filtering consists of calling pd.DataFrame.filter on
+    the passed dataframe and using rules' 'filter' dictionary as kwarg,
+    i.e., df.filter(**rules['filter']).
+
+    If `rules` contains 'expr' string, pd.DataFrame.query is called
+    directly. Otherwise, the expression is build as:
+        <column..0> <criteria> [<join> <column..1> <criteria>]*
+    where 'join' operator is used just when more than one column is found in
+    (maybe pre-filtered) dataframe and it is the 'or' string if `rules` does
+    not provide it.
+    """
+    # If the configuration does not have the 'filter' field, we apply
+    # the filter which returns the identical df
+    prefilter = rules.get('filter', {'items': df.columns})
+    df_filtered = df.filter(**prefilter)
+
+    if not df_filtered.empty:
+        expr = create_ear_dataframe_query(df_filtered, rules)
+        return df_filtered.query(expr), expr
+    return df_filtered, None
+
+
+def create_ear_dataframe_query(df, rules):
+    """Support function for creating the query usied by
+    ear_dataframe_filter_and_query"""
+    expr = rules.get('expr', None)
+    if expr is None:
+        try:
+            criteria = rules['criteria']
+        except KeyError as e:
+            warning(f'The rule has not {e} field.')
+            return None
+        # Create the query to check whether some row matches the
+        # alert criteria
+        # Format: <column> <criteria> <join> <column> <criteria>...
+        join = rules.get('join', 'or')
+        expr = (f' {join} '
+                .join([f'`{col}` {criteria}'
+                       for col in df.columns])
+                )
+    return expr
+