A multiflow global optimization approach for plasmid binning in short read assembly graph: PlasBin-HMF
Install
In a virtual environment:
pip install plasbin-hmf
Or if you want to install it via uv:
# As a dependency of your project:
uv add plasbin-hmf
# As an uv tool:
uv tool install plasbin-hmf
Usage
In your virtual environment:
plasbin-hmf --help
You can also use uv tools:
uvx plasbin-hmf --help
To get the plasmid bins:
uvx plasbin-hmf run --help
Options
Algorithm parameters can be given via CLI or you can use --config config.yaml:
bins:
circular:
max_with_seeds: <int> | auto # default: auto
max_optional_seeds: <int> # default: 2
partially_circular:
max_with_seeds: <int> | auto # default: auto
max_optional_seeds: <int> # default: 0
constraints:
min_bin_size: <int> # default: 1000
min_coverage: <(0, inf)> # default: 0.3
plasmidness_coefficient: <[0, 1]> # default: 0
max_coverage_ratio: <(1, inf]> | null # default: 20
partially_circular_s_t_constraints: <bool> # default: false
input:
input_format: PlasBin-HMF | PlasBin-flow # default: PlasBin-HMF
gfa_origin: Unicycler | SKESA # default: Unicycler
default_plasmidness: <[-1, 1]> # default: 0
contig_length_threshold: <int> # default: 100
output:
keep_optimization_traces: <bool> # default: false
plasbin_flow_output: <bool> # default: false
Gurobi can also be configured, via CLI of via --gurobi-config gurobi_cfg.yaml:
mip_gap: <float> # default: 0.0
time_limit: <float> | null # default: null
threads: <int> | all # default: all
Input
PlasBin-HMF takes as input:
- An assembly graph (GFA v1 file produced by Unicycler or SKESA, see
--gfa-originoption), can be compressed. - A file listing the seed contigs
- A file associating to each contig a plasmidness score
Seed contigs (e.g. seeds.tsv, tabulation-separated values):
| Column ID | Type | Description |
|---|---|---|
contig_id |
str |
Contig ID (corresponds to the ID of the segment line in the GFA) |
Plasmidness scores (e.g. plasmidness.tsv, tabulation-separated values):
| Column ID | Type | Description |
|---|---|---|
contig_id |
str |
Contig ID (corresponds to the ID of the segment line in the GFA) |
plasmidness_score |
float |
Plasmidness score |
Output
Suppose --output-dir/-o output_dir is provided.
PlasBin-HMF keeps your configuration for future reproducibility:
📂 output_dir
├── ℹ️ configs.yaml
└── ℹ️ gurobi_cfg.yaml
Solution
📂 output_dir
├── ℹ️ solution_metadata.yaml
├── 📄 bins.tsv
└── 📂 subgraphs
├── 📄 link_arcs.tsv
├── 📄 source_arcs.tsv
└── 📄 sink_arcs.tsv
Predicted bins
The predicted bins are stored in the 📄 bins.tsv file (tabulation separated columns):
| Column ID | Type | Description |
|---|---|---|
bin_id |
str |
Bin ID |
contig_id |
str |
Contig ID in the bin (corresponds to the ID of the segment line in the GFA) |
contig_norm_cov |
int |
Normalized coverage of the contig |
Solution networks
PlasBin-HMF uses the assembly graph topology to produce the bins.
Folder 📂 subgraphs contains the arcs defining the subnetworks associated with the bins.
For each subnetwork (bin), the set of arcs is the union of:
- a set of link-arcs (arcs between two oriented contigs);
- a set of source-arcs (arcs from the source to the oriented contigs);
- a set of sink-arcs (arcs from the oriented contigs to the sink).
File 📄 link_arcs.tsv contains the solution link arcs for all the subnetworks.
A link is an arc that corresponds to a link in the assembly graph (between two oriented contigs).
| Column ID | Type | Description |
|---|---|---|
bin_id |
str |
Bin ID |
pred_id |
str |
Predecessor oriented contig ID |
pred_or |
{'+', '-'} |
Predecessor oriented contig orientation |
succ_id |
str |
Successor oriented contig ID |
succ_or |
{'+', '-'} |
Successor oriented contig orientation |
flow |
float |
Flow on the arc (always strictly positive) |
File 📄 source_arcs.tsv contains the solution source arcs for all the subnetworks.
| Column ID | Type | Description |
|---|---|---|
bin_id |
str |
Bin ID |
succ_id |
str |
Successor oriented contig ID |
succ_or |
{'+', '-'} |
Successor oriented contig orientation |
flow |
float |
Flow on the arc (can be 0) |
File 📄 sink_arcs.tsv contains the solution sink arcs for all the subnetworks
| Column ID | Type | Description |
|---|---|---|
bin_id |
str |
Bin ID |
pred_id |
str |
Predecessor oriented contig ID |
pred_or |
{'+', '-'} |
Predecessor oriented contig orientation |
flow |
float |
Flow on the arc (can be 0) |
Solution metadata
File ℹ️ solution_metadata.yaml is a YAML stream.
Each document (separated by --- at the top) describes one predicted bin:
---
bin_id: <str> # e.g. Bin_1
property:
topology: circular|partially_circular
seed_constraint: required|optional
stats:
active_contigs: <int> # Number of active (unoriented) contig
active_contig_vertices: <int> # Number of active oriented contig
active_source_arcs: <int> # Number of active source arcs
active_sink_arcs: <int> # Number of active link arcs
active_link_arcs: <int> # Number of active sink arcs
cumulative_contig_length: <int> # Do not account for the multiplicity of a contig
plasmidness_score: <float> # A good bin has a plasmidness score greater than 0
minimum_positive_arc_flow: <float> # This can be used as a coverage normalization factor
maximum_contig_coverage: <float> # Maximum contig coverage in the bin
origin: # only if --keep-optimization-traces
instance_id: <str> # e.g. instance_1
multiflow_id: <str> # e.g. multiflow_2
flow_id: <str> # e.g. flow_1
If there is no solution
In case PlasBin-HMF was not able to find any bin under the parametrized constraints, the program produces:
📂 output_dir
└── ℹ️ no_solution.yaml
Where no_solution.yaml contains:
status: no_solution
Optimization traces
If you provide --keep-optimization-traces, the optimization traces will be kept in the output directory.
📂 output_dir
└── 📂 optimization_traces
├── ℹ️ traces_metadata.yaml
├── 🗄️ instance_1.tar.xz # or .zip
├── 🗄️ instance_2.tar.xz # or .zip
└── ...
Compressed instance results
Directory 📂 optimization_traces keeps trace for each instance of the steps to find the bins corresponding to that instance.
An instance is defined by:
- an ID (prefixed with
instance_and the same ID given in theinstance_idkey insolution_metadata.yaml); - a network such that removing the source and the sink vertices still gives a connected subgraph;
- a topology (circular or partially circular);
- a seed constraint (required or optional);
One compressed file corresponds to one instance.
Decompressing it gives one directory (for example instance_1.<archive>):
📂 instance_1 # Instance ID prefixed with `instance_`
├── ℹ️ metadata.yaml
├── 📂 multiflow_1 # The 1-multiflow attempt was succesful
│ ├── 📃 gurobi.log
│ ├── 📄 gurobi.sol
│ └── ℹ️ solution_metadata.yaml
└── 📂 multiflow_2 # The 2-multiflow attempt failed
├── 📃 gurobi.log
└── ℹ️ infeasible.yaml
File ℹ️ metadata.yaml describes the instance:
instance_id: <str>
multiflow_size_upper_bound: <int>
required_bin_property:
topology: circular|partially_circular
seed_constraint: required|optional
input_stats:
number_of_contigs: <int>
number_of_links: <int>
number_of_seeds: <int>
null_plasmidness: <bool> # True if every contig has null plasmidness. The multiflow score function depends on this boolean.
parent_instance: <str> | null # Instance ID, if any. Otherwise null
For each instance, there is at least one optimization attempt.
An attempt multiflow_n means an attempt to find the best (n)-multiflow with the instance properties.
In a multiflow attempt (multiflow_1 means a multiflow of size 1), file ℹ️ solution_metadata.yaml contains:
multiflow_id: <str>
multiflow_size: <int>
status: <str> # Gurobi status, see https://docs.gurobi.com/projects/optimizer/en/current/reference/numericcodes/statuscodes.html
multiflow_score: <float>
flows:
flow_ID: # Flow ID e.g. flow_1
active_contigs: <int> # Number of active (unoriented) contig
active_contig_vertices: <int> # Number of active oriented contig
active_source_arcs: <int> # Number of active source arcs
active_sink_arcs: <int> # Number of active link arcs
active_link_arcs: <int> # Number of active sink arcs
total_flow: <float> # Should be 0 in the circular context
plasmidness_score: <float> # A good bin has a plasmidness score greater than 0
cumulative_contig_length: <int> # Do not account for the multiplicity of a contig
min_positive_arc_flow: <float> # Corresponds to the minimum positive arc flow
max_positive_arc_flow: <float> # Corresponds to the maximum positive arc flow
min_positive_contig_inflow: <float> # Corresponds to the minimum positive contig inflow (forward + reverse orientations)
max_positive_contig_inflow: <float> # Corresponds to the maximum positive contig inflow (forward + reverse orientations)
In case PlasBin-HMF was not able to find any bin under the parametrized constraints, the program produces file ℹ️ infeasible.yaml:
multiflow_id: <str>
multiflow_size: <int>
status: <str> # Gurobi status, see https://docs.gurobi.com/projects/optimizer/en/current/reference/numericcodes/statuscodes.html
Traces metadata
File ℹ️ traces_metadata.yaml is a YAML stream of all the instance_id/metadata.yaml, see instance metadata.
Each document (separated by --- at the top) describes one optimization instance.
---
instance_id: <str>
multiflow_size_upper_bound: <int>
required_bin_property:
topology: circular|partially_circular
seed_constraint: required|optional
input_stats:
number_of_contigs: <int>
number_of_links: <int>
number_of_seeds: <int>
parent_instance: <str> | null # Instance ID, if any. Otherwise null
# ---
# ... Another instance
Metadata
Release files for plasbin-hmf 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| plasbin_hmf-0.3.0.tar.gz | 83.5 kB | Without provenance | Details for plasbin_hmf-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| plasbin_hmf-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for plasbin_hmf-0.3.0-py3-none-any.whl |
Total release size: 245.3 kB
Release files / plasbin_hmf-0.3.0.tar.gz
| Download URL | plasbin_hmf-0.3.0.tar.gz |
|---|---|
| Size | 83.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e8e09c4d199faad4847cd9b05f0a0b40fea216c67360cb832458675cda308d01
|
|
BLAKE2b-256 checksum How to use checksums |
030a9d5a079c4e2c7ee4dc4cde143ee77341cd1628c16c0332dfaade8d5c08fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.9.30 {"installer":{"name":"uv","version":"0.9.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / plasbin_hmf-0.3.0-py3-none-any.whl
| Download URL | plasbin_hmf-0.3.0-py3-none-any.whl |
|---|---|
| Size | 161.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9e051dc1327b487f5395399c75881de284f1ab1c6afbd736e42c883b3cf9f59f
|
|
BLAKE2b-256 checksum How to use checksums |
3d72575e52806c43d2ced98fc90188dacb490ccf272aac3f871ca1179708ff38
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.9.30 {"installer":{"name":"uv","version":"0.9.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for plasbin-hmf 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.