/AutoQuake_New

AutoQuake: An Automated, All-in-One Solution for Earthquake Catalog Generation

Primary LanguageJupyter NotebookMIT LicenseMIT

AutoQuake

AutoQuake: An Automated, All-in-One Solution for Earthquake Catalog Generation.: An object-oriented package that integrates each step of generating an earthquake catalog. The package connects each step as an object, making it easy to manage and streamline the process.

Table of Contents

Getting Started

To get started with this project, choose the scenario that best describes your needs:

Scenario 1: Preliminary Users (Use Only)

If you only want to use the package without contributing to the codebase, follow these simple steps:

  1. Clone the repository: 
    git clone --branch main git@github.com:IES-ESLab/AutoQuake.git
cd AutoQuake
  2. Install dependecies: Follow the installation instructions in the Installation section.
  3. Use the Package: Follow the instructions in the Usage section to start generating earthquake catalogs.
  4. Report Issues: If you encounter any problems or have suggestions for improvement, please open or report an issue. Describe the problem in detail to help us address it quickly.

Scenario 2: Contributors (Recommended. Develop and Improve)

If you’re interested in contributing to the development of this project, follow these steps:

  1. Fork the repository: Visit the GitHub page of the repository and click on "Fork" to create your own copy.
  2. Clone your forked repository: 
    git clone --branch dev https://github.com/your-username/AutoQuake.git # clone the dev branch
cd AutoQuake
  3. Install dependecies: Follow the installation instructions in the Installation section.
  4. Create a new branch: It’s a good practice to work on a feature or bug fix in a separate branch. 
    git checkout -b feature/your-feature-name
  5. Make your changes and commit them: 
    git add .
git commit -m "Description of your changes"
  6. Push your changes to your forked repository: 
    git push origin feature/your-feature-name
  7. Open a Pull Request: Once your changes are pushed, go to the original repository on GitHub and open a Pull Request from your branch to the dev branch of the main repository. Read to our Contributing section for more details on how to contribute to this project.

Installation

This package supports both requirements.txt and env.yml for dependency management. Choose one of the following installation methods:

1. Using Conda (env.yml)

If you’re using Conda, create a new environment directly from the provided env.yml file:

conda env create -f env.yml
conda activate AutoQuake_v0

2. Using pip (requirements.txt)

To install dependencies using pip:

pip install -r requirements.txt

3. Configurations with pyproject.toml

The pyproject.toml file contains configuration settings, including code linting rules (using ruff) and project metadata. To apply these settings, make sure to install ruff:

pip install ruff

Dataset Structure (both hdf5 for DAS and SAC for Seismometer)

Important: For the package to function correctly, the dataset must follow a specific directory structure. Ensure your data is organized as follows:

/dataset_parent_dir/
 ├── YYYYMMDD/             # Year-Month-Day format for each data folder
 │   └── waveform.SAC      # Waveform data in SAC format
  • Waveform files should be placed in YYYYMMDD subdirectories under the dataset_parent_dir.
  • Certain steps or programs may require that the dataset be placed in specific directories to operate correctly due to their original design.

Usage

This package includes a Sphinx-generated documentation site and a Jupyter Notebook for a step-by-step guideline.

Documentation

The documentation includes:

  • Installation and Setup Guide: Step-by-step instructions for setting up and using the package.
  • API Reference: Detailed explanations of each class, method, and function.
  • Workflow Examples: Usage examples demonstrating how to generate an earthquake catalog from start to finish.

To build the Sphinx documentation locally, run:

cd docs
make html

The documentation will be generated in docs/_build/html and can be opened in a browser.

Contributing

We encourage developers to contribute to this project. Here’s a quick guide:

  1. Fork the repository and clone your fork (recommended to work with the dev branch).
  2. Create a new branch for your feature or bug fix.
  3. Make changes and commit them.
  4. Push to your branch and open a Pull Request to the dev branch.

Roadmap

Here are the planned future improvements for this project:

  • Interactive Visualization: Add interactive tools for visualizing and analyzing earthquake catalogs.
  • Enhanced Validation: Improved data validation checks to ensure datasets are correctly formatted and complete.
  • Performance Optimization: Memory and performance enhancements to better handle large datasets.
  • Additional Data Format Support: Add compatibility for other seismic data formats.
  • Refactoring Fortrans into Python: Replace existing Fortran code with Python implementations for better maintainability and compatibility.
  • Integration with Existing Tools: Integrate with popular seismic data processing tools and platforms.

The roadmap can adapt based on user feedback and new technology developments. If you’re interested in contributing to any of these features, check the Contributing section.

License

This project is licensed under the MIT License, which allows for reuse, modification, and distribution with minimal restrictions. See the LICENSE file for the full MIT License text.

Submodule Licenses

This repository includes third-party submodules with their own licensing terms:

  1. GaMMA - MIT License: Permissive license allowing free use, modification, and distribution.
  2. EQNet - Academic and Commercial License:
    • This submodule is available for academic and research use only. For commercial use, a separate license is required. Contact the authors for more information.
    • Users must provide proper attribution in any publications resulting from its use.

Please review each submodule’s LICENSE file for detailed terms.

Submodules and External Dependencies

This project relies on the following external repositories as submodules:

  1. EQNet: A forked repository contains the PhaseNet, PhaseNet-DAS.
  2. GaMMA: A forked repository contains the Gaussian Mixture Model for Earthquake Detection and Location.

References

Contact

If you have any questions or suggestions, feel free to reach out: