BatchLens Bio · 0.3.0 · Study design review

Before the next biological claim.

Experimental units, batch allocation and your explicit comparison. No expression data are fitted or corrected.

SYNTHETIC Confounded allocation; original synthetic cell metadata

6Declared experimental units
6Samples
920Linked cells / spots
Metadata and the declared additive model only. This audit does not establish power, independence, randomization, absence of unmeasured confounding, or causality.

Your requested comparisons

NON_ESTIMABLE NON_ESTIMABLE

selected-comparison

condition: regeneration − control

The requested effect cannot be uniquely separated from the other declared terms.

Findings 7

CRITICAL BL-CONTRAST-001

selected-comparison: the requested contrast is not estimable in this model.

Discuss crossed sampling or a revised scientific question; correction cannot supply missing design information.

Inspect the evidence
[
  {
    "denominator": "control",
    "id": "selected-comparison",
    "numerator": "regeneration",
    "row_space_residual": 0.7071067811865474,
    "status": "NON_ESTIMABLE",
    "tolerance": 1e-10,
    "vector": [
      0.0,
      1.0,
      0.0
    ]
  },
  [
    [
      -0.0,
      1.0,
      -1.0
    ]
  ]
]

JSON pointers in result.json:

/contrasts/0
/matrix_diagnostics/dependencies
WARNING BL-CELL-001

Hepatocyte / control: few units reach the configured cell-count threshold.

Inspect unit-level coverage. Thresholds are review heuristics, not power tests; samples are pooled within each unit and target level.

Inspect the evidence
[
  {
    "cell_type": "Hepatocyte",
    "cells": 220,
    "dominance_threshold": 0.6,
    "eligible_units": 3,
    "largest_unit_share": 0.9090909090909091,
    "min_cells": 20,
    "min_units": 3,
    "observed_units": 3,
    "supported_units": 1,
    "target_level": "control"
  }
]

JSON pointers in result.json:

/cell_support/2
WARNING BL-CELL-001

Hepatocyte / regeneration: few units reach the configured cell-count threshold.

Inspect unit-level coverage. Thresholds are review heuristics, not power tests; samples are pooled within each unit and target level.

Inspect the evidence
[
  {
    "cell_type": "Hepatocyte",
    "cells": 220,
    "dominance_threshold": 0.6,
    "eligible_units": 3,
    "largest_unit_share": 0.9090909090909091,
    "min_cells": 20,
    "min_units": 3,
    "observed_units": 3,
    "supported_units": 1,
    "target_level": "regeneration"
  }
]

JSON pointers in result.json:

/cell_support/3
WARNING BL-CELL-002

Hepatocyte / control: one unit dominates the cell count.

Check sampling and unit contributions; do not automatically remove that unit.

Inspect the evidence
[
  {
    "cell_type": "Hepatocyte",
    "cells": 220,
    "dominance_threshold": 0.6,
    "eligible_units": 3,
    "largest_unit_share": 0.9090909090909091,
    "min_cells": 20,
    "min_units": 3,
    "observed_units": 3,
    "supported_units": 1,
    "target_level": "control"
  }
]

JSON pointers in result.json:

/cell_support/2
WARNING BL-CELL-002

Hepatocyte / regeneration: one unit dominates the cell count.

Check sampling and unit contributions; do not automatically remove that unit.

Inspect the evidence
[
  {
    "cell_type": "Hepatocyte",
    "cells": 220,
    "dominance_threshold": 0.6,
    "eligible_units": 3,
    "largest_unit_share": 0.9090909090909091,
    "min_cells": 20,
    "min_units": 3,
    "observed_units": 3,
    "supported_units": 1,
    "target_level": "regeneration"
  }
]

JSON pointers in result.json:

/cell_support/3
WARNING BL-COVER-001

Some target-by-batch combinations have no samples.

Review coverage. An empty combination alone is not non-estimability.

Inspect the evidence
[
  [
    {
      "batch_level": "B1",
      "batch_variable": "batch",
      "samples": 3,
      "target_level": "control",
      "units": 3
    },
    {
      "batch_level": "B2",
      "batch_variable": "batch",
      "samples": 0,
      "target_level": "control",
      "units": 0
    },
    {
      "batch_level": "B1",
      "batch_variable": "batch",
      "samples": 0,
      "target_level": "regeneration",
      "units": 0
    },
    {
      "batch_level": "B2",
      "batch_variable": "batch",
      "samples": 3,
      "target_level": "regeneration",
      "units": 3
    }
  ]
]

JSON pointers in result.json:

/coverage
WARNING BL-DESIGN-001

The declared design matrix is rank deficient.

Inspect the dependencies and each contrast separately; do not drop batch blindly.

Inspect the evidence
[
  [
    [
      -0.0,
      1.0,
      -1.0
    ]
  ]
]

JSON pointers in result.json:

/matrix_diagnostics/dependencies

Target × batch coverage

Counts use samples and distinct declared units. Empty combinations alone do not prove non-estimability.

Batch variableBatchTargetSamplesUnits
batchB1control33
batchB2control00
batchB1regeneration00
batchB2regeneration33

Cell-type donor support

Cell counts are pooled within each unit, target and cell type. Thresholds prompt review; no power test or subgroup model is fitted.

Minimum units: 3Cells per unit: 20Dominance threshold: 60%

Cell typeTargetCellsEligible unitsObserved unitsUnits at thresholdLargest share
Endothelialcontrol12033333.3%
Endothelialregeneration12033333.3%
Hepatocytecontrol22033190.9%
Hepatocyteregeneration22033190.9%
Kupffercontrol12033333.3%
Kupfferregeneration12033333.3%

Experimental-unit structure

Repeated samples and extra cells do not create additional experimental units.

Unit aliasSamplesTarget levels
unit-00011control
unit-00021control
unit-00031control
unit-00041regeneration
unit-00051regeneration
unit-00061regeneration

Cell type / region summary

AnnotationLabelTargetCells/spotsSamplesUnits
cell_typeEndothelialcontrol12033
cell_typeEndothelialregeneration12033
cell_typeHepatocytecontrol22033
cell_typeHepatocyteregeneration22033
cell_typeKupffercontrol12033
cell_typeKupfferregeneration12033

Declared model & numerical evidence

Intercept + condition + batch

Rank 2 / 3 columns · 6 design rows · residual row degrees of freedom 4

Encoding and column dependencies
IndexVariableLevel / kind
0Interceptintercept
1conditionregeneration
2batchB2

Each dependency follows the column order above and satisfies Xv ≈ 0. Contrasts are checked against the row space.

[[-0.0, 1.0, -1.0]]

Rank tolerance: 4.2638060825584685e-15

selected-comparison: residual 0.7071067811865474 / tolerance 1e-10

Quick check uses the same BatchLens contrast engine. Only declared columns were adapted.

Input mapping and source fingerprint
{
  "cell_id_uniqueness": "checked",
  "column_mapping": {
    "batch": "batch",
    "cell_id": "cell_id",
    "cell_type": "cell_type",
    "sample": "sample",
    "target": "condition",
    "timepoint": null,
    "unit": "donor"
  },
  "mode": "quick",
  "rows": 920,
  "source_sha256": "24dd5c13d4c8688c847206e9fda8e0840def886a359452a6e33033a51ae9ba6a"
}
Complete declared configuration
{
  "adjust_for": [
    "batch"
  ],
  "cell_coverage": {
    "dominance": 0.6,
    "min_cells": 20,
    "min_units": 3
  },
  "contrasts": [
    {
      "denominator": "control",
      "id": "selected-comparison",
      "numerator": "regeneration"
    }
  ],
  "design_mode": "independent",
  "sample_id": "sample_id",
  "schema_version": "1.0",
  "target": "condition",
  "unit_id": "unit_id",
  "variables": {
    "batch": {
      "levels": [
        "B1",
        "B2"
      ],
      "reference": "B1",
      "role": "batch",
      "type": "categorical"
    },
    "condition": {
      "levels": [
        "control",
        "regeneration"
      ],
      "reference": "control",
      "role": "target",
      "type": "categorical"
    }
  }
}