User Guide ############# Start Menu ----------- From the start menu you can start a treatment analysis with a new patient or access treatments analysis in progress or treat the requests from external institution in case Tucuxi is connected to another information system. The **New Patient** icon leads to the process of a new patient registration and the start of a new treatment analysis. The **Load interpretation** icon displays the list of patients already registered. Finding treatments analysis of a specific drug is possible with the drug filter situated above the list. Other filters are avaible on the right in addition to the refresh button which updates the list. Clicking on a table heading allows to list the requests depending on the order desired. By default, the list is displayed by patient's ID order. The **Pending requests** icon gives access to requests sent to Tucuxi. Depending of the software version used, treatment requests may provide datas automatically set such as the patient's required informations, the drug subjects to the analysis, the history dosages administrated and the measured drug concentration in the sample. The **Shutdown** icon and the icons mentioned above are accessible anytime during the use of the software, on the top right corner of the interface. .. figure:: images/user_guide/start_menu.png :align: center :width: 100 % Interface general informations ------------------------------- The interface of Tucuxi is seperated in four parts. .. figure:: images/user_guide/interface/3parts.png :align: center :width: 100 % In the top-right part are situated multiple icons. The first one is to save the current interpretation, the second one is used to return to the main menu, and the third one is to switch to the pending request list. Then there is a set of four icons. The first one is to (TODO)**open/activate** the help, then there is the icon to hopen the information about Tucuxi itself, after that there is the application setting icon, and lastly the button to shutdown the application. .. figure:: images/user_guide/interface/settings1.png :align: center :width: 100 % Inside the settings menu, there are four tabs. The first one, called Analyst, is to fill the analyst informations that then will be displayed on the final report. The second tab, called General, is for the general application setting like enabling the percentile computation or enabling the automatic computation. The automatic computatiohn will automatically refresh the graph at each changes of informations instead, if it is turned off, it will onlys compute the graph when the refresh button is clicked. .. figure:: images/user_guide/interface/settings1.png :align: center :width: 100 % The last two tabs of the setting menu are Sentences, that is used to set where is located the XML file that contains the sentences, and lastly there is the Connectivity tab that is currently empty. (TODO) Thene, there is the process panel situated on the top displays every step of the treatment analysis, from the beginning on the left to the end on the right, allowing to navigate through them. The order of this flow variates slightly depending on the state of the treatment started with the patient. Regarding the analysis of measured drug rates from a patient currently in treatment, the process is the following: .. figure:: images/user_guide/interface/process1.png :align: center :width: 100 % Regarding the case of a patient who has not revceived any doses of drugs yet, the process is the following: .. figure:: images/user_guide/interface/process2.png :align: center :width: 100 % The step in progress is slightly darker than the others. Each step is represented with an icon and a checkbox on the top right corner to indicate the state of the process. .. |img1| image:: images/user_guide/interface/green.png :scale: 50% :align: middle .. |img2| image:: images/user_guide/interface/yellow.png :scale: 50% :align: middle .. |img3| image:: images/user_guide/interface/red.png :scale: 50% :align: middle +--------+------------------------+ | |img1| | valid parameters set | +--------+------------------------+ | |img2| | step in progress | +--------+------------------------+ | |img3| | invalid parameters | +--------+------------------------+ The part below displayed in two equal sections is used to set values and show informations. On the left part, the control panel allows to set and edit parameters listed in different sections below collapsable titles. The plus symbol (1) on the top right corner of lists allows to add an element. Removing one is possible with the minus symbol (2) on the rigth of each row and the pen symbol (3) next to it can be used to edit the element. To set dates, an information field can be manually filled with the DD/MM/YYYY format or by choosing the date by clicking on the calendar icon (4). Some parameters to set require to fill a window with information fields. .. figure:: images/user_guide/interface/control_panel.png :align: center :width: 100 % On the right, the graph panel displays graphs and informations given the parameters set for each step. Curves are shown with percentils values of the result for the ordered list {5, 25 , 75 , 95}. The 5-95 percentil area is shown lighter than the 25-75 percentil area. Clicking on the principle curve prompts an information box providing the exact details of the value of the point selected and precisions about the concentration. Clicking on the checking box of each legend allows to remove or add curves. **Apriori** curves show the results based on a sub-group of the population with specific covariates. **Aposteriori** curves are the results of the measured drug concentration. The time's scale axe is editable by scrolling anywhere on the graph area. Moving in the time's axe is possible by maintening a selected point and moving to the right or to the left area of the graph. A grey vertical line with a clock icon appears to indicate the current situation of the patient at the current time. .. figure:: images/user_guide/interface/graph_panel.png :align: center :width: 100 % Graph settings ^^^^^^^^^^^^^^ By default Tucuxi centers the graph on the end of the treatment, adjusts the time scale, and scales the Y-axis to allow all curves to fit in (percentiles and adjustments). However the user can act on different values: * Vertical scale: * Horizontal scale: * Horizontal displacement: * Continuous * Event-based * Date-based .. figure:: images/user_guide/interface/graph_menu.png :align: center :width: 30 % In order to perform those actions, the user need to either right-click on the graph and select the wanted interaction from the menu that appears, or use one of the available key combinations like *shift + wheel up* to zoom in the vertical axis. Moreover, in this menu that pops up, there is the option to open up the graph settings menu. .. figure:: images/user_guide/interface/graph_settings.png :align: center :width: 60 % Inside this menu there are three submenus. The first one, *Measure settings*, is setted automatically by the application based on the current steps the user is in. However, it is still possible to activate or desactivate any of the selected measure to allow a full customisation on how the graph is displayed on each step. The next submenu, *Percentiles*, allow to customise which percentile are calculated and displayed on the graph. By default all the options are selected. Lastly there is the *General Settings* submenu where it is possible to customise if the current time (the clock icon) is shown on the graph, or if the change in covariates is shown on the graph, or if by hovering over the graph a live annotations with information about the current point is shown or not. Hotkeys and Shortcuts ^^^^^^^^^^^^^^^^^^^^^ There is also a set of predefined hotkeys and shortucts available in Tucuxi to show and perform certains actions. Here below it is possible to find a list of the presetted key combination available and what they do inside the application. .. table:: Aviable Hotkeys and Shortcuts :align: center +-------------------+--------------------------------+ |**Key combination**| **Function** | +===================+================================+ | CTRL + SHIFT + F2 |Validate the selected drug | +-------------------+--------------------------------+ | CTRL + SHIFT + T |Show the tooltip | +-------------------+--------------------------------+ | CTRL + SHIFT + O |Go to the load request | +-------------------+--------------------------------+ | CTRL + SHIFT + E |Save the statistics | +-------------------+--------------------------------+ | CTRL + SHIFT + A |Show the population statistics | +-------------------+--------------------------------+ | CTRL + SHIFT + S |Show the a priori statistics | +-------------------+--------------------------------+ | CTRL + SHIFT + D |Show the a posteriori statistics| +-------------------+--------------------------------+ | CTRL + SHIFT + F |Show the adjustement statistics | +-------------------+--------------------------------+ | CTRL + SHIFT + G |Save the graph | +-------------------+--------------------------------+ | CTRL + SHIFT + X |Export the current data | +-------------------+--------------------------------+ | 1 |Change to the Patient tab | +-------------------+--------------------------------+ | 2 |Change to the Drugs tab | +-------------------+--------------------------------+ | 3 |Change to the Dosages tab | +-------------------+--------------------------------+ | 4 |Change to the Covariates tab | +-------------------+--------------------------------+ | 5 |Change to the Measures tab | +-------------------+--------------------------------+ | 6 |Change to the Targets tab | +-------------------+--------------------------------+ | 7 |Change to the Adjustements tab | +-------------------+--------------------------------+ | 8 |Change to the Validation tab | +-------------------+--------------------------------+ | 9 |Change to the Reports tab | +-------------------+--------------------------------+ | 0 |Validate the current tab | +-------------------+--------------------------------+ 1. Patients ------------ In this first step, three sections are shown, to register or/and to display informations about the patient. The **Patient required information** section must be completed in order to register a new patient, requiring to give the patient's first name, last name, birth date and gender. The **Patient extra informations** allows you to add several informations such as the patient's ID, stay number and the patient's complete address. The **Physician in charge** allows you to add all the informations about the physician in charge of the patients. .. figure:: images/user_guide/patients.png :align: center :width: 100 % 2. Drugs --------- In this second step, there are three sections displaying several informations about the drugs provided to the patient for the current analysis treatment. The **Active substance** lists the supported drugs in Tucuxi, also referenced in the "Supported drugs" chapter of this manual. For the registration of a new patient, selecting one of them is necessary to go to the next step. By choosing a drugs, its informations details are shown in two sections below and on the right panel. The **Domain** section indicates informations about the user range of the selected drug. The **Study** section quotes the source study of the selected drug. On the right panel, more detailed informations about the drug is displayed. .. figure:: images/user_guide/drugs.png :align: center :width: 100 % 3. Dosages ----------- This step shows informations about dosages previously given to the patient. On the control panel, the **Dosages history** section displays the list of dosages. Each row indicates the dosage of the drug and the route of administration for that dosage. Adding a dosage prompts a parameters window containing the default parameters for the selected drug. Editing a dosage promts the same windows as the adding function does, but this time the fields contains the values of the dosage that is edited. Steady state constatation is included in the informations to give. Clicking on *Apply* displays the curve corresponding to the value set. Clicking on *Ok* validates the dosage. .. figure:: images/user_guide/control_panel/dosages.png :align: center :width: 100 % On the graph panel, the curve corresponding to each dosage selected, applied or set is displayed and represents the prediction of drug concentration evaluated in the population. .. figure:: images/user_guide/graph_panel/dosages.png :align: center :width: 100 % 4. Covariates -------------- In the **Covariates** step, important variates about the patient must be set here. This variates influence how the concentration of a drug is computed. For each drug subject to the treatment analysis, different covariates are displayed inside the **Drug covariates list**. Every covariate is indicated with the covariate's name, the default value, and the current value of the patient. Selecting a covariate displays the **Patient covariate history** in the section below. Each row of this list indicates the selected covariate's name, the value set, and the date on which it was set. Adding or editing a covariate prompt a window that contains the specific covariate parameters. .. figure:: images/user_guide/control_panel/covariates.png :align: center :width: 100 % On the graph panel, the prediction curve of drug concentration is displayed and represents the result for individuals in the population given the covariates set. .. figure:: images/user_guide/graph_panel/covariates.png :align: center :width: 100 % 5. Measures ------------ In this step, measures of the concentration of drugs in the analized sample are listed with corresponding curves. In the **Measures list** the previous measures done are displayed. Each measure's row indicates the ID of the sample, the concentration value, the sampling date and the sample's date of arrival. Adding or editing a measure prompt a window with those parameters to set. .. figure:: images/user_guide/control_panel/measures.png :align: center :width: 100 % On the graph panel, the result measured is displayed and represents the prediction curve of drug concentration of the patient. .. figure:: images/user_guide/graph_panel/measures.png :align: center :width: 100 % 6. Targets ----------- This step concerns the target given for a patient's case depending on the informations set in previous steps. The **Targets list** displays a default target based on the drug selected for this analysis. Multiple target can be added manually, and for each one of them multiple type (residual, peak, mean, AUC, ...) are available. Moreover, depending on the selected type a list of different paramenter are to be filled in. In the example in the image below, the *Residual* type as been choosen, and it is necessary to fill in the minimal, the best and maxiaml rate for this target type. .. figure:: images/user_guide/control_panel/targets.png :align: center :width: 100 % On the graph panel, the selected target range is shaded on the graph area. Black crosses indicate the ideal value. .. figure:: images/user_guide/graph_panel/targets.png :align: center :width: 100 % 7. Adjustments --------------- In this step, the adjustemet for the dosage given to the patient must be set or selected. Dosages generated with the parameters previously given are suggested in the **Suggested adjustments** section, it is possible to select one of the proposed drug dosage by clicking the check mark on the right of the row. Once an adjustement is selected it will be displayed in the section **Adjustment** below. Morever, it is possible to have Tucuxi try to add a rest period and/or a loading dose. If either or both of this two cases are selected, the application will try to generate them and add them in the Adjustment list. Furthermore, it is also possible to add manually an adjustement or to modify a suggested one that have been selected. This can be used if either the suggested adjustement are not viable options or that the physician want to perform a slight modification to the suggested one. Adding or editing a dose will prompt a windows that allow to set the interval of time in which the drug should be administered, the dosage to give, in which interval of time, and the duration of time in the case of an infusion.Clicking on *Apply* changes the curve displayed on the graph panel and clicking on *Ok* valdiates the parameters. The date and time of the moment when the adjustment need to be done is shown and is editable above the suggested adjustments section. .. figure:: images/user_guide/control_panel/adjustments.png :align: center :width: 100 % On the graph panel, for each suggested dosage adjustment, the expected curve of drug concentration is displayed in yellow, following the existing curve of the current treatment analysis. The curve of the selected suggestion adjustment is shown thicker and the expected curve of the loading dose of the manual adjustment set is shown in a thin black curve. .. figure:: images/user_guide/graph_panel/adjustments.png :align: center :width: 100 % 8. Validation -------------- In this step, detailed informations are displayed with the final dosage. Comments on the treatment can be added and validated to end the analysis. In the **Parameters** section, the parameters that the computation have used are shown. In this list the name of the Pk parameter is shown with the respective typical patient value, the A priori value and A posteriori value. In the **Validation** section, final dosage(s) chosen during the Adjustment step are displayed. The date and time of the next control can be specified. Some comments on the expectedness, suitabiliy, prediction, remonitoring, and warning can be added by filling the empty fields. Selecting *Validate* ends the treatment analysis. .. figure:: images/user_guide/control_panel/validation.png :align: center :width: 60 % Morevoer, in the **Validation** section by clicking on the palette icon, it is possible to open up a menu for every section. In this menu, it is possible to define some global or drug specific phrases in order to simplify and speed up the completion process. Furthermore, when you add a new sentence, it is possible to define a specific shortcut that will allow the completion of the section text by simply pressing the predefined key combination. .. figure:: images/user_guide/interface/validation_shortcuts.png :align: center :width: 100 % On the graph panel, every curve generated in the previous steps are shown. .. figure:: images/user_guide/graph_panel/validation.png :align: center :width: 100 % 9. Reports ----------- This last step shows the report generated for the analyzed treatment. In the left section it is possible to see a preview of the final report that contains all the informations that were used in this analysis like the patient's current informations and covariates. Informations about the sample such as the ID sample, the sampling date and the measured rate are shown. The graph generated during the treatment analysis is also displayed, illustrating the previous and future concentration profile. The final dosage proposed, and the date of the next control is also shown on the bottom of the report. A report in pdf format can be saved by clicking on the button below the report. .. figure:: images/user_guide/control_panel/report.png :align: center :width: 80 % On the graph panel, every curve showing the informations about the treatment analyzed is displayed. .. figure:: images/user_guide/graph_panel/report.png :align: center :width: 100 %