Skip to content

Latest commit

 

History

History
360 lines (285 loc) · 20 KB

USAGE.md

File metadata and controls

360 lines (285 loc) · 20 KB

Usage

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.

Quick start

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.sh
  • python3 problems/biochemistry-problems/alpha_helix_h-bonds.py --mc -d 5
  • Review the generated bbq-*.txt output 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 --bbexport

Add -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 -I

PNG 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.

Binomial notation

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.

Chi-square table colors

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.

Text replacement rules

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.

Pedigree homework

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 mapping evidence

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 --selftest

Gene 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.

Visual letter translocation

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 --selftest

The 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.

Visual chromosome alterations

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 --selftest

Matching 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.

Genetic code translation

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 -I

Lengths 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.

Large-cross working tables

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 7

Use --no-hint to omit the explanatory hints; the blank working table remains.

CLI

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 -B ZIP.
  • --image-scale N: render PNGs at positive integer scale N (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.

Blackboard Ultra defaults

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.

Blackboard ZIP export

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.

Examples

  • 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 transcription

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 and outputs

  • Inputs: YAML/CSV/text reference data in data, YAML banks under matching_sets and multiple_choice_statements, and images in images.
  • Outputs (written to the repo root, ignored by git): Blackboard bbq-*.txt files, Blackboard bez-*.zip packages (and older blackboard_export_zip-*.zip files), QTI qti*.zip packages, and selftest-*.html previews.

Known gaps

  • Confirm which generators expose a --dry-run flag, if any.

Image density also accepts the short option -Z 2 (equivalent to --image-scale 2).