SWC_BATCH_CHECK 1.1.0

Batch validation and repair of directories containing SWC neuron morphology files.

What it checks

• Parses the seven required SWC fields and reports malformed rows.
• Accepts integers, decimals, leading-dot decimals, and scientific notation.
• Renumbers nonsequential node IDs and correctly remaps parent IDs.
• Detects duplicate IDs, missing parents, self-parenting, and parent cycles.
• Ensures the first valid node is a root soma.
• Optionally repairs soma, axon, basal-dendrite, and apical-dendrite connections.
• Optionally replaces zero or negative radii with a positive ancestor radius.
• Reports morphology statistics based on actual parent-child relationships.
• Can package the corrected files into a ZIP archive.

The original files are never modified. Corrected files are written to a separate output directory.

Requirements

• Perl 5.14 or newer
• IO::Compress::Zip

The remaining runtime modules are included with standard Perl distributions.

Installation

From the project directory:

cpanm --installdeps .
perl Makefile.PL
make
make test
make install

For a local installation without administrator permissions:

cpanm --local-lib "$HOME/perl5" --installdeps .
perl Makefile.PL INSTALL_BASE="$HOME/perl5"
make
make test
make install

Command-line usage

After installation:

swc_batch_check --d ./my_swc_directory

Directly from a cloned repository:

perl bin/swc_batch_check --d ./sample_input

Options

--d DIRECTORY       Input directory containing SWC files (required)
--soma              Repair invalid soma parent connections
--axon              Repair invalid axon parent connections
--apic              Repair invalid apical-dendrite parent connections
--basal             Repair invalid basal-dendrite parent connections
--rad               Replace zero/negative radii using a valid ancestor radius
--zip               Create a ZIP archive containing this run's output files
--out-dir PATH      Output directory (default: ./NEW_SWC)
--error-log PATH    Validation log (default: __error_log__.txt)
--quiet             Suppress per-file reports
--help, -h          Show command help

Example with all repair options:

perl bin/swc_batch_check \
  --d ./sample_input \
  --soma --axon --apic --basal --rad --zip \
  --out-dir ./NEW_SWC \
  --error-log ./swc_validation.log

Perl API

use SWC_BATCH_CHECK;

my $app = SWC_BATCH_CHECK->new(
    d         => './sample_input',
    apic      => 1,
    basal     => 1,
    rad       => 1,
    out_dir   => './NEW_SWC',
    error_log => './swc_validation.log',
);

my $summaries = $app->run_SWC_BATCH_CHECK();

for my $summary (@{$summaries}) {
    print "$summary->{file}: $summary->{compartments} compartments\n";
}

For compatibility with the original interface, command-line applications can still use:

my $app = SWC_BATCH_CHECK->new_with_options();
$app->run_SWC_BATCH_CHECK();

Repair behavior

ID sequence

IDs are rewritten as 1..N in file order. Every valid parent reference is remapped through the old-ID-to-new-ID table. The earlier version inserted an extra array field when an ID was out of sequence, which shifted all columns and corrupted the row.

Connectivity

When a repair flag is enabled, a node with an incompatible parent is reattached to the nearest compatible ancestor. The parent node's biological type is not changed.

Allowed parent types are:

• Soma (1): soma
• Axon (2): soma or axon
• Basal dendrite (3): soma or basal dendrite
• Apical dendrite (4): soma or apical dendrite

Radius

With --rad, a zero or negative radius is replaced by the nearest positive ancestor radius. When no ancestor has a positive radius, the first positive radius in the file is used. An unrecoverable file with no positive radius receives an error entry.

Output and log

Corrected files are named new_<original-name>.swc. The log records corrections, warnings, and errors with the original source line number. The log is removed automatically when a run has no issues.

Reported statistics include compartments, edges, roots, branch points, terminal points, point-type counts, diameter range, total cable length, and longest parent-child segment.

Testing

make test

The functional tests cover:

• nonsequential ID and parent remapping
• malformed rows
• comments with leading whitespace
• scientific notation and leading-dot numbers
• missing parents
• parent cycles
• connectivity repair
• zero and negative radius repair
• parent-child distance calculations

References

1. SWC Format Specification: http://www.neuronland.org/NLMorphologyConverter/MorphologyFormats/SWC/Spec.html
2. SWC+ Format Specification: https://neuroinformatics.nl/swcPlus/
3. Stockley EW, Cole HM, Brown AD, Wheal HV. A system for quantitative morphological measurement and electronic modelling of neurons: three-dimensional reconstruction. Journal of Neuroscience Methods. 1993;47:39-51.

License

GNU General Public License, version 2.