Merge pull request #11 from redcapuzgent/issue_10

gadeynebram · web-flow · commit 0041e3fc66f9 · 2019-08-23T12:43:52.000+02:00
Add method to change randomisation target
diff --git a/Randapi.php b/Randapi.php
@@ -200,7 +200,7 @@ function getFreeAllocationRecordForTarget($criteriaFields,$fields=array(),$group
      */
     function changeSources(string $recordId,int $projectId,$fields=array(),array $allocations,$group_id='',string $arm_name='Arm 1', string $event_name='Event 1'){
 
-        error_log("init randomize record");
+        error_log("init change sources");
         $this->initRandomizeRecord($recordId, $projectId);
 
         global $status;
@@ -248,7 +248,7 @@ function changeSources(string $recordId,int $projectId,$fields=array(),array $al
                 error_log("Found a new aid $newAid");
                 // No need to change the target_field value in redcap_data. This remains the same.
                 if(!$this->query("update redcap_randomization_allocation set is_used_by = null where aid = '$currentAid' and is_used_by = '$recordId'")){
-                    throw new RandapiException("Could not unsed is_used_by for aid $currentAid");
+                    throw new RandapiException("Could not unset is_used_by for aid $currentAid");
                 }
                 error_log("updated is_used_by from old aid $currentAid to null");
                 if(!$this->query("update redcap_randomization_allocation set is_used_by = '$recordId' where aid = $newAid;")){
@@ -292,6 +292,142 @@ function changeSources(string $recordId,int $projectId,$fields=array(),array $al
         }
     }
 
+    /**
+     * In limited cases it might be necessary to change the outcome of the randomization. E.g. in an automated process a record was assigned to a certain target group.
+     * Due to some manual changes, the record is unrandomized. Correcting the error and randomizing the record again, results in a different target value.
+     * This can be done using the following steps
+     * 1) Check if an allocation record is available for the given recorid
+     * 2) Collect the current source_field value.
+     * 3) Look for a new allocation record (aid) for the new source_field values but for the same target_field.
+     * 4) Select the first free allocation. If none available, add new ones as defined in $newAllocations and select first (aid)
+     * 5) Update is_used_by field for the current allocation to null, update the new allocation to the new found aid.
+     * 6) Update the source field values in the record
+     *
+     * @param string $recordId
+     * @param int $projectId
+     * @param string $new_target The new target value
+     * @param string $group_id
+     * @param RandomizationAllocation[] $allocations These allocations will be added if no allocations are available for the given combination of source fields and the target field.
+     * @param string $arm_name (optional) The name of the arm. default = 'Arm 1'
+     * @param string $event_name (optional) The name of the event. default = 'Event 1'
+     * @return int
+     * @throws Exception
+     */
+    function changeTarget(string $recordId,int $projectId,string $new_target,array $allocations,$group_id='',string $arm_name='Arm 1', string $event_name='Event 1'){
+
+        error_log("init change target");
+        $this->initRandomizeRecord($recordId, $projectId);
+
+        global $status;
+
+        $recordId = db_real_escape_string($recordId);
+
+        /**
+         * @var $source_fields array key value array with key source_fieldx and value the source_field's name
+         */
+        $source_fields = Randomization::getRandomizationFields(false,true);
+
+        $source_field_columns = array_keys($source_fields);
+        for($i = 0; $i < sizeof($source_field_columns); $i++){
+            $source_field_columns[$i]="ra.".$source_field_columns[$i];
+        }
+
+        // What is the current target_field value?
+        $currentTargetFieldQuery = $this->query("SELECT ra.aid, ".implode(',',$source_field_columns)."
+                    FROM redcap_randomization r
+                    join redcap_randomization_allocation ra on 
+                        ra.rid = r.rid and
+                        ra.is_used_by = '$recordId' and 
+                        ra.project_status = $status
+                    where r.project_id = $projectId");
+        if($row = $currentTargetFieldQuery->fetch_assoc()){
+
+            // copy of Randomization::randomizeRecord
+            // Ensure that fields have all correct criteria fields. If not, return false to throw AJAX error msg.
+            $criteriaFieldsOk = true;
+            $criteriaFields = Randomization::getRandomizationFields(false,true);
+
+            //create RandomizationField objects
+            /**
+             * @var $source_fields_rf RandomizationField[]
+             */
+            $source_fields_rf = array();
+            foreach(array_keys($source_fields) as $source_field){
+                $source_fields_rf[] = new RandomizationField($criteriaFields[$source_field], strval($row[$source_field]));
+            }
+            $currentAid = $row["aid"];
+
+            $source_fields_str = array();
+            foreach($source_fields_rf as $rf){
+                $source_fields_str[] = $rf->getKey()." => ".$rf->getValue();
+            }
+
+            error_log("Received current source fields ".implode(",",$source_fields_str)." and current aid $currentAid");
+            if (count($source_fields_rf) != count($criteriaFields)) $criteriaFieldsOk = false;
+            foreach (array_keys($source_fields_rf) as $field) {
+                if (!in_array($field, $criteriaFields)) $criteriaFieldsOk = false;
+            }
+
+            if(!$criteriaFieldsOk){
+                throw new Exception("The given criteria fields are not valid");
+            }
+            error_log("criteria fields are oké.");
+            $newAid = $this->getFreeAllocationRecordForTarget($criteriaFields, $source_fields_rf, $group_id, $new_target);
+            if($newAid == 0) {
+                error_log("No allocations are present");
+                if (is_array($allocations) && sizeof($allocations) > 0) {
+                    error_log("Adding new allocations");
+                    $this->addRecordsToAllocationTable($projectId, $status, $allocations);
+                    $newAid = $this->getFreeAllocationRecordForTarget($criteriaFields, $source_fields_rf, $group_id, $new_target);
+                } else {
+                    throw new RandapiException('No free allocation was available and no allocations were passed through the $allocations argument');
+                }
+            }
+            if($newAid != 0){
+                error_log("Found a new aid $newAid");
+                // No need to change the target_field value in redcap_data. This remains the same.
+                if(!$this->query("update redcap_randomization_allocation set is_used_by = null where aid = '$currentAid' and is_used_by = '$recordId'")){
+                    throw new RandapiException("Could not unset is_used_by for aid $currentAid");
+                }
+                error_log("updated is_used_by from old aid $currentAid to null");
+                if(!$this->query("update redcap_randomization_allocation set is_used_by = '$recordId' where aid = $newAid;")){
+                    throw new RandapiException("Could not set is_used_by for aid $newAid");
+                }
+                error_log("updated is_used_by from new aid $newAid to $recordId");
+                // update the target field in the record
+
+                $randomization_fields = Randomization::getRandomizationFields(false,false);
+
+                $updateQuery = "
+                    update redcap_data rd
+                    join redcap_events_metadata md on 
+                        md.event_id = rd.event_id and
+                        md.descrip = '$event_name'
+                    join redcap_events_arms a on 
+                        a.arm_id = md.arm_id and
+                        a.arm_name = '$arm_name'
+                    join redcap_randomization_allocation newa on newa.aid = $newAid
+                    set rd.value = newa.target_field
+                    where rd.project_id = $projectId and
+                        rd.record = '$recordId' and
+                        rd.field_name = '".$randomization_fields["target_field"]."'
+                ";
+                error_log("Executing query $updateQuery");
+                if(!$this->query($updateQuery)){
+                    throw new RandapiException("Could not update target_field  to value '".$new_target."' for project $projectId, record $recordId, event $event_name and arm $arm_name from aid $currentAid to aid $newAid");
+                }else{
+                    error_log("updated target_field to value '".$new_target."' for project $projectId, record $recordId, event $event_name and arm $arm_name from aid $currentAid to aid $newAid");
+                }
+                return $newAid;
+            }else{
+                throw new RandapiException("Could not find an empty allocation record for the given target and source fields");
+            }
+
+        }else{
+            throw new RandapiException("Record $recordId has not yet been randomized");
+        }
+    }
+
     /**
      * @param int $projectId The project id
      * @param int $project_status (0 = development, 1 = production)
@@ -509,6 +645,10 @@ public function handleRequest(stdClass $jsonObject, string $jsonText):void{
                         $newAid = $this->handleChangeSources($jsonObject);
                         echo json_encode($newAid);
                         break;
+                    case "changeTarget":
+                        $newAid = $this->handleChangeTarget($jsonObject);
+                        echo json_encode($newAid);
+                        break;
                     default:
                         throw new RandapiException("Invalid Action was specified");
                 }
@@ -709,4 +849,63 @@ private function handleChangeSources(stdClass $jsonObject){
             $eventName);
     }
 
+    /**
+     * @param stdClass $jsonObject
+     * @return int
+     * @throws RandapiException
+     */
+    private function handleChangeTarget(stdClass $jsonObject){
+
+        error_log("Received parameters in changeTarget: ".print_r($jsonObject,true));
+
+        if(!property_exists($jsonObject,"parameters")){
+            error_log("parameters property not found.");
+            throw new RandapiException("parameters property not found.");
+        }
+        if(!property_exists($jsonObject->parameters, "recordId")){
+            error_log("parameters->recordId property not found.");
+            throw new RandapiException("parameters->recordId property not found.");
+        }
+        if(!property_exists($jsonObject->parameters, "target")){
+            error_log("parameters->fields property not found.");
+            throw new RandapiException("parameters->fields property not found.");
+        }
+        if(!property_exists($jsonObject->parameters, "allocations")){
+            error_log("parameters->allocations property not found.");
+            throw new RandapiException("parameters->allocations property not found.");
+        }
+        if(!is_array($jsonObject->parameters->allocations)){
+            error_log("parameters->allocations is not an array.");
+            throw new RandapiException("parameters->allocations is not an array.");
+        }
+
+        // optional
+        $groupId = "";
+        if(property_exists($jsonObject->parameters, "groupId")){
+            $groupId = $jsonObject->parameters->groupId;
+        }
+        $armName = "Arm 1";
+        if(property_exists($jsonObject->parameters, "armName")){
+            $groupId = $jsonObject->parameters->armName;
+        }
+        $eventName = "Event 1";
+        if(property_exists($jsonObject->parameters, "eventName")){
+            $eventName = $jsonObject->parameters->eventName;
+        }
+
+        $allocations = array();
+        foreach($jsonObject->parameters->allocations as $allocation){
+            array_push($allocations,RandomizationAllocation::fromstdClass($allocation));
+        }
+
+        error_log("executing changeTarget");
+        return $this->changeTarget($jsonObject->parameters->recordId,
+            $this->getProjectId(),
+            $jsonObject->parameters->target,
+            $allocations,
+            $groupId,
+            $armName,
+            $eventName);
+    }
+
 }
diff --git a/help.php b/help.php
@@ -167,6 +167,42 @@
                     }
                 </code>
             </pre>
+
+            <h2>changeTarget</h2>
+            <p>In limited cases it might be necessary to change the outcome of the randomization. E.g. in an automated process a record was assigned to a certain target group. Due to some manual changes, the record is unrandomized. Correcting the error and randomizing the record again, results in a different target value.</p>
+            <p>If possible, another allocation record for the preferred target will be used that maintains the current assigned sources.</p>
+            <p>If no such records exist, there is a possibility to provide additional allocation records</p>
+
+            <h3>parameters:</h3>
+            <ul>
+                <li><b>recordId</b>: The record that we want to change source fields for</li>
+                <li><b>target</b>: The new target value</li>
+                <li><b>allocations</b>: A list of new allocation records, in case there is no record available anymore.
+                <li><b>groupId</b>: (optional) The DAG identifier. default = '' (none)</li>
+                <li><b>armName</b>: (optional) The name of the arm. default = 'Arm 1'</li>
+                <li><b>eventName</b>: (optional) The name of the event. default = 'Event 1'</li>
+            </ul>
+            <h3>Example:</h3>
+            <p>This examples changes the target for record 1 to assignedto A. In case there is no allocation record available anymore, we allow the algorithm to add these 4 new allocations.</p>
+
+            <pre>
+                <code>
+                    {
+                        "action":"changeTarget",
+                        "token":"F33F6876ADC5EC63CE79EBFF88FF0092",
+                        "parameters":{
+                            "recordId":1,
+                            "target":'A',
+                            "allocations":[
+                                {"source_fields":["2"],"target_field":"1"},
+                                {"source_fields":["2"],"target_field":"2"},
+                                {"source_fields":["2"],"target_field":"1"},
+                                {"source_fields":["2"],"target_field":"2"},
+                            ]
+                        }
+                    }
+                </code>
+            </pre>
         </div>
     </body>
 </html>
diff --git a/typescript/ChangeSourcesParameters.ts b/typescript/ChangeSourcesParameters.ts
@@ -7,14 +7,16 @@ export class ChangeSourcesParameters{
      *
      * @param recordId The record that we want to randomize
      * @param fields An array of RandomizationFields
-     * @param resultFieldName The field where the randomization result can be stored.
+     * @param allocations New allocations in case none are available for the given fields and current target
      * @param groupId (optional) The DAG identifier. default = '' (none)
      * @param armName (optional) The name of the arm. default = 'Arm 1'
      * @param eventName (optional) The name of the event. default = 'Event 1'
      */
-    constructor(public recordId: string, public fields: RandomizationField[],
+    constructor(public recordId: string,
+                public fields: RandomizationField[],
                 public allocations: RandomizationAllocation[],
                 public groupId: string = '',
-                public armName: string= 'Arm 1', public eventName: string = 'Event 1') {
+                public armName: string= 'Arm 1',
+                public eventName: string = 'Event 1') {
     }
 }
diff --git a/typescript/ChangeTargetAction.ts b/typescript/ChangeTargetAction.ts
@@ -0,0 +1,9 @@
+import {RandApiAction} from "./RandApiAction";
+import {ChangeTargetParameters} from "./ChangeTargetParameters";
+
+export class ChangeTargetAction extends RandApiAction{
+
+    constructor(public parameters:ChangeTargetParameters, public token: string){
+        super("changeTarget",token, parameters);
+    }
+}
diff --git a/typescript/ChangeTargetParameters.ts b/typescript/ChangeTargetParameters.ts
@@ -0,0 +1,21 @@
+import {RandomizationAllocation} from "./RandomizationAllocation";
+
+export class ChangeTargetParameters{
+
+    /**
+     *
+     * @param recordId The record that we want to randomize
+     * @param target The new target
+     * @param allocations allocations New allocations in case none are available for the given target and current sources
+     * @param groupId (optional) The DAG identifier. default = '' (none)
+     * @param armName (optional) The name of the arm. default = 'Arm 1'
+     * @param eventName (optional) The name of the event. default = 'Event 1'
+     */
+    constructor(public recordId: string,
+                public target: string,
+                public allocations: RandomizationAllocation[],
+                public groupId: string = '',
+                public armName: string= 'Arm 1',
+                public eventName: string = 'Event 1') {
+    }
+}
