API Reference

The entire public API is the Barcodes class.

from barcodeEZ import Barcodes

Most methods return the Barcodes object itself, so calls can be chained:

b = (Barcodes(n_sites=2)
        .add_positions(n_per_site=4)
        .generate_barcodes(bc_len=20, n_barcodes=96)
        .validate())

barcodeEZ.Barcodes

Design a combinatorial barcode library for molecular assembly.

The only object users need. Methods that configure the library return self, so steps can be chained or called sequentially on the same variable -- both styles are equivalent.

Parameters:

Name	Type	Description	Default
n_sites	int	Number of barcoded sites. With the default enzyme panel, must be <= 6.	None
custom_enzymes	list of str	Restriction-enzyme panel defining site boundaries. Must contain exactly n_sites + 1 enzyme names (case-sensitive, Biopython-recognized). Overrides the default panel (EcoRI, BamHI, NheI, XhoI, PluTI, AgeI, MluI).	None

Raises:

Type	Description
TypeError	If n_sites is not an integer.
ValueError	If n_sites > 6 with default enzymes, the custom panel length is not n_sites + 1, or an enzyme name is not recognized by Biopython.

Examples:

Chained:

>>> b = (Barcodes(n_sites=2)
...         .add_positions(n_per_site=4)
...         .generate_barcodes(bc_len=25, n_barcodes=96)
...         .validate())

Sequential (equivalent):

>>> b = Barcodes(n_sites=2)
>>> b.add_positions(n_per_site=4)
>>> b.generate_barcodes(bc_len=25, n_barcodes=96)
>>> b.validate()

Export:

>>> b.view()
>>> b.write_order_form('order.csv')

__init__(n_sites=None, custom_enzymes=None)

Initialize.

add_positions(*, n_per_site)

Add multiple barcode positions per site for combinatorial designs.

Call before generate_barcodes() -- resets any existing barcodes. Positions are labelled A-H; adjacent positions are joined by automatically assigned 4 bp overhangs.

Parameters:

Name	Type	Description	Default
n_per_site	int	Number of positions per site (1-8). Keyword-only.	required

Raises:

Type	Description
TypeError	If n_per_site is not a positive integer.
ValueError	If n_per_site > 8.

print_structure()

Print the site-and-enzyme layout to stdout.

generate_barcodes(bc_len, n_barcodes)

Draw barcodes from the corpus and assemble forward/reverse oligos.

Barcodes are drawn without replacement from the ~30,000-member corpus, so all barcodes in the library are unique. Values of bc_len > 60 are built by concatenating multiple 60-mer corpus sequences. Resets the validated status of the library.

Parameters:

Name	Type	Description	Default
bc_len	int	Length of each barcode in bp.	required
n_barcodes	int	Number of barcodes to generate per position.	required

add_fixed_sequence(seq, site, side)

Attach a constant flanking sequence to one side of a site.

Applies to all positions in the site, immediately adjacent to the barcode. Calling again for the same site and side overwrites the previous sequence. Resets the validated status.

Parameters:

Name	Type	Description	Default
seq	str	Fixed DNA sequence to attach.	required
site	int	Site number to modify (1-indexed).	required
side	str	'left' or 'right'.	required

Raises:

Type	Description
ValueError	If side is not 'left' or 'right', or site does not exist.

validate(ignore_defaults=False, motifs=None)

Screen barcodes for unwanted motifs and replace contaminated ones.

Each assembled barcode is checked for the presence of unwanted sequences. Contaminated barcodes are replaced with clean draws from the corpus. Prints the number of replacements made, or a confirmation that no motifs were found. Marks the library as validated.

Each item in motifs may be a restriction-enzyme name (e.g. 'BsaI'), a raw DNA sequence (e.g. 'TATAAA'), or a path to a FASTA file (.fa, .fasta, .fna, optionally .gz).

The default motif panel (used unless ignore_defaults=True): BsiWI, MreI, FseI, EcoRI, AvrII, BamHI, KpnI, NheI, PciI, XhoI, SpeI, PluTI, NotI, AgeI, AsiSI, MluI, SbfI, MauBI.

Parameters:

Name	Type	Description	Default
ignore_defaults	bool	If True, skip the default restriction-enzyme panel. Default is False.	False
motifs	list	Additional motifs to screen. Items may be enzyme names, raw DNA sequences, or FASTA file paths (mixed freely). Default is None.	None

Raises:

Type	Description
ValueError	If a motifs item is neither a recognized enzyme name nor a valid DNA sequence.
RuntimeError	If the corpus is exhausted before a clean replacement is found. Usually means the motif comes from a fixed sequence or overhang.

view()

Return the library as a pandas DataFrame.

Columns appear conditionally based on what has been configured:

• site, position, barcode: always present.
• barcode_with_fixed_seq: after add_fixed_sequence().
• forward_oligo, reverse_oligo: after generate_barcodes().

Returns:

Type	Description
DataFrame	A copy of the library. Modifying it does not affect the library.

write_order_form(file, metadata=False)

Export the oligo pool as a CSV ready for synthesis.

Writes opool_name and oligo_sequence columns. Each barcode produces two rows -- a forward oligo (site{N}_f) and a reverse oligo (site{N}_r). Prints a warning if validate() has not been run since the last design change.

Parameters:

Name	Type	Description	Default
file	str	Output CSV path.	required
metadata	bool	If True, include site, position, and barcode columns alongside the oligo sequences. Default is False.	False

Raises:

Type	Description
RuntimeError	If no oligos exist (call generate_barcodes() first).