ThreeWToolkit 0.0.1__tar.gz → 1.0.0__tar.gz

threewtoolkit-1.0.0/LICENSE.md

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) 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. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 Petróleo Brasileiro S.A.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

threewtoolkit-1.0.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: ThreeWToolkit
+Version: 1.0.0
+Summary: A modular and open-source AI toolkit for time-series processing, aimed at fault detection and classification in oil well operation
+Author-email: Ricardo Emanuel Vaz Vargas <ricardo.vargas@petrobras.com.br>
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: scipy>=1.15.2
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: scikit-learn>=1.6.1
+Requires-Dist: matplotlib>=3.10.1
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: plotly>=6.0.0
+Requires-Dist: imbalanced-learn>=0.13.0
+Requires-Dist: ipykernel>=6.29.5
+Requires-Dist: ipywidgets==8.1.7
+Requires-Dist: jupyter-client==8.6.3
+Requires-Dist: jupyter-core==5.8.1
+Requires-Dist: Pillow>=11.0.0
+Requires-Dist: scikit-image>=0.25.2
+Requires-Dist: torch>=2.7.0
+Requires-Dist: torchvision>=0.22.0
+Requires-Dist: torchmetrics>=1.6.2
+Requires-Dist: timm>=1.0.15
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: pydantic>=2.11
+Requires-Dist: PyWavelets>=1.8.0
+Requires-Dist: pyarrow>=20.0.0
+Requires-Dist: pylatex>=1.4.2
+Requires-Dist: statsmodels>=0.14.5
+Requires-Dist: requests<=2.35.5
+Provides-Extra: dev
+Requires-Dist: black>=25.9.0; extra == "dev"
+Requires-Dist: mypy>=1.16.0; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: jupyter; extra == "dev"
+Requires-Dist: ruff>=0.12.2; extra == "dev"
+Requires-Dist: uv; extra == "dev"
+Requires-Dist: types-requests>=2.32.4.20250611; extra == "dev"
+Requires-Dist: coverage>=7.8.1; extra == "dev"
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: pytest-mock>=3.14.1; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Dynamic: license-file
+
+[![Apache 2.0][apache-shield]][apache] 
+[![Code style][black-shield]][black]
+[![Versioning][semver-shield]][semver]
+
+[apache]: https://opensource.org/licenses/Apache-2.0
+[apache-shield]: https://img.shields.io/badge/License-Apache_2.0-blue.svg
+[black]: https://github.com/psf/black
+[black-shield]: https://img.shields.io/badge/code%20style-black-000000.svg
+[semver]: https://semver.org
+[semver-shield]: https://img.shields.io/badge/semver-2.0.0-blue
+
+<h1>
+  <img src="../../images/3w_logo.png" width="45" style="vertical-align: middle; margin-right: 10px;" />
+  3W Toolkit
+</h1>
+
+<a id="readme-top"></a>
+
+<summary>Table of Contents</summary>
+
+<ol>
+<li><a href="#about-the-project">About</a></li>
+<li><a href="#architecture_overview">Architecture Overview</a></li>
+<li><a href="#dataset">3W Dataset</a></li>
+<li><a href="#installation">Installation & Setup</a></li>
+<li><a href="#notebooks">Jupyter Notebooks & Examples</a></li>
+<li><a href="#contributing">Contributing</a></li>
+</ol>
+
+## 📘 About <a id="about-the-project"></a>
+
+The evolution of machine learning has been catalyzed by the rapid advancement in data acquisition systems, scalable storage, high-performance processing, and increasingly efficient model training through matrix-centric hardware (e.g., GPUs). These advances have enabled the deployment of highly parameterized AI models in real-world applications such as health care, finance, and industrial operations.
+
+In the oil & gas sector, the widespread availability of low-cost sensors has driven a paradigm shift from reactive maintenance to condition-based monitoring (CBM), where faults are detected and classified during ongoing operation. This approach minimizes downtime and improves operational safety. The synergy between AI and big data analysis has thus enabled the development of generalizable classifiers that require minimal domain knowledge and can be effectively adapted to a wide range of operational scenarios.
+
+In this context, we present 3WToolkit+, a modular and open-source AI toolkit for time-series processing, aimed at fault detection and classification in oil well operation. Building upon the experience with the original 3WToolkit system and leveraging the Petrobras <a href="https://github.com/petrobras/3W">3W Dataset</a>, 3WToolkit introduces enhanced functionalities, such as advanced data imputation, deep feature extraction, synthetic data augmentation, and high-performance computing capabilities for model training.
+
+<p align="center">
+  <img src="../../images/petrobras_logo.png" width="150" style="margin-right: 30px;" />
+  <img src="../../images/coppe_logo.png" width="150" />
+</p>
+
+The development of the 3WToolkit+ is the result of a collaborative partnership between Petrobras, with a focus on the CENPES research center, and the COPPE/Universidade Federal do Rio de Janeiro (UFRJ). This joint effort brings together complementary strengths: COPPE/UFRJ contributes decades of proven expertise in signal processing and machine learning model development, while CENPES offers access to highly specialized technical knowledge and real-world operational challenges in the oil and gas sector. This synergy ensures that 3WToolkit+ is both scientifically rigorous and practically relevant, addressing complex scenarios with robust and scalable AI-based solutions for time-series analysis and fault detection in oil well operations.
+
+## 🧩 Architecture Overview <a id="architecture_overview"></a>
+
+The following image illustrates the high-level architecture of the 3W Toolkit, designed to support the full pipeline of machine learning applications using the 3W dataset. From raw data ingestion to model evaluation and delivery to end users. 
+
+The schema below illustrates the main classes of the toolkit. 
+
+<img width="1200" src="../../images/3w_classes_in_groups.jpg">
+
+To better understand how the system is organized, we can divide all classes into two main abstraction layers: **`Application`** and **`Core`**.
+
+* The **`Core`** layer contains all **configuration (`Config`) classes**. These classes define the parameters required by each functional module. In other words, they describe *how* each component should behave, specifying its inputs and parameters.
+
+* The **`Application`** layer contains the **operational classes**, which implement the actual logic for interacting with datasets, preprocessing tools, feature extraction, models, evaluation, visualization, and pipelines. These are the classes that you will uses in workflows.
+
+
+## 📊 3W Dataset <a id="dataset"></a>
+The **3W dataset** serves as a **reference dataset** for this project and is hosted on [Figshare](https://figshare.com/projects/3W_Dataset/251195). However, the toolkit is not limited to the 3W dataset and can be adapted for other datasets as well. 
+
+Further details on the 3W dataset’s structure, preprocessing, and usage are available in the [3W_DATASET_STRUCTURE.md](../3W_DATASET_STRUCTURE.md) file.
+
+
+## ⚙️ Installation & Setup  <a id="installation"></a>
+
+It is possible to perform the installation in different ways.
+
+**1. Fork or clone the repository**  
+**Option A: Fork** 
+1. Go to [https://github.com/petrobras/3W](https://github.com/petrobras/3W)
+2. Click “Fork” in the top-right corner to create a copy under your GitHub account.
+3. Clone your forked repository:
+```bash
+git clone git@github.com:<your-username>/3W.git
+```
+
+**Option B: Clone**
+```bash
+git clone git@github.com:petrobras/3W.git
+```
+
+**2. Install the package**  
+**Option A: Using `pip`** 
+```bash
+pip install -e .
+```
+
+**Option B: Using `uv`**
+```bash
+uv venv .venv
+source venv/bin/activate
+uv pip install -e .
+```
+
+**Option C: Using `conda`**
+```bash
+conda env create -f environment.yml
+conda activate 3W
+```
+
+## 🪐 Jupyter Notebooks & Examples <a id="notebooks"></a>
+A curated set of ready-to-use jupyter notebooks that demonstrate how to use the toolkit to common fault detection tasks using the 3W dataset. These examples accelerate onboarding and reproducibility.
+
+The set of notebooks can be found in the [notebooks folder](../docs/notebooks/)
+
+
+## 🤝 Contributing  <a id="contributing"></a>
+
+We welcome contributions to help us improve and expand the functionality of the 3W toolkit. To ensure a smooth collaboration process, please follow our contrubuting guidelines [here](../CONTRIBUTING.md).
+
+

threewtoolkit-1.0.0/README.md

@@ -0,0 +1,181 @@
+
+[![Apache 2.0][apache-shield]][apache] 
+[![CC BY 4.0][cc-by-shield]][cc-by]
+[![Code style][black-shield]][black]
+[![Versioning][semver-shield]][semver]
+
+[apache]: https://opensource.org/licenses/Apache-2.0
+[apache-shield]: https://img.shields.io/badge/License-Apache_2.0-blue.svg
+[cc-by]: http://creativecommons.org/licenses/by/4.0/
+[cc-by-shield]: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg
+[black]: https://github.com/psf/black
+[black-shield]: https://img.shields.io/badge/code%20style-black-000000.svg
+[semver]: https://semver.org
+[semver-shield]: https://img.shields.io/badge/semver-2.0.0-blue
+
+# Table of Content
+
+* [Introduction](#introduction)
+  * [Motivation](#motivation)
+  * [Strategy](#strategy)
+  * [Ambition](#ambition)
+  * [Governance](#governance)
+  * [Contributions](#contributions)
+  * [Licenses](#licenses)
+  * [Versioning](#versioning)
+  * [Questions](#questions)
+* [3W Dataset](#3w-dataset)
+  * [Structure](#structure)
+  * [Overview](#overview)
+* [3W Toolkit](#3w-toolkit)
+  * [Structure](#structure-1)
+  * [Incorporated Problems](#incorporated-problems)
+  * [Examples of Use](#examples-of-use)
+  * [Reproducibility](#reproducibility)
+* [3W Community](#3w-community)
+
+# Introduction
+
+This is the first repository published by Petrobras on GitHub. It supports the 3W Project, which aims to promote experimentation and development of Machine Learning-based approaches and algorithms for specific problems related to detection and classification of undesirable events that occur in offshore oil wells. 
+				
+The 3W Project is based on the 3W Dataset, a database described in [this paper](https://doi.org/10.1016/j.petrol.2019.106223), and on the 3W Toolkit, a software package that promotes experimentation with the 3W Dataset for specific problems. The name **3W** was chosen because this dataset is composed of instances from ***3*** different sources and which contain undesirable events that occur in oil ***W***ells.
+
+## Motivation
+
+Timely detection of undesirable events in oil wells can help prevent production losses, reduce maintenance costs, environmental accidents, and human casualties. Losses related to this type of events can reach 5% of production in certain scenarios, especially in areas such as Flow Assurance and Artificial Lifting Methods. In terms of maintenance, the cost of a maritime probe, required to perform various types of operations, can exceed US $500,000 per day.
+
+Creating a dataset and making it public to be openly experienced can greatly foment the development of tools that can:
+
+* Improve the process of identifying undesirable events in the drilling, completion and production phases of offshore wells;
+* Increase the efficiency of monitoring the integrity of wells and subsea systems, whose related problems can generate invaluable losses for people, environment, and company's image.
+
+## Strategy
+
+The 3W is the first pilot of a Petrobras' program called [Conexões para Inovação - Módulo Open Lab](https://tecnologia.petrobras.com.br/modulo-open-lab). This pilot is an ***open project*** composed by two major resources:
+
+* The [3W Dataset](#3w-dataset), which will be evolved and supplemented with more instances from time to time; 
+* The [3W Toolkit](#3w-toolkit), which will also be evolved (in many ways) to cover an increasing number of undesirable events during its development.
+
+Therefore, our strategy is to make these resources publicly available so that we can develop the 3W Project with a global community collaboratively.
+
+## Ambition
+
+With this project, Petrobras intends to develop (fix, improve, supplement, etc.):
+
+* The [3W Dataset](#3w-dataset) itself;
+* The [3W Toolkit](#3w-toolkit) itself;
+* Approaches and algorithms that can be incorporated into systems dedicated to monitoring undesirable events in offshore oil wells during their respective drilling, completion and production phases;
+* Tools that can be useful for our ambition.
+
+## Governance
+
+The 3W Project was conceived and publicly launched on May 30, 2022 as a strategic action by Petrobras, led by its department responsible for Flow Assurance and its research center ([CENPES](https://www.petrobras.com.br/inovacao-e-tecnologia/centro-de-pesquisa)). Since then, 3W has become increasingly consolidated at Petrobras in several aspects: more professionals specialized in labeling instances, more projects and teams using the resources made available by 3W, more investment in developing the digital tools needed to label and export instances, more interest in including different types of undesirable events that occur in wells during the drilling, completion and production phases, etc. 
+
+Due to this evolution, from May 1st, 2024 the 3W's governance is now done with the participation of the Petrobras' department responsible for Well Integrity.
+
+## Contributions
+
+We expect to receive various types of contributions from individuals, research institutions, startups, companies and partner oil operators.
+
+Before you can contribute to this project, you need to read and agree to the following documents:
+
+* [CODE OF CONDUCT](CODE_OF_CONDUCT.md);
+* [CONTRIBUTOR LICENSE AGREEMENT](CONTRIBUTOR_LICENSE_AGREEMENT.md);
+* [CONTRIBUTING GUIDE](CONTRIBUTING.md).
+
+It is also very important to know, participate and follow the discussions. See the discussions section.
+
+## Licenses
+
+All the code of this project is licensed under the [Apache 2.0 License][apache] and all 3W Dataset's data files (Parquet files saved in subdirectories of the [dataset](dataset) directory) are licensed under the [Creative Commons Attribution 4.0 International License][cc-by].
+
+## Versioning
+
+In the 3W Project, three types of versions will be managed as follows.
+
+* Version of the 3W Toolkit: specified in the [__init__.py](toolkit/__init__.py) file;
+* Version of the 3W Dataset: specified in the [dataset.ini](dataset/dataset.ini) file;
+* Version of the 3W Project: specified with tags in the git repository;
+* We will exclusively use the semantic versioning defined in https://semver.org;
+* Versions will always be updated manually;
+* Versioning of the 3W Toolkit and 3W Dataset are completely independent of each other;
+* The version of the 3W Project will be updated whenever, and only when, there is a new commit in the `main` branch of the repository, regardless of the updated resource: 3W Toolkit, 3W Dataset, 3W Project's documentation, example of use, etc;
+* We will only use annotated tags and for each tag there will be a release in the remote repository (GitHub);
+* Content for each release will be automatically generated with functionality provided by GitHub.
+
+## Questions
+
+See the discussions section. If you don't get clarification, please open discussions to ask your questions so we can answer them.
+
+# 3W Dataset
+
+To the best of its authors' knowledge, this is the first realistic and public dataset with rare undesirable real events in oil wells that can be readily used as a benchmark dataset for development of machine learning techniques related to inherent difficulties of actual data. For more information about the theory behind this dataset, refer to the paper **A realistic and public dataset with rare undesirable real events in oil wells** published in the **Journal of Petroleum Science and Engineering** (link [here](https://doi.org/10.1016/j.petrol.2019.106223)). 
+
+## Structure
+
+The 3W Dataset consists of multiple Parquet files saved in subdirectories of the [dataset](dataset) directory and structured as detailed [here](3W_DATASET_STRUCTURE.md). 
+
+## Overview
+
+A 3W Dataset's general presentation with some quantities and statistics is available in [this](overviews/_baseline/main.ipynb) Jupyter Notebook.
+
+# 3W Toolkit
+
+The 3W Toolkit is a software package written in Python 3 that contains resources that make the following easier:
+
+* [3W Dataset](#3w-dataset) overview generation;
+* Experimentation and comparative analysis of Machine Learning-based approaches and algorithms for specific problems related to undesirable events that occur in offshore oil wells during their respective drilling, completion and production phases;
+* Standardization of key points of the Machine Learning-based algorithm development pipeline.
+
+It is important to note that there are arbitrary choices in this toolkit, but they have been carefully made to allow adequate comparative analysis without compromising the ability to experiment with different approaches and algorithms.
+
+## Structure
+
+The 3W Toolkit is implemented in sub-modules as discribed [here](3W_TOOLKIT_STRUCTURE.md).
+
+## Incorporated Problems
+
+Specific problems will be incorporated into this project gradually. At this point, we can work on:
+
+* [Binary classifier of Spurious Closure of DHSV](problems/01_binary_classifier_of_spurious_closure_of_dhsv/README.md).
+
+All specification is detailed in the [CONTRIBUTING GUIDE](CONTRIBUTING.md).
+
+## Examples of Use
+
+The list below with examples of how to use the 3W Toolkit will be incremented throughout its development.
+
+* 3W Dataset's overviews:
+  * [Baseline](overviews/_baseline/main.ipynb)
+  * [André Machado's overview](overviews/AndreMachado/main.ipynb)
+* Binary classifier of Spurious Closure of DHSV:
+  * [Baseline](problems/01_binary_classifier_of_spurious_closure_of_dhsv/_baseline/main.ipynb)
+
+For a contribution of yours to be listed here, follow the instructions detailed in the [CONTRIBUTING GUIDE](CONTRIBUTING.md).
+
+## Reproducibility
+
+For all results generated by the 3W Toolkit to be consistent, we recommend you create and use a virtual environment with the packages versions specified in the [environment.yml](environment.yml), which was generated with [conda](https://docs.conda.io). Our current recommendation is to use the conda distributed by [Miniforge](https://conda-forge.org/download/). Download and install Miniforge according to the official instructions. Open a prompt on your operating system (Windows, Linux or MacOS). Make sure the current directory is the directory where you have the 3W. Run the following commands as needed:
+
+* To create a virtual environment from our [environment.yml](environment.yml): 
+```
+$ conda env create -f environment.yml
+```
+* To activate the created virtual environment:
+```
+$ conda activate 3W
+```
+* To use the 3W Toolkit resources interactively:
+```
+$ python
+```
+* To initialize a local Jupyter Notebook server:
+```
+$ jupyter notebook
+```
+
+# 3W Community
+
+The 3W Community is gradually expanding and is made up of independent professionals and representatives of research institutions, startups, companies and oil operators from different countries.
+
+More information about this community can be found [here](community/README.md).

threewtoolkit-1.0.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "ThreeWToolkit"
+version = "1.0.0"
+description = "A modular and open-source AI toolkit for time-series processing, aimed at fault detection and classification in oil well operation"
+readme = { file = "toolkit/ThreeWToolkit/README.md", content-type = "text/markdown" }
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Ricardo Emanuel Vaz Vargas", email = "ricardo.vargas@petrobras.com.br" },
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy>=1.26.4",
+    "scipy>=1.15.2",
+    "pandas>=2.2.3",
+    "scikit-learn>=1.6.1",
+    "matplotlib>=3.10.1",
+    "seaborn>=0.13.2",
+    "plotly>=6.0.0",
+    "imbalanced-learn>=0.13.0",
+    "ipykernel>=6.29.5",
+    "ipywidgets==8.1.7",
+    "jupyter-client==8.6.3",
+    "jupyter-core==5.8.1",
+    "Pillow>=11.0.0",
+    "scikit-image>=0.25.2",
+    "torch>=2.7.0",
+    "torchvision>=0.22.0",
+    "torchmetrics>=1.6.2",
+    "timm>=1.0.15",
+    "tqdm>=4.67.1",
+    "pydantic>=2.11",
+    "PyWavelets>=1.8.0",
+    "pyarrow>=20.0.0",
+    "pylatex>=1.4.2",
+    "statsmodels>=0.14.5",
+    "requests<=2.35.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "black>=25.9.0",
+    "mypy>=1.16.0",
+    "flake8",
+    "jupyter",
+    "ruff>=0.12.2",
+    "uv",
+    "types-requests>=2.32.4.20250611",
+    "coverage>=7.8.1",
+    "pytest>=8.3.5",
+    "pytest-mock>=3.14.1",
+]
+docs = [
+    "mkdocs",
+    "mkdocstrings[python]",
+    "sphinx",
+]
+
+[tool.setuptools.packages.find]
+where = ["toolkit"]
+
+[tool.setuptools.exclude-package-data]
+"*" = ["dataset/*"] 
+
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.coverage.run]
+source = ["toolkit/"]
+branch = true
+omit = ["*/__init__.py"]
+
+[tool.coverage.report]
+show_missing = true
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.10"
+mypy_path = "toolkit/"
+ignore_missing_imports = true
+

threewtoolkit-1.0.0/setup.cfg

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