numpy

Files (1)

• SKILL.md

SKILL.md (first lines)

# numpy

Rules and patterns for pure numpy ndarray work — vectorized computation, broadcasting, reshaping, and aggregation.
Builds on `python-style.instructions.md`; do not restate general Python or import-alias rules.

Cross-references:

- DataFrame + numpy bridges (running balance, `array_split` parallelism) → load the `pandas` skill.
- Indicators, signals, forecasting on price series → load the `financial-timeseries` skill.

## Load Patterns and Solutions

Read the following files for named, ready-to-use implementations with when/replaces/gotchas:

- `../../catalogs/numpy-patterns.md`
- `../../catalogs/numpy-solutions.md`

---

## Baseline

Retain NumPy 2.x API guidance. For a dated combined NumPy/pandas/TensorFlow
reference and interpreter fallback, use the
[TensorFlow baseline](../tensorflow/SKILL.md#baseline).
Select a NumPy release compatible with the target interpreter; general Python
style remains 3.11+, not a blanket requirement to use Python 3.12.

---

## Reshaping

Use when an estimator or layer demands a specific array rank.

- sklearn needs 2D: pass `df[["col"]]` (keeps feature names) or `s.to_numpy().reshape(-1, 1)` — not `.values.reshape(len(s), 1)`.
- Keras LSTM/GRU needs a feature axis: append it with `X[..., np.newaxis]` — not a hardcoded `(X.shape[0], X.shape[1], 1)`.
- Flatten with `.ravel()` or `reshape(-1)` (view when possible); `.flatten()` always copies.
  Avoid `.squeeze()` for flattening — it drops every length-1 axis, so a 1-element input becomes 0-d.

```python
scaler.fit_transform(df[["col"]])

X = X[..., np.newaxis]        # (samples, timesteps) -> (samples, timesteps, 1)

flat = arr.ravel()            # 1D regardless of source shape
```

---

## Vectorized Conditionals

Use to encode conditions as numeric signals without a Python loop or `.apply`.

- Binary signal: `np.where(cond, 1.0, 0.0)`; wrap in a `pd.Series` with the original index to keep alignment.
- Three-way outcome: one nested `np.where` level or `np.select`; for 4+ branches use
  `np.select(conditions, choices, default=...)`.
- `np.where` evaluates both branches — wrap guarded division in `np.errstate(divide="ignore", invalid="ignore")`.
- Sign-split rolling sum: clip, then roll — not `rolling().apply(lambda x: np.sum(np.where(...)))`.
- Positions of a value: `np.flatnonzero(arr == target)`; to select values, index with the mask directly.

```python
pos_flow = series.clip(lower=0).rolling(window, min_periods=mp).sum()
neg_flow = series.clip(upper=0).rolling(window, min_periods=mp).sum()

buy_idx = np.flatnonzero(signals == 1)
x_buy = x_array[signals == 1]
```

Catalog: `where-conditional-series`, `where-index-extraction`.

---

## Crossings and Extrema

Use to detect where signals cross or turn.

- Crossing of two series: `np.flatnonzero(np.diff(np.sign(y1 - y2)))` — not an element-wise loop.
  Indices are in `y1[:-1]` coordinates; an exact touch (`sign == 0`) reports two flips.
- Turning points with aligned indices: `np.gradient` (same length) then `np.diff(np.sign(...))`.
  Plain `np.diff` is faster when the off-by-one does not matter → `sign-change-inflection-detection`.

---

## Sign and Clamp

Use to encode direction or bound a value; both broadcast over arrays, Series, and scalars.

- Direction as −1/0/+1: `np.sign(...)` — not a ternary `lambda` → `sign-direction-encoding`.
- Clamp with `np.clip(value, low, high)`; Python `min(max(...))` fails on arrays. Use `np.maximum`/`np.minimum`
  when the bounds are computed independently → `score-clamp-0-100`.

---

## Assembly

Use to build arrays or frames from separately computed pieces.

- Join arrays along an existing axis with `np.concatenate([...])`; build class labels with `np.full(n, label)`.
  Use `np.vstack` only to stack 1D rows into 2D.
- Heterogeneous 1D arrays → `pd.DataFrame({name: array, ...})`. `np.column_stack` coerces every column to
  one dtype (all strings if any input is a string array).
- Plot x-axis offsets: `np.arange(off, off + len(y))` — not `list(range(...))` → `arange-plot-x-axis`.

```python
X = np.concatenate([pos, noise, neg])
y = np.concatenate([
    np.full(len(pos), 1),
    np.full(len(noise), 0),
    np.full(len(neg), -1),
])

result = pd.DataFrame({"id": ids, "label": labels, "score": scores})
```

---

## Scalar Extraction

Use when a numpy reduction feeds a list, JSON, or a Python-typed comparison.

From mabrosim/aet-content-pack, MIT.

More from mabrosim/aet-content-pack