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 “Your Projects”.

your-projects

From the projects listing page click the “Create New Project” button:

create-new-project

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 website that has more information 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.

Clicking the “Next” button allows you to select samples that have been added to your cart and add them to the project.

If there are no samples currently in the cart a message will be displayed:

Samples

When samples are in the cart, only samples that you have full permissions on can be added to a new project.

Samples

To prevent samples from being modified or copied within the new project, check the “Prevent modification and copying of these samples” box. This setting will only allow the sample owner to edit any sample data.

Clicking the “Next” button allows you to set metadata field restrictions that are available from the samples that are added from the cart. The Current Restriction is the metadata restriction on the field from the project that it was added from. The Target Restriction is the metadata restriction to apply to the field in the new project.

Metadata Restrictions

If there are no samples currently in the cart or if there are and they weren’t selected to be added to the new project then you should see the following message displayed:

Metadata Restrictions

Once you’ve finished entering the details, selecting any samples from the cart, and setting the metadata restrictions (if available) 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.

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 Proj1.

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) using the search box, selecting the checkboxes for the files you wish to download, 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 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.

By default, the 10 most recent activities wil be displayed. Clicking the “Load More” button will load 10 more activties until all the activities are loaded.

Managing project settings

Project managers can manage settings on individual projects. These settings are found in the Settings tab at the top of the project page.

Project settings tab.

Project Details

Project details include:

Project settings detail layout.

Managers can edit the modifiable fields by clicking on the edit (pencil) icon within the field. Updates will be saved immediately after hitting the enter key or clicking anywhere outside the field. If you want to cancel the update, just press the esc key and the original value will be displayed.

Coverage, Processing and Automated Pipelines

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

Processing tab

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.

Coverage

To edit coverage settings, click the Edit button.

Coverage Edit Button

You can then enter your coverage settings and click Ok.

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.

Automated Pipelines

A project can be setup to automatically trigger the execution of a pipeline on upload of new data. Any installed pipeline that analyzes individual sample files may be launched on upload (including plugin pipelines). This setting is enabled on a project-by-project basis and must be enabled by a project manager.

To set up a new automated pipeline, click the Add Automated Pipeline button on the processing page.

Automated pipelines check

After clicking the Add Automated Pipeline button you’ll be brought to the pipeline list page similar to launching a regular pipeline with data in your cart. From here you can follow the same process for launching a pipeline including selecting the pipeline, customizing parameters, sharing results, etc. See more about this process in the pipelines documentation.

When you have successfully set up your automated analysis pipeline, you’ll be returned to the project settings processing page. Any new data uploaded to the project will now trigger the execution of the selected pipelines.

Automated pipelines check

To remove an automated pipeline, click the X button to the right of the pipeline description and confirm. Automated pipelines can only be removed by a project manager.

Note that automated pipeline parameters cannot currently be modified after the pipeline has been created. To modify the parameters for an automated pipeline, you should remove the original automated pipeline and create a new one with the new desired parameters.

Administrators can change the priority of automated pipelines for a given project. The default setting for a project is “LOW”.

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 project roles: a project collaborator (read-only permissions), and a project manager (read and modify permissions). Project members also have a metadata role (Level 1, Level 2, Level 3, Level 4). Level 4 is the highest metadata role for a project. A Manager has a metadata role of Level 4 and this cannot be changed. Project collaborators can have one of the metadata roles assigned to them. A user must be a Manager on a project to add or remove members, modify project roles, and/or modify metadata roles.

A project Collaborator will only be able to view the project members and their project roles on the project. A collaborator can not view the metadata roles assigned to the project members:

Project members (as a collaborator).

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

Project members (as a manager).

Project user groups

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. You can also select the Project Role and Metadata Role that the new member should have. If the Project Role is set to Manager then the Metadata Role will default to the highest level (Level 4):

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. You can also select the Project Role and Metadata Role that the user group should have. If the Project Role is set to Manager then the Metadata Role will default to the highest level (Level 4):

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 and metadata role on this project. If the Project Role is set to Manager then the Metadata Role will default to the highest level (Level 4).

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

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

Changing a project member’s project role

You may want to change a project member’s project 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 project 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 project role drop-down menu of the user that you would like to change:

Edit project member project role.

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

Changing a project member’s metadata role

You may want to change a project member’s metadata role if you wish to restrict an individual user from viewing certain metadata on the project. You can only change a project member’s metadata role if you have the Manager role on the project and the member is also not a Manager on the project.

Start by viewing the project members.

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

Edit project member metadata role.

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

Changing a project user group’s project role

You may want to change a project user group’s project role if you wish to remove permissions for members of a user group to modify project details, but still want to allow that user group to view the project data. You can only change a project user group’s project role if you have the Manager role on the project.

Start by viewing the project user groups.

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

Edit project user group project role.

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

Changing a project user group’s metadata role

You may want to change a project user group’s metadata role if you wish to restrict the members of the group from viewing certain metadata on the project. You can only change a project user group’s metadata role if you have the Manager role on the project and the user group is also not a Manager on the project.

Start by viewing the project user groups.

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

Edit project user group metadata role.

The metadata 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.

Removing a user group from a project

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

Start by viewing the project user groups.

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

Remove project user group button.

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

Remove project user group confirmation dialog.

To confirm, click the “Ok” button.

Metadata

Metadata associated with the project can be viewed from the Metadata tab. A project Manager can view all the metadata fields associated with the project, and view/modify the metadata restriction levels for each of these fields.

Metadata fields manager view

The Manager also has the ability to select metadata fields, create templates, and set a default template which members of the project can use to view data on the Linelist page.

Metadata templates manager view

Clicking on the name of the template takes you to a page where you can modify template details. Note that the field restriction levels must be modified from the Fields tab and cannot be modified within a template.

Metadata template fields manager view

A collaborator can only view a subset of the metadata fields which are at their metadata restriction level and below. For example the user below has a project metadata role of Level 2, so they can only view metadata fields which have a restriction Level 1 or Level 2:

Metadata fields collaborator view

A project collaborator can only view/download the templates that exist and the fields that makes up those templates:

Metadata templates  collaborator view

Clicking on the name of the template takes you to a page where you can view template details.

Metadata template fields collaborator view

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

This is how the table will look for a Collaborator on the project

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. When going to the associated projects tab, managers will see the currently associated projects selected, as well as all projects they have access to. Using the toggle

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.

Adding or removing an associated project can be accomplished by clicking on the toggle box in the first column of the table. If the toggle is “On” (blue) then the project is associated.

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 or by dragging and dropping files onto it:

Upload reference file button.

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

Reference file invalid.

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 data associated with a remote project will be updated 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.

The following data will be synchronized:

The following data will not be synchronized:

Some of the above items that are not currently synchronized are expected to be available in future IRIDA versions.

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

If you know the URL of the project you want to synchronize, you can directly add the url by checking the Set URL Manually and entering it into the input field.

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:

Reconnecting after token expiry

Occasionally the token used for synchronizing a remote project may expire at which point the project will need to be reconnected. When this token expires, the synchronization user for the project (usually the person who created the project) will receive an email notifying them that the connection has expired and they must reconnect.

To re-connect after an expired token:

Delete project

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