copy_number_segment
Segment one chromosome of an Affymetrix copy-number container by up to four independent methods and report where they agree.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "copy_number_segment"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | which copy-number file in this project, by name. Unset, it is the project's only one — and it refuses rather than guessing when there is more than one. | |
| graph | No | which graph column to segment. Unset is the first log2-ratio column, which is what the panel segments. A column that is not a log2 ratio is refused rather than segmented: a copy-number STATE column is already someone's answer. | |
| _files | No | The project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name. | |
| pelt_q | No | changepoint's `Q`: BinSeg's most change points, SegNeigh's most segments. Read only by those two. Same default as the panel. Only applies when pelt_method is BinSeg or SegNeigh. | |
| cbs_eta | No | DNAcopy's `eta`: the error budget for stopping each permutation test early once its outcome is settled. Not the significance level; any value but 0.05 recomputes the stopping boundary. Same default as the panel. | |
| methods | No | which methods to run, comma-separated: `hmm`, `cbs`, `pcf`, `pelt`. Unset runs all four, because the point of this node is where they agree. The panel has each of them off until asked, so running one here is not a different default — it is the same control, pressed. | |
| _subject | No | The record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several. | |
| cbs_seed | No | CBS accepts a boundary by permutation test, so the run is seeded and about 1 borderline dataset in 40 segments differently under a different seed. Same default as the panel. | |
| cbs_trim | No | DNAcopy's `trim`: the fraction cut from each tail before sdundo measures the noise SD. Read only when `cbs_undo_splits` is sdundo. Same default as the panel. Only applies when cbs_undo_splits is sdundo. | |
| data_set | No | which data set to segment, by name. Unset is the file's FIRST, which is what the panel opens on. | |
| pcf_kmin | No | PCF's shortest allowed segment, in markers — the finest change the fit may claim. Same default as the panel. | |
| hmm_model | No | which copy-number state model the HMM calls against. `file` is the model the container's own header states, and is used when unset if the file states one; otherwise the first preset. `apt-cn-state` is APT's generic method with its GC-corrected means, `apt-cn-cyto2` the six-state method written for CytoScan arrays. The panel lists the same models in the same order. Values: file (This file’s own parameters), apt-cn-state (APT cn-state (GC-corrected)), apt-cn-cyto2 (APT cn-cyto2 (CytoScan)). | |
| pcf_gamma | No | PCF's penalty per jump — how much evidence a level change must carry. Scaled by the squared MAD noise estimate unless `pcf_normalize` is off, which is what makes 40 mean the same thing on a quiet array and a noisy one. Same default as the panel. | |
| chromosome | No | which chromosome to segment, as the file numbers them (1-22, then 23=X, 24=Y, 25=MT — the file's own convention). Unset is the first the index carries, which is what the panel selects. | |
| pcf_method | No | which piecewise-constant fit: `auto` (copynumber's own rule — the exact dynamic program under 400 markers, its selectFastPcf approximation above), `exact`, or `fast`. Both are graded against R, so this is a real choice. `exact` is refused above 25,000 markers rather than silently downgraded: it is quadratic there (21 s at 100,000), where the approximation fits a whole 142,000-marker chromosome in about 0.3 s. Same default as the panel. Values: auto (Automatic), exact (Exact), fast (Approximate). | auto |
| cbs_undo_sd | No | DNAcopy's `undo.SD`: the merge threshold in trimmed noise SDs. Read only when `cbs_undo_splits` is sdundo. Same default as the panel. Only applies when cbs_undo_splits is sdundo. | |
| pelt_method | No | which of changepoint's three multiple-change searches the `pelt` method runs over the same costs and penalties: `PELT` prunes to the exact optimum in linear time (changepoint's default); `BinSeg` splits greedily, at most `pelt_q` times, keeping each split while it pays for its penalty; `AMOC` scans for at most one change and keeps it only if it pays for the penalty, reporting Chen & Gupta's confidence; `SegNeigh` finds the exact optimum for every segment count up to `pelt_q` and lets the penalty pick one, at quadratic cost, so it declines past a Q·n² work budget (5,000 markers at Q = 5) and refuses MBIC and a shortest segment above 1, as changepoint does. Same default as the panel. Values: PELT (Pruned exact linear time), BinSeg (Binary segmentation), SegNeigh (Segment neighborhood), AMOC (At most one change). | PELT |
| pelt_penalty | No | PELT's penalty, and the reason its knob is a different KIND of knob from PCF's gamma: it is an information criterion, so the number of segments follows from a model-selection rule rather than from a constant calibrated against this array's noise. MBIC is changepoint's own default and adds log(segment length) to each segment's cost as well as its (parameters + 2)·log(n) penalty. `Manual` is the only one that reads `pelt_penalty_value`; `CROPS` is a RANGE (Haynes, Eckley & Fearnhead 2017), read from `pelt_crops_*`, and needs `pelt_method` PELT. Same default as the panel. Values: MBIC (MBIC), BIC (BIC), SIC0 (BIC without the location term), AIC (AIC), Hannan-Quinn (Hannan-Quinn), Manual (Manual), None (None), CROPS (A range (CROPS)). | MBIC |
| pcf_normalize | No | scale the PCF penalty by the squared MAD noise estimate (the vendor’s `normalize`). Off makes gamma an absolute penalty in squared log2 units, which is a different parameter wearing the same name. Same default as the panel. | |
| pelt_crops_to | No | the largest penalty of the CROPS range, in multiples of log(n). Read only when `pelt_penalty` is CROPS. Same default as the panel. Only applies when pelt_penalty is CROPS. | |
| cbs_undo_prune | No | DNAcopy's `undo.prune`: the fractional increase in residual cost pruning may accept. Read only when `cbs_undo_splits` is prune. Same default as the panel. Only applies when cbs_undo_splits is prune. | |
| pelt_minseglen | No | PELT's shortest allowed segment, in markers (changepoint's `minseglen`) — the finest change the fit may claim. Same default as the panel. | |
| cbs_undo_splits | No | DNAcopy's `undo.splits`, the post-hoc merge over what CBS found: `none` keeps every significant split, `sdundo` merges adjacent segments whose medians are within `cbs_undo_sd` trimmed SDs (is this boundary bigger than the noise?), `prune` keeps the fewest change points whose cost stays within `cbs_undo_prune` (how few boundaries explain this almost as well?). Same default as the panel. Values: none (Keep every split), sdundo (Merge within SDs), prune (Prune by cost). | none |
| pelt_crops_from | No | the smallest penalty of the CROPS range, in multiples of log(n). changepoint's own range is 1 to 10. Read only when `pelt_penalty` is CROPS. Same default as the panel. Only applies when pelt_penalty is CROPS. | |
| pelt_standardize | No | divide by the robust MAD before fitting. ON by default, and this is the one PELT default that is ours rather than the vendor's, because the vendor documents the assumption and does not enforce it: a change-in-mean cost is a raw residual sum of squares while the penalty is on a log(n) scale, so the two are only commensurate at unit variance. Off, a noisy array buys boundaries it should not and a quiet one buys none, and both look like plausible answers. Same default as the panel. | |
| pelt_crops_draw_at | No | which CROPS segmentation becomes `segments.pelt`: the one optimal at this penalty, in multiples of log(n) (2 is BIC for a change in mean). Every segmentation in the range is in the derivation either way. Same default as the panel. Only applies when pelt_penalty is CROPS. | |
| pelt_penalty_value | No | the cost a boundary must save to be worth buying, in the cost function's own units. Read ONLY when `pelt_penalty` is Manual; the named criteria derive their own from the marker count. Same default as the panel. Only applies when pelt_penalty is Manual. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | what each method answered on this chromosome, generated from the run — never a fixed sentence over a variable outcome | |
| segments | Yes | per method, its segments with their marker range, genomic span and level — and for the HMM, the state it called | |
| agreement | Yes | where the methods that ran put their boundaries, and which boundaries more than one of them found. This is the reading no single method can produce | |
| derivation | Yes | per method, what it actually used: the model and its means for the HMM, the seed for CBS, kmin and the raw and scaled gamma for PCF — plus each method's published provenance, and the reason where one declined to run |