{"id":24319400,"url":"https://github.com/btskinner/randomizelabel","last_synced_at":"2025-09-27T04:31:24.520Z","repository":{"id":28718852,"uuid":"32239821","full_name":"btskinner/randomizelabel","owner":"btskinner","description":"Python script to randomize experimental treatment assignment and produce labels","archived":false,"fork":false,"pushed_at":"2016-08-09T21:40:31.000Z","size":44,"stargazers_count":6,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-04-04T18:10:21.154Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/btskinner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-15T01:17:33.000Z","updated_at":"2023-12-26T18:17:53.000Z","dependencies_parsed_at":"2022-08-21T22:50:40.950Z","dependency_job_id":null,"html_url":"https://github.com/btskinner/randomizelabel","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btskinner%2Frandomizelabel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btskinner%2Frandomizelabel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btskinner%2Frandomizelabel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/btskinner%2Frandomizelabel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/btskinner","download_url":"https://codeload.github.com/btskinner/randomizelabel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234384345,"owners_count":18823662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-17T15:32:59.561Z","updated_at":"2025-09-27T04:31:24.222Z","avatar_url":"https://github.com/btskinner.png","language":"Python","readme":"## Purpose\n\nThe purpose of this script is to:\n\n1. randomize a list of participants into treatment and control groups\n2. create a label for each participant that can be affixed to his or her experimental materials\n3. create a master table that links each participant to his or her assignment \n\n## Rationale\n\nThe script may be used for any randomized control trial (RCT) in which participants are known ahead of time, who may be nested within groups, and who have observable and known characteristics upon which further stratification is required.\n\nThis script assumes that treatment and control group members will receive different materials but are unaware of the difference, that is, the materials themselves will not indicate experimental condition. It's important, therefore, that each participant gets the correct materials, especially if participants take part in the experiment concurrently. As part of its randomization routine, this script automatically creates labels that can be affixed to the proper materials ahead of time.\n\n## Supplementary file requirements\n  \n1. [Requires this code](https://raw.githubusercontent.com/reingart/pyfpdf/master/tools/pdflabels.py) in the same directory saved as `pdflabels.py`. If not found, the script automatically downloads and saves the file.\n2. Requires a `*.csv` file with participant names and any information required if sampling should be blocked within groups (e.g., classroom id, student gender, student race or ethnicity)\n\n## To Use\n\n### Initialize\n\nIn terminal (works on OS X...not tested in other systems), navigate to the script directory and type: \n\n```bash\n./randomizelabel.py\n```\n\nor, if you want to set the Python interpreter manually:\n\n```\npython\u003c3\u003e randomizelabel.py\n```\n\nNote that this script requires Python 3.x.\n\n## Choose task\n\n```\n-----------------------\nWhat do you want to do?\n-----------------------\n\n( 1 ) Randomize and make labels\n( 2 ) Generate labels from prior randomization\n\nCHOICE: \n```\nIf you've already randomized a roster and simply want to reprint the labels, choose the second option (see instructions below).\n\n## (1) Randomize and make labels\n\n### Locate `*.csv` file\n\nYou will be prompted for the location of the `*.csv` file. The script will first search the local directory for all `*.csv` files and list them:\n\n```\n------------------------------------------------------------\nWhich CSV file contains the names of those to be randomized?\n------------------------------------------------------------\n\n( 1 ) fakeclasslist.csv\n( 2 ) File not in this directory\n\nCHOICE: \n```\nIf you place the names file in the same directory, you can just choose it from here. If you don't, you should select the number for `File not in this directory`. You will then be prompted with:\n\n```\nPlease give path to CSV file:\n```\n\nYou can give the full or relative paths. For example, each of the below should work:\n\n```\n/Users/\u003cusername\u003e/randomizelabel/fakeclasslist.csv\n~/randomizelabel/fakeclasslist.csv\n./randomizelabel/fakeclasslist.csv\n```\n\n### Set seed\n```\nGive integer seed of at least 6 digits:\n```\nThis seed is saved as `seed.txt` in the working directory. If you lose all assignment files, but have the roster and seed, you should be able to reproduce the same assignments.\n\n### Choose primary unit of randomization\n\n```\n---------------------------------------------\nWhich column contains the randomization unit?\n---------------------------------------------\n\n( 1 ) classid\n( 2 ) id\n( 3 ) name\n( 4 ) gender\n( 5 ) racecat\n\nCHOICE: \n```\n*NB: Randomization unit column cannot contain duplicate values.*\n\n### Decide if you want to block randomize\n```\n------------------------------------\nShould random assignment be blocked?\n------------------------------------\n\n( 1 ) Yes\n( 2 ) No\n\nCHOICE: \n```\nIf you choose `yes` then:\n\n```\n----------------------------------------\nOn which column(s) do you wish to block?\n----------------------------------------\n\n( 1 ) classid\n( 2 ) id\n( 3 ) name\n( 4 ) gender\n( 5 ) racecat\n```\nYou may choose more than one category. Separate multiple choices with a space.  \n\n*NB: You cannot block on the primary randomization unit.*\n\n\n### Check your options\n\nTo make that you get what you are expecting, the program will give you some descriptive information about your randomization choices. For example, if you chose to randomize on `id`, group on `classid`, and stratify across `gender` and `racecat`, you will see the following:\n\n```\n================================================================================\n\nFor the randomization unit: id\n\n................................................................................\n\nNumber of unique values = 400\n\n================================================================================\n\n\n================================================================================\n\nFor the grouping category: classid\n\n................................................................................\n\nNumber of unique values = 17\nUnique values: \n\nENGL101.01\nENGL101.02\nENGL101.03\nENGL101.04\nENGL101.05\nENGL101.06\nENGL101.07\nENGL101.08\nENGL101.09\nENGL101.10\nENGL101.11\nENGL101.12\nENGL101.13\nENGL101.14\nENGL101.15\nENGL101.16\nENGL101.17\n\n================================================================================\n\n\n================================================================================\n\nFor the stratification category: gender\n\n................................................................................\n\nNumber of unique values = 2\nUnique values: \n\nFemale\nMale\n\n================================================================================\n\n\n================================================================================\n\nFor the stratification category: racecat\n\n................................................................................\n\nNumber of unique values = 3\nUnique values: \n\n1\n2\n3\n\n================================================================================\n\n\n```\n\n### Decide the number of treatment groups\n\n\n```\n-------------------------------------------------\nHow many treatment conditions, excluding control?\n-------------------------------------------------\n\n( 1 ) 1\n( 2 ) 2\n( 3 ) 3\n( 4 ) 4\n( 5 ) 5\n\nCHOICE: \n```\n\n### Choose the type of labels  \n  \n\n```\n--------------------------\nWhich labels will you use?\n--------------------------\n\n( 1 ) Apli-01277\n( 2 ) Avery-3422\n( 3 ) Avery-5160\n( 4 ) Avery-5161\n( 5 ) Avery-5162\n( 6 ) Avery-5163\n( 7 ) Avery-5164\n( 8 ) Avery-8600\n( 9 ) Avery-L7163\n\nCHOICE: \n```\n\n### Choose what you want on the labels  \n\n\n```\n---------------------------------------\nWhat do you want on the printed labels?\n---------------------------------------\n\n( 1 ) classid\n( 2 ) id\n( 3 ) name\n( 4 ) gender\n( 5 ) racecat\n\nCHOICE: \n```\n\nSeparate multiple options with a space keeping in mind that the order matters. For example, `3 2 1`, would gives labels that showed: \n\n\n```\n\u003cname\u003e\n\u003cid\u003e\n\u003cclassid\u003e\n```\n\n## Output\n\nTwo primary files are placed in the working directory:\n\n1. `assignment.csv`\n2. `assignmentlabels_*.pdf` sheets with the labels\n\n#### `assignment.csv`\n\nIs a long file that contains, the randomization column and the treatment condition. Example:\n\nid      | assign  \n:-----: | :------:\nq4NSkKLNNags | C  \nNRIL0Ewhq8A5\t| T\nUXCFYfIM6JGn\t| T\nMMNjGO4CtvlL\t| T\n5Pe8c9rHidi8\t| C\n\nFor merging purposes, it's probably a good idea to randomize using a uniquely identifiable variable.\n\n#### `assignmentlabels_*.csv`\n\nThere will be one `*.pdf` for the labels for each experimental group. If you only have one treatment and one control, the you will have two files:\n\n```\nassignmentlabels_T.csv\nassignmentlabels_C.csv\n```\n\nIf you have, for example, two treatment groups and one control, you will have:\n\n```\nassignmentlabels_T1.csv\nassignmentlabels_T2.csv\nassignemntlabels_C.csv\n```\n\nThe labels themselves **will not** indicate experimental group status (for obvious reasons) so this printing scheme will mitigate mix ups. The number of pages for each group will depend on the types of labels choosen.\n\n## (2) Generate labels from prior randomization\n\nIf you have already randomized your roster and want to reprint the labels, choose the second option from the first prompt. You will be asked:\n\n```\n-----------------------------------\nWhich CSV file contains the roster?\n-----------------------------------\n\n( 1 ) assignment.csv\n( 2 ) fakeclasslist.csv\n( 3 ) File not in this directory\n\nCHOICE: \n```\nwhich should be the original roster file, and,  \n\n```\n---------------------------------------\nWhich CSV file contains the assignment?\n---------------------------------------\n\n( 1 ) assignment.csv\n( 2 ) fakeclasslist.csv\n( 3 ) File not in this directory\n\nCHOICE: \n```\nwhich should be the `assigment.csv` file generated the first time. These two files will be merged on the randomization column. After these steps, you will once again be asked to choose the types of labels and what you want printed on them.\n\n### Adjustments to labels\n\nWhen reprinting labels, you will able to adjust the printing placement of the labels as well as the font size.\n\n```\n-----------------------------------------------------\nDo you want to adjust label margins and/or font size?\n-----------------------------------------------------\n\n( 1 ) Yes\n( 2 ) No\n```\nIf you say yes, you will get the following options:\n\n```\nPlease enter horizontal adjustment (negative number for left): \nPlease enter vertical adjustment (negative number for up):\nPlease enter font size from 7 to 15 (default is 11):\n```\nHorizontal/vertical adjustments are additive. A positive number moves the labels to the right and down. Negative numbers are reverse the direction. Units are in millimeters.\n\nFont size must be one of the following options: `7, 8, 9, 10, 11, 12, 13, 14, 15`.\n\n\n## Acknowledgements\n* Originators and contributors to [PyFPDF](https://code.google.com/p/pyfpdf/)\n* [List of random names](http://listofrandomnames.com/) and [Mark Heckmann at ryouready](https://ryouready.wordpress.com/2008/12/18/generate-random-string-name/) for helping me generate my fake class data\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbtskinner%2Frandomizelabel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbtskinner%2Frandomizelabel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbtskinner%2Frandomizelabel/lists"}