Skip to content

Commit 642eaea

Browse files
author
Chao Yang
committed
Initial open-source release of ECHO
0 parents  commit 642eaea

43 files changed

Lines changed: 2943 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
* text=auto eol=lf
2+
3+
*.npy binary
4+
*.pt binary
5+
*.png binary
6+
*.pdf binary
7+
*.wav binary

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Bug report
2+
description: Report a reproducible software defect.
3+
title: "[Bug]: "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: Thank you for helping improve ECHO.
9+
- type: textarea
10+
id: description
11+
attributes:
12+
label: Description
13+
description: What happened, and what did you expect?
14+
validations:
15+
required: true
16+
- type: textarea
17+
id: reproduction
18+
attributes:
19+
label: Minimal reproduction
20+
description: Include the command, configuration, and relevant traceback.
21+
render: shell
22+
validations:
23+
required: true
24+
- type: input
25+
id: environment
26+
attributes:
27+
label: Environment
28+
description: OS, Python, PyTorch, CUDA, and selected Mamba backend.
29+
validations:
30+
required: true
31+
- type: checkboxes
32+
id: checks
33+
attributes:
34+
label: Checks
35+
options:
36+
- label: I removed private data and credentials from this report.
37+
required: true
38+
- label: I searched existing issues for duplicates.
39+
required: true

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: Feature request
2+
description: Propose an engineering or research-oriented improvement.
3+
title: "[Feature]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: textarea
7+
id: motivation
8+
attributes:
9+
label: Motivation
10+
description: What problem would this feature solve?
11+
validations:
12+
required: true
13+
- type: textarea
14+
id: proposal
15+
attributes:
16+
label: Proposed change
17+
description: Describe the API, experiment, or implementation you suggest.
18+
validations:
19+
required: true
20+
- type: textarea
21+
id: evidence
22+
attributes:
23+
label: Supporting evidence
24+
description: Include references or evaluation plans where applicable.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
## Summary
2+
3+
Describe the problem and the proposed change.
4+
5+
## Validation
6+
7+
- [ ] `ruff check src scripts tests`
8+
- [ ] `python -m unittest discover -s tests -v`
9+
- [ ] New or changed behavior is covered by tests.
10+
11+
## Reproducibility
12+
13+
Describe affected configurations, data splits, metrics, and seeds. Do not use
14+
synthetic smoke-test results as evidence of scientific improvement.
15+
16+
## Data and privacy
17+
18+
- [ ] This change contains no private recordings, labels, credentials, or
19+
generated model artifacts.

‎.github/workflows/ci.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
test:
14+
runs-on: ubuntu-latest
15+
strategy:
16+
fail-fast: false
17+
matrix:
18+
python-version: ["3.10", "3.11"]
19+
20+
steps:
21+
- name: Check out repository
22+
uses: actions/checkout@v4
23+
24+
- name: Set up Python
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: ${{ matrix.python-version }}
28+
cache: pip
29+
30+
- name: Install CPU PyTorch and project
31+
run: |
32+
python -m pip install --upgrade pip
33+
python -m pip install torch==2.5.1 torchaudio==2.5.1 \
34+
--index-url https://download.pytorch.org/whl/cpu
35+
python -m pip install -e ".[dev]"
36+
37+
- name: Lint
38+
run: ruff check src scripts tests
39+
40+
- name: Test
41+
env:
42+
PYTHONDONTWRITEBYTECODE: "1"
43+
run: python -m unittest discover -s tests -v

‎.gitignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
__pycache__/
2+
*.py[cod]
3+
.pytest_cache/
4+
.ruff_cache/
5+
.uv-cache/
6+
.venv/
7+
build/
8+
dist/
9+
*.egg-info/
10+
11+
data/audio/
12+
data/mel/
13+
data/synthetic/
14+
data/manifest.csv
15+
runs/
16+
tests/generated/

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
## [0.1.0] - 2026-07-16
6+
7+
### Added
8+
9+
- Reference ECHO implementation with dual-level context calibration.
10+
- Portable selective-SSM fallback and optional `mamba-ssm` backend.
11+
- Context-only, acoustic-only, append-only, FiLM, CNN-BiGRU, and ablation
12+
variants.
13+
- Audio preprocessing, condition-level splitting, training, evaluation,
14+
XGBoost, and paired-bootstrap scripts.
15+
- Synthetic-data smoke test, unit tests, documentation, and release metadata.

‎CITATION.cff‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
cff-version: 1.2.0
2+
message: >-
3+
If you use ECHO in your research, please cite this software and the
4+
associated article once its final bibliographic information is available.
5+
title: >-
6+
ECHO: Environment-Calibrated Hydroacoustic Observation for Shrimp
7+
Feed-Intake Estimation
8+
type: software
9+
version: 0.1.0
10+
date-released: 2026-07-16
11+
license: MIT
12+
repository-code: https://github.com/OucAI4ScienceLab/Echo
13+
url: https://github.com/OucAI4ScienceLab/Echo
14+
authors:
15+
- family-names: Huang
16+
given-names: Xin
17+
- family-names: Han
18+
given-names: Xiaoye
19+
- family-names: Li
20+
given-names: Yesen
21+
- family-names: Liu
22+
given-names: Chao
23+
- family-names: Guo
24+
given-names: Zhongwen
25+
- family-names: Wang
26+
given-names: Fang
27+
- family-names: Yang
28+
given-names: Chao
29+
email: chao.yang@ouc.edu.cn

‎CODE_OF_CONDUCT.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Code of Conduct
2+
3+
## Our pledge
4+
5+
We pledge to make participation in this project a respectful and
6+
harassment-free experience for everyone, regardless of age, body size,
7+
disability, ethnicity, sex characteristics, gender identity and expression,
8+
experience level, education, socioeconomic status, nationality, personal
9+
appearance, race, caste, color, religion, sexual identity and orientation, or
10+
technical choices.
11+
12+
## Expected behavior
13+
14+
Examples of behavior that contributes to a positive community include:
15+
16+
- showing empathy and respect for differing viewpoints;
17+
- giving and accepting constructive feedback;
18+
- focusing discussion on reproducible evidence and the project goals;
19+
- acknowledging mistakes and learning from them;
20+
- respecting data ownership, animal-welfare concerns, and research ethics.
21+
22+
Unacceptable behavior includes harassment, discriminatory language, personal
23+
attacks, deliberate disruption, publication of private information, and other
24+
conduct that would reasonably be considered inappropriate in a professional
25+
setting.
26+
27+
## Enforcement
28+
29+
Project maintainers may remove, edit, or reject contributions and interactions
30+
that violate this Code of Conduct. Serious or repeated violations may result in
31+
a temporary or permanent ban from project spaces.
32+
33+
Instances of abusive or unacceptable behavior may be reported privately to
34+
`chao.yang@ouc.edu.cn`. Reports will be reviewed fairly and kept confidential
35+
to the extent possible.
36+
37+
This policy applies in project spaces and when representing the project in
38+
public spaces.

‎CONTRIBUTING.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Contributing to ECHO
2+
3+
Thank you for helping improve ECHO. Contributions that improve
4+
reproducibility, portability, documentation, tests, or scientifically justified
5+
model variants are welcome.
6+
7+
## Development setup
8+
9+
```bash
10+
git clone https://github.com/OucAI4ScienceLab/Echo.git
11+
cd Echo
12+
python -m venv .venv
13+
python -m pip install --upgrade pip
14+
pip install -e ".[dev]"
15+
python -m unittest discover -s tests -v
16+
ruff check src scripts tests
17+
```
18+
19+
The optional fused Mamba implementation is not required for the test suite.
20+
Tests use the portable selective-SSM fallback.
21+
22+
## Pull requests
23+
24+
1. Create a focused branch from `main`.
25+
2. Keep changes scoped and add tests for behavioral changes.
26+
3. Run the test and lint commands above.
27+
4. Explain the scientific or engineering rationale in the pull request.
28+
5. Do not commit private recordings, labels, credentials, or generated model
29+
artifacts.
30+
31+
Changes that claim improved scientific performance should identify the data
32+
split, evaluation metric, random seeds, and comparison protocol. Results from
33+
synthetic smoke-test data are not scientific evidence.
34+
35+
## Issues
36+
37+
Use GitHub issues for reproducible bugs and feature proposals. Include the
38+
operating system, Python and PyTorch versions, selected Mamba backend, command,
39+
configuration, and full error message where relevant.
40+
41+
By participating, you agree to follow the project
42+
[Code of Conduct](CODE_OF_CONDUCT.md).

0 commit comments

Comments
 (0)