1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
//! JSON shapes of flow-cytometry analysis: `openreadout analyze gate` / `openreadout_gate`
//! `gate` (FlowJo workspace or Gating-ML populations with event counts) and the processing record
//! that `table --compensate/--transform/--gatingml/--workspace` attaches to a table slice. The
//! computation lives in the FCS reader crate; these types are shared by the CLI and MCP.
use std::collections::BTreeMap;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
/// Output of `analyze gate`.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct GateOutput {
/// The FCS file gated; absent when only the gating file was described.
#[serde(skip_serializing_if = "Option::is_none")]
pub path: Option<String>,
/// The gating file (FlowJo workspace or Gating-ML document).
pub gating_file: String,
/// `flowjo-wsp` or `gating-ml`.
pub gating_format: String,
/// Workspace-level facts (FlowJo only).
#[serde(skip_serializing_if = "Option::is_none")]
pub workspace: Option<WorkspaceSummary>,
/// The workspace sample whose gates were used (FlowJo only).
#[serde(skip_serializing_if = "Option::is_none")]
pub sample: Option<SampleSummary>,
/// FCS data set (table) gated.
#[serde(skip_serializing_if = "Option::is_none")]
pub table: Option<u32>,
/// Events in the data set.
#[serde(skip_serializing_if = "Option::is_none")]
pub event_count: Option<u64>,
/// Compensation matrices the gating file defines (and whether any gate used them).
pub compensation: Vec<CompensationSummary>,
/// Transforms by id (FlowJo: by parameter name).
pub transforms: Vec<TransformSummary>,
/// One row per population, parents before children.
pub populations: Vec<PopulationRow>,
/// The same populations as a tree (quadrant gates appear as grouping nodes without a count).
pub tree: Vec<PopulationNode>,
/// Caveats: skipped populations, disagreements with counts stored in the workspace, scaling.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub notes: Vec<String>,
}
/// Facts about a FlowJo workspace.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct WorkspaceSummary {
/// Workspace format version (`20.0`).
#[serde(skip_serializing_if = "Option::is_none")]
pub version: Option<String>,
/// FlowJo release that saved it.
#[serde(skip_serializing_if = "Option::is_none")]
pub flowjo_version: Option<String>,
/// Modification date as written.
#[serde(skip_serializing_if = "Option::is_none")]
pub modified: Option<String>,
/// Groups and their member sample names.
pub groups: Vec<GroupSummary>,
/// Every sample in the workspace.
pub samples: Vec<SampleSummary>,
}
/// A workspace group.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct GroupSummary {
/// Group name.
pub name: String,
/// Sample names in the group.
pub samples: Vec<String>,
}
/// A workspace sample.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct SampleSummary {
/// FlowJo sample id.
pub id: String,
/// Sample name.
pub name: String,
/// Where FlowJo found the FCS file.
#[serde(skip_serializing_if = "Option::is_none")]
pub uri: Option<String>,
/// Event count FlowJo stored.
#[serde(skip_serializing_if = "Option::is_none")]
pub event_count: Option<u64>,
/// Groups the sample belongs to.
pub groups: Vec<String>,
/// Populations in the sample's gate tree.
pub population_count: usize,
/// Name of the sample's compensation matrix.
#[serde(skip_serializing_if = "Option::is_none")]
pub compensation: Option<String>,
/// Keywords FlowJo stored with the sample (FCS TEXT plus its own).
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub keywords: BTreeMap<String, String>,
}
/// A compensation or unmixing matrix.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct CompensationSummary {
/// Matrix name or id; `$SPILLOVER`/`$SPILL`/`SPILL` for the FCS file's own.
pub name: String,
/// Where it comes from: `workspace`, `gating-ml`, `fcs` or `command-line`.
pub source: String,
/// Detectors (columns), `$PnN`.
pub detectors: Vec<String>,
/// Rows: fluorochromes, or the detectors that receive the unmixed values.
pub fluorochromes: Vec<String>,
/// Row-major coefficients (spillover fractions).
pub matrix: Vec<Vec<f64>>,
/// More detectors than rows: unmixed by ordinary least squares.
pub spectral: bool,
/// Whether a gate (or the table) used it.
pub used: bool,
}
/// A parameter transform defined in the gating file.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct TransformSummary {
/// Id (FlowJo: the parameter it applies to).
pub id: String,
/// `linear`, `log`, `arcsinh`, `logicle`, `hyperlog`, `ratio`, `flowjo-log`, `flowjo-biex`,
/// `arcsinh-cofactor`, or the element name of an unsupported FlowJo transform.
pub kind: String,
/// Parameters (`T`, `W`, `M`, `A`, `offset`, `decades`, `neg`, `width`, `pos`, `maxRange`, …).
pub parameters: BTreeMap<String, f64>,
/// False for transforms this reader does not evaluate.
pub supported: bool,
}
/// One gate axis.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct GateDimension {
/// Parameter (`$PnN`, fluorochrome) or ratio id.
pub parameter: String,
/// `uncompensated`, `FCS` or a matrix name.
pub compensation: String,
/// Transform id, if any.
#[serde(skip_serializing_if = "Option::is_none")]
pub transform: Option<String>,
/// Lower bound (inclusive), as stored.
#[serde(skip_serializing_if = "Option::is_none")]
pub min: Option<f64>,
/// Upper bound (exclusive), as stored.
#[serde(skip_serializing_if = "Option::is_none")]
pub max: Option<f64>,
}
/// One population.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct PopulationRow {
/// `/`-separated path from the root (`/Lymphocytes/Single Cells/CD3+`).
pub path: String,
/// Population name.
pub name: String,
/// Parent path; absent for populations of all events.
#[serde(skip_serializing_if = "Option::is_none")]
pub parent: Option<String>,
/// `rectangle`, `polygon`, `ellipsoid`, `quadrant` or `boolean`.
pub gate_type: String,
/// Gate axes.
pub dimensions: Vec<GateDimension>,
/// Gate geometry as stored: `vertices`, `mean`/`covariance`/`distance_square`, `foci`/`edge`,
/// or `op`/`operands` (paths, with `complement`).
pub gate: serde_json::Value,
/// Events outside the gate form the population (FlowJo `eventsInside="0"`).
pub complement: bool,
/// Coordinates are stored before the transform (`untransformed`, FlowJo) or after it.
pub coordinates: String,
/// Events in the population (absent when no FCS file was given).
#[serde(skip_serializing_if = "Option::is_none")]
pub count: Option<u64>,
/// Percent of the parent population's events.
#[serde(skip_serializing_if = "Option::is_none")]
pub percent_of_parent: Option<f64>,
/// Percent of all events.
#[serde(skip_serializing_if = "Option::is_none")]
pub percent_of_total: Option<f64>,
/// The count the gating software stored (FlowJo `count`), for comparison.
#[serde(skip_serializing_if = "Option::is_none")]
pub stored_count: Option<u64>,
/// Median fluorescence (or scatter) of the population's events for each parameter asked for
/// (`analyze gate --median`), keyed by the name as asked: scale values (after `$PnE`/`$PnG`),
/// compensated when the name carries the workspace's `Comp-` prefix. Absent for an empty
/// population.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub medians: BTreeMap<String, f64>,
}
/// A node of the population tree.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct PopulationNode {
/// Population name.
pub name: String,
/// `/`-separated path from the root (`/Lymphocytes/Single Cells/CD3+`).
pub path: String,
/// Gate type, or `quadrant-gate` for the node grouping a quadrant gate's quadrants.
pub gate_type: String,
/// Events (absent without an FCS file, and for quadrant-gate grouping nodes).
#[serde(skip_serializing_if = "Option::is_none")]
pub count: Option<u64>,
/// Child populations.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub children: Vec<PopulationNode>,
}
/// What `table` did to the raw values before returning them.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct TableProcessing {
/// Channel-to-scale conversions applied (`$PnE`, `$PnG`, `$TIMESTEP`); every processed table
/// starts from scale values.
pub scale: Vec<String>,
/// The compensation applied, if any.
#[serde(skip_serializing_if = "Option::is_none")]
pub compensation: Option<CompensationSummary>,
/// Transforms applied, by parameter.
pub transforms: Vec<AppliedTransform>,
/// Membership columns appended (1 = in the population, 0 = not).
pub gates: Vec<GateColumn>,
}
/// A transform applied to one table column.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct AppliedTransform {
/// Column (`$PnN`).
pub parameter: String,
/// Transform kind.
pub kind: String,
/// Its parameters.
pub parameters: BTreeMap<String, f64>,
}
/// A population membership column.
#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
pub struct GateColumn {
/// Column name in the table (`gate:<path>`).
pub column: String,
/// Population path.
pub population: String,
/// Path of the workspace or Gating-ML file that defines the population.
pub gating_file: String,
/// Members among the returned rows.
pub count_in_rows: u64,
}