petrobras/3W: a labeled dataset and toolkit for offshore oil well anomaly detection
Timely detections for more proactive and effective actions in offshore oil wells!
At a glance
- What is it?
- Petrobras published the 3W Dataset and 3W Toolkit to give researchers labeled multivariate time series from offshore oil wells. The dataset is the real asset; the toolkit is thin glue around it, and the licensing split between code and data matters more than the model choices.
- Who is it for?
- Adopt 3W if your problem is detection or classification of undesirable events in offshore oil wells and you need labeled multivariate time series rather than another unlabeled SCADA dump. Skip it if you need a trained model, a streaming inference service, or a general-purpose time series library: the repository ships data and experimentation scaffolding, not a deployed detector.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Jupyter Notebook, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem 3W addresses, and the people it is written for
Offshore oil wells generate multivariate sensor streams, and some of the events buried in those streams are undesirable: flow assurance problems, artificial lifting failures, integrity issues. The README states that losses related to this type of event can reach 5% of production in certain scenarios, and that a maritime probe needed for various operations can exceed US $500,000 per day. Those two numbers explain why timely detection matters, and they also explain why the interesting part of this repository is not code.
Public labeled data for this domain barely exists. Operators treat well event logs as commercially sensitive, so a researcher who wants to train a classifier for a specific event type usually has nothing to train on. Petrobras' stated ambition is to change that by publishing instances and inviting a global community to develop approaches and algorithms against them. The intended audience is therefore narrow and specific: data scientists and ML engineers working on drilling, completion and production phase monitoring, plus research groups who need a realistic multivariate time series benchmark with domain labels rather than a synthetic one.
The name is explained in the README: instances come from 3 different sources and contain undesirable events that occur in oil wells. That is a provenance statement, not a modeling claim, and it is worth reading as one. The heterogeneity across sources is part of the difficulty, not a defect to be normalized away.
How the dataset and toolkit are split, and why that split is the architecture
The project is two resources, not one. The 3W Dataset holds the instances. The 3W Toolkit is a software package that promotes experimentation with that dataset for specific problems. The README describes the dataset as Parquet files saved in subdirectories of the dataset directory, and the toolkit as the layer you use to work with them.
That division shows up in versioning too. The README states that the 3W Toolkit version lives in pyproject.toml, the 3W Dataset version lives in dataset/dataset.ini, and the two are completely independent of each other. A separate 3W Project version is applied as annotated git tags, updated whenever and only when there is a new commit on main, regardless of which resource changed. Practically, this means a pip install of the toolkit and a git checkout of the repository are two different version decisions, and a bug report needs both.
The repository is primarily Jupyter Notebook, which tells you how the maintainers expect the toolkit to be consumed: interactively, with examples of use and reproducibility sections in the README pointing at notebook workflows. The README also mentions an incorporated problems section, meaning the toolkit ships with a defined set of tasks rather than a general API surface. If your event type is not among those incorporated problems, you are working with the raw Parquet files and writing your own loading and windowing code.
Getting it running: versions, config files, and what the README actually gives you
The README does not print an installation command, and this review will not invent one. What it does give is the set of files that pin behavior: pyproject.toml for the 3W Toolkit version, dataset/dataset.ini for the 3W Dataset version, and the dataset directory holding the Parquet files organized in subdirectories. Those three paths are the ones to inspect first in any checkout.
The licensing is stated explicitly and splits along the same line as the versioning. All code in the project is Apache-2.0. All 3W Dataset data files, meaning the Parquet files under the dataset directory, are CC BY 4.0. That is a permissive combination for code and an attribution requirement for data. If you redistribute a derived dataset, or ship a model trained on it alongside the training data, the attribution obligation attaches to the data, not to your code. The repository also carries a CC BY 4.0 badge alongside the Apache 2.0 badge, consistent with that split.
Contributions have their own gate. The README requires reading and agreeing to CODE_OF_CONDUCT.md, CONTRIBUTOR_LICENSE_AGREEMENT.md and CONTRIBUTING.md before contributing, and points to discussions as the place where project discussion happens. If you plan to submit new labeled instances rather than just consume them, the contributor license agreement is the document to read before writing code, because it governs what Petrobras can do with what you send.
What the toolkit does not do, and where the release cadence becomes a problem
The release history is dense: v.1.86.0, v.1.85.0 and v.1.84.0 all landed within roughly two days of each other, and the repository's last push timestamp matches the newest release. SemVer is used, and the README states versions are always updated manually. Frequent patch and minor bumps are consistent with a project that is actively labeling instances and adjusting the toolkit, but they also mean a pinned dependency on the toolkit can drift quickly. Anyone building a reproducible pipeline should pin an exact 3W Toolkit version rather than a range, and record the 3W Dataset version from dataset/dataset.ini in the same artifact, because the two move independently.
The larger limitation is scope. This is an experimentation resource. The README describes the toolkit as promoting experimentation with the dataset for specific problems, and describes the project's ambition as developing approaches and algorithms that can be incorporated into monitoring systems. Incorporated into, not shipped as. There is no claim of a production detector, no streaming inference component, no alerting path, and no operational deployment guidance in the material provided. A team looking for a drop-in anomaly detection service for a live well will not find one here, and should not read the toolkit's existence as implying one.
A second, quieter constraint is the labeling dependency. The README notes that more professionals specialized in labeling instances is one of the ways 3W has consolidated at Petrobras, and that governance now involves the Well Integrity department as well as Flow Assurance and CENPES. Labels in this domain come from domain experts interpreting well behavior, so dataset growth is bounded by expert time, not by compute. Expect the class distribution to be uneven and the coverage of event types to expand unevenly over time.
Where 3W sits against the alternatives you already know
The obvious comparison is a general time series anomaly detection library or a generic benchmark such as an unlabeled sensor corpus. Those tools give you algorithms and evaluation harnesses, and they expect you to supply data and labels. 3W inverts that: the dataset is the contribution, and the toolkit exists to make the dataset usable. If your bottleneck is model selection, a general library is the better starting point. If your bottleneck is that you have no labeled examples of the failure mode you care about, no amount of algorithm choice fixes it, and 3W is aimed squarely at that gap.
The second comparison is an internal operator dataset. A company with its own historical well data and event logs already has something 3W cannot match: it is drawn from the exact asset class, sensor configuration and operating envelope you will deploy against. 3W's advantage is that it is public, citable and available before you have collected anything, which makes it useful for prototyping, for benchmarking across institutions, and for publishing results that others can reproduce. Treat it as a starting point and a common reference, not as a substitute for your own labeled history. The README's own framing supports this: instances come from 3 different sources, and your well will be a fourth.
A third comparison is to unlabeled anomaly detection on your own telemetry. That approach avoids the labeling problem entirely and can catch deviations nobody has catalogued. It also cannot distinguish between an undesirable event and a benign operational change, which is exactly the distinction the 3W labels encode. The two approaches answer different questions, and the labeled dataset is the only one of the pair that lets you report precision on a named event type.
Governance, maintenance and the cost of staying current
3W is not a side project. The README states it was conceived and publicly launched on May 30, 2022 as a strategic action led by the department responsible for Flow Assurance and CENPES, and that from May 1st, 2024 governance includes the Well Integrity department. It is described as the first pilot of a Petrobras program called Conexões para Inovação - Módulo Open Lab, and as the first repository Petrobras published on GitHub. Institutional backing of that kind is the reason a labeled industrial dataset can keep growing at all, and it is also the reason to read the governance sections rather than skip them: the departments involved shape which event types get labeled next.
The maintenance cost for an adopter is real but bounded. Because toolkit and dataset version independently, every experiment needs both versions recorded. Because releases are frequent and manual, an upgrade path that follows main will churn. Because the data is CC BY 4.0 while the code is Apache-2.0, any redistribution of Parquet files or derived datasets carries an attribution obligation that Apache-2.0 does not impose on the code. None of this is unusual, but all of it has to be handled deliberately rather than discovered later.
One thing the README does not settle is how long a given dataset version remains available and whether older dataset versions stay fetchable after new instances are added. The versioning rules are documented in VERSIONING.md, which this review has not read in full. Verify that before you build a pipeline that depends on a specific dataset snapshot, because a benchmark result is only reproducible if the snapshot behind it is still retrievable.
A concrete reading of who should adopt 3W
The decision turns on whether labeled undesirable event data is your bottleneck. If it is, 3W is one of the few public sources in this domain, and the Apache-2.0 plus CC BY 4.0 split imposes no barrier beyond attribution on the data. Start by checking which incorporated problems the toolkit covers against the event types you care about, then read dataset/dataset.ini to see which dataset version you are actually getting.
If labeled data is not your bottleneck, 3W adds little. A team that already has years of labeled well history gains a benchmark and a citation, not a capability. A team that wants a deployed detector gains nothing operational at all, because the repository stops at experimentation.
What to verify first, in order: the incorporated problems list against your event taxonomy; the dataset version in dataset/dataset.ini and the toolkit version in pyproject.toml, recorded together in whatever experiment tracker you use; and the attribution mechanics of CC BY 4.0 for any derived Parquet files you plan to publish or share internally. The project's own versioning note is the cleanest statement of its character: the toolkit and the dataset are completely independent of each other, and any pipeline that treats them as one artifact will break on the next release.
Editorial conclusion
Adopt 3W if your problem is detection or classification of undesirable events in offshore oil wells and you need labeled multivariate time series rather than another unlabeled SCADA dump. Skip it if you need a trained model, a streaming inference service, or a general-purpose time series library: the repository ships data and experimentation scaffolding, not a deployed detector. Before committing, verify which undesirable event classes are actually populated in the dataset version you pin, check the 3W Dataset version in dataset/dataset.ini against the 3W Toolkit version in pyproject.toml, and confirm that CC BY 4.0 attribution is compatible with how you intend to redistribute derived data.
Community notes