Translate core BML MATLAB toolbox modules to Python

[Copilot]

Python translation of the foundational BML MATLAB toolbox modules (utils, annot, sync, stat) that other modules depend on.

Package structure

• python/bml/ package with pyproject.toml (numpy, pandas, scipy deps)

Translated modules

• utils.py — getopt, map_values, getidx, readjson, getFs (config parsing, mapping, sampling frequency estimation)
• annot.py — 12 functions for annotation table manipulation using pandas DataFrames: annot_table, annot_overlap, annot_intersect, annot_filter, annot_consolidate, annot_rename, annot_read/write, annot_read_tsv/write_tsv, annot_rowbind, annot_coverage
• sync.py — time2idx, idx2time (time↔sample index conversion with skip factor and split-sync DataFrame support)
• stat.py — robust_std, FDR, fdr_bh, permutation_test (robust statistics, Benjamini-Hochberg FDR, permutation testing with exact mode)

Design decisions

• MATLAB tables → pandas DataFrames; table description stored in df.attrs['description']
• 1-based id column preserved (matches MATLAB convention and domain semantics)
• MATLAB round(x, n, 'significant') → custom _round_significant() helper
• MATLAB ties-away-from-zero rounding → _matlab_round() helper

from bml.annot import annot_table, annot_intersect, annot_filter
import pandas as pd

x = annot_table(pd.DataFrame({"starts": [1.0, 5.0], "ends": [3.0, 8.0]}))
y = annot_table(pd.DataFrame({"starts": [2.0, 6.0], "ends": [4.0, 9.0]}))
result = annot_intersect(x, y)

Not yet translated

signal/, io/, timefreq/, anat/, spksunit/, plot/, argus/ — these build on the core modules translated here. Tests not yet added.

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.