Package: nsb-toolbox
NSB ToolboxA command-line utility for formatting Science Bowl questionsVersion 0.5.2 - Updated for 2024 NSBThe NSB Toolbox contains a set of tools to make it easier to write and edit Science Bowl questions. It ensures that questions are compliant with the official Science Bowl format, allowing writers to focus on just writing the questions. It also highlights common formatting errors for editors, allowing them to focus on checking content without worrying that they're missing formatting issues here and there.Table of ContentsInstallationDocumentationnsb formatAuto-FormattingLintingnsb assignSample Configurationnsb makeKnown IssuesInstallationCurrently, the NSB Toolbox can be installed via pip from this github. To do so, you will need:Python 3.8 or greater installed on your computer.Enter and runpip install nsb-toolboxin your command line.Verify the installation worked by runningnsb -hin your command line. If the help information for the toolbox appears, the installation was successful.DocumentationYou can access the NSB Toolbox via thensbcommandlet. Runningnsb -hdisplays the following help menu.(base)PSC:\Users\rishik>nsb-husage:nsb[-h]{format,make}...UtilitiesformanagingScienceBowl.docxfiles.optionalarguments:-h,--helpshowthishelpmessageandexitsubcommands:{format,make}formatformataScienceBowlfilemakemakeaScienceBowltablensb formatnsb formatprovides two functions in one - first, it is a formatter than ensures Science Bowl questions are properly spaced (four spaces between question type and start of stem, blank line between stem and answer, etc). Second, it is a linter that highlights questions that it cannot fix. It is important to note thatnsb formatcannot catch every problem with the question! For example,nsb formatwill never be able to check question content for correctness. Allnsb formatcan do is eliminate or highlight typical formatting errors.Usagensb formattakes a single mandatory argument, the path to the target .docx file. For example:nsb format path/to/nsb/questions.docxIt also takes an optional argument,--capitalize. If given,nsb formatwill force every answer line to be capitalized. For example:nsb format path/to/nsb/questions.docx --capitalizeIt also provides a--line-after-stemoptional argument to add a blank line after the stem in Multiple Choice questions (the official style prior to 2023). For example:nsb format path/to/nsb/questions.docx --line-after-stemAuto-Formattingnsb formatoutright fixes a number of formatting errors. It strives to produce questions that have the following characteristics:The question class (TOSS-UP, BONUS) is uppercase.Subject (Biology, Chemistry, etc.) are title case.Question type (Multiple Choice, Short Answer) are italicized and title case.There are four spaces between the question type and the start of the stem.For multiple choice questions, the stem and choices are each separated by a single paragraph break.There are two paragraph breaks before the answer line.The answer line is uppercase, assuming the--capitalizeargument is used.Notably,nsb formatoperates by moving, copying, and inserting XML elements. This ensures thatuser-provided formatting won't be overwritten(for example, superscripts and subscripts for mathematical formulae).For example, all of the following improperly formatted questions:nsb formatwill automatically convert these questions to be compliant with the Science Bowl format:Shorthand notation can also be used to reduce the amount of time writers spend writing boilerplate.TU and B will be converted to TOSS-UP and BONUS, respectively. The shorthand for the subject categories is the first letter of the subject, aside for Earth and Space (ES) and Energy (EN). MC and SA will be converted to Multiple Choice and Short Answer, as well.Finally,nsb formatwill automatically correct minor errors in question structure. For example, the following question has multiple X) choices:The mislabeled choices will be automatically corrected. Note that an answer line that has been explicitly given will not be auto-capitalized:LintingIfnsb formatfails to parse a cell, it will raise linting errors by highlighting the question and printing the error in the command line. There are two levels of errors: parsing errors, which will highlight a cell red, and question structure errors, which will highlight the problematic structure yellow.nsb formatsearches for the following errors:The question has a class, subject, type, stem, and answer. Multiple Choice questions should also have four choices.Question type is correctly labeled - Multiple Choice questions should have choices, Short Answer questions should not.For multiple choice questions, the wording of the answer line should match the wording of the choice.For example:The first question is missing two choices, so it can't be fully parsed, raising a red error. The second question is merely mislabeled - it says it's a Multiple Choice question, but is recognized as a Short Answer question. This raises a yellow error, highlighting the question type. Messages corresponding to these errors are printed in the terminal, as well:(base) rishi@RISHI-DESKTOP:~$ nsb format after_format.docx
Question 6: Couldn't parse question, was looking for QuestionFormatterState.CHOICES
Question 7: Question type is MC, but has no choices.nsb formatis not capable of deleting lines that contain text. This is intentional - while there are errors thatnsb formathighlights that it could probably fix automatically, the maintainer believes it is more prudent to leave whitespace formatting tonsb formatand making any other changes by hand.nsb assignnsb assignuses a set of configuration options to automatically assign a set of edited questions to rounds.Usagensb assigntakes two mandatory arguments, the path to the edited set of Science Bowl questions and the path to the configuration file. For example:nsb assign path/to/nsb/questions.docx -c path/to/config.yamlIt also takes an optional--dry-runargument, which will report statistics on the assignment procedure, but will not write the successful assignment to disk. This is primarily useful for determining what additional questions of a given difficulty or type are required. For example:❯nsbassignKulkarni_HS_Chemistry_Regionals.docx-cassign.yaml--dry-run
SetLODTUBNeedHave
HSR1BONUS840HSR1TOSS-UP846HSR2BONUS021HSR2TOSS-UP1031HSR3BONUS022HSR3TOSS-UP030HSR-A1BONUS2510HSR-A1TOSS-UP255HSR-A2BONUS233HSR-A2TOSS-UP305HSR-A3BONUS1313HSR-A3TOSS-UP69HSR-B1BONUS257HSR-B1TOSS-UP256HSR-B2BONUS236HSR-B2TOSS-UP304HSR-B3BONUS1313HSR-B3TOSS-UP69Notwritingassignmentsasthisisadryrun.Sample Configuration FileBelow is a sample configuration file for a High School Regional set. The sections are explained in more detail further below.Configuration:Shuffle Subcategory:TrueShuffle Pairs:FalseShuffle LOD:FalseRandom Seed:~Subcategory Mismatch Penalty:1Preferred Writers:[]Round Definitions:Tiebreakers:TU:LOD:[2]RoundRobin:TU:LOD:[1,1,1,1]Subcategory:[Organic,~,~,~]B:LOD:[1,1,1,1]Subcategory:[Organic,~,~,~]DoubleElim1-4:TU:LOD:[2,2,2,2]B:LOD:[2,2,2,2]DoubleElim5-6:TU:LOD:[2,2,2,2]B:LOD:[2,2,3,3]DoubleElim7-9:TU:LOD:[2,2,3,3]B:LOD:[2,3,3,3]Sets:-Set:[HSR]Prefix:RRRounds:[1,2]Template:RoundRobin-Set:[HSR]Prefix:TBRounds:[1,2,3,4,5,6,7,8,9,10]Template:Tiebreakers-Set:[HSR-A,HSR-B]Prefix:RRRounds:[3,4,6,7,8]Template:RoundRobin-Set:[HSR-A,HSR-B]Prefix:RRRounds:[5]Template:from:RoundRobinadd:TU:LOD:[1]B:LOD:[1]-Set:[HSR-A,HSR-B]Prefix:DERounds:[1,2,3,4]Template:DoubleElim1-4-Set:[HSR-A,HSR-B]Prefix:DERounds:[5,6]Template:DoubleElim5-6-Set:[HSR-A,HSR-B]Prefix:DERounds:[7,8,9]Template:DoubleElim7-9Configuration OptionsShuffle Subcategory: Setting this option toTruerandomizes the order that any subcategory specification appears in a round. For example, if you have requested["Organic", ~, ~, ~], setting this option toTruemakes the"Organic"subcategory uniformly distributed rather than the first question of each round. Note that setting this option toTruebreaks any matching betweenTUandBsubcategories.Shuffle Pairs: Setting this option toTrueadds a randomization step after each pair of questions has been constructed. This is useful when you have intentionally matchedTUandBsubcategories, for example, but want to randomize the order that the subcategories appear in each round. Note that even when this is enabled, the final pair of each round will beShort Answerquestions.Shuffle LOD: Setting this option toTruerandomizes the order that question difficulties appear in each round, similar to the above options.Random Seed: Setting this option to an integer fixes the generated assignment, all else being equal. If left unspecified or set to None, the assignment will have a slight random element to it.Subcategory Mismatch Penalty: Setting this option to an integer specifies how much cost is incurred by creating a subcategory mismatch. Common options include:1, which says that matching a question with the right difficulty but wrong subcategory is equally costly as using a question whose difficulty is off by1, but the subcategory is correct.2, which says that matching a question with the right difficulty but wrong subcategory is always less preferable than using a question with the right subcategory but off-by-one difficulty, but also always more preferable than using a question with the right subcategory but off-by-two difficulty.Preferred Writers: If specified, any writers NOT in this list are given a small penalty, encouraging the optimization algorithm to use the preferred writers. This penalty is very small and should never result in a question of the wrong subcategory or difficulty from a preferred writer being used over a question of the right subcategory and difficulty from an unpreferred writer.Round DefinitionsRound Definitions:Tiebreakers:TU:LOD:[2]RoundRobin:TU:LOD:[1,1,1,1]Subcategory:[Organic,~,~,~]B:LOD:[1,1,1,1]Subcategory:[Organic,~,~,~]Round Definitionsserve as templates to build round specifications. Each round definition needs to specify the question types it uses (TUand/orBfor TOSS-UP and BONUS) and the Level of Difficulty of each question. Optionally, the subcategories can be specified. Entering a~indicates that there is no subcategory preference for that slot.To explain the above specification in plain English, we want all Tiebreaker rounds to consist of a single
TOSS-UP question with a difficulty of 2, and all Round Robin rounds to consist of 4 TOSS-UPs and 4 BONUSes that each have a difficulty of 1. Finally, a quarter of TOSS-UPs and BONUSes should use the "Organic" subcategory.SetsSets:-Set:[HSR-A,HSR-B]Prefix:RRRounds:[1,2]Template:RoundRobinTheSetssection actually specifies what rounds will be built. A set is defined with theSet,Prefix,Rounds, andTemplatekeys. TheSet,Prefix, andRoundskeys are round meta-data, while theTemplatekey will build the round using the matching entry in theRound Specificationssection.These keys are used combinatorially - the above set will generate 4 rounds: HSR-A RR1, HSR-A RR2, HSR-B RR1, and HSR-B RR2.Optionally,Setscan use thefrom:,add:syntax:-Set:[HSR-A,HSR-B]Prefix:RRRounds:[5]Template:from:RoundRobinadd:TU:LOD:[1]B:LOD:[1]This syntax specifies that theRoundRobintemplate should be used, but there should be an extra TOSS-UP and BONUS that each have a difficulty of 1.nsb makensb makeproduces a blank Science Bowl question table with a designated number of lines. This is a convenience function for writers.nsb make -hshows the following help menu:(base)PSC:\Users\rishik>nsbmake-husage:nsbmake[-h][-nNAME][-st{HSR,HSN,MSR,MSN}][-su{B,C,P,M,ES,EN}]pathrowspositionalarguments:pathpathtotheScienceBowldocxfilerowsnumberofrowsinoutputtableoptions:-h,--helpshowthishelpmessageandexit-nNAME,--nameNAMELast,Firstnameofauthor-st{HSR,HSN,MSR,MSN},--set{HSR,HSN,MSR,MSN}Set-su{B,C,P,M,ES,EN},--subj{B,C,P,M,ES,EN}SubjectFor example, to create a table for 120 high school regional Physics questions for author: "Kulkarni, Rishi" the following command would work:nsbmake-n"Kulkarni, Rishi"-stHSR-suPKulkarni_HS_Physics_Regionals120Known IssuesIfnsb formatis used on a document with tracked changes, it will assume the changes were accepted.Please report any other issues you find onGithub.