Python API Reference#

This section documents the public import surface intended for Python callers.

Primary module#

Public library API for swcstudio.

All interfaces (GUI, CLI, and external Python callers) should import these functions or the corresponding tool/feature modules.

class swcstudio.api.RuleBatchOptions(soma: 'bool' = False, axon: 'bool' = False, apic: 'bool' = False, basal: 'bool' = False, rad: 'bool' = False, zip_output: 'bool' = False)[source]#

Bases: object

Parameters:

  • soma (bool)

  • axon (bool)

  • apic (bool)

  • basal (bool)

  • rad (bool)

  • zip_output (bool)

soma: bool = False#
axon: bool = False#
apic: bool = False#
basal: bool = False#
rad: bool = False#
zip_output: bool = False#
swcstudio.api.batch_validate_folder(folder, *, config_overrides=None)#
Parameters:

  • folder (str)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.batch_split_folder(folder, *, config_overrides=None)#
Parameters:

  • folder (str)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.batch_auto_typing(folder, *, options=None, config_overrides=None)#
Parameters:
swcstudio.api.batch_simplify_folder(folder, *, config_overrides=None)#
Parameters:

  • folder (str)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.batch_index_clean_folder(folder, *, config_overrides=None)#
Parameters:

  • folder (str)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.batch_radii_cleaning(folder, *, config_overrides=None)#
Parameters:

  • folder (str)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.radii_clean_path(path, *, write_file_report=True, config_overrides=None)#
Parameters:

  • path (str)

  • write_file_report (bool)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.auto_fix_text(swc_text, *, config_overrides=None)[source]#
Parameters:

  • swc_text (str)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.auto_fix_file(path, *, out_path=None, write_output=False, config_overrides=None)[source]#
Parameters:

  • path (str)

  • out_path (str | None)

  • write_output (bool)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.validation_index_clean_text(swc_text, *, config_overrides=None)#
Parameters:

  • swc_text (str)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.validation_index_clean_file(path, *, out_path=None, write_output=False, write_report=True, config_overrides=None)#
Parameters:

  • path (str)

  • out_path (str | None)

  • write_output (bool)

  • write_report (bool)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.validation_auto_typing_file(file_path, *, options=None, config_overrides=None, output_path=None, write_output=True, write_log=True)#
Parameters:

  • file_path (str)

  • options (RuleBatchOptions | None)

  • config_overrides (dict | None)

  • output_path (str | None)

  • write_output (bool)

  • write_log (bool)

swcstudio.api.validation_run_text(swc_text, *, config_overrides=None, feature_overrides=None)#
Parameters:

  • swc_text (str)

  • config_overrides (dict | None)

  • feature_overrides (dict | None)

swcstudio.api.validation_run_file(path, *, config_overrides=None, feature_overrides=None)#
Parameters:

  • path (str)

  • config_overrides (dict | None)

  • feature_overrides (dict | None)

swcstudio.api.build_mesh_from_text(swc_text, *, config_overrides=None)[source]#
Parameters:

  • swc_text (str)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.build_mesh_from_file(path, *, config_overrides=None)[source]#
Parameters:

  • path (str)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.reassign_subtree_types(swc_text, *, node_id, new_type, config_overrides=None)[source]#
Parameters:

  • swc_text (str)

  • node_id (int)

  • new_type (int)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.reassign_subtree_types_in_file(path, *, node_id, new_type, out_path=None, write_output=False, config_overrides=None)[source]#
Parameters:

  • path (str)

  • node_id (int)

  • new_type (int)

  • out_path (str | None)

  • write_output (bool)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.morphology_set_node_type_text(swc_text, *, node_id, new_type, config_overrides=None)#
Parameters:

  • swc_text (str)

  • node_id (int)

  • new_type (int)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.morphology_set_node_type_file(path, *, node_id, new_type, out_path=None, write_output=False, config_overrides=None)#
Parameters:

  • path (str)

  • node_id (int)

  • new_type (int)

  • out_path (str | None)

  • write_output (bool)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.morphology_set_node_radius_text(swc_text, *, node_id, radius, config_overrides=None)#
Parameters:

  • swc_text (str)

  • node_id (int)

  • radius (float)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.morphology_set_node_radius_file(path, *, node_id, radius, out_path=None, write_output=False, config_overrides=None)#
Parameters:

  • path (str)

  • node_id (int)

  • radius (float)

  • out_path (str | None)

  • write_output (bool)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.validation_auto_label_file(file_path, *, options=None, config_overrides=None, output_path=None, write_output=True, write_log=False)#
Parameters:

  • file_path (str)

  • options (RuleBatchOptions | None)

  • config_overrides (dict | None)

  • output_path (str | None)

  • write_output (bool)

  • write_log (bool)

Return type:

dict[str, Any]

swcstudio.api.morphology_smart_decimation_text(swc_text, *, config_overrides=None)#
Parameters:

  • swc_text (str)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.morphology_smart_decimation_file(path, *, out_path=None, write_output=False, write_report=True, config_overrides=None)#
Parameters:

  • path (str)

  • out_path (str | None)

  • write_output (bool)

  • write_report (bool)

  • config_overrides (dict | None)

Return type:

dict[str, Any]

swcstudio.api.geometry_move_node_absolute(df, node_id, x, y, z)#
Parameters:

  • df (DataFrame)

  • node_id (int)

  • x (float)

  • y (float)

  • z (float)

Return type:

DataFrame

swcstudio.api.geometry_move_subtree_absolute(df, root_id, x, y, z)#
Parameters:

  • df (DataFrame)

  • root_id (int)

  • x (float)

  • y (float)

  • z (float)

Return type:

DataFrame

swcstudio.api.geometry_reconnect_branch(df, source_id, target_id)#
Parameters:

  • df (DataFrame)

  • source_id (int)

  • target_id (int)

Return type:

DataFrame

swcstudio.api.geometry_disconnect_branch(df, start_id, end_id)#
Parameters:

  • df (DataFrame)

  • start_id (int)

  • end_id (int)

Return type:

DataFrame

swcstudio.api.geometry_delete_node(df, node_id, reconnect_children=False)#
Parameters:

  • df (DataFrame)

  • node_id (int)

  • reconnect_children (bool)

swcstudio.api.geometry_delete_subtree(df, root_id, return_id_map=False)#
Parameters:

  • df (DataFrame)

  • root_id (int)

  • return_id_map (bool)

swcstudio.api.geometry_insert_node_between(df, start_id, end_id, x, y, z, radius=None, type_id=None)#
Parameters:

  • df (DataFrame)

  • start_id (int)

  • end_id (int)

  • x (float)

  • y (float)

  • z (float)

  • radius (float | None)

  • type_id (int | None)

swcstudio.api.geometry_reindex_dataframe_with_map(df)#
Parameters:

df (DataFrame)

Return type:

tuple[DataFrame, dict[int, int]]

swcstudio.api.load_plugin_module(module_name, *, force_reload=False)[source]#

Load one plugin module and register its methods.

Expected plugin contract: 1) PLUGIN_MANIFEST dict (or get_plugin_manifest()) 2) register_plugin(registrar) function OR PLUGIN_METHODS attribute

Parameters:

  • module_name (str)

  • force_reload (bool)

Return type:

dict[str, Any]

swcstudio.api.load_plugins(modules)[source]#

Load multiple plugin modules and return per-module results.

Parameters:

modules (Iterable[str])

Return type:

list[dict[str, Any]]

swcstudio.api.autoload_plugins_from_environment(env_var='SWCSTUDIO_PLUGINS')[source]#

Autoload plugin modules from comma-separated environment variable.

Parameters:

env_var (str)

Return type:

list[dict[str, Any]]

swcstudio.api.register_plugin_manifest(manifest)[source]#

Register and validate a plugin manifest.

Parameters:

manifest (PluginManifest | dict[str, Any])

Return type:

PluginManifest

swcstudio.api.register_plugin_method(plugin_id, feature_key, method_name, func)[source]#

Register a feature method owned by a named plugin.

Parameters:

  • plugin_id (str)

  • feature_key (str)

  • method_name (str)

  • func (Callable)

Return type:

None

swcstudio.api.unregister_plugin(plugin_id)[source]#

Remove plugin manifest and all methods owned by this plugin.

Parameters:

plugin_id (str)

Return type:

None

swcstudio.api.list_plugins()[source]#

Return registered plugin manifests.

Return type:

list[dict[str, Any]]

swcstudio.api.get_plugin(plugin_id)[source]#

Return one plugin manifest as dictionary.

Parameters:

plugin_id (str)

Return type:

dict[str, Any] | None

swcstudio.api.register_method(feature_key, method_name, func, *, plugin_id=None)[source]#

Register a user/plugin method that overrides builtins with same name.

Parameters:

  • feature_key (str)

  • method_name (str)

  • func (Callable)

  • plugin_id (str | None)

Return type:

None

swcstudio.api.unregister_method(feature_key, method_name)[source]#
Parameters:

  • feature_key (str)

  • method_name (str)

Return type:

None

swcstudio.api.list_feature_methods(feature_key)[source]#

Return plugin + builtin method names for a feature.

Parameters:

feature_key (str)

Return type:

dict

swcstudio.api.list_all_feature_methods()[source]#

Return all feature method registrations.

Return type:

dict

Validation API layer#

Validation tool API.

tools/validation is the public entry layer. Core implementation lives in swcstudio.core and is consumed by these tool features.

class swcstudio.tools.validation.CheckResult(key: 'str', label: 'str', passed: 'bool', severity: 'Severity', message: 'str', failing_node_ids: 'list[int]' = <factory>, failing_section_ids: 'list[int]' = <factory>, metrics: 'dict[str, Any]'=<factory>, source: 'str' = 'native', params_used: 'dict[str, Any]'=<factory>, thresholds_used: 'dict[str, Any]'=<factory>, status: 'Status' = 'pass')[source]#

Bases: object

Parameters:

  • key (str)

  • label (str)

  • passed (bool)

  • severity (str)

  • message (str)

  • failing_node_ids (list[int])

  • failing_section_ids (list[int])

  • metrics (dict[str, Any])

  • source (str)

  • params_used (dict[str, Any])

  • thresholds_used (dict[str, Any])

  • status (str)

key: str#
label: str#
passed: bool#
severity: str#
message: str#
failing_node_ids: list[int]#
failing_section_ids: list[int]#
metrics: dict[str, Any]#
source: str = 'native'#
params_used: dict[str, Any]#
thresholds_used: dict[str, Any]#
status: str = 'pass'#
static from_pass_fail(*, key, label, passed, severity, message, source, params_used=None, thresholds_used=None, failing_node_ids=None, failing_section_ids=None, metrics=None, error=False)[source]#
Parameters:

  • key (str)

  • label (str)

  • passed (bool)

  • severity (str)

  • message (str)

  • source (str)

  • params_used (dict[str, Any] | None)

  • thresholds_used (dict[str, Any] | None)

  • failing_node_ids (list[int] | None)

  • failing_section_ids (list[int] | None)

  • metrics (dict[str, Any] | None)

  • error (bool)

Return type:

CheckResult

to_dict()[source]#
Return type:

dict[str, Any]

class swcstudio.tools.validation.PreCheckItem(key: 'str', label: 'str', source: 'str', severity: 'Severity', params: 'dict[str, Any]'=<factory>, enabled: 'bool' = True)[source]#

Bases: object

Parameters:

  • key (str)

  • label (str)

  • source (str)

  • severity (str)

  • params (dict[str, Any])

  • enabled (bool)

key: str#
label: str#
source: str#
severity: str#
params: dict[str, Any]#
enabled: bool = True#
to_dict()[source]#
Return type:

dict[str, Any]

class swcstudio.tools.validation.ValidationReport(profile: 'str', precheck: 'list[PreCheckItem]' = <factory>, results: 'list[CheckResult]' = <factory>)[source]#

Bases: object

Parameters:
profile: str#
precheck: list[PreCheckItem]#
results: list[CheckResult]#
summary()[source]#
Return type:

dict[str, int]

to_dict()[source]#
Return type:

dict[str, Any]

swcstudio.tools.validation.register_check(*, key, label, source, runner)[source]#
Parameters:

  • key (str)

  • label (str)

  • source (str)

  • runner (Callable[[Any, dict[str, Any]], Any])

Return type:

None

swcstudio.tools.validation.register_plugin_check(*, key, label, runner)[source]#

Register custom user-defined checks in the shared validation registry.

Parameters:

  • key (str)

  • label (str)

  • runner (Callable[[Any, dict[str, Any]], Any])

Return type:

None

swcstudio.tools.validation.get_check(key)[source]#
Parameters:

key (str)

Return type:

CheckDefinition | None

swcstudio.tools.validation.list_checks()[source]#
Return type:

list[CheckDefinition]

swcstudio.tools.validation.load_validation_config(profile='default', overrides=None)[source]#
Parameters:

  • profile (str)

  • overrides (dict[str, Any] | None)

Return type:

dict[str, Any]

swcstudio.tools.validation.build_precheck_summary(config)[source]#
Parameters:

config (dict[str, Any])

Return type:

list[PreCheckItem]

swcstudio.tools.validation.run_validation_text(swc_text, *, profile='default', config_overrides=None)[source]#
Parameters:

  • swc_text (str)

  • profile (str)

  • config_overrides (dict[str, Any] | None)

Return type:

ValidationReport

Plugin API layer#

Plugin helpers for swcstudio.

Plugin entrypoints can be registered in two ways:

  1. Simple in-process override (direct):

    register_method("batch_processing.auto_typing", "default", func)

  2. Dynamic module load with manifest contract:

    load_plugin_module("my_lab_plugins.summary_plugin")
class swcstudio.plugins.PluginManifest(plugin_id, name, version, api_version='1', description='', author='', capabilities=(), entrypoint='')[source]#

Bases: object

Structured plugin metadata required by the swcstudio plugin loader.

Parameters:

  • plugin_id (str)

  • name (str)

  • version (str)

  • api_version (str)

  • description (str)

  • author (str)

  • capabilities (tuple[str, ...])

  • entrypoint (str)

plugin_id: str#
name: str#
version: str#
api_version: str = '1'#
description: str = ''#
author: str = ''#
capabilities: tuple[str, ...] = ()#
entrypoint: str = ''#
swcstudio.plugins.parse_plugin_manifest(raw)[source]#

Validate and normalize a plugin manifest dictionary.

Parameters:

raw (dict[str, Any])

Return type:

PluginManifest

swcstudio.plugins.plugin_manifest_to_dict(manifest)[source]#

Serialize a PluginManifest into JSON-friendly dictionary.

Parameters:

manifest (PluginManifest)

Return type:

dict[str, Any]

swcstudio.plugins.load_plugin_module(module_name, *, force_reload=False)[source]#

Load one plugin module and register its methods.

Expected plugin contract: 1) PLUGIN_MANIFEST dict (or get_plugin_manifest()) 2) register_plugin(registrar) function OR PLUGIN_METHODS attribute

Parameters:

  • module_name (str)

  • force_reload (bool)

Return type:

dict[str, Any]

swcstudio.plugins.load_plugins(modules)[source]#

Load multiple plugin modules and return per-module results.

Parameters:

modules (Iterable[str])

Return type:

list[dict[str, Any]]

swcstudio.plugins.autoload_plugins_from_environment(env_var='SWCSTUDIO_PLUGINS')[source]#

Autoload plugin modules from comma-separated environment variable.

Parameters:

env_var (str)

Return type:

list[dict[str, Any]]

swcstudio.plugins.register(name, func)[source]#

Register a callable under a flat legacy key.

Parameters:

  • name (str)

  • func (Callable)

Return type:

None

swcstudio.plugins.get(name)[source]#

Retrieve a flat legacy callable or None.

Parameters:

name (str)

Return type:

Callable | None

swcstudio.plugins.unregister(name)[source]#
Parameters:

name (str)

Return type:

None

swcstudio.plugins.clear()[source]#

Clear all registry content (legacy + feature methods).

Return type:

None

swcstudio.plugins.registered_names()[source]#
Return type:

list[str]

swcstudio.plugins.register_builtin_method(feature_key, method_name, func)[source]#

Register an internal builtin method for a feature.

Parameters:

  • feature_key (str)

  • method_name (str)

  • func (Callable)

Return type:

None

swcstudio.plugins.register_plugin_manifest(manifest)[source]#

Register and validate a plugin manifest.

Parameters:

manifest (PluginManifest | dict[str, Any])

Return type:

PluginManifest

swcstudio.plugins.register_plugin_method(plugin_id, feature_key, method_name, func)[source]#

Register a feature method owned by a named plugin.

Parameters:

  • plugin_id (str)

  • feature_key (str)

  • method_name (str)

  • func (Callable)

Return type:

None

swcstudio.plugins.register_method(feature_key, method_name, func, *, plugin_id=None)[source]#

Register a user/plugin method that overrides builtins with same name.

Parameters:

  • feature_key (str)

  • method_name (str)

  • func (Callable)

  • plugin_id (str | None)

Return type:

None

swcstudio.plugins.unregister_method(feature_key, method_name)[source]#
Parameters:

  • feature_key (str)

  • method_name (str)

Return type:

None

swcstudio.plugins.unregister_plugin(plugin_id)[source]#

Remove plugin manifest and all methods owned by this plugin.

Parameters:

plugin_id (str)

Return type:

None

swcstudio.plugins.resolve_method(feature_key, method_name, fallback=None)[source]#

Resolve method by priority: plugin override -> builtin -> fallback.

Parameters:

  • feature_key (str)

  • method_name (str)

  • fallback (Callable | None)

Return type:

Callable

swcstudio.plugins.list_feature_methods(feature_key)[source]#

Return plugin + builtin method names for a feature.

Parameters:

feature_key (str)

Return type:

dict

swcstudio.plugins.list_all_feature_methods()[source]#

Return all feature method registrations.

Return type:

dict

swcstudio.plugins.list_plugins()[source]#

Return registered plugin manifests.

Return type:

list[dict[str, Any]]

swcstudio.plugins.get_plugin(plugin_id)[source]#

Return one plugin manifest as dictionary.

Parameters:

plugin_id (str)

Return type:

dict[str, Any] | None

On this page