Checking Yarn Substitutions by Yardage-per-Gram Density

Yarn Sub compares the yarn a pattern calls for against a candidate substitute using yardage-per-gram density, gives a match verdict, and computes how many skeins of the substitute to buy when the put-ups differ. It shares the saved yarn stash with the Skein & Gauge calculator — read-only — so ball bands entered in one tool prefill in the other [1].

The problem

Yarn weight categories are too coarse to answer the substitution question. Two yarns both labeled "worsted" can differ enough in actual thickness to change gauge, drape, and total yardage — and the label on the band ("4-medium") hides that. The number that doesn't lie is density: how many yards a gram of the yarn provides. Two yarns with matching yardage-per-gram knit up at close to the same thickness regardless of what the band calls them. The second half of the problem is put-ups: the pattern wants six 100 g balls of one yarn, the substitute comes in 50 g skeins of different length, and the conversion gets fumbled at the register.

How it works

Enter ball-band grams and length for the pattern yarn and the candidate — or pick either from the saved stash dropdowns, which read the Skein & Gauge stash. The tool reports each yarn's density, plots both on a scale bar with the pattern yarn's ±10% band shaded, and renders a verdict. The buy panel takes the pattern's total requirement (directly, or as balls × ball length) plus a safety margin, and returns the skein count of the substitute to buy with the leftover stated.

The math

density = ball_length / ball_grams        (yd/g or m/g)

difference = |candidate − pattern| / pattern
  ≤ 10%   safe substitution
  ≤ 20%   close — swatch first
  > 20%   different fabric

skeins = ceil(pattern_total × (1 + margin) / substitute_skein_length)

The verdict thresholds are epsilon-tolerant so a candidate at exactly 10.0% or 20.0% lands in the friendlier bucket instead of falling out of it by floating-point noise. The unit toggle (yd/m) converts entered lengths in place, and the two tools' stash units reconcile automatically when a saved yarn is loaded.

Editing the config

There is no facility table. The two storage keys at the top of the <script> block are the integration points: SKEIN_KEY (skeinmath.v1, the shared stash — read via readStash(), never written) and LS_KEY (yarnsub.v1, this tool's own unit/mode preferences). The verdict thresholds live in verdictOf().

Limitations

• Density matches thickness, not fiber behavior. A cotton and a wool at identical yd/g will still drape differently, halo differently, and define stitches differently. The verdict says the gauge should transfer; it says nothing about whether the fabric will feel right for the design.
• The buy math trusts the ball band. Bands round their yardage, and a 3% band error compounds across a sweater quantity — the safety margin input exists for exactly that.
• The stash link is one-way by design. Yarns are saved and managed in Skein & Gauge; deleting or renaming happens there.