"""Read CND-format subject recordings used by the challenge.

A CND subject directory holds ``dataSubN.mat`` (EEG) and ``dataStimN.mat``
(auditory envelopes), both MATLAB v7 files.  Each file carries one struct
(``neural`` / ``stim``) whose ``data`` field stores the recordings as a cell
array with one entry per trial; a trial loads from its own cell.

The optional preprocessing stage mirrors ``matlab/loadSubject.m`` step for step:
channel selection -> re-referencing -> resampling -> per-trial normalisation.
"""

from __future__ import annotations

import os
import re
from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional, Sequence, Tuple

import numpy as np
import scipy.io as sio

from .config import NEURAL_PREFIX, STIM_PREFIX

# Options that loadSubject() accepts.
_KNOWN_OPTIONS = (
    "channelSelection",
    "reReference",
    "targetFs",
    "normEEG",
    "normFeatures",
)


@dataclass
class SubjectData:
    """One subject's recordings, split per trial.

    Attributes
    ----------
    subject_id : int
        Subject number from the file name.
    fs : float
        Sampling rate of ``neural`` and ``stim`` after preprocessing.
    neural : list of np.ndarray
        Per trial, an ``(n_channels, n_samples)`` EEG matrix.
    stim : list of np.ndarray
        Per trial, an ``(n_streams, n_samples)`` envelope matrix.
    chan_labels : list of str
        Channel labels actually produced, in output order.
    """

    subject_id: int
    fs: float
    neural: List[np.ndarray] = field(default_factory=list)
    stim: List[np.ndarray] = field(default_factory=list)
    chan_labels: List[str] = field(default_factory=list)


def _cellstr(value: Any) -> List[str]:
    """Flatten a MATLAB cellstr / char array as scipy hands it back."""
    if value is None:
        return []
    array = np.asarray(value)
    if array.size == 0:
        return []
    if array.dtype.kind in "US":
        return [str(item) for item in array.reshape(-1)]
    out = []
    for item in array.reshape(-1):
        while isinstance(item, np.ndarray):
            if item.size == 0:
                item = ""
                break
            item = item.reshape(-1)[0]
        out.append(str(item))
    return out


def _resolve_options(preprocessing: Optional[Dict[str, Any]]) -> Dict[str, Any]:
    """Fill the loadSubject() defaults and reject unknown keys.

    Port of ``loadSubject>resolveOpts``: an unknown option raises.
    """
    options = {
        "channelSelection": None,
        "reReference": "none",
        "targetFs": None,
        "normEEG": "none",
        "normFeatures": "none",
    }
    if not preprocessing:
        return options
    unknown = sorted(set(preprocessing) - set(_KNOWN_OPTIONS))
    if unknown:
        raise ValueError(
            "unknown preprocessing option(s) %s; loadSubject knows %s"
            % (unknown, list(_KNOWN_OPTIONS))
        )
    options.update(preprocessing)
    return options


def _build_stream_map(feature_names: List[str]) -> List[int]:
    """Rows of ``stim.data`` carrying ``<feature>_stream<k>``, ordered by ``k``.

    Port of ``loadSubject>buildStreamMap``.  ``k`` is the stream identity (which
    talker).  Rows are ordered by ``k`` numerically (``_stream2`` precedes
    ``_stream10``); that order is what the per-sample labels index.
    """
    rows = []
    identity = []
    for position, name in enumerate(feature_names):
        match = re.search(r"_stream(\d+)$", name)
        if match:
            identity.append(int(match.group(1)))
            rows.append(position)
    if not rows:
        raise ValueError(
            "stim.names contains no '<feature>_stream<k>' entries; there are no "
            "candidate streams to decide between (found: %s)."
            % (", ".join(feature_names) if feature_names else "none")
        )
    order = np.argsort(identity, kind="stable")
    return [rows[i] for i in order]


def load_subject(
    data_dir: str,
    subject_id: int,
    preprocessing: Optional[Dict] = None,
    neural_prefix: str = NEURAL_PREFIX,
    stim_prefix: str = STIM_PREFIX,
) -> SubjectData:
    """Load one subject's neural and stimulus recordings.

    Parameters
    ----------
    data_dir : str
        Directory containing ``<neural_prefix>N.mat`` / ``<stim_prefix>N.mat``.
    subject_id : int
        Subject number ``N``.
    preprocessing : dict, optional
        ``channelSelection``, ``reReference``, ``targetFs``, ``normEEG``,
        ``normFeatures`` -- the same names and meanings as ``loadSubject.m``.
        Default: no channel selection, no re-referencing, native rate, no
        normalisation.
    neural_prefix, stim_prefix : str
        File-name prefixes.  The default reads the raw recordings; pass
        ``pre_dataSub`` / ``pre_dataStim`` for the downsampled copies, which
        are what the shipped decoder was fitted on.

    Returns
    -------
    SubjectData
        Trials are ordered by their column index in the source cell array.
    """
    options = _resolve_options(preprocessing)

    neural_path = os.path.join(data_dir, f"{neural_prefix}{subject_id}.mat")
    stim_path = os.path.join(data_dir, f"{stim_prefix}{subject_id}.mat")

    neural_struct = sio.loadmat(neural_path)["neural"][0, 0]
    stim_struct = sio.loadmat(stim_path)["stim"][0, 0]

    fs_in = float(np.asarray(neural_struct["fs"]).reshape(-1)[0])
    fs_stim = float(np.asarray(stim_struct["fs"]).reshape(-1)[0])
    if fs_stim != fs_in:
        raise ValueError(
            "neural.fs (%g) ~= stim.fs (%g): reconcile upstream first" % (fs_in, fs_stim)
        )

    raw_labels: List[str] = []
    if "chanlocs" in neural_struct.dtype.names:
        chanlocs = neural_struct["chanlocs"]
        if chanlocs.size:
            raw_labels = _cellstr(chanlocs["labels"])

    indices, out_labels = _resolve_channel_selection(
        options["channelSelection"], raw_labels
    )

    neural_cell = neural_struct["data"]
    stim_cell = stim_struct["data"]
    n_trials = neural_cell.shape[1]
    if stim_cell.shape[1] != n_trials:
        raise ValueError(
            "neural has %d trials but stim.data has %d columns"
            % (n_trials, stim_cell.shape[1])
        )

    fs_out = fs_in if options["targetFs"] is None else float(options["targetFs"])

    neural_trials: List[np.ndarray] = []
    for trial_index in range(n_trials):
        block = np.asarray(neural_cell[0, trial_index], dtype=np.float64)  # (T, C)
        block = _apply_channel_selection(block, indices)
        block = _apply_rereference(block, options["reReference"], indices, out_labels)
        block = _resample(block, fs_in, options["targetFs"])
        block = _normalise(block, options["normEEG"])
        neural_trials.append(block.T)  # (n_channels, n_samples)

    if "names" in stim_struct.dtype.names:
        feature_names = _cellstr(stim_struct["names"])
    else:
        feature_names = []
    stream_rows = _build_stream_map(feature_names)

    stim_trials: List[np.ndarray] = []
    for trial_index in range(n_trials):
        streams = []
        for stream_index in stream_rows:
            raw = np.asarray(stim_cell[stream_index, trial_index], dtype=np.float64)
            if raw.ndim > 1 and min(raw.shape) > 1:
                raise ValueError(
                    "stream feature %r has %d columns; the per-sample target "
                    "gather assumes one column per stream. Reduce it before "
                    "decoding." % (feature_names[stream_index], raw.shape[1])
                )
            column = raw.reshape(-1, 1)
            column = _resample(column, fs_in, options["targetFs"])
            column = _normalise(column, options["normFeatures"])
            streams.append(column.reshape(-1))
        trial = np.stack(streams, axis=0)
        if trial.shape[1] != neural_trials[trial_index].shape[1]:
            raise ValueError(
                "trial %d: EEG is %d samples but the features are %d"
                % (trial_index, neural_trials[trial_index].shape[1], trial.shape[1])
            )
        stim_trials.append(trial)

    return SubjectData(
        subject_id=subject_id,
        fs=fs_out,
        neural=neural_trials,
        stim=stim_trials,
        chan_labels=out_labels,
    )


# =====================================================================
# Channel selection
# =====================================================================
def _resolve_channel_selection(
    selection: Any, labels: Sequence[str]
) -> Tuple[Sequence[float], List[str]]:
    """Return ``(column indices, output labels)``; ``NaN`` marks an absent channel.

    Port of ``loadSubject>resolveChannelSelection``: a requested channel the
    dataset lacks becomes a zero column, and the output order is the requested
    order.
    """
    if selection is None:
        return [], list(labels)

    if isinstance(selection, str):
        raise ValueError(
            "channelSelection %r is a set name; pass an explicit list of labels "
            "or indices (the MATLAB package resolves set names through "
            "resolveChannelSet.m)" % (selection,)
        )

    if not isinstance(selection, (int, float, np.integer, np.floating)):
        requested = _cellstr(selection)
        if not labels:
            raise ValueError("label-based channelSelection needs chanlocs labels")
        lowered = [label.lower() for label in labels]
        indices: List[float] = []
        missing = []
        for name in requested:
            try:
                indices.append(lowered.index(name.lower()))
            except ValueError:
                indices.append(np.nan)
                missing.append(name)
        if len(missing) == len(requested):
            raise ValueError("none of the requested channels are present in this dataset")
        if missing:
            print(
                "warning: %d of %d requested channels are missing and become zero "
                "columns: %s" % (len(missing), len(requested), ", ".join(missing))
            )
        return indices, requested

    # Numeric indices: the escape hatch, 1-based like MATLAB. The labels returned
    # describe the SELECTED columns, one per entry of the block, as in
    # ``loadSubject>selectedChannelLabels``.
    column_indices = [int(item) for item in np.asarray(selection).reshape(-1)]
    if not labels:
        return column_indices, []
    out_of_range = [i for i in column_indices if not 1 <= i <= len(labels)]
    if out_of_range:
        raise ValueError(
            "channelSelection indices %s are outside 1..%d (indices are 1-based)"
            % (out_of_range, len(labels))
        )
    return column_indices, [labels[i - 1] for i in column_indices]


def _apply_channel_selection(block: np.ndarray, indices: Sequence[float]) -> np.ndarray:
    if not indices:
        return block
    present = ~np.isnan(np.asarray(indices, dtype=float))
    out = np.zeros((block.shape[0], len(indices)), dtype=block.dtype)
    columns = [int(i) for i, keep in zip(indices, present) if keep]
    out[:, present] = block[:, columns]
    return out


def _present_mask(indices: Sequence[float], n_cols: int) -> np.ndarray:
    if not indices:
        return np.ones(n_cols, dtype=bool)
    return ~np.isnan(np.asarray(indices, dtype=float))


# =====================================================================
# Re-referencing, resampling, normalisation
# =====================================================================
def _apply_rereference(
    block: np.ndarray, reference: Any, indices: Sequence[float], labels: Sequence[str]
) -> np.ndarray:
    if reference in (None, "none"):
        return block
    if reference in ("CAR", "avg"):
        present = _present_mask(indices, block.shape[1])
        block[:, present] = block[:, present] - block[:, present].mean(axis=1, keepdims=True)
        return block
    if reference == "mastoids":
        raise ValueError("mastoid re-referencing is not implemented")
    if isinstance(reference, str):
        match = [i for i, label in enumerate(labels) if label == reference]
        if not match:
            raise ValueError(
                "reReference %r is not a known option or a selected channel label"
                % (reference,)
            )
        return block - block[:, [match[0]]]
    # Numeric reference: 1-based, the same base as the numeric channelSelection
    # above and as ``loadSubject>applyReReference`` (``X - X(:, ref)``).
    column = int(reference)
    if not 1 <= column <= block.shape[1]:
        raise ValueError(
            "reReference index %d is outside 1..%d (indices are 1-based)"
            % (column, block.shape[1])
        )
    return block - block[:, [column - 1]]


def _resample(block: np.ndarray, fs_in: float, target_fs: Optional[float]) -> np.ndarray:
    """Port of ``loadSubject>resampleSignal``.

    An integer ratio decimates without an anti-alias filter (MATLAB
    ``downsample``); anything else goes through ``resample_poly`` (MATLAB
    ``resample``) and warns.
    """
    if target_fs is None or float(target_fs) == fs_in:
        return block
    target_fs = float(target_fs)
    ratio = fs_in / target_fs
    if ratio == int(ratio):
        return block[:: int(ratio)]
    from fractions import Fraction

    from scipy.signal import resample_poly

    print(
        "warning: resampling %g -> %g Hz is not an integer ratio; this trial "
        "cannot be reproduced bit-for-bit by runPredictions.m (MATLAB resample "
        "uses its own filter design). The shipped preprocessing uses 128 -> 32 Hz."
        % (fs_in, target_fs)
    )
    step = Fraction(target_fs / fs_in).limit_denominator(1000)
    return resample_poly(block, step.numerator, step.denominator, axis=0)


def _normalise(block: np.ndarray, kind: Optional[str]) -> np.ndarray:
    """Port of ``loadSubject>applyNormalization`` (zscore uses the N-1 divisor)."""
    if kind in (None, "none"):
        return block
    if kind == "zscore":
        sigma = block.std(axis=0, ddof=1, keepdims=True)
        sigma[sigma == 0] = 1.0
        return (block - block.mean(axis=0, keepdims=True)) / sigma
    if kind == "center":
        return block - block.mean(axis=0, keepdims=True)
    if kind == "froNorm":
        scaled = block / np.linalg.norm(block, "fro") * block.shape[1]
        return scaled - scaled.mean(axis=0, keepdims=True)
    raise ValueError("unknown normalisation %r (use none/zscore/center/froNorm)" % (kind,))
