Each script under problems is a standalone generator that emits
quiz or homework items. Most use shared helpers from bptools.py
and a common argparse CLI. Follow INSTALL.md to install
qti-package-maker, then run a script after sourcing the environment.
Gene-mapping testcross questions now include individual fly illustrations beside gene
descriptions. Unordered-tetrad questions display four labeled spores in each ascus followed by
a color-coded calculation worksheet with aligned allele columns. The shared renderers and color rules are in
genemap_art/README.md.
Use --selftest to preview them, or -B -I to package the illustrated tables as PNGs for
Blackboard. Existing generated banks must be regenerated to include the artwork.
source source_me.shpython3 problems/biochemistry-problems/alpha_helix_h-bonds.py --mc -d 5- Review the generated
bbq-*.txtoutput in the repo root.
Add --bbexport when Blackboard needs an importable pool ZIP:
python3 problems/biochemistry-problems/alpha_helix_h-bonds.py --mc -d 5 --bbexportAdd -I when the Blackboard ZIP must convert every HTML table into packaged PNGs:
python3 problems/dna_profiling-problems/blood_type_agglutination_test.py -d 5 -B -IPNG conversion defaults to 4x resolution. Use --image-scale 2 when a smaller package is needed.
To test a question immediately in your default browser:
python3 problems/biochemistry-problems/alpha_helix_h-bonds.py --mc -d 1 -O-O / --open-selftest saves selftest-<name>.html beside the BBQ file and opens its
local file URL. The QTI self-test engine previews one randomly selected question from the
saved bank. Use --selftest to save without opening; combine either option with -B
to also export the Blackboard ZIP. No local web server is needed. If browser launch fails,
open the printed URL manually.
The binomial, coefficient, and explain modes of
progeny_probability_practice.py
use stacked binomial coefficients in parentheses. Probability expressions use the coefficient
directly; sequence-count choices and interpretation questions pair it with the factorial form.
binomiallib.py owns the shared notation:
binomial_coefficient(n, r) renders the stack, and format_expression(parts) keeps a complete
expression together for HTML and table-to-image output. The offspring-sex generator uses the
same coefficient renderer.
Calculation tables share the headings Category, Expected, Observed, Calculation, and Statistic. Worked examples put the substituted formula in Calculation and its numerical contribution in Statistic, with the exact and rounded chi-square total below.
The shared renderer in
chisquarelib.py accepts an optional
keyword argument, color="#004d99". Use a dark six-digit hex color: the caption uses that accent
for its text and top border, while the caption and column headings receive a pale fill mixed
with 90% white. Body rows keep their neutral styling.
create_data_table() and create_worked_table() forward the same argument. Omitting it or passing
color=None preserves the neutral appearance. make_chi_square_table() defaults to subdued gray
(#606060); pass another color to override it, or None for the neutral style. These options
change presentation only; supplied calculations, totals, and intentional errors remain intact.
bptools.applyReplacementRulesToText() and applyReplacementRulesToList() apply literal
substring rules in one pass over each original string. At each position, the longest matching
key wins, so phenotypes takes precedence over phenotype regardless of YAML order. Inserted
text and HTML are not scanned again. Regex symbols in keys and backslashes in values are literal.
Write each replacement as its final output; rules cannot depend on another rule's output.
Use separate singular and plural entries instead of rules that repair generated closing tags.
Apply the helpers once per source field: they do not skip existing HTML or make repeated calls
idempotent. Base emphasis rules and automatic <strong> wrapping still apply.
The webwork_lib text/list and prepared-pair helpers use the same longest-match behavior.
Palette placeholders are retained for future additions, and short aliases such as stattest
remain supported. Avoid embedded bold tags inside color spans; the helpers supply the outer
bold wrapper. These are literal substring rules, so retain explicit space or punctuation
guards when necessary to prevent matches inside unrelated words.
All three pedigree commands use randomly generated families and retain biological, teaching, difficulty, and layout checks. For rigorous families accepted by the shared difficulty policy, geometry-first repair addresses a large bottom gap before the existing bounded polisher runs. Candidates are then ordered by five equally weighted, pool-relative percentile ranks. The fresh pool target is 20 candidates per question, or 100 candidates per five-pedigree selection or matching question. A separate generation search may try up to 5,000 families to find each candidate. The pipeline guide covers cache reuse and additional-batch behavior.
source source_me.sh
python3 problems/inheritance-problems/pedigrees/write_pedigree_to_pattern.py -d 5 --selftest
python3 problems/inheritance-problems/pedigrees/write_pattern_to_pedigree.py -d 2 --selftest
python3 problems/inheritance-problems/pedigrees/write_pedigree_pattern_matching.py -d 2 -B -I -r output_pedigree/review-s SEED reproduces a verification run. -r saves editable SVGs and instructor-only evidence JSON.
Use -A / --autosomal on any writer for a warm-up limited to autosomal dominant and autosomal
recessive: two choices or matching pairs, with 40 candidates per selection/matching question.
Autosomal exports include an autosomal filename suffix.
The filenames encode pedigree to pattern, pattern to pedigree, and matching in both directions.
Prebuilt-bank generation and source-selection flags are retired.
See PEDIGREE_PIPELINE.md.
deletion_mutant_random.py
and deletion_mutant_words.py
retain their gene-list presentation by default. Add -e complementation (or
--evidence-format complementation) to replace uncovered-gene lists with an experimental
matrix beside the numbered chromosome map, wrapping below it when space is limited:
source source_me.sh
python3 problems/inheritance-problems/deletion_mutants/deletion_mutant_random.py -g 6 -e complementation --mc -d 5 -B -I --selftest
python3 problems/inheritance-problems/deletion_mutants/deletion_mutant_words.py --medium -e complementation --fib -d 5 --selftestGene columns are alphabetical. + means complementation and a wild-type phenotype;
the minus sign means failure to complement and a mutant phenotype: the deletion uncovers
the mutation. Deletion row colors match the chromosome map. Minus cells have a pale tint
of that deletion's color; plus cells remain white, and both symbols stay black. The map and matrix
use the same wrapping flex layout as the four-gene testcross problem. Each table exports as a
separate image, preserving the wrapping layout and independent scaling on narrow screens.
Complementation banks include complementation in their filenames.
The word generator's --medium samples five or six genes independently for each question in
one bank, using the 05-06_genes filename suffix. Its existing --num-genes option fixes the
count when supplied. Both sizes keep the existing unique-letter/anagram filter.
Existing -F / -N first-gene hints and word/random-sequence hints still apply. Uncovered
gene lists are omitted from complementation questions so students must interpret the results.
letter_translocation_problem_visual.py is a parallel version of the original colored-letter translocation question. It places gene sequences inside shaded chromosome rods and asks which of five products cannot result from the marked breaks. Original chromosomes have solid gray telomere caps and break arrows. Caps travel with their original fragment ends when a fragment reverses in an answer; the diagrams retain the gene sequences and exchange junctions without centromeres. Each question selects four distinct light fills from the color wheel, as described in REPO_COLOR_PALETTE.md. Fragment colors stay consistent across the originals and answers. Telomeres occupy short, solid gray segments outside the gene letters, with rounded outer ends like the deletion-map chromosomes.
source source_me.sh
python3 problems/inheritance-problems/translocation/letter_translocation_problem_visual.py -d 5 -B -I --selftestThe original generator and its output bank remain available. The visual bank uses its own
letter_translocation_problem_visual filename. Both share the fragment model and size controls:
-n/--min-chromosome-size (default 7) and -f/--min-fragment-size (default 3).
The visual generator requires at least three genes per fragment, as required by that model.
All choices contain fragments from both originals, so color alone does not identify the answer.
chromosome_alterations_visual.py uses one Python sequence model to connect deletion, duplication, inversion, and translocation with chromosome diagrams. The name colors identify the alteration, and the fills identify source material. See REPO_COLOR_PALETTE.md. Original arms use consecutive letters so gaps only appear after a deletion. Letters identify ordered regions, blank collars mark centromeres, and colors follow exchanged material. Arm lengths vary between chromosomes: p is always drawn before the centromere and q after it. Original p arms have two to five regions and q arms four to eleven, with q longer than p in the originals. The two originals share distinct consecutive A-Z labels. The arm used for deletion and inversion has at least five genes. Each deletion or inversion spans at least three genes, leaving retained material on both sides; tandem duplication repeats two genes to keep the resulting chromosome compact. The diagrams show an internal deletion, a tandem duplication, an inversion within one arm, or a reciprocal exchange of terminal segments. The shading and stripes are decorative; these questions do not require cytoband coordinates.
source source_me.sh
python3 problems/inheritance-problems/translocation/chromosome_alterations_visual.py --matching -d 5 -B -I --selftest
python3 problems/inheritance-problems/translocation/chromosome_alterations_visual.py --mc -d 5 -B -I --selftest
python3 problems/inheritance-problems/translocation/chromosome_alterations_visual.py --mc --flip -d 5 -B -I --selftestMatching is the default, with four name-diagram pairs. --mc shows an altered
chromosome arrangement and asks for its alteration name; --mc --flip gives the full name
and four possible diagrams. Deletion, duplication, and inversion use a single chromosome
by default in MC; translocation uses two. Matching always shows both chromosomes in every
original and rearranged diagram.
All choices in a flipped MC question show the same number of chromosomes. For a compact
single-chromosome question, the fourth diagram is the unchanged original alongside deletion,
duplication, and inversion. A translocation question shows both chromosomes in every choice.
Add --always-two to retain both chromosomes throughout MC, keeping chromosome
count from helping identify the event in picture-to-name questions.
White zigzags mark the deletion join, the join between tandem copies, both ends of an
inverted segment, and the exchanged-segment joins in translocations. The centromeres
use the shared blank Robertsonian collar style.
Each diagram has a text alternative listing genes, centromeres, and breaks in reading order,
such as H I centromere J K break O. These descriptions also survive PNG image export.
Output filenames end in matching, which_one, or which_one-flipped; --mc --always-two
adds a two_chromosomes suffix. All formats draw fresh scenarios and share the same
chromosome renderer. The existing text-based chromosome-alterations YAML bank is separate.
translate_genetic_code.py
defaults to fill-in-the-blank. Use --mc for multiple choice and -c for the number of
choices (default four):
source source_me.sh
python3 problems/molecular_biology-problems/translate_genetic_code.py --mc -n 5 -c 4 -d 2 -B -ILengths divisible by five use Wordle words for every option. Distractors replace one word
with the nearest available alternatives by Hamming distance (differing letter positions),
with randomized ties. Other lengths use single amino-acid substitutions. All choices retain
the initial M and the requested length. -X adds untranslated flanking nucleotides in either
format. MC requires at least two amino acids; --fib explicitly selects the original format.
MC filenames include the format and choice count; existing FiB filenames are unchanged.
The generators in large_crosses
include blank per-gene tables for students to fill in before selecting a multiple-choice
answer. Gamete questions show one genotype and one counting row. Genotype cross questions
build through rows (a)-(d); phenotype cross questions include all rows (a)-(e).
Names are randomly sampled from student_names.txt using
bptools.get_repo_data_path(), with two distinct names for each cross. Tables provide space
for Punnett square dimensions and the total number of cells, with no completed counts.
source source_me.sh
python3 problems/inheritance-problems/large_crosses/unique_gametes.py -B -I --hint --num_genes 7
python3 problems/inheritance-problems/large_crosses/unique_cross_genotypes.py -B -I --hint --num_genes 7
python3 problems/inheritance-problems/large_crosses/unique_cross_phenotypes.py -B -I --hint --num_genes 7Use --no-hint to omit the explanatory hints; the blank working table remains.
Generators built on bptools share a common argument set (see any script's
--help for the authoritative list):
-d,--duplicates: number of duplicate runs (questions to generate).-x,--max-questions: cap the total number of questions written.-c: number of answer choices.--mc,--ma,--format {mc,ma,num}: select the question format.--selftest: save an HTML self-test of one randomly selected question.-O,--open-selftest: save the HTML self-test and open it in your default browser.-B,--bbexport: also create a Blackboard pool export ZIP.-I,--html-to-image: convert every HTML table and RDKit canvas to packaged PNGs in a-BZIP.--image-scale N: render PNGs at positive integer scaleN(default: 4; requires-I).--hidden-terms: enable hidden decoy terms for Blackboard Learn Original.--noclick-div: enable the no-click wrapper for Blackboard Learn Original.-h,--help: show the full flag list for that script.
Hidden terms and the no-click wrapper are off by default. Hidden terms use visually hidden spans; Ultra strips their CSS and can expose the decoy words. The no-click wrapper uses inline event handlers that Ultra strips. The two Original-specific features remain available as explicit opt-ins.
The Original-specific positive flags remain supported and may be deprecated if that compatibility path is retired. The command surface omits redundant negative flags because all three features default off.
This default covers the shared anti-cheat markup only. Authored color, scripts, and table layouts can have separate Ultra limitations; see the ultra_classic_showcase_question_catalog.md.
With --bbexport, each generator first retains its normal bbq-<name>-questions.txt file, then
creates bez-<name>.zip beside it through the qti_package_maker library.
Supported export types are MC, MA, MATCH, FIB, MULTI_FIB, and NUM. Other types, including
ORDER, raise a clear error because the Blackboard export engine has no writer for them.
The ZIP replaces its destination only after it opens successfully and contains the Blackboard manifest and pool data. A failed conversion retains the BBQ text for diagnosis and removes the new temporary ZIP.
-I is opt-in and requires -B. It uses qti-package-maker to screenshot every HTML table
and RDKit canvas at 4x resolution by default, then embeds the resulting PNGs in the Blackboard ZIP.
--image-scale changes pixel density while preserving the image's displayed dimensions. It requires the Python
playwright package and its Chromium browser; after installing package dependencies, run
playwright install chromium. Nested tables are included in the outer table's image. Missing RDKit only affects banks
that contain RDKit canvases.
- Generate 5 multiple-choice questions:
python3 problems/biochemistry-problems/alpha_helix_h-bonds.py --mc -d 5
- Generate the same BBQ text plus a Blackboard pool export ZIP:
python3 problems/biochemistry-problems/alpha_helix_h-bonds.py --mc -d 5 -B
- Generate a Blackboard pool ZIP with packaged PNG drawings:
python3 problems/dna_profiling-problems/blood_type_agglutination_test.py -d 5 -B -I
- Show a generator's full options:
python3 problems/inheritance-problems/<script>.py --help
- Validate a YAML input file:
python3 tools/check_yaml.py data/genetic_disorders.yml
rna_transcribe.py replaces the three
former rna_transcribe* executables. Select one format and one direction mode:
| Options | Questions |
|---|---|
-m, --mc |
Multiple choice |
-f, --fib |
Fill in the blank |
-D, --directionless |
No prime labels; RNA bases align left-to-right with the template |
-p, --prime |
Prime labels; transcription respects strand direction |
source source_me.sh && python3 problems/molecular_biology-problems/rna_transcribe.py -m -p -d 5
source source_me.sh && python3 problems/molecular_biology-problems/rna_transcribe.py -f -D -s 12 -d 5-s/--sequence-length (also --seqlen) sets DNA length; the default is 9 and the minimum is 2.
MC supports -c/--num-choices from 2 to 5 (default: 5). Output filenames include format,
direction mode, and length. Standard export and anti-cheat options remain available.
Prime FiB questions randomly use coding or template DNA and accept RNA in the 5' to 3' direction.
FiB accepts optional commas every three bases; prime mode also accepts direction labels.
rna_transcribe_lib.py provides
transcribe_sequence, fib_answers, prompt/choice builders, and generate_question for reuse.
- Inputs: YAML/CSV/text reference data in
data, YAML banks undermatching_setsandmultiple_choice_statements, and images inimages. - Outputs (written to the repo root, ignored by git): Blackboard
bbq-*.txtfiles, Blackboardbez-*.zippackages (and olderblackboard_export_zip-*.zipfiles), QTIqti*.zippackages, andselftest-*.htmlpreviews.
- Confirm which generators expose a
--dry-runflag, if any.
Image density also accepts the short option -Z 2 (equivalent to --image-scale 2).