TimePoint.class.inc

<?php declare(strict_types=1);

/**
 * This file contains a TimePoint class which represent's a single session
 * for a single candidate in Loris.
 *
 * PHP Version 8
 *
 * @category Main
 * @package  Loris
 * @author   Alex Zijdenbos <zijdenbos@example.com>
 * @license  http://www.gnu.org/licenses/gpl-3.0.txt GPLv3
 * @link     https://www.github.com/aces/Loris-Trunk/
 */
use \LORIS\StudyEntities\Candidate\CandID;
use \LORIS\Data\Filters\HasAnyPermissionOrUserSiteMatch;

/**
 * The Loris TimePoint class
 *
 * @category Main
 * @package  Loris
 * @author   Alex Zijdenbos <zijdenbos@example.com>
 * @license  http://www.gnu.org/licenses/gpl-3.0.txt GPLv3
 * @link     https://www.github.com/aces/Loris-Trunk/
 */
class TimePoint implements \LORIS\StudyEntities\AccessibleResource,
    \LORIS\StudyEntities\SiteHaver
{
    /* NOTE If these are private variables then they should probably be
     * declared and scoped as such. var is equivalent to public.
     */
    var $_timePointInfo;

    var $_stageOptions = [
        null,
        'Not Started',
        'Screening',
        'Visit',
        'Approval',
        'Subject',
        'Recycling Bin',
    ];

    var $_dynamicStageOptions = [
        'Screening',
        'Visit',
        'Approval',
    ];

    var $_statusOptions = [
        null,
        'Pass',
        'Failure',
        'Withdrawal',
        'In Progress',
    ];

    var $bvlQcTypes = [
        null,
        'Visual',
        'Hardcopy',
    ];

    var $bvlQcStatuses = [
        null,
        'Complete',
    ];

    var $bvlQcExclusionStatuses = [
        null,
        'Excluded',
        'Not Excluded',
    ];


    /**
     * A DTO for TimePoint related data
     */
    protected ?TimePointData $data;

    /**
     * Construct a TimePoint object seeded with the data
     * from the given DTO.
     *
     * @param ?TimePointData $data The Timepoint DTO
     */
    public function __construct(?TimePointData $data=null)
    {
        $this->data = $data;
    }

    /**
     * Returns an object representing this Timepoint, and ensures that only
     * one is ever created per Session.
     *
     * @param SessionID $sessionID The ID of the TimePoint to retrieve from the
     *                             database
     *
     * @return TimePoint object representing $sessionID
     */
    static function &singleton(SessionID $sessionID)
    {
        // instantiate new TimePoint object
        static $timePointList = [];
        if (!isset($timePointList["$sessionID"])) {
            try {
                $timePointList["$sessionID"] = new TimePoint();

                $timePointList["$sessionID"]->select($sessionID);
            } catch (Exception $e) {
                // Since there was a problem with this $sessionID, don't store
                // it in the static list but then keep propagating the error..
                unset($timePointList["$sessionID"]);
                throw $e;
            }
        }

        return $timePointList["$sessionID"];
    }

    /**
     * Loads the data from the given sessionID into the current TimePoint class.
     *
     * @param SessionID $sessionID The $sessionID to load.
     *
     * @return void (but side-effect loads current object.)
     */
    function select(SessionID $sessionID): void
    {
        $factory      = NDB_Factory::singleton();
        $db           = $factory->database();
        $config       = $factory->config();
        $useScreening = $config->getSetting('useScreening');
        $screeningIndex = array_search('Screening', $this->_stageOptions);
        if ($useScreening != 'true' && $screeningIndex !== false) {
            unset($this->_stageOptions[$screeningIndex]);
            $this->_stageOptions = array_values($this->_stageOptions);
        }

        // get user data from database
        $query = "SELECT s.ID AS SessionID, c.CandID, p.Name AS PSC, s.CenterID,
                         s.VisitNo, s.Visit_label, s.CohortID, s.Submitted,
                         s.Current_stage, s.Screening, s.Date_screening, s.Visit,
                         s.Date_visit, s.Approval, s.Date_approval, s.Active,
                         s.registeredBy, s.UserID, u.Real_name, s.Hardcopy_request,
                         s.BVLQCStatus, s.BVLQCType, s.BVLQCExclusion, s.Scan_done,
                         pr.Name as ProjectName, p.Alias as SiteAlias,
			 s.ProjectID as ProjectID,
                         l.language_code as LanguageCode,
                         l.language_label as LanguageLabel
                    FROM session AS s
                        LEFT JOIN psc AS p USING (CenterID)
                        LEFT JOIN users AS u on (s.registeredBy=u.UserID)
                        LEFT JOIN Project AS pr USING(ProjectID)
                        LEFT JOIN candidate AS c ON (s.CandidateID=c.ID)
                        LEFT JOIN language l ON (s.languageID=l.language_id)
                    WHERE s.ID = :SID AND s.Active = 'Y'";
        $row   = $db->pselectRow(
            $query,
            ['SID' => $sessionID]
        );

        $this->data = new TimePointData(
            $sessionID,
            isset($row['ProjectID'])
                ? ProjectID::singleton($row['ProjectID'])
                : null,
            isset($row['CenterID'])
                ? \CenterID::singleton($row['CenterID'])
                : null,
        );

        // store user data in object property
        if (is_array($row) && count($row) > 0) {
            $this->_timePointInfo = $row;
            if (isset($row['LanguageCode'])) {
                $this->_timePointInfo['Language'] = new \Language(
                    $row['LanguageLabel'],
                    $row['LanguageCode']
                );
            }
            unset($row['language_code'], $row['language_label']);
            $cohortSettings = $config->getCohortSettings(
                intval($row['CohortID'] ?? null)
            );
            $title          = $cohortSettings['title'] ?? '';
            $this->_timePointInfo['CohortTitle'] = $title;

            $this->_timePointInfo['CandID']
                = new CandID(strval($row['CandID']));
        } else {
            // return error when 0 rows to prevent creation of an empty object
            throw new LorisException(
                "Failed to retrieve data for timepoint $sessionID"
            );
        }
        // New feature, older databases might not have the table created,
        // so require a config option to be set
        if ($config->getSetting("SupplementalSessionStatus") == 'true') {

            $query = "SELECT ss.Name, ss.Value
                        FROM session_status ss
                            JOIN session s ON (s.ID=ss.SessionID)
                        WHERE s.ID=:sessionID AND s.Active='Y'";

            $statuses = $db->pselect($query, [":sessionID" => $sessionID]);
            foreach ($statuses as $row) {
                if (!isset($this->_timePointInfo['status'])) {
                    $this->_timePointInfo['status'] = [];
                }
                $this->_timePointInfo['status'][$row['Name']] = $row['Value'];
            }
        }

        $this->_timePointInfo['WindowInfo'] = $db->pSelectRow(
            "SELECT (w.WindowMinDays IS NOT NULL
                     OR w.OptimumMinDays IS NOT NULL)
                        as WindowDefined,
                    DATEDIFF(s.Date_visit, c.DoB) as AgeDays,
                    DATEDIFF(s.Date_visit, c.DoB) BETWEEN
                        w.OptimumMinDays
                        AND w.OptimumMaxDays as Optimum,
                    (DATEDIFF(s.Date_visit, c.DoB) BETWEEN
                        w.WindowMinDays AND w.WindowMaxDays
                    ) as Permitted
                FROM session s
                    JOIN candidate c ON c.ID=s.CandidateID
                    JOIN Visit_Windows w ON (
                        LOWER(w.Visit_label)=LOWER(s.Visit_label)
                    )
                WHERE s.ID=:sessionID",
            [":sessionID" => $sessionID]
        );
    }

    /**
     * Registers a new timepoint into the session table
     *
     * @param \Candidate   $candidate      The Candidate to create this timepoint for
     * @param integer      $CohortID       The cohortID of the new timepoint
     * @param string|null  $nextVisitLabel The visit label of the timepoint
     *                                     being created. If null,
     *                                     consecutive V1, V2, etc will be
     *                                     created.
     * @param \Site        $psc            The center of the timepoint
     * @param \Project     $project        The project of the timepoint
     * @param integer|null $lang           The language id
     *
     * @throws DatabaseException
     *
     * @return void
     */
    static function createNew(
        \Candidate $candidate,
        int $CohortID,
        ?string $nextVisitLabel,
        \Site $psc,
        \Project $project,
        ?int $lang = null
    ): void {

        // insert into session set CandID=$candID,
        // CohortID=$CohortID, VisitNo=nextVisitNumber(),
        // UserID=$State->getUsername(), etc...  NO Date_* are
        // specified here!
        $factory = NDB_Factory::singleton();
        $db      = $factory->database();

        // if this is a web hit (thus state exists)
        if (isset($_SESSION) && is_object($_SESSION['State'])) {
            // get username from State
            $userID = $_SESSION['State']->getUsername();
        } else {
            // not a web hit, so use the unix username from the environment
            $userID = getenv('USER');
        }

        // generate today's date for the Date registered field
        $today = date("Y-m-d");

        $visitNo = $candidate->getNextVisitNo();
        // setup the insert data array
        $VisitLabel = $nextVisitLabel;
        if ($VisitLabel === null) {
            $VisitLabel = "V$visitNo";
        }

        $language = $lang;
        if ($language === null) {
            $langList = Utility::getLanguageList();
            $language = array_key_first($langList);
        }

        $insertData = [
            'CandidateID'     => $candidate->getID(),
            'CohortID'        => $CohortID,
            'VisitNo'         => $visitNo,
            'Visit_label'     => $VisitLabel,
            'CenterID'        => $psc->getCenterID()->__toString(),
            'ProjectID'       => $project->getId(),
            'Current_stage'   => 'Not Started',
            'Submitted'       => 'N',
            'registeredBy'    => $userID,
            'UserID'          => $userID,
            'Date_registered' => $today,
            'Date_active'     => $today,
            'languageID'      => $language,
        ];

        // insert the data
        $db->insert('session', $insertData);
    }

    /**
     * Validates if a given visit_label follows the study's config settings
     * and if that same visit label can be created for the given candidate.
     *
     * @param CandID     $candid    The candidate identifier
     * @param \ProjectID $projectID The Project identifier
     * @param integer    $cohortID  The cohortID
     * @param string     $visitName The visit name
     *
     * @throws LorisException
     *
     * @return void
     */
    static function isValidVisitLabel(
        CandID $candid,
        \ProjectID $projectID,
        int $cohortID,
        string $visitName
    ): void {
        // This can happen if the user quickly clicks "Create Time Point" before the
        // page has loaded and the Visit Label dropdown hasn't been selected yet.
        // The page will create "V1" when this is the case without this check.
        if (empty($visitName)) {
            throw new \LorisException(
                'A visit label is required.'
            );
        }

        // Check if visit label exists for this cohort
        if (!array_key_exists(
            $visitName,
            \Utility::getVisitsForCohort(
                $cohortID
            )
        )
        ) {
            throw new \LorisException(
                'This visit label is not valid for this cohort.'
            );
        }

        $candidate =& \Candidate::singleton($candid);

        // The function below gets a list of VisitNames from the DB, not real labels
        $timePointArray = $candidate->getListOfVisitLabels();

        //If the visitLabel is already in use then let the user pick another
        foreach ($timePointArray AS $used_name) {
            if (strcasecmp($visitName, $used_name) == 0) {
                // Get project name
                $project     = \Project::getProjectFromID($projectID);
                $projectName = $project->getName();

                // Get cohort title
                $factory        = \NDB_Factory::singleton();
                $config         = $factory->config();
                $cohortSettings = $config->getCohortSettings($cohortID);
                $cohortTitle    = $cohortSettings['title'] ?? 'Unknown';

                // Get participant PSCID
                $pscid = $candidate->getPSCID();

                $message = sprintf(
                    dgettext(
                        "create_timepoint",
                        "A timepoint with these conditions (%s, %s, %s, %s) "
                            . "already exists."
                    ),
                    $pscid,
                    $projectName,
                    $cohortTitle,
                    $visitName
                );

                throw new \LorisException($message);
            }
        }
    }

    /**
     * Gets a piece of data regarding this TimePoint. Usually, you should
     * use one of the get* methods below, but in cases where it does not
     * exist you can use this function directly.
     *
     * @param string|null $var The variable to retrieve about this timepoint.
     *
     * @return mixed The value of $var for this timepoint, or all values.
     */
    function getData(?string $var = null)
    {
        if (is_null($var)) {
            return $this->_timePointInfo;
        } elseif (isset($this->_timePointInfo[$var])) {

            return $this->_timePointInfo[$var];
        }
        return null;
    }

    /**
     * Sets a piece of data for this timepoint and saves it to the session table.
     * $newData should be in the form: array($key => $value).
     *
     * This should usually not be used directly but instead use one of the set*
     * methods below. However, there are cases where it may be easier to directly
     * use setData.
     *
     * @param array $newData Key-value pair(s) of the field(s) to change and its
     *                       new value(s).
     *
     * @return bool
     *
     * @throws DatabaseException
     * @throws LorisException
     */
    public function setData(array $newData): bool
    {
        /* $newData should be in the form: array($key => $value). Count should
         * equal 1 if this is the case.
         */
        if (empty($newData)) {
            throw new LorisException(
                'TimePoint::setData() cannot be called with an empty array!'
            );
        }

        \NDB_Factory::singleton()->database()->update(
            'session',
            $newData,
            [
                'ID' => $this->getData('SessionID'),
            ]
        );
        // this select updates the timepoint object
        $this->select($this->getSessionID());
        return true;
    }

    /**
     * Returns the CandID for the candidate who had this visit.
     *
     * @return CandID (6-10 digit) CandID for this timepoint.
     */
    function getCandID(): CandID
    {
        /* _timePointInfo contains information that comes from the database
         * which returns values in string format. CandID is used here to
         * ensure we return a validated CandID object.
         */
        return $this->_timePointInfo["CandID"];
    }

    /**
     * Returns the SessionID for this visit.
     *
     * @return SessionID The ID for this session.
     */
    function getSessionID(): SessionID
    {
        return $this->data->getSessionID();
    }

    /**
     * Return the string representing the center for this visit.
     *
     * @return string The center of this visit
     */
    function getPSC(): string
    {
        return $this->_timePointInfo["PSC"];
    }

    /**
     * Returns the CenterID for this visit.
     *
     * @return \CenterID
     */
    function getCenterID(): \CenterID
    {
        return $this->data->getCenterID();
    }

    /**
     * Return the visit number for this timepoint.
     *
     * @return integer the number of this visit.
     */
    function getVisitNo(): int
    {
        /* _timePointInfo contains information that comes from the database
         * which returns values in string format. Intval is used here to
         * ensure we return a numerical ID instead of its string representation.
         */
        return intval($this->_timePointInfo["VisitNo"]);
    }

    /**
     * Returns the visit label of this timepoint.
     *
     * @return string the visit label
     */
    function getVisitLabel(): string
    {
        return $this->_timePointInfo["Visit_label"];
    }

    /**
     * Returns the CohortID of this timepoint.
     *
     * @return int|null the CohortID, or null
     */
    function getCohortID(): ?int
    {
        /* _timePointInfo contains information that comes from the database
         * which returns values in string format. Intval is used here to
         * ensure we return a numerical ID instead of its string representation.
         */
        if (is_numeric($this->_timePointInfo["CohortID"])) {
            return intval($this->_timePointInfo["CohortID"]);
        }
        return null;
    }

    /**
     * Gets this timepoint's screening status.
     *
     * @return ?string 'Pass', 'Failure', 'Withdrawal', or 'In Progress'
     */
    function getScreeningStatus(): ?string
    {
        return $this->_timePointInfo["Screening"];
    }

    /**
     * Gets the visit status of this timepoint.
     *
     * @return ?string 'Pass', 'Failure', 'Withdrawal', or 'In Progress'
     */
    function getVisitStatus(): ?string
    {
        return $this->_timePointInfo["Visit"];
    }

    /**
     * Return the approval status of this timepoint.
     *
     * @return string|null 'In Progress', 'Pass' or 'Failure'
     */
    function getApprovalStatus(): ?string
    {
        return $this->_timePointInfo["Approval"];
    }

    /**
     * Returns the date of screening for this session.
     *
     * @return string|null of form "YYYY-MM-DD" (or null)
     */
    function getDateOfScreening(): ?string
    {
        return $this->_timePointInfo["Date_screening"];
    }

    /**
     * Returns the date of visit for this session.
     *
     * @return string|null of form "YYYY-MM-DD" (or null)
     */
    function getDateOfVisit(): ?string
    {
        return $this->_timePointInfo["Date_visit"];
    }

    /**
     * Returns the date of approval of this session.
     *
     * @return string|null of form "YYYY-MM-DD" (or null)
     */
    function getDateOfApproval(): ?string
    {
        return $this->_timePointInfo["Date_approval"];
    }

    /**
     * Returns whether this timepoint was submitted to DCC
     *
     * @return true if submitted
     */
    function isSubmitted(): bool
    {
        return $this->_timePointInfo["Submitted"] == 'Y';
    }

    /**
     * Returns whether this timepoint is active or not.
     *
     * @return boolean true if active.
     */
    function isActive(): bool
    {
        return $this->_timePointInfo["Active"] == 'Y';
    }

    /**
     * Gets whether or not a scan was done for this TimePoint
     *
     * @return string 'Y' if a scan was done 'N' if not.
     */
    function getScanDone(): string
    {
        return $this->_timePointInfo["Scan_done"];
    }

    /**
     * Returns BVLQC status (Y-hardcopy QC, N-no QC, V-visual QC)
     *
     * @return string|null
     */
    function getBVLQCStatus(): ?string
    {
        return $this->_timePointInfo['BVLQCStatus'];
    }

    /**
     * Returns BVLQC exclusion type
     *
     * @return string|null
     */
    function getBVLQCType(): ?string
    {
        return $this->_timePointInfo['BVLQCType'];
    }

    /**
     * Returns BVLQC exclusion status
     *
     * @return string
     */
    function getBVLQCExclusion(): string
    {
        return $this->_timePointInfo['BVLQCExclusion'];
    }

    /**
     * Returns the list of BVLQC exclusion statuses
     *
     * @return array
     */
    function getBVLQCExclusionStatusList(): array
    {
        return $this->bvlQcExclusionStatuses;
    }

    /**
     * Returns the current stage of the selected timepoint
     *
     * @return string the current stage
     */
    function getCurrentStage(): string
    {
        return $this->_timePointInfo["Current_stage"];
    }

    /**
     * Gets the current stage status
     *
     * @return string|null status of current stage
     */
    function getCurrentStatus(): ?string
    {
        $method = 'get' . $this->getCurrentStage() . 'Status';
        if (method_exists($this, $method)) {
            return $this->$method();
        } else {
            return null;
        }
    }

    /**
     * Gets the date of the current stage.
     *
     * @return string|null "YYYY-MM-DD"
     */
    function getCurrentDate(): ?string
    {
        $getDateMethod = "getDateOf" . $this->getCurrentStage();
        if (method_exists($this, $getDateMethod)) {
            return $this->$getDateMethod();
        }
        return null;
    }

    /**
     * Defines the next study stage
     *
     * @return string|null study stage title
     */
    function getNextStage(): ?string
    {
        if ($this->getData('Current_stage') == 'Approval'
            && $this->getData('Approval') != 'Pass'
        ) {

            // if the time point is sent to DCC and the outcome is not Pass
            // then the next stage is Recycling Bin
            return 'Recycling Bin';

        }
        // otherwise just get the next stage in the sequence
        $index = array_search(
            $this->getData('Current_stage'),
            $this->_stageOptions
        );

        $nextStageIndex = $index + 1;

        return $this->_stageOptions[$nextStageIndex];
    }

    /**
     * Defines a stage as dynamic - that can be assigned a BVL
     * battery, its status updated, and sent to DCC
     *
     * @param string $stage A study stage, from the field session.Current_stage
     *
     * @return bool
     */
    function isStudyStageDynamic(string $stage): bool
    {
        // if not $stage is passed, evaluate the current stage
        if (empty($stage)) {
            throw new Exception("Study Stage Not Specified");
        } else {
            return in_array($stage, $this->_dynamicStageOptions);
        }
    }

    /**
     * Determine whether the current stage is static or dynamic.
     *
     * @return boolean true if stage is dynamic.
     */
    function isCurrentStageDynamic()
    {
        $isStageDynamic = $this->isStudyStageDynamic($this->getCurrentStage());
        return $isStageDynamic;
    }

    /**
     * Determine whether the next stage is dynamic or static
     *
     * @return boolean true if stage is dynamic.
     */
    function isNextStageDynamic(): bool
    {
        return $this->isStudyStageDynamic($this->getNextStage());
    }

    /**
     * Derives what stage the TimePoint should be set to and updates
     * the session table.
     *
     * @return void
     */
    function setCurrentStage(): void
    {
        $db = \NDB_Factory::singleton()->database();

        // this class does not handle Subject & Recycling Bin stage at the moment
        if (in_array($this->getCurrentStage(), ['Subject', 'Recycling Bin'])) {
            return;
        }

        // if sent to DCC then it either Approval, Subject or Recycling Bin
        if ($this->isSubmitted() && $this->getApprovalStatus() != 'NULL') {
            if ($this->getApprovalStatus() == 'Failure') {
                $newCurrentStage = 'Recycling Bin';
                // delete from conflicts_unresolved if marked Recycling Bin
                $commentIDs = $db->pselect(
                    "SELECT CommentID FROM flag WHERE SessionID=:SID",
                    ['SID' => $this->getSessionID()]
                );
                foreach ($commentIDs as $commentID) {
                    $deleteWhere1 = ['CommentId1' => $commentID];
                    $deleteWhere2 = ['CommentId2' => $commentID];
                    $db->delete('conflicts_unresolved', $deleteWhere1);
                    $db->delete('conflicts_unresolved', $deleteWhere2);
                }
            } else {
                // in all other cases
                $newCurrentStage = 'Approval';
            }
        } else {
            // of not sent to DCC get the latest stage
            if ($this->getVisitStatus() != null) {
                $newCurrentStage = 'Visit';
            } elseif ($this->getScreeningStatus() != null) {
                $newCurrentStage = 'Screening';
            } else {
                $newCurrentStage = 'Not Started';
            }
        }

        // generate today's date in MySQL format
        $today = date("Y-m-d");

        // update session table
        $update_columns = [
            "Date_stage_change" => $today,
            'Current_stage'     => $newCurrentStage,
        ];

        $db->update(
            'session',
            $update_columns,
            ['ID' => $this->getSessionID()]
        );

        // reload TimePoint object
        $this->select($this->getSessionID());
    }

    /**
     * Starts a stage.
     *
     * @param string $stage The stage which is being started.
     *                      valid options are those in session.Current_stage
     *                      enum
     *
     * @return void (but as a side-effect modifies database.)
     */
    function startStage(string $stage): void
    {
        $setArray = [
            'Current_stage'     => $stage,
            'Date_stage_change' => date('Y-m-d'),
        ];

        if (in_array($stage, $this->_dynamicStageOptions)
            && $this->getData($stage) == null
        ) {
            $setArray[$stage] = 'In Progress';
            $setArray['Date_status_change'] = date('Y-m-d');
        }

        if ($setArray['Current_stage'] == 'Approval') {
            $setArray['Date_approval'] = date('Y-m-d');
        }

        $this->setData($setArray);
    }

    /**
     * Sends Time Point to DCC
     * also allow "unsend", i.e. sets session.Submit='N' in case it ever
     * becomes necessary
     *
     * @param string $type see session.QCd field options, what is passed
     *                     here is the label from the bvlQcTypes array
     *
     * @return void
     */
    function setBVLQCType(string $type): void
    {
        $db = \NDB_Factory::singleton()->database();

        if (!in_array($type, $this->bvlQcTypes)) {
            throw new Exception("You need to specify a valid BVL QC Type");
        }

        $setArray = ['BVLQCType' => $type];

        // update session table
        $db->update(
            'session',
            $setArray,
            ['ID' => $this->getSessionID()]
        );

        // reload TimePoint object
        $this->select($this->getSessionID());
    }

    /**
     * Set BVL QC Status.
     *
     * @param string $status The status to set the BVL QC to.
     *                       Valid options are Complete or null.
     *
     * @return void
     */
    function setBVLQCStatus(string $status): void
    {
        $db =& \NDB_Factory::singleton()->database();

        if (!in_array($status, $this->bvlQcStatuses)) {
            throw new Exception("You need to specify a valid BVL QC Type");
        }

        // get the current bvlqc type
        $qcType = $this->getBVLQCType();

        // can't set the status to Complete unless the type is set
        if ($status == 'Complete' && empty($qcType)) {
            throw new Exception("Cannot complete QC until the type is defined");
        }

        $setArray = ['BVLQCStatus' => $status];

        // update session table
        $db->update(
            'session',
            $setArray,
            ['ID' => $this->getSessionID()]
        );

        // reload TimePoint object
        $this->select($this->getSessionID());
    }

    /**
     * Sets the BVL QC Exclusionary status for this timepoint.
     *
     * @param string $status The status to set this TimePoint to.
     *                       Valid options are "Excluded" or "Not Excluded"
     *
     * @return true on success
     */
    function setBVLQCExclusion(string $status): bool
    {
        $db = \NDB_Factory::singleton()->database();

        // check the status
        if (!in_array($status, $this->bvlQcExclusionStatuses)) {
            throw new Exception(
                "TimePoint::setBVLQCExclusion: "
                . "You need to specify a valid BVL QC Exclusion Status"
            );
        }

        // fields to update
        $setArray = ['BVLQCExclusion' => $status];

        // update session table
        $db->update(
            'session',
            $setArray,
            ['ID' => $this->getSessionID()]
        );

        // reload TimePoint object
        $this->select($this->getSessionID());

        return true;
    }

    /**
     * Determines whether the next stage for the timepoint is startable.
     *
     * Rules:  1. User must have permission.
     *         2. If the stage to be started is a testing stage, then there can
     *            be no other timepoints of the same cohort that are in a
     *            testing stage (screening or visit).
     *         3. If the stage to be started is not a testing stage, the the
     *            current stage status cannot be "In Progress".
     *
     * @return bool
     */
    function isStartable(): bool
    {
        $currentStage = $this->getData('Current_stage');

        // if we have not yet started, and at least one timepoint is in
        // screening or visit, do not allow the user to start another timepoint
        if ($currentStage == 'Not Started') {
            return true;
        } elseif ($currentStage == 'Screening'
            && in_array($this->getData('Screening'), ['Pass', 'Failure'])
        ) {
            return true;
        }
        return false;
    }

    /**
     * Returns either EDC or DOB depending on the settings of the cohort
     * that this timepoint belongs to.
     *
     * @return string|null date YYYY-MM-DD
     */
    function getEffectiveDateOfBirth(): ?string
    {
        $candidate = \Candidate::singleton($this->getCandID());
        if (!is_null($this->getCohortID())) {
            $settings = \NDB_Config::singleton()
                ->getCohortSettings($this->getCohortID());
            if (isset($settings['options']['useEDC'])
                && $settings['options']['useEDC'] == "true"
            ) {
                return $candidate->getCandidateEDC();
            }
        }

        return $candidate->getCandidateDoB();
    }

    /**
     * Gets the Images of that session.
     *
     * @param \LORIS\LorisInstance $loris The LORIS instance to retrieve data
     *                                    from.
     * @param \User                $user  The requesting user.
     *
     * @return \LORIS\Data\Models\ImageDTO[] A traversable of ImageDTO
     */
    public function getImages(\LORIS\LorisInstance $loris, \User $user): array
    {
        $provisioner = new \LORIS\Data\Provisioners\TimepointImagesRowProvisioner(
            $loris,
            $this
        );

        $provisioner = $provisioner
            ->filter(new \LORIS\Data\Filters\ScansFilter())
            ->filter(new \LORIS\Data\Filters\PhantomsFilter());

        $traversable = (new \LORIS\Data\Table())
            ->withDataFrom($provisioner)
            ->getRows($user);

        return iterator_to_array($traversable);
    }

    /**
     * Gets the first Image of that session matching a given filename.
     *
     * @param \LORIS\LorisInstance $loris    The LORIS instance to retrieve data
     *                                       from.
     * @param \User                $user     The requesting user.
     * @param string               $filename The requested filename.
     *
     * @throws \NotFound
     * @return \LORIS\Image
     */
    public function getImageByFilename(
        \LORIS\LorisInstance $loris,
        \User $user,
        string $filename
    ): \LORIS\Image {
        $filtered = array_filter(
            $this->getImages($loris, $user),
            function ($dto) use ($filename) {
                return $dto->getFilename() == $filename;
            }
        );

        if (empty($filtered)) {
            throw new \NotFound($filename . ' not found.');
        }

        // Take the first corresponding file.
        $imagedto = array_pop($filtered);

        return new \LORIS\Image($imagedto->getFileid());
    }

    /**
     * Gets the Electrophysiology recordings of that session.
     *
     * @param \LORIS\LorisInstance $loris The LORIS instance to retrieve data
     *                                    from.
     * @param \User                $user  The requesting user.
     *
     * @return \Traversable
     */
    public function getRecordings(
        \LORIS\LorisInstance $loris,
        \User $user
    ): \Traversable {
        $provisioner
            = new \LORIS\Data\Provisioners\TimepointRecordingsRowProvisioner(
                $loris,
                $this
            );

        $filter = new HasAnyPermissionOrUserSiteMatch(
            ['electrophysiology_browser_view_allsites']
        );

        $provisioner = $provisioner->filter($filter);
        return $provisioner->execute($user);
    }

    /**
     * Gets the first Recording of that session matching a given filename.
     *
     * @param \LORIS\LorisInstance $loris    The LORIS instance to retrieve data
     *                                       from.
     * @param \User                $user     The requesting user
     * @param string               $filename The requested filename
     *
     * @throws \NotFound
     * @return \LORIS\Recording
     */
    public function getRecordingByFilename(
        \LORIS\LorisInstance $loris,
        \User $user,
        string $filename
    ): \LORIS\Recording {
        $filtered = array_filter(
            iterator_to_array($this->getRecordings($loris, $user)),
            function ($dto) use ($filename) {
                return $dto->getFilename() == $filename;
            }
        );

        if (empty($filtered)) {
            throw new \NotFound($filename . ' not found.');
        }

        // Take the first corresponding file.
        $recordingdto = array_pop($filtered);

        return new \LORIS\Recording($recordingdto->getFileid());
    }

    /**
     * Gets the DicomTars of that session.
     *
     * @param \LORIS\LorisInstance $loris The LORIS instance to retrieve data
     *                                    from.
     * @param \User                $user  The requesting user.
     *
     * @return \LORIS\data\Models\DicomTarDTO[] A traversable of DicomTarDTO
     */
    public function getDicomTars(\LORIS\LorisInstance $loris, \User $user): iterable
    {
        $provisioner = new \LORIS\api\provisioners\VisitDicomsRowProvisioner(
            $loris,
            $this
        );
        return iterator_to_array($provisioner->execute($user));
    }

    /**
     * Gets the first DicomTar of that session matching a given filename.
     *
     * @param string $tarname The requested filename
     *
     * @throws \NotFound
     * @return \LORIS\Data\Models\DicomTarDTO
     */
    public function getDicomTarByFilename(
        string $tarname
    ): \LORIS\Data\Models\DicomTarDTO {
        $db  = \NDB_Factory::singleton()->database();
        $row = $db->pselectRow(
            'SELECT
               TarchiveID as tarchiveid
             FROM
               tarchive
             WHERE
               tarchive.SessionID = :v_sessionid AND
               tarchive.ArchiveLocation LIKE :v_basename',
            [
                'v_sessionid' => $this->getSessionID(),
                'v_basename'  => '%' . $tarname,
            ]
        );

        if (empty($row)) {
            throw new \NotFound($tarname . ' not found.');
        }

        return (new \LORIS\DicomTar(intval($row['tarchiveid'])))->asDTO();
    }

    /**
     * Try to get an existing MRI upload ID for this session and a given file, or
     * insert a new one if no corresponding MRI upload exists.
     *
     * @param \User        $user        The user inserting the file.
     * @param \SplFileInfo $file        The file on the file system.
     * @param string       $patientname The patient name
     * @param bool         $isphantom   True if it's a phantom file
     *
     * @return int The UploadID from the mri_upload table sequence.
     */
    public function getOrAddMRIUpload(
        \User $user,
        \SplFileInfo $file,
        string $patientname,
        bool $isphantom
    ): int {
        // We try to re-use an existing MRI upload if there already is one for the
        // file to insert. There may be several uploads per file, so we choose to
        // re-use the last upload when that is the case.
        $db         = \NDB_Factory::singleton()->database();
        $mri_upload = $db->pselect(
            '
                SELECT UploadID
                FROM mri_upload
                WHERE
                    UploadedBy     = :UploadedBy     AND
                    UploadLocation = :UploadLocation AND
                    SessionID      = :SessionID      AND
                    PatientName    = :PatientName    AND
                    IsPhantom      = :IsPhantom
                ORDER BY UploadID DESC
                LIMIT 1
            ',
            [
                'UploadedBy'     => $user->getUsername(),
                'UploadLocation' => $file->getPathname(),
                'SessionID'      => $this->getSessionID(),
                'PatientName'    => $patientname,
                'IsPhantom'      => $isphantom ? 'Y' : 'N',
            ],
        );

        if ($mri_upload->count() !== 0) {
            return $mri_upload->getFirstRow()['UploadID'];
        }

        $db->insert(
            'mri_upload',
            [
                'UploadedBy'     => $user->getUsername(),
                'UploadDate'     => date('Y-m-d H:i:s'),
                'UploadLocation' => $file->getPathname(),
                'SessionID'      => $this->getSessionID(),
                'PatientName'    => $patientname,
                'IsPhantom'      => $isphantom ? 'Y' : 'N',
            ],
        );

        return (int) $db->getLastInsertId();
    }

    /**
     * This retrieves all MRIUpload with the given filename for that session.
     *
     * @param \LORIS\LorisInstance $loris    The LORIS instance.
     * @param \User                $user     The requesting user.
     * @param string               $filename The mri_upload file's basename.
     *
     * @return \LORIS\Data\Models\MRIUploadDTO[]
     */
    public function getMRIUploadsByFilename(
        \LORIS\LorisInstance $loris,
        \User $user,
        string $filename,
    ): array {
        $provisioner = new \LORIS\Data\Provisioners\TimepointMRIUploadsProvisioner(
            $loris,
            $this,
            $filename,
        );
        $traversable = (new \LORIS\Data\Table())
            ->withDataFrom($provisioner)
            ->getRows($user);

        return iterator_to_array($traversable);
    }

    /**
     * This retrieves a MRIUpload with the given id for that session.
     *
     * @param \User $user        The requesting user.
     * @param int   $mriuploadid The mri_upload id.
     *
     * @throws \NotFound When the id can not be found for that session.
     *
     * @return \LORIS\Data\Models\MRIUploadDTO
     */
    public function getMRIUploadsById(
        \User $user,
        int $mriuploadid
    ): \LORIS\Data\Models\MRIUploadDTO {
        $db  = \NDB_Factory::singleton()->database();
        $row = $db->pselectRow(
            '
             SELECT
               m.UploadID as mri_upload_id,
               m.UploadedBy as uploaded_by,
               m.UploadDate as upload_date,
               m.UploadLocation as upload_location,
               m.DecompressedLocation as decompress_location,
               m.InsertionComplete as insertion_complete,
               m.Inserting as inserting,
               m.PatientName as patient_name,
               m.number_of_mincInserted as inserted_minc_count,
               m.number_of_mincCreated as created_minc_count,
               m.TarchiveID as tarchive_id,
               m.SessionID as session_id,
               m.IsCandidateInfoValidated as is_candidate_info_validated,
               m.IsTarchiveValidated as is_tarchive_validated,
               m.IsPhantom as is_phantom
             FROM
               mri_upload m
             WHERE
               m.SessionID = :v_sessionid AND
               m.UploadID = :v_mriuploadid
            ',
            [
                'v_sessionid'   => $this->getSessionID(),
                'v_mriuploadid' => $mriuploadid,
            ]
        );
        if (empty($row)) {
            throw new \NotFound('MRIUploadID not found.');
        }

        return \LORIS\Data\Models\MRIUploadDTO::fromDBRow($row);
    }

    /**
     * Accessor for this timepoint imaging QC status.
     *
     * @return \LORIS\TimePointImagingQC
     */
    public function getImagingQC(): \LORIS\TimePointImagingQC
    {
        $db  = \NDB_Factory::singleton()->database();
        $row = $db->pselectRow(
            '
             SELECT
               MRIQCStatus as qcstatus,
               MRIQCPending as ispending,
               MRICaveat as hascaveat
             FROM
               session
             WHERE
               ID = :v_sessionid
            ',
            ['v_sessionid' => $this->getSessionID()]
        );

        return new \LORIS\TimePointImagingQC(
            $row['qcstatus'] ?? null,
            $row['ispending'] ?? null,
            $row['hascaveat'] ?? null
        );
    }

    /**
     * Gets the instrument names associated to this timepoint
     *
     * The DISTINCT keyword is used because DDE instruments would meke
     * duplicates.
     *
     * @return array A list of test_name
     */
    public function getInstrumentNames(): array
    {
        $db     = \NDB_Factory::singleton()->database();
        $result = $db->pselectCol(
            '
             SELECT DISTINCT
               tn.Test_name as shortname
             FROM
               flag f
             JOIN test_names tn ON (f.TestID=tn.ID)
             WHERE
               f.SessionID = :v_sessionid
            ',
            ['v_sessionid' => $this->getSessionID()]
        );
        return $result;
    }

    /**
     * Gets the project of this Timepoint
     *
     * @return \Project
     */
    public function getProject(): \Project
    {
        return \NDB_Factory::singleton()->project(
            $this->getData('ProjectName')
        );
    }

    /**
     * Returns the ProjectID for this TimePoint
     *
     * @return \ProjectID
     */
    public function getProjectID() : \ProjectID
    {
        return $this->data->getProjectID();
    }

    /**
     * Implements the AccessibleResource interface. A TimePoint can
     * be accessed by a user if it has a project and a site in common.
     *
     * @param \User $user The user whose access should be validated.
     *
     * @return bool
     */
    public function isAccessibleBy(\User $user) : bool
    {
        $centers = $user->getCenterIDs();

        $projMatch   = in_array($this->getProjectID(), $user->getProjectIDs());
        $centerMatch = in_array($this->getCenterID(), $centers);
        return $projMatch && $centerMatch;
    }

    /**
     * Get the language for this timepoint.
     *
     * @return \Language
     */
    public function getLanguage() : \Language
    {
        $lang = $this->getData('Language');
        if ($lang === null) {
            return new \Language("Unknown", "en_CA");
        }
        return $lang;
    }
}