PEN Quick Start Guide

This is the quick start guide for the Project Explorer for NEES (PEN). The application images shown and descriptions of functionality described in this guide are for PEN versions 1.4 and higher.

To see what changes and enhancements have been implemented in the latest version of PEN, please check the Release Notes.

Please enter all tickets, questions, and wishes associated with PEN on the PEN home page.

Launching PEN

PEN can be run as either a local executable (by downloading the application file from the tool page) or from within the hub (by clicking the “Launch Tool” button on the tool page). If you run PEN as a desktop executable, it will connect to your local computer. If you launch PEN from within the hub, it will connect to your personal workspace. If the files you wish to upload are on your local computer, you should launch PEN as a desktop executable. If the files you wish to upload reside in your personal workspace on NEEShub, you should launch PEN from within the hub.

If you run PEN as a local executable, a folder named “pen” will be placed on your desktop the first time the application is launched. This folder contains the .jar files that the program needs to run. Should you accidentally (or intentionally) delete this folder, do not panic. PEN will recreate this folder the next time it is launched.

When you launch PEN, the application will present two panes (Figure 1). The left pane is the local directory tree. Initially, this pane is empty. Once you have connected to a project, this pane will contain the directory structure of the project from the Project Warehouse. The right pane initially shows the login screen. Once you have connected to a project, the right pane will have two other tabs (“Info” and “File Import”) that will be used to prepare data for upload.

Figure 1: Initial launch screen

Logging in to PEN

Step 1: Create an empty directory somewhere on your computer. This is the local directory to which PEN will connect. PEN will download the project warehouse directory structure and files for your project to this local directory. This directory is permanently linked to the project to which it is first connected. The next time you open this directory in PEN, PEN will automatically connect to the associated project. Therefore, it is necessary that each project you work on have its own directory.

Step 2: Gather the following three pieces of information that you will need to connect to a project via PEN:

(1) Your NEEShub login and password. This is the same login and password that you use to login to the NEEShub website.

(2) The location of your local directory. This is the directory you created in Step 1.

(3) Your project number. If you do not know your project number, you have two options. You can locate and select your project from the list of available projects during the login process (Figure 2) or you can locate your project number on your project page in the Project Warehouse (Figure 3).

Figure 2: List of available projects shown during the login process

Figure 3: Locating a project number in the Project Warehouse

Step 3: Follow these sequential steps to login to PEN

a. Enter your NEEShub username and password and click the “Login” button (Figure 4)
b. Locate your project in the list of available projects or manually enter your project number (Figure 5)
c. Click the “Change” button and enter or browse to your local directory (Figure 5)
d. Click the “Open” button (Figure 5)

Figure 4: Entering your NEEShub username and password

Figure 5: Entering your project number and your local directory

At this point PEN will begin connecting to the project and downloading the project directory structure and metadata. When the connection process is complete (Figure 6), a local copy of the project’s warehouse directory structure will now exist on your hard drive in the folder that you created in step 1. This copy of the project’s directory structure will persist even after PEN has been closed. This allows you to add files, create directories, etc. while offline. These files and directories will then be available for upload the next time you launch PEN.

Figure 6: PEN connected to a project

If you close PEN without logging out, PEN will automatically log back into the NEEShub account and project that was open when the application was closed the next time that the application is launched.

You can access any public project through PEN regardless of whether or not you are a member of that project. However, if you do not have the appropriate permission settings, you will not be able to upload files or edit the file information. If you have trouble uploading files or changing file information when working in PEN, the first thing to check is your permission settings in the Project Warehouse.

Editing Preferences

You may have noticed during the login process that PEN tried to populate a default location for your local directory. This default location can be changed through the Tools > Preferences menu (Figure 7). Some other options that can be modified in this menu include the automatic checksum and the failed upload recovery.

Figure 7: PEN Preferences Dialog Box

The checksum is what PEN uses to determine whether your local file matches the file on the NEEShub. If you upload files without checksumming them, they will turn red instead of black. However, checksumming very large files can take some time; you may want to turn this option off if you are uploading large files and you notice that the checksum is significantly slowing down the process. If you choose not to automatically checksum a file, you can always checksum it at a later time by right-clicking on the file name in the left panel and selecting “checksum” from the menu.

Downloading Files

If you expand the directory structure in the left panel, you will see the project directories and any files that you uploaded to the project via the Project Editor (Figure 8).

You may notice that your files appear in grey. PEN uses the following color codes:

Grey

The file exists on the NEEShub but not locally

Blue

The file exists locally but not on the NEEShub

Black

The file exits locally and on the NEEShub, and the files are the same

Red

The file exists locally and on the NEEShub, but the files may not be the same

If you forget what the color codes mean, there is a dialog box within PEN (Help > Color Legend) that lists the colors and their meanings.

Figure 8: Expanded directory structure with previously uploaded files in grey

Right click on a grey file in the left panel and select “Download” to download it to your computer (Figure 9). Once the file is downloaded, the file will turn black in the project editor, indicating that the file now resides both locally and on the NEEShub. The file that you downloaded was placed in its appropriate sub directory within the local directory specified during the log in process (the directory created in Step 1 of the logging in process).

You can download multiple files within the same directory by performing the download at the directory level.PEN will recursively download all the files with the object you select for download.

You can also download files at the project level. Be careful not to attempt to download the full project of a large project because that could take awhile.

Figure 9: Download Options

Creating an Experiment/Trial/Repetition

You can create experiments, trials, and repetitions in PEN. PEN has context sensitive menus, meaning that the application knows what actions are appropriate for each level of the project. When you right click on the project, you have the option to create a new experiment; when you right click on an experiment, you have the option to create a new trial; and when you right click on a trial, you have the option to create a new repetition (Figure 10).

Figure 10: Creating an Experiment/Trial/Repetition

All new experiments, trials, and repetitions that you create in PEN will be created locally. You will notice that they are color-coded blue (Figure 11). Before you can view these new experiments/trials/repetitions in the Project Warehouse, you will first need to upload them.

Figure 11: New experiment shown in blue

Importing Files

There are two ways to import data into your project. Locate the files you want to import using the “file import” tab in the right pane. Select the files you want to import. You can either drag the selected files to their desired location in the left panel and drop them there or you can highlight the target folder in the left panel and use the “Import Selected Files” button to copy the files to the desired location (Figure 12). Imported files will appear in blue and need to be uploaded before they can be viewed in the Project Warehouse.

Figure 12: Importing data files

Editing Directory/File Information

For experiments, trials, and repetitions, you can edit basic information such as the title, description, start date, and end date by clicking on the “Info” tab in the right panel (Figure 13). Be sure to click the “Save” button when you are done or your edits will be lost. If you are editing information on a file or directory that already exists in the warehouse, there is no need to re-upload that file or directory. When you click the save button, your changes will automatically take place in the project warehouse.

Figure 13: Editing directory information

For photos and drawings, you can not only edit basic information such as the title and description, you can also designate the image as a “film strip” image (Figure 14).

Figure 14: Editing image information

For data files, you can make tool associations in addition to editing the title and description of the file (Figure 15).

Figure 15: Editing data file information

For all other file types, you can only edit basic information such as the title and description (Figure 16). For more advanced editing, you will need to use the Project Editor.

Figure 16: Editing basic file information

Uploading Files

When uploading files, you have to perform the upload at the highest level. For example, you cannot upload an imported data file if the experiment into which it was imported has not been uploaded. If you right click on a file that is not eligible for upload, the upload option will not appear in the menu (Figure 17).

Figure 17: You cannot upload a file if the directories above it have not already been uploaded

In the figure above, the upload needs to be performed at the experiment level (Figure 18). This will upload the entire experiment, including all of its directories an imported files.

Figure 18: Experiment upload

If you perform an upload on a directory that already exists in the Project Warehouse, only the local (blue) files within that directory will be uploaded to the Project Warehouse (Figure 19).

Figure 19: Directory-level upload

After the upload is complete, the uploaded files in the left panel should change colors from blue to black. If your files turn red instead of black, check the Tools > Preferences menu to make sure that a checksum is being performed prior to upload. Checksums can take a long time to perform if your files are large, so you may want to turn this option off if you have large data files. You can checksum individual files by right clicking on the file and choosing “Checksum File.” You can checksum an entire directory of files by right clicking on the directory and choosing “Checksum Files.” If you checksum a file and it does not turn black, that indicates that the local file does not match the file located on the NEEShub. If there is no reason why your files should not match or if you are absolutely certain that your local file is the correct file, you can delete the erroneous file from the warehouse (right click on the file and select “Delete from Warehouse) and upload the correct file in its place.

Creating Specimens

You can add your materials to your Experiment by creating a specimen. Right click on an experiment in the left panel and select “Create Specimen” (Figure 20). This will create a Specimen_1, Component_1, and Material_1.

Figure 20: Creating a Specimen

To edit the material, click on Material_1 in the left panel and use the “Info” tab in the right panel to add a material of your choosing (Figure 21). Be sure to click the “Save” button when you are done. You can create additional materials by right clicking on the component in the left panel and choosing “Create Material.”

Figure 21: Editing a Material

Specimens and materials created in PEN are created locally and need to be uploaded before they can be viewed in the Project Warehouse.

Deleting Files

You can delete both local (blue) files and files that reside in the Project Warehouse (black files). To delete a file, right click on the file and select “Delete Local” or “Delete from Warehouse” (Figure 22). When you delete the local copy of a file that only exists locally (the filename is blue), the file will be deleted from your local directory. When you delete the local copy of a file that resides in the warehouse, the filename in the left panel will turn grey, indicating that although the local copy of the file is gone, the file still exists in the Project Warehouse. When you delete a file from the Project Warehouse that does not reside locally (the filename is grey), the file will be removed from the project. You can delete directories from the Project Warehouse, but you must first delete all of the files from the directory (just like in the Project Editor). If a directory contains files, the delete option will not appear in the right-click menu for that directory.

Figure 22: Deleting a File

Asynchronous Changes

If you make asynchronous changes to your local directory (e.g., copying files into your local directory through Windows Explorer instead of PEN), you must “refresh” the project see these changes (Figure 23).

Figure 23: Refreshing PEN

Logging Out of PEN

If you shut down PEN without logging out, it will automatically log you back in and reconnect to your project the next time you launch the application. You can logout and exit through the File menu (File > Logout & Exit). If you want to logout and close your project without exiting PEN, you can use the button next to your username in the right panel (Figure 24). If you want to close your project without logging out, you can use the red “x” button in the upper right corner (Figure 24). Closing the project without logging out will return you to the second screen of the login process (Figure 5).

Figure 24: Closing the Project

Created on 08 Nov 2011, Last modified on 19 Jan 2012