====== Create a sample for a person ======

A sample is a compressed file of the .tgz (.tar.gzip) format, containing a number of metaphase images from the person. It is the basic unit for estimating the radiation dose that the person was exposed to. To create a sample, click the ‘New samples’ menu item within the ‘Sample sets’ menu.

===== Prepare =====

{{ file:bgq:create_a_sample_prepare.png?nolink }}

<WRAP group>
<WRAP half column>
First, you need to upload the metaphase images of the person to the BGQ server, which can be accomplished by the bottom area of the right panel. In this area, the left part displays the contents on the disk drives of the local computer you are using; the right part displays the contents in your account on the BGQ server. In the left part, select the metaphase images or the directory containing them; in the right part, select the destination directory on the BGQ server. The default, recommended destination directory is 'MetaphaseImages', as shown in the above figure, which is automatically selected and expanded. Then click the ‘Upload’ button in the middle. If the upload takes some time, a progress dialog will pop up. It displays the current uploading percentage in a progress bar and the name of the file being uploaded.
</WRAP>
<WRAP half column>
{{ file:bgq:upload.png?nolink }}
</WRAP>
</WRAP>
In the right part, you can also create a new directory, rename and delete a directory/file on the BGQ server by right-clicking on the item. You can upload multiple files and directories at one time. The metaphase images of each person should be uploaded to a separate destination directory; for example, Persons ‘S01’ and ‘S02’ will correspond to two directories on the BGQ server named ‘S01’ and ‘S02’. And the directory should only contain the images.

After uploading the metaphase images, you can create samples using the top area of the right panel.  You can create multiple samples at one time. Click the ‘Select’ button within the row containing the ‘Source’ label. In the directory chooser that pops up, select one or more directories to which the images were uploaded on the BGQ server, and click the ‘OK’ button.

{{ file:bgq:remote_directory_chooser.png?nolink }}

Then the paths of all selected directories will be displayed in the drop-down list. For the source directory currently being selected in the drop-down list, the other components in the top area of the right panel provide the following associated information:
  * ‘Name’ text field: the name of the newly created sample. It is prepopulated with the name of the directory.
  * ‘Description’ text area: providing a number of description entries for the sample. It is prepopulated with common entries, including ‘Coordinate of the person’ and ‘Exposed physical dose’. You can add or remove any description entry. 
  * ‘Apply to all’ checkbox: If checked, the current content in the ‘Description’ text area will be applied to all samples; in other words, all samples will have the same descriptions.
  * ‘Metaphase images included’ list: It is automatically populated with the names of all *.tif images in the directory and the image count.

You can select another directory in the drop-down list, then the ‘Name’ text field, ‘Description’ text area and ‘Metaphase images included’ list will be updated accordingly. After you finish editing ‘Name’ or ‘Description’ for one sample, its content will be automatically saved. You can also click the ‘Clear’ button to clear the contents in all of the components. Each sample must have a name, but may not have any description.

Then select a destination directory into which the created samples will be put by clicking the 'Select' button. This directory is also the directory from which you will create a sample set (see the next section). In the directory chooser dialog that pops up, the default directory 'SampleSets' is automatically selected and expanded. It is recommended that you right click on it, then create a new subdirectory as the destination directory.

{{ file:bgq:remote_directory_chooser_new_samples_desti.png?nolink }}

===== Download metaphase images from an external computer =====

<WRAP group>
<WRAP half column>
It is very likely that metaphase images are produced by microscope devices of a remote laboratory, thus initially stored on a remote computer of the laboratory. In this case, the images need to be first downloaded to the local computer that you are using, which can also be accomplished by the bottom area of the right panel. In the drop-down list in the right part of the panel, select the item 'Connect to another computer'. In the popped-up dialog, enter the IP address or host name of the remote computer from which you want to download metaphase images, the port number, the user name of an account on that computer and the corresponding password. The remote computer you want to connect to must be running an SSH server.

The following figure shows that after successfully connecting to the remote computer, its name will be filled into the drop-down list and selected. For privacy, the right tree will only show the contents in one directory on the remote computer, which is the 'Biodosimetry' subdirectory under the default directory (on the Windows operating system, the default directory is (System drive):/Users/(User name)). Therefore, in order to be able to see the metaphase image files, they need to be first placed under the 'Biodosimetry' subdirectory on the remote computer.
</WRAP>
<WRAP half column>
{{ file:bgq:connect_to_remote_computer.png?nolink }}
</WRAP>
</WRAP>

{{ file:bgq:remote_computer.png?nolink }}

===== Monitor progress =====

After finishing entering these preparation information, the process of creating samples from the source directories can be started by clicking the ‘Create’ button. If a source directory contains other files besides the *.tif images, those files will be first deleted. Then a progress dialog will pop up.

<WRAP group>
<WRAP half column>
In the top grouping box of this progress dialog, the progress bar displays the percentage progress of creating the sample currently being selected in the drop-down list. The components n the middle grouping box display the following information:
  * ‘Completed samples’ label: displays the number of samples that have finished creating to date / the total number of samples.
  * ‘Elapsed time’ label: displays how long this sample creation process has been running for.
  * Progress bar: displays the overall percentage progress of creating all samples.

The text area displays real-time feedback messages during the creation process, and will show a summary message after the process terminates.

You can also cancel the creation process by clicking the ‘Cancel’ button. Then an inquiry dialog will pop up to ask whether you want to keep the already created samples; if you click the ‘No’ button, these completed samples will also be deleted from the BGQ server, apart from terminating the creation process of the remaining samples.
</WRAP>
<WRAP half column>
{{ file:bgq:create_a_sample_progress.png?nolink }}
</WRAP>
</WRAP>