pc2bs (point cloud → ball and stick) is a small command-line tool that converts a point-cloud Spacewalk .sw file into a ball-and-stick .sw file. The conversion is one-way only: it does not turn ball-and-stick files back into point clouds.
The tool reads and writes HDF5 using h5py. Output files are written as plain, non-indexed HDF5 so they load reliably in the Spacewalk web app.
You need Python 3.10 or newer and a copy of this repository on your machine (git clone or download a ZIP).
If you already use a Conda env, a venv, or a system/user pip setup, activate it and install from the repository root:
cd /path/to/pc2bs
python3 -m pip install -e .The -e (editable) flag means git pull picks up source changes immediately — you do not need to reinstall after every update. The only time you need to re-run the install command is when the project's required libraries change (for example, a newer minimum version of h5py or numpy). When that happens, run the same command again:
python3 -m pip install -e .A note on shared environments. If your active environment already holds other tools (for example streamlit, numba, or a Jupyter stack), installing pc2bs into it may pull in newer versions of numpy or other shared libraries and trigger pip warnings about dependency conflicts with those other tools. pc2bs itself will still work, but the other tools may break. If you hit this, use Option B below to install pc2bs into its own dedicated environment. Avoid pip install --force-reinstall in a shared environment — it aggressively upgrades transitive libraries and is the most common cause of these conflicts.
If Python environments are new to you, install Miniconda, then create and activate an environment for this tool:
conda create -n pc2bs python=3.11
conda activate pc2bs
cd /path/to/pc2bs
python3 -m pip install -e .Run conda activate pc2bs whenever you want to use the tool.
pc2bs --versionpc2bs INPUT.sw OUTPUT.sw- INPUT.sw must be a point-cloud
.sw(Spacewalkmulti_pointlayout: spatial traces with four values per sample—region index and x, y, z—or equivalent layout recognized by the reader). - OUTPUT.sw is created (or overwritten) as a ball-and-stick
.sw(single_point: one x, y, z per genomic region per trace).
If you pass a file that is already ball-and-stick, the tool exits with an error and does not overwrite your output with a misleading conversion.
pc2bs -q INPUT.sw OUTPUT.swYou may use - for the input and/or output. The whole HDF5 file is buffered to a temporary file internally (HDF5 needs random access), which is the usual pattern for binary CLI tools.
pc2bs - OUTPUT.sw < INPUT.sw
pc2bs INPUT.sw - > OUTPUT.swPass --open to hand the converted file off to the Spacewalk web app in your default browser:
pc2bs --open INPUT.sw OUTPUT.swpc2bs writes OUTPUT.sw, starts a short-lived local web server, and opens a launcher page that uses Spacewalk's postMessage protocol (spacewalk-ready / spacewalk-load) to transfer the file in-memory — no upload and no drag-and-drop. If your browser blocks the pop-up, the launcher page shows a one-click button to continue.
Override the Spacewalk URL (for a self-hosted build, for example) with --spacewalk-url:
pc2bs --open --spacewalk-url http://localhost:5173/ INPUT.sw OUTPUT.sw--open is incompatible with OUTPUT = - (the browser needs a real file to hand off).
With your environment activated, pull the latest source and refresh metadata:
cd /path/to/pc2bs
git pull
python3 -m pip install -e .Plain pip install -e . leaves already-satisfied libraries alone, so it is safe to run in a shared environment. Avoid --force-reinstall unless you are in a dedicated environment — it can upgrade shared libraries (e.g. numpy) and break other tools installed alongside pc2bs.
With your environment activated:
python3 -m pip uninstall pc2bsActivate the environment you installed into (conda activate pc2bs, or source ~/.venvs/pc2bs/bin/activate), or call the executable by full path (for example ~/.venvs/pc2bs/bin/pc2bs).
With your environment activated, reinstall so dependencies are applied:
cd /path/to/pc2bs
python3 -m pip install -e .If that does not resolve the problem and you are using a dedicated pc2bs environment (Option B, or a venv used only for pc2bs), you can do a clean refresh with python3 -m pip install --force-reinstall -e .. Do not use --force-reinstall in a shared environment — it can upgrade numpy and other libraries in ways that break other tools installed alongside pc2bs.
If the install log ends with lines like ERROR: pip's dependency resolver … this behaviour is the source of the following dependency conflicts naming packages such as streamlit, numba, protobuf, or numpy, pc2bs itself is installed — but the environment you installed into has other tools whose pinned versions disagree with what pip just pulled in. Run pc2bs --version to confirm pc2bs works. The cleanest fix is to reinstall pc2bs into a dedicated environment (Option B), so its dependencies cannot clobber the other tools.
- Confirm the input was really a point-cloud
.sw(not already ball-and-stick). - Try opening the output in an HDF5 viewer (for example myHDF5) to confirm the file is valid HDF5.
- If the problem persists, compare against a known-good ball-and-stick
.swfrom the same project or documentation.
From the repository root:
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytestSee docs/development-notes.md for versioning and release notes.
Spacewalk documents the .sw layout here:
- https://aidenlab.github.io/spacewalk/file-format/specification
- https://aidenlab.github.io/spacewalk/file-format/data-structure
This tool intentionally does not read or write optional datasets such as live_contact_map_vertices.