# SEED-vault
#### SEED Vault is a cross platform GUI utility which can search, view and download seismic data from FDSN servers
- Download & view EQ arrival data via a station-to-event OR an event-to-station search
- Quickly download and archive bulk continuous data, saving your progress along the way
- View and plot event arrivals
- A CLI scripting tool to automate common jobs
- Search, export, or import earthquake event catalogs and station metadata
- Download restricted/embargoed data by storing auth passwords in local config
- Add and use custom FDSN servers
- Saves all downloaded data as miniseed in a local SDS database to speed up future retrievals
- Local sqlite3 database editor
- Load and save search parameters and configuration
Runs on:
- Linux
- Windows
- MacOS
Can run:
- As web service
- From the command line (CLI)
#### User Guide
https://auscope.github.io/seed-vault
---
### Requirements
- 8 GB RAM
- Python >= 3.10
- ObsPy (>=1.4.1), Streamlit (>=1.39), Plotly (>-5.24), Pandas (>=2.2.2), Matplotlib (>=3.8.5)
# Install via pip (easy way)
```
$ python3 -m pip install seed-vault
```
# Install from source (if you insist!)
### Step 1: Clone repository
```bash
$ git clone https://github.com/AuScope/seed-vault.git
```
### Step 2: Setup and run
Then can build via pip:
```
$ python3 -m pip install ./seed-vault
```
Or,
```
#### Linux/MacOS
cd seed-vault
source setup.sh
source run.sh
```
#### Windows
Open a powershell and run following commands:
```
cd seed-vault
.\setup-win.ps1
.\run-win.ps1
```
**NOTES:**
1. For Win OS, you would need to convert the shell scripts to PowerShell. Or simply follow the steps in the shell scripts to set up the app.
2. Requires python3 venv software package e.g. For python v10 on Ubuntu you may need to:
```
sudo apt update
sudo apt install python3.10-venv
```
## Project Folder structure
```
seed-vault/
│
├── seed_vault/ # Python package containing application code
│ ├── docs/ # Documentation
│ ├── models/ # Python modules for data models
│ ├── scripts/ # Example CLI scripts
│ ├── service/ # Services for logic and backend processing
│ ├── tests/ # Test data and utilities
│ ├── ui/ # UI components (Streamlit files)
│ ├── utils/ # Utility functions and helpers
│
└── pyproject.toml # Project configuration file
```
---
# Development
## Setting up with Poetry
If you look to further develop this app, it is highly recommended to set up the project with `poetry`. Follow the steps below to set up using `poetry`.
### Install poetry
Refer to this link: https://python-poetry.org/docs/
Alternatively,
**Linux**
```bash
curl -sSL https://install.python-poetry.org | python3 -
```
then, add following to .bashrc:
```bash
export PATH="$HOME/.local/bin:$PATH"
```
**Windows**
powershell:
```powershell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
```
then, add poetry to your system path. It should be located here:
```
%USERPROFILE%\.poetry\bin
```
**Optional**
To configure poetry to create `.venv` inside project folder, run following:
```
poetry config virtualenvs.in-project true
```
## Install pyenv (Optional)
This project uses python 3.10.\*. If your base python is a different version (check via `python --version`), you may get errors when trying to install via poetry. Use pyenv to manage this.
**Linux**
Install the required packages for building Python with the following command
```
sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev
libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev
xz-utils tk-dev libffi-dev liblzma-dev git
```
Then, install pyenv
```
curl https://pyenv.run | bash
```
After installation, add following to `.bashrc`:
```
export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
```
Run .bashrc to get things updated: `source ~/.bashrc`
### Start the project
Install python 3.12.\* if you have a different version locally:
```
pyenv install 3.12.0
pyenv global 3.12.0
```
Confirm your python version: `python --version`
Install the packages using following.
```
poetry install
```
Start the project:
```
poetry shell
```
To run the app:
```
streamlit run seed_vault/ui/main.py
```
Alternatively, command line is configured for this project. You can also run the app, simply by:
```
seed-vault start
```
## Build Project
### Build Python Library
```
poetry build
```
### Build Installers
_Need to be added_
## Docker Development
To develop and run the application using Docker, follow these steps:
### Prerequisites
- Install Docker Application on your system
### Build and Run the Docker Container
1. Navigate to the project root directory:
```bash
cd seed-vault
```
2. Build and run the Docker container:
```bash
docker compose up --build
```
The application should now be running and accessible at `http://localhost:8501`.
## Export poetry packages to requirements.txt
```
poetry export -f requirements.txt --output requirements.txt --without-hashes
```
## Publishing the lib to test: pypi
Define a package name in pyproject.toml (e.g. `seed-vault`).
Then, run following commands
```bash
poetry build
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry config pypi-token.test-pypi <YOUR PYPI TOKEN>
poetry publish -r testpypi
```
To install from pypi-test:
```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple seed-vault
```
Note: include both `test` and `official` indexes.
## Publishing the lib to official: pypi:
```
poetry build
poetry config pypi-token.pypi <YOUR_PYPI_TOKEN>
poetry publish
```
## Unit test
The repository includes a number of unit tests. These tests only covers
the main functions in `seed_vault.service.seismoloader` as these are the
core logics adopted in the app.
### Run tests
To run the test units:
1. Running only mockup tests
```
poetry run pytest
```
2. Running tests with actual FDSN API calls
```
poetry run pytest --run-real-fdsn
```
3. Generate coverage report:
**to include the whole module:**
```
poetry run pytest --run-real-fdsn --cov=seed_vault --cov-report=html
```
**to only include `service/*` tests:**
```
poetry run pytest --run-real-fdsn --cov=seed_vault --cov-config=.coveragerc --cov-report=html
```
4. Generate coverage badge
```
poetry run coverage-badge -o coverage.svg
```
Raw data
{
"_id": null,
"home_page": null,
"name": "seed-vault",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.10",
"maintainer_email": null,
"keywords": "seismic, FDSN, obspy, earthquakes, miniseed",
"author": "Ben Motevalli",
"author_email": "benyamin.motevalli@csiro.au",
"download_url": "https://files.pythonhosted.org/packages/2f/5c/081fd98ded004878279af526b6ec1e3416c91cfac2f787d2f0220e6f2eae/seed_vault-1.0.0.tar.gz",
"platform": null,
"description": "# SEED-vault\n\n\n\n#### SEED Vault is a cross platform GUI utility which can search, view and download seismic data from FDSN servers\n\n- Download & view EQ arrival data via a station-to-event OR an event-to-station search\n- Quickly download and archive bulk continuous data, saving your progress along the way\n- View and plot event arrivals\n- A CLI scripting tool to automate common jobs\n- Search, export, or import earthquake event catalogs and station metadata\n- Download restricted/embargoed data by storing auth passwords in local config\n- Add and use custom FDSN servers\n- Saves all downloaded data as miniseed in a local SDS database to speed up future retrievals\n- Local sqlite3 database editor\n- Load and save search parameters and configuration\n\nRuns on:\n\n- Linux\n- Windows\n- MacOS\n\nCan run:\n\n- As web service\n- From the command line (CLI)\n\n#### User Guide \n\nhttps://auscope.github.io/seed-vault\n\n---\n\n### Requirements\n\n- 8 GB RAM\n- Python >= 3.10\n- ObsPy (>=1.4.1), Streamlit (>=1.39), Plotly (>-5.24), Pandas (>=2.2.2), Matplotlib (>=3.8.5)\n\n# Install via pip (easy way)\n\n```\n$ python3 -m pip install seed-vault\n```\n\n# Install from source (if you insist!)\n\n### Step 1: Clone repository\n\n```bash\n$ git clone https://github.com/AuScope/seed-vault.git\n```\n\n### Step 2: Setup and run\n\nThen can build via pip:\n\n```\n$ python3 -m pip install ./seed-vault\n```\n\nOr,\n\n```\n#### Linux/MacOS\ncd seed-vault\nsource setup.sh\nsource run.sh\n```\n\n#### Windows\n\nOpen a powershell and run following commands:\n\n```\ncd seed-vault\n.\\setup-win.ps1\n.\\run-win.ps1\n```\n\n**NOTES:**\n\n1. For Win OS, you would need to convert the shell scripts to PowerShell. Or simply follow the steps in the shell scripts to set up the app.\n2. Requires python3 venv software package e.g. For python v10 on Ubuntu you may need to:\n ```\n sudo apt update\n sudo apt install python3.10-venv\n ```\n\n## Project Folder structure\n\n```\nseed-vault/\n\u2502\n\u251c\u2500\u2500 seed_vault/ # Python package containing application code\n\u2502 \u251c\u2500\u2500 docs/ # Documentation\n\u2502 \u251c\u2500\u2500 models/ # Python modules for data models\n\u2502 \u251c\u2500\u2500 scripts/ # Example CLI scripts\n\u2502 \u251c\u2500\u2500 service/ # Services for logic and backend processing\n\u2502 \u251c\u2500\u2500 tests/ # Test data and utilities\n\u2502 \u251c\u2500\u2500 ui/ # UI components (Streamlit files)\n\u2502 \u251c\u2500\u2500 utils/ # Utility functions and helpers\n\u2502\n\u2514\u2500\u2500 pyproject.toml # Project configuration file\n```\n\n---\n\n# Development\n\n## Setting up with Poetry\n\nIf you look to further develop this app, it is highly recommended to set up the project with `poetry`. Follow the steps below to set up using `poetry`.\n\n### Install poetry\n\nRefer to this link: https://python-poetry.org/docs/\n\nAlternatively,\n\n**Linux**\n\n```bash\ncurl -sSL https://install.python-poetry.org | python3 -\n```\n\nthen, add following to .bashrc:\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n**Windows**\npowershell:\n\n```powershell\n(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -\n```\n\nthen, add poetry to your system path. It should be located here:\n\n```\n%USERPROFILE%\\.poetry\\bin\n```\n\n**Optional**\nTo configure poetry to create `.venv` inside project folder, run following:\n\n```\npoetry config virtualenvs.in-project true\n```\n\n## Install pyenv (Optional)\n\nThis project uses python 3.10.\\*. If your base python is a different version (check via `python --version`), you may get errors when trying to install via poetry. Use pyenv to manage this.\n\n**Linux**\n\nInstall the required packages for building Python with the following command\n\n```\nsudo apt update\n\nsudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev\nlibreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev\nxz-utils tk-dev libffi-dev liblzma-dev git\n```\n\nThen, install pyenv\n\n```\ncurl https://pyenv.run | bash\n```\n\nAfter installation, add following to `.bashrc`:\n\n```\nexport PATH=\"$HOME/.pyenv/bin:$PATH\"\n\neval \"$(pyenv init --path)\"\n\neval \"$(pyenv init -)\"\n```\n\nRun .bashrc to get things updated: `source ~/.bashrc`\n\n### Start the project\n\nInstall python 3.12.\\* if you have a different version locally:\n\n```\npyenv install 3.12.0\n\npyenv global 3.12.0\n```\n\nConfirm your python version: `python --version`\n\nInstall the packages using following.\n\n```\npoetry install\n```\n\nStart the project:\n\n```\npoetry shell\n```\n\nTo run the app:\n\n```\nstreamlit run seed_vault/ui/main.py\n```\n\nAlternatively, command line is configured for this project. You can also run the app, simply by:\n\n```\nseed-vault start\n```\n\n## Build Project\n\n### Build Python Library\n\n```\npoetry build\n```\n\n### Build Installers\n\n_Need to be added_\n\n## Docker Development\n\nTo develop and run the application using Docker, follow these steps:\n\n### Prerequisites\n\n- Install Docker Application on your system\n\n### Build and Run the Docker Container\n\n1. Navigate to the project root directory:\n\n```bash\ncd seed-vault\n```\n\n2. Build and run the Docker container:\n\n```bash\ndocker compose up --build\n```\n\nThe application should now be running and accessible at `http://localhost:8501`.\n\n## Export poetry packages to requirements.txt\n\n```\npoetry export -f requirements.txt --output requirements.txt --without-hashes\n```\n\n## Publishing the lib to test: pypi\n\nDefine a package name in pyproject.toml (e.g. `seed-vault`).\nThen, run following commands\n\n```bash\npoetry build\npoetry config repositories.testpypi https://test.pypi.org/legacy/\npoetry config pypi-token.test-pypi <YOUR PYPI TOKEN>\npoetry publish -r testpypi\n```\n\nTo install from pypi-test:\n\n```bash\npip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple seed-vault\n```\n\nNote: include both `test` and `official` indexes.\n\n## Publishing the lib to official: pypi:\n\n```\npoetry build\npoetry config pypi-token.pypi <YOUR_PYPI_TOKEN>\npoetry publish\n```\n\n## Unit test\n\nThe repository includes a number of unit tests. These tests only covers\nthe main functions in `seed_vault.service.seismoloader` as these are the\ncore logics adopted in the app.\n\n### Run tests\n\nTo run the test units:\n\n1. Running only mockup tests\n\n```\npoetry run pytest\n```\n\n2. Running tests with actual FDSN API calls\n\n```\npoetry run pytest --run-real-fdsn\n```\n\n3. Generate coverage report:\n\n**to include the whole module:**\n\n```\npoetry run pytest --run-real-fdsn --cov=seed_vault --cov-report=html\n```\n\n**to only include `service/*` tests:**\n\n```\npoetry run pytest --run-real-fdsn --cov=seed_vault --cov-config=.coveragerc --cov-report=html\n```\n\n4. Generate coverage badge\n\n```\npoetry run coverage-badge -o coverage.svg\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Seismic FDSN data search, view and download tool.",
"version": "1.0.0",
"project_urls": null,
"split_keywords": [
"seismic",
" fdsn",
" obspy",
" earthquakes",
" miniseed"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "844a42e51439e89fe57b02640acbf296aa992c7e2743245f61dfc9fa576a28c6",
"md5": "f36d92252f476635a37b54a9ce31c518",
"sha256": "a7fef9e786d0285591d03464b8915e003be1d103a96dd05fdf2a8c4e468cac3f"
},
"downloads": -1,
"filename": "seed_vault-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f36d92252f476635a37b54a9ce31c518",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.10",
"size": 131436,
"upload_time": "2025-03-19T04:28:36",
"upload_time_iso_8601": "2025-03-19T04:28:36.741448Z",
"url": "https://files.pythonhosted.org/packages/84/4a/42e51439e89fe57b02640acbf296aa992c7e2743245f61dfc9fa576a28c6/seed_vault-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2f5c081fd98ded004878279af526b6ec1e3416c91cfac2f787d2f0220e6f2eae",
"md5": "653762382315106303a7ff636eeee42c",
"sha256": "29ffa85214080de7838c5aa4f47706fb606a8903b6c2d394d29f972a896c41cd"
},
"downloads": -1,
"filename": "seed_vault-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "653762382315106303a7ff636eeee42c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.10",
"size": 113845,
"upload_time": "2025-03-19T04:28:38",
"upload_time_iso_8601": "2025-03-19T04:28:38.868614Z",
"url": "https://files.pythonhosted.org/packages/2f/5c/081fd98ded004878279af526b6ec1e3416c91cfac2f787d2f0220e6f2eae/seed_vault-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-19 04:28:38",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "seed-vault"
}
JSON