Managing Projects

The main organizational tool in IRIDA is the project. This section of the user guide descibes how you can view projects, edit project metadata (including uploading reference files), search for projects by name, and create new projects.

Viewing existing projects

You can access the list of projects that you have permission to view and modify by clicking on the “Projects” menu at the top of the dashboard and selecting “Your Projects”:

Your projects dashboard location.

The projects list shows all projects that you are permitted to view or modify:

List of projects.

The projects list provides a high-level overview of project details, including:

To enter into a project click the Name of the project:

Project name button.

Searching the Projects Table

There are two ways to find a specific project in the projects table - filtering and searching.

Searching

Project search entry.

Search is always available in the text field directly above and to the right of the table. This search across the project’s id, name, and organism.

Example searching the projects table for O157 results in 2 items.

Projects search by out

Creating a new project

You can create a new project by clicking on the “Projects” menu at the top of the dashboard and selecting “Create New Project”:

Create new project dashboard location.

When you create a new project, you’ll need to provide a project name, and can optionally provide a project organism, a free-form project description, and a link to another web site that has more inforamtion about the project:

Create new project form.

A project name must be at least 5 characters long, and must not contain any of the following characters: ? ( ) [ ] / \ = + < > : ; " , * ^ | &

If you choose to set a project organism, click on the “Select an Organism” drop-down menu and begin typing the name of the organism. For example, if you wanted to specify a project organism of “Salmonella enterica”, you would begin to type “Sal” and the menu would allow you to choose from a set of well-defined organism names:

Project organism entry.

The organism names are derived from the NCBI taxonomy database.

To lock sample modification in the new project, check the “Lock sample modification” box. This setting will only allow the sample owner to edit any sample data.

To enable automated assemblies for the project, check the “Automatically assemble data uploaded to project” box. This setting will perform an assembly on all sequence files uploaded to this project. For more information about automated assemblies see the samples documentation.

When you’ve finished entering the details for your new project, click on the “Create Project” button. You will be redirected to the projects list.

IRIDA will automatically generate a numeric project identifier for your project. The project identifier is used by external tools for uploading sequencing data to IRIDA. The project identifier can be found in the “Project Details” panel, or in the projects list.

Creating a project from cart

You can create a project with samples already added to the project by using the cart. Continue creating the project details as described above, but select the checkbox Add samples in cart to project. If this checkbox is enabled any samples in the cart will be automatically added to this project. If there are any samples which you cannot add to the project, a warning will be displayed below.

Create project cart warning

Viewing project samples

The project samples page provides a view of the samples that belong to the project. To view the samples for a project, click on the Samples tab on the project page:

Project samples tab.

You can find out more about managing samples in a project by navigating to the managing samples section.

Project samples panel.

Project analysis results

To view the results of an analysis that has been shared with a project, click the Analysis tab at the top of the project page.

From this page you can view and monitor the progress of all analyses which have been shared with this project. To view the results of an analysis click on the analysis name. For more information on analysis results, see the pipeline documentation page.

If there are shared single sample analysis output files, you will see them in the Shared Single Sample Analysis Outputs tab:

If there are automated single sample analysis output files, you will see them in the Automated Single Sample Analysis Outputs tab:

There are no automated analysis output files for this project test1.

From these tables you can select which files you wish to download by filtering based on values in certain columns (e.g. contigs in the File column), clicking on the rows for the files you wish to download while holding the Ctrl or Shift buttons, and clicking the Download button to download your selected files.

For more information on using the single analysis output file tables, see the pipeline documentation page.

Project details

To view project details, click the Details tab on the project page:

Project details tab

This view will display basic information about the project such as:

Project details view

To edit project details, from the project details page click on the “Edit” button:

Project metadata edit button.

The project details editing page provides the same form as when you created the project, and all of the same descriptions apply. When you’ve finished editing the project details, you can click on the “Update” button at the bottom of the form.

Project NCBI Exports

To view exports from this project to NCBI, click on the NCBI Exports tab.

Project exports tab

For more information on exporting to NCBI, see the documentation on the samples page.

Viewing recent project activity

Project data and metadata is changed over time. You can see a list of recent changes that have taken place by viewing the recent activity for a project.

Starting from viewing project details, you can view recent project activity by clicking on the “Recent Activity” tab at the top of the projects page:

Project recent activities tab.

Recent activities include adding or modifying project members and adding new samples to a project:

Project recent activities.

Managing project settings

If you are a manager on a project you can manage settings on individual projects. These settings can be found in the Settings tab at the top of the project page.

Project settings tab.

Processing

Project processing settings can be found in the Processing tab in the project settings page.

Processing tab

Automated pipelines

A project can be setup to automatically trigger the execution of a pipeline on upload of new data. The two pipelines available to be triggered are the Assembly pipeline (for bacterial genomes) and the SISTR pipeline (for typing of Salmonella genomes). This setting is enabled on a project-by-project basis and must be enabled by a project manager.

To enable an automated pipeline, check the Automatically assemble data uploaded to project or Automatically type data uploaded to the project with SISTR boxes. Any new data uploaded to the project will now trigger the execution of the selected pipelines.

Automated pipelines check

Project coverage

IRIDA can calculate the coverage of uploaded sequencing data for a sample. To enable this a genome size and expected coverage must be set for a project in the project settings page.

To edit coverage settings, click the Edit button.

Coverage Edit Button

You can then enter your coverage settings and click Update.

Coverage Update

When these options are set IRIDA will flag any samples which do not meet the expected coverage requirement in the project/samples list. It will also display the coverage for a sample when you view sequence files for a sample.

Project members

Project member settings can be found in the Members tab in the project settings page.

Project details members tab.

Project members are users who have permissions to view or edit project metadata. Project members can also view, download, and submit pipelines using sequencing data that’s contained in a project. Project members can have two different roles: a project collaborator (read-only permissions), and a project manager (read and modify permissions). A user must be a Manager on a project to add or remove members.

A project Collaborator will only be able to view the project members:

Project members (as a collaborator).

A project Manager will be able to modify the project members:

Project members (as a manager).

Similar to project members, user groups can also be added to projects to manage collections of users.

Project details groups tab.

Adding a project member

Adding an individual project member

To add an individual project member, click on the “Add Member” button:

Add project member button.

You can use the dialog that appears to select a user account, and choose the Project Role that the new member should have:

Add project member dialog.

Remember: a project collaborator has read-only permissions, and a project manager is allowed to modify project details.

Once you’ve selected the user and role to add to the project, click on the “OK” button.

Adding a group project member

To add a group to the project, click on the “Groups” button on the left-side of the page, then click on “Add Group”:

Add project group member button.

You can use the dialog that appears to select a user group, and choose the Project Role that the new group member should have:

Add project group member dialog.

Remember: a project collaborator has read-only permissions, and a project manager is allowed to modify project details. When adding a user group, all members of the user group will have that project role on this project.

Note: If a user is added both as an individual member and as part of a group, the individual user project role takes precedence over the group project role. For example, if Bob is added to Project 5 as a Project Owner as an individual member, and is in a Group that’s on Project 5 as a Project Member, Bob would be given Project Owner permissions to Project 5.

Once you’ve selected the user group and role to add to the project, click on the “OK” button.

Changing a project member role

You may want to change a project member role if you wish to remove permissions for an individual user account to modify project details, but still want to allow that user account to view the project data. You can only change a project member role if you have the Manager role on the project.

Start by viewing the project members.

To change the role of a project member, click on the role drop-down menu of the user that you would like to change:

Edit project role button.

The project role is saved as soon as you make a selection – you do not need to click a “Save” button.

Removing a user from a project

You may want to completely remove all permissions for a user to access data in a project. To remove those permissions, you must remove the user account from the project members list.

Start by viewing the project members.

To remove a project member, click on the remove button on the right-hand side of the table:

Remove project member button.

When you click the remove button, you will be asked to confirm the project member removal:

Remove project member confirmation dialog.

To confirm, click the “Ok” button.

Associated Projects

Associated projects can be used to help manage related sample data across multiple projects. Samples from associated projects can be viewed seamlessly with samples from the local project and used together in analysis pipelines.

To view associated projects click the Associated Projects tab in the project settings page.

Associated projects tab

Viewing associated projects

The “Associated Projects” list will display the projects associated with this project. Projects in this view will be available in the “Associated Projects” view on the project samples listing.

Associated projects list

Adding or removing associated projects

Project Managers can add or remove associated projects for a project. From the “Associated Projects” page, click the “Edit” button.

Note: To add or remove a project to the list of associated projects, the manager must at least be able to read the data in the project to be added in the associated projects list.

You will be presented with a list of all projects you have access to in the local installation. To add or remove an associated project, click the “On/Off” switch.

Edit local associated projects

Reference files

Reference files are required by at least one of the workflows that are installed in IRIDA by default. Reference files are stored on a project-by-project basis.

You can view or add reference files by clicking on the “Reference Files” tab in the project settings page.

Project details reference files tab.

You can upload a new reference file to the project by clicking on the “Upload Reference File” button:

Upload reference file button.

Reference files must be in fasta format. Files containing ambiguous base calls will be rejected.

Once you’ve uploaded a reference file, you can optionally download the reference file (useful if someone else uploaded the reference file for the project) by clicking on the Download icon. download icon in the list of reference files.

Remote project settings

Settings for remote synchronized projects can also be managed from the project settings page. Note: these settings will only appear for synchronized projects, and will be available within the ‘Remote’ menu item.

Remote Project Settings

Synchronizing a remote project

IRIDA allows you to synchronize projects between different IRIDA installations. A remote project appears similar to a local project, but users are not allowed to add samples or sequencing data to a remote project. Instead all data associated with a remote project will be pulled from a remote IRIDA instance on a regular schedule. The only data that can be managed for a remote project is the members that are allowed to view the project and associated sample data.

Connecting to a remote instance of IRIDA

Before a remote project can be synchronized a connection must be set up between the IRIDA project host installation and the receiving IRIDA installation. The connection between installations is handled by the IRIDA client and the remote instance of IRIDA.

First the IRIDA installation hosting the project must create a client which will be used to connect to the remote instance of IRIDA. The client must be created with a grant type of authorization_code and scope of read. It is also recommended to enable refresh tokens for clients which will be involved in project synchronization. Documentation on creating system clients can be found in the administrator guide’s managing system clients section and it must be performed by a system administrator.

Next the receiving IRIDA installation must set up a remote connection to the hosting IRIDA site. Information on adding a remote instance of IRIDA connection can be found in the administrator guide’s adding a remote connections section and must also be perfomed by an administrator.

Creating a remote synchronized project

Once the client and remote instance of IRIDA have been created a user can create a synchronized project. Note that in order to synchronize a remote project, a user must have login credentials to the host IRIDA installation and be a project member on the project they wish to synchronize.

To begin creating a synchronized project, click the Synchronize Remote Project option in the Projects menu.

Synchronize menu option

Once on the Synchronize New Remote Project page, you must select the required remote instance of IRIDA and verify your connection status. If you don’t have a valid connection to the remote instance, you must click the Connect button and follow the instructions to connect in order to proceed. For more information on connecting to remote instance of IRIDA see the remote instance of IRIDA documentation.

Synchronize api connect

Once you have connected to the remote instance of IRIDA, you can select the project you wish to synchronize from the Project dropdown. Here you wil be given a listing of all the projects you have access to on the remote IRIDA installation.

After you have selected your project, you can select a synchronization frequency. You should select a frequency that matches how often data will be added to the project. This option can be updated later in the project settings panel.

Synchronize details

The advanced section allows you to manually paste in an IRIDA project’s REST URL rather than selecting it from the projects dropdown. This option should only be used by advanced IRIDA users.

Once your project and an appropriate synchronization frequency have been selected, click the Synchronize Project button to create your project.

After the synchronized project has been created, you can view it’s synchronization status at the top of the project’s landing page.

Synchronization status

The status section will be one of the following messages:

Deleting a project

Projects can be deleted from the Delete Project tab in the settings panel.

Delete project tab

To delete a project, first read and understand the warning on the deletion page. Deleting a project is a permanent action! Deleted projects and samples may not be able to be recovered. If you are sure you want to delete the project, check the confirmation box, then click Delete Project. Once the project has been successfully deleted you will be redirected to your list of projects.

Delete project

Previous: Managing user groupsNext: Managing samples