# EQTransformer gives you two models and one threshold to choose > A Python package for earthquake detection and P and S phase picking with a pre-trained attention network, where the practical differences between the original and conservative models live in the threshold you pass and the pinning problems you hit while installing. The source metadata demands Python 3.10.5 exactly while the README still says 3.6 or 3.7. **smousavi05/EQTransformer** — EQTransformer, a python package for earthquake signal detection and phase picking using AI. - Repository: https://github.com/smousavi05/EQTransformer - Website: https://rebrand.ly/EQT-documentations - Stars: 418 · Forks: 167 - Language: Python - License: MIT - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/smousavi05-eqtransformer ## Two pre-trained models, one architecture EQTransformer is a deep neural network with an attention mechanism and a hierarchical layout built for seismic signals, trained on global data. Detection and arrival time picking happen in the same pass, and the package returns prediction probabilities alongside estimated model uncertainties, which is what lets a caller decide how much to trust a pick rather than only whether one was made. The package wraps the whole job list: downloading continuous seismic data, preprocessing, running detection and picking with pre-trained models, building and testing new models, and a simple phase association step. The part worth knowing before you install anything is that two model variants ship and they are not two architectures. The stated difference is one or two layers at most. What actually separates them is the training procedure and the hyperparameters used for data augmentation. One was optimized to minimize the false negative rate, the other to minimize the false positive rate, so the choice is a recall against precision decision you make with a threshold rather than a checkpoint you pick from a menu. The developer is S. Mostafa Mousavi, and the paper behind the original model is linked from the README alongside the documentation site. ## The threshold is the interface you actually work with Since the models differ by a layer or two, the numbers you pass are the real interface. The original model, the one in the paper, is meant to run at roughly 0.3 for P and S and 0.5 for detection. The conservative model is meant to run at a much lower level, 0.03 for P and S. The reasoning behind each is specific. The original model suits work where false positives are cheap, and event location is the named case, because association, location and especially relocation will remove most of them downstream. The conservative model suits work where they are not cheap: travel time tomography, and the case where you take the detected events as templates for template matching, where a bad template propagates into every match drawn from it. Two catalog building recipes follow from the same split. Run the original model for detection and picking, then finish with a cross correlation based event relocation to clean up false positives. Or treat the conservative model's detections as template events and run a complementary template matching pass to pick up the rest. There is also a setting for the failure mode where large events go missing while small ones are found: increase the overlap on the moving windows, 0.9 being the value the README suggests. ## setup.py demands one exact interpreter, the README names two The installation story is inconsistent in a way that will cost you time. The written instructions say you need Python 3.x, specifically 3.6 or 3.7, and the recommended conda line creates the environment with python=3.7. The packaging metadata in `setup.py` declares `python_requires='==3.10.5'`, an exact pin rather than a range, at a moment when the README's own M1 note asks for Python 3.9 or newer and creates python=3.10. That combination is not a rounding difference. An exact `==` marker in `python_requires` is checked by pip before anything is installed, so a 3.11 or 3.12 interpreter will not satisfy it, while the 3.7 environment the README tells you to create would not satisfy it either. The version in the same file is 0.1.61, and the package name is capitalized as EQTransformer, which matters because the PyPI install line uses that exact spelling. The default branch is master rather than main. The practical reading is that the conda channel and PyPI artifacts are the paths the maintainer actually builds, and the GitHub tree is where the drift has accumulated. Note too that the README says the GitHub version has been modified for Tensorflow 2.5.0, which tells you the repository is not identical to the published package. ## Three TensorFlow distributions and a numpy pin that contradict each other The dependency list is where the source install path gets fragile. `install_requires` names three TensorFlow distributions at once: `tensorflow-deps==2.9.0`, `tensorflow-macos==2.9.2` and `tensorflow~=2.5.0`, alongside `keras==2.9.0` and `tensorflow-estimator==2.9.0`. `tensorflow-deps` and `tensorflow-macos` are platform specific distributions, and `matplotlib-base==3.5.2` is the macOS flavour of matplotlib, so a Linux or Windows install is asked for packages that only exist for another platform. The numpy line contradicts the TensorFlow line inside the same list. `numpy==1.22.4` is pinned, with a comment saying the approximate version wanted is 1.19.x but at least 1.19.2, and `tensorflow~=2.5.0` carries the comment that tensorflow below 2.7.0 needs numpy below 1.20.0. A pin of 1.22.4 is above that. `requirements.txt` is a different list again, looser throughout: numpy~=1.19.2, keras~=2.3.1, h5py~=3.1.0, scipy>=1.4.1, keyring>=15.1, pkginfo>=1.4.2, tqdm>=4.48.0, with matplotlib, pandas, obspy and jupyter unpinned. So `python setup.py install` and `pip install -r requirements.txt` produce different environments from the same repository, and the comments in `setup.py` suggest the loose file is closer to what the code was written against. ## Four install paths and one that needs repeating The conda path is the recommended one, and it comes with the most honest warning in the README: sometimes you need to keep re-executing the last line multiple times before it succeeds. ```bash conda create -n eqt python=3.7 conda activate eqt conda install conda-forge::obspy conda install -c smousavi05 eqtransformer ``` That gets ObsPy from conda-forge and EQTransformer from the author's own channel. PyPI is the short route if you already have ObsPy installed: ```bash pip install EQTransformer ``` Source is for people who need the tree itself: ```bash git clone https://github.com/smousavi05/EQTransformer.git cd EQTransformer python setup.py install ``` The same file also carries an upgrade line, `pip install EQTransformer -U`, and a Colab oriented variant that installs straight from the git URL instead of cloning. Apple Silicon gets its own documented procedure, and it is the only path that asks you to edit the source. The README says to change tensorflow to tensorflow-maco in `setup.py`, which does not match the `tensorflow-macos` spelling already present in the dependency list, then create a 3.10 environment, install `tensorflow-deps` from the apple channel, install obspy, jupyter and pandas, install `tensorflow-macos`, and run `python3 setup.py install`. That path hand edits a dependency list, which is the first sign you are now maintaining your own fork. ## Five notebooks, one per job in the package The `examples/` directory is organised by task rather than by API surface, and the file names map directly onto the modules the package provides: `downloading.ipynb` for pulling continuous data, `detection.ipynb` for detection and picking, `association.ipynb` for the phase association step, `training.ipynb` for building and testing new models, and `visualization.ipynb` for inspecting results. There is a third notebook at the repository root, `EQTransformerviaGoogleColab.ipynb`, for running the package in Colab, and a `ModelsAndSampleData/` directory that holds what the pre-trained models and the examples need. `tests/` and `docs/` sit alongside them, and `CONTRIBUTING.md` is at the root rather than under `.github/`. One warning about the notebooks is easy to miss and ruins a first run if you hit it. To execute the examples you may need to reinstall jupyter inside the same environment where EQTransformer is installed, which is why jupyter appears in both `setup.py` and `requirements.txt` at all. If you installed into one environment and are running notebooks from another, that is the fix rather than anything in the notebooks themselves. The tutorials themselves live off the repository, at the documentation site and at a separate examples site, so the notebooks are the worked code and the prose guidance is not in the tree. ## Six named projects that pick up where EqT stops The README keeps a list of related packages, and it is more useful than a generic further reading section because each entry names a specific failure mode of the base model. QuakePhase targets the case of traces recorded at epicentral distances over 100 km, other instrument types, and larger events, all of which degrade a pre-trained pick. The Siamese Earthquake Transformer works the other end, using the learned features inside EqT's own layers as templates and measuring similarity with a Siamese network instead of cross correlation, to recover phase picks missed in low signal to noise seismograms. EdgePhase is a graph based variant that picks phases using multi station data rather than one trace at a time. OBSTransformer is the closest relative: a transfer learned phase picker for ocean bottom seismometer data adopted from EqT, trained on an auto labeled dataset of roughly 36k earthquake and 25k noise samples. QuakeLabeler is the tool for making your own training set in the STEAD format. Blocky Earthquake Transformer is the no code route, a user interface for fine tuning EqT on a specific region without writing code or knowing machine learning in depth. That list is effectively a map of the extension points. If your data is offshore, low SNR, regional, or multi station, one of these already exists, and SeisBench is named as well before the visible text cuts off. ## Conclusion EQTransformer suits a seismologist who already has ObsPy in hand and wants detection and picking from one forward pass with uncertainty estimates attached, and the conservative model is the one to reach for when your catalog cannot absorb false positives. Avoid the GitHub install path unless you have to: its dependency list pins TensorFlow 2.5 while declaring numpy 1.22.4, which its own comment says will not work, so the conda channel or PyPI route is the shorter road. Before running anything, check the Python version against the metadata, since `setup.py` demands exactly 3.10.5 while the written instructions ask for 3.7, and decide whether you want the original model at a 0.3 picking threshold or the conservative one at 0.03. The last push was on 2026-04-13 and the repository publishes no GitHub releases, so there is no changelog to check against except `CHANGELOG`-free commit history; if you depend on it in a pipeline, pin the commit you validated rather than the branch. ## FAQ ### What is the difference between the original and conservative EQTransformer models? Very little in the architecture, only one or two layers. The original model was optimized to minimize the false negative rate and the conservative model to minimize the false positive rate, and the main difference comes from the training procedure and the data augmentation hyperparameters. ### What detection and picking thresholds should I use with EQTransformer? About 0.3 for P and S and 0.5 for detection with the original model, and a much lower 0.03 for P and S with the conservative model. The original fits event location work where false positives get removed by association and relocation; the conservative model fits tomography and template matching, where they do not. ### Which Python version does EQTransformer need? The written instructions say Python 3.6 or 3.7 and create the environment with python=3.7, while `setup.py` declares `python_requires='==3.10.5'`. The Apple Silicon instructions ask for 3.10. Because the marker is an exact match, pip will refuse an interpreter other than 3.10.5. ### How do I install EQTransformer on an M1 Mac? The documented path edits `setup.py` to swap tensorflow for the macOS build, then creates a python=3.10 conda environment, installs `tensorflow-deps` from the apple channel, installs obspy, jupyter and pandas, installs `tensorflow-macos`, and runs `python3 setup.py install`. It is the only route that asks you to modify the dependency list by hand. ### Why is EQTransformer missing large earthquakes in my run? The README points at the window overlap rather than the model. If larger events are missed while smaller ones are detected, increase the overlapping value used for the moving windows, with 0.9 given as an example. Switching from the conservative model to the original one is the other lever, since the original favours recall. ## Sources - [Issues](https://github.com/smousavi05/EQTransformer/issues) - [License: MIT](https://github.com/smousavi05/EQTransformer/blob/master/LICENSE) - [Project website](https://rebrand.ly/EQT-documentations) - [README](https://github.com/smousavi05/EQTransformer/blob/master/README.md) - [smousavi05/EQTransformer on GitHub](https://github.com/smousavi05/EQTransformer) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/smousavi05-eqtransformer