Plugins, Hooks, & External Modules
Developer methods for
Plugins, Hooks, & External Modules
Hook functions
REDCap Developer Tools:
Documentation for Plugins, Hooks, & External Modules
REDCap Version 14.9.1
REDCap::getNextRandomizationAllocation
(REDCap >= 14.7.0)
REDCap::getNextRandomizationAllocation
— Returns the allocation id of the next unallocated table entry for the randomization and stratum specified (and project).
Description
mixed REDCap::getNextRandomizationAllocation ( int $project_id, int $randomization_id, array $fields_values, mixed $group )
Returns the integer allocation id if an unallocated entry is found, or string '0' if no entry is available (allocation table is exhausted). Returns false on error, e.g. if incorrect stratification information provided.
Parameters
project_id
The project ID number of the REDCap project for which you want to read the allocation table.
The project ID number of the REDCap project for which you want to read the allocation table.
randomization_id
The id of the current randomization (i.e., the primary key value from the redcap_randomization_table. Obtain corresponding randomization attributes using
The id of the current randomization (i.e., the primary key value from the redcap_randomization_table. Obtain corresponding randomization attributes using
\Randomization::getRandomizationAttributes($randomization_id, $project_id)).fields_values
An array of the field names (keys) and corresponding data values for the stratification fields. Value can be null or an empty array for unstratified randomizations.
An array of the field names (keys) and corresponding data values for the stratification fields. Value can be null or an empty array for unstratified randomizations.
group_id
The unique DAG name or group ID number corresponding to the data access group of the record. Value can be null when not required for randomization and the user is not assigned to a DAG.
The unique DAG name or group ID number corresponding to the data access group of the record. Value can be null when not required for randomization and the user is not assigned to a DAG.
Return Values
Returns integer allocation id if an unallocated entry is found, or string '0' if no entry is available (allocation table is exhausted). Returns false on error, e.g. if incorrect stratification information provided.
Examples
Example #1:
Randomizing a record using a custom group allocation algorithm.
$randomization_id = 465;
$fields_values = array('stratumfield1'=>'1', 'stratumfield2'=>'2');
$dag_name = "site_abc";
$allocation_id = REDCap::getNextRandomizationAllocation($project_id, $randomization_id, $fields_values, $dag_name);
if ($allocation_id === false) {
// One or more arguments are not valid
} elseif ($allocation_id === '0') {
// Allocation table for stratum is exhasted
} else {
// $allocation_id contains the id of the next available entry for the stratum
}
REDCap 14.9.1 - © 2024 Vanderbilt University