Introduction
In the last decade, advances in flow cytometry instrumentation and reagent technologies have enabled simultaneous single-cell measurement of surface and intracellular markers, including cellular activation markers, intracellular cytokines, immunological signaling, and cytoplasmic and nuclear cell cycle and transcription factors, thus positioning cytometry to play an even larger role in health care and medical research. However, the rapid expansion of flow cytometry applications has outpaced the development of tools for storage, analysis, and data representation (Bocsi and Tárnok, 2008; Bashashati and Brinkman, 2009; Lugli et al., 2010). In addition, datasets are usually not stored with an explicit link to experimental metadata, such as data analysis procedures, experimental conditions used, or information about the samples processed. This link between data and metadata is crucial, as it facilitates better understanding of analysis approaches and reproducible research. When datasets are linked to figures and summaries through a detailed explanation of the sample processing and analysis pipeline, other scientists can increase the amount of detailed analysis that can be conducted on already collected data, re-examine and expand on biological results, and better reproduce and understand published findings.
We developed FlowRepository.org, a public flow cytometry data repository, to address this shortcoming by facilitating the integrated review of datasets referenced in published literature with its associated metadata. Through FlowRepository, users can access, review, download, deposit, annotate, share, and analyze flow cytometry datasets. Since proper annotation is key to third-party interpretation, FlowRepository supports all annotation concepts specified by the Minimum Information about a Flow Cytometry Experiment (MIFlowCyt, Lee et al., 2008).
MIFlowCyt establishes criteria to describe flow cytometry experiments that provide enough information to allow for correct interpretation and review of experimental details including samples, analysis, and results. It enumerates all the items that are required to be reported, and the depth of detail. Therefore, it minimizes problems such as alternative interpretations resulting from nonuniform and inconsistent reporting, which are critical issues for public data repositories (Burgoon, 2006). Since MIFlowCyt does not specify the format or the location of the required information, data submitters are not forced to provide all of their annotations on line. Information that exists in a manuscript does not necessarily need to be repeated in FlowRepository; however, the more information that is integrated with the dataset on line, the easier it is to locate and interpret the data and experimental findings by independent researchers.
The protocols in this unit explain the use of FlowRepository to explore, review, and retrieve public datasets (Basic Protocol 1), and to deposit and annotate data in compliance with the MIFlowCyt standard (Basic Protocol 2). Since FlowRepository is built on top of the Cytobank platform, the majority of Cytobank's functionality is also available in FlowRepository. Exceptions include the ability to clone experiments, publish duplicated datasets, or keep experiments private for an unlimited time. Despite these minor restrictions, additional information including protocols to analyze data on line within FlowRepository and creating illustrations and reports can be easily adapted from Cytobank's guidelines (unit 10.17).
Basic Protocol 1: FlowRepository Public Data Retrieval
- Top of page
- Introduction
- Basic Protocol 1: FlowRepository Public Data Retrieval
- Basic Protocol 2: FlowRepository Data Upload and Annotation
- Commentary
Basic Protocol 1 explains how to access FlowRepository and to locate and review public datasets and download data, reports, and images from these datasets. Datasets in FlowRepository are organized using the notion of experiments; an experiment is a set of data files accompanied by annotations, which may include details about data analysis and its results. In this unit, the terms “experiment” and “dataset” are used as synonyms.
- A computer with an Internet connection and a supported Web browser: Firefox (http://www.mozilla.org) is recommended; some other major Web browsers, such as Safari, Internet Explorer, or Chrome can also be used; however, their use may result in suboptimal visual appearance or limited functionality of the application
- Ability to run Java applets in your Web browser: the Java version should be version 1.5.1 or higher (Java version 1.6 or higher is recommended, preferably provided by Sun Microsystems Inc.); navigate your browser to http://javatester.org/version.html to verify your ability to run Java and your Java version. If needed, Mac users should use the Apple software update feature to install Java; Windows users can get the latest Java from a Java download page (http://www.java.com), and Linux users should preferably obtain Java and the Firefox Java plugin directly from their distribution.
- A Google ID, Yahoo! ID, or another OpenID, optional: the ID is not needed for basic anonymous read-only access to FlowRepository, but it is required in order to deposit and annotate datasets, analyze data online, and perform additional advanced tasks. You may have an OpenID already if you have an account with certain Web-based service providers, such as Google, Yahoo!, Flickr, AOL, Orange, Blogger, WordPress, or MySpace. Visit http://openid.net/get-an-openid/ for further details.
| 1. | Navigate your Web browser to https://flowrepository.org. p type = annotation Alternatively, you could also use the http://flowrepository.org Web site, since FlowRepository is available using Hypertext Transfer Protocol (HTTP) directly, as well as its secure version—HTTPS—which provides encrypted communication between your computer and the FlowRepository server. Using HTTPS is typically preferable. | ||
| 2. | Take a moment to review the FlowRepository landing page (Fig. 10.18.1). p type = annotation The Web site is horizontally divided into three sections: the FlowRepository logo and main menu in the header at the top, the main section in the middle, and a few static links (i.e., Terms of Service, Privacy Policy, Support, and Feedback) in the footer at the bottom. If you are accessing FlowRepository anonymously, then the main menu contains the Login link only; other items will be displayed if you are logged in. The main section is vertically divided, with some quick links, references, and contextual menu items on your left and the main contents stretching from the center to the right. The main content is commonly organized into boxes; these are typically blue to display requested information or to point to available actions. On the landing page, there is a box with basic information about FlowRepository, another box to query the repository, and finally a box with various useful links, such as for browsing public datasets or submitting data. On other pages, colors, such as green or red, are used for additional tips (green) and notifications about a positive (green) or negative (red) result of an attempted action. An orange color is also used to either indicate a warning or to provide a context-aware link backwards. Some boxes have an “i” in a circle at the top right corner of their title bar. Mousing over this “i” displays an additional informative floating box. Boxes having an “x” in the top right corner of their title bar can be closed by clicking on the “x” symbol. Finally, boxes having a small triangular arrow in the top left corner of their title bar may be collapsed (if the arrow is pointing down) or restored from a collapsed state (if the arrow is pointing right).
| ||
| 3. | Search for the experiment FR-FCM-ZZZ3 (Identification of B cells through negative gating; Blimkie et al., 2010). You can search by typing in the Query box and pressing the Query button. For example, you can type Identification of B cells or FR-FCM-ZZZ3 to locate this experiment. p type = annotation You may also click on the Show query fields link to show and select which query fields should be used for your search (e.g., experiment names, repository identifiers, keywords, researcher names, sample annotations, PubMed IDs, etc.). | ||
| 4. | Click on the Query button, which will direct you to a page with a table of experiments matching your search criteria (Fig. 10.18.2). Review the results of your query. p type = annotation The result table may list a single experiment if your query was specific enough. Alternatively, several experiments may be shown. You may filter these further by typing in the Search field. In addition, you may sort the table by clicking on the up or down arrow in any of the table headings (i.e., the experiment name, the repository identifier, the PubMed identifiers of related publications, the number of FCS files, the number of illustrations, the name of the primary researcher, the name of the project, MIFlowCyt score, and the date of the last update of the experiment).
| ||
| 5. | Click on FR-FCM-ZZZ3 to open the public view of this experiment. p type = annotation FR-FCM-ZZZ3 is the repository identifier of this experiment. Each repository identifier is in the form of FR-FCM-xxxx, where xxxx is a sequence of four alphanumeric characters (case sensitive). Knowing the repository identifier, a public view of an experiment can be accessed directly by a URL in the form of https://flowrepository.org/id/FR-FCM-xxxx, e.g., https://flowrepository.org/id/FR-FCM-ZZZ3. | ||
| 6. | Take a moment to review the annotation of this experiment. p type = annotation The public experiment header at the top displays the experiment name, repository identifier, primary researcher, and its MIFlowCyt score—a value between 0% and 100% that approximates the level of compliance with the MIFlowCyt standard (Lee et al., 2008). The public view of this experiment is shown in four boxes corresponding to the four major sections of MIFlowCyt: experiment overview, flow sample/specimen details, flow cytometer details, and data analysis details. You can collapse and restore these boxes by clicking on the arrow in the left top corner. You can also select a single FCS file in the Flow Sample/Specimen Details box and display relevant sample details by clicking on the Display button. Finally, you may review instrumentation details for a specific FCS file by clicking on the details link in Flow Cytometer Details. |
| 7. | Follow the Download FCS Files link in the Download box on the left (Fig. 10.18.3). This will start a Java applet on your Web page. Depending on your browser security settings, you may need to explicitly confirm that you allow this applet to run. p type = annotation If you do not see anything in the Download Experiment Files box, then your browser did not execute the applet. Please verify that your browser is able to run Java applets (see Necessary Resources). p type = annotation Follow the instructions in the green information box to download the FCS files. If you are only trying to get familiar with the repository, you may not need to download all 284 FCS files (2.7 GB); possibly select just a few. |
| 8. | Download individual attachments (FlowJo workspaces, MS Excel spreadsheet) by clicking on the appropriate links and saving the files on your file system. p type = annotation In addition, you may export Gating-ML (Spidlen et al., 2008) files, download PDF files with illustrations, or download the MIFlowCyt report. Note that rendering of the PDFs may take a few minutes due to the size of the actual report. |
| 9. | Log in to FlowRepository by following the Login link in the top right corner of your screen; you will need an OpenID in order to log in (see Necessary Resources). If it is your first time logging in, then you will need to register for a new account with FlowRepository by clicking on the registration link in the New Users box. p type = annotation For registration, fill out your name and e-mail address and select your OpenID provider. Optionally, you may specify your location and organization. Finally, you will have to agree to the FlowRepository Terms of Service in order to proceed with the registration by clicking on the Register button. |
| 10. | Locate and select the FR-FCM-ZZZ3 (Identification of B cells through negative gating) experiment in your inbox. p type = annotation You can filter the experiments by starting to type in the Search field. You can also sort the Inbox table by any of the columns by clicking on the up or down arrow with any of the column headings. |
| 11. | Take a moment to get familiar with the advanced experiment view. p type = annotation This is your personal view of this experiment, which is similar to the view displayed when you create your own experiments. However, in this case you do not have write permissions for this experiment; therefore, no editing actions are offered. p type = annotation You may click on FR-FCM-ZZZ3 in the experiment header to quickly switch to the experiment public view discussed earlier. Since you are now logged in, you may click on “Identification of B cells through negative gating” in the header, to return to your personal view of this experiment. |
| 12. | Review the details of the a2006_O1T2pb05i_A1_A01.fcs FCS file by clicking on the appropriate link in the FCS Files box (Fig. 10.18.4). p type = annotation The first box shows general information about the FCS file. The second box displays details about instrumentation, the third about laser configuration, and the fourth information about channels. The last box shows a raw FCS file header (Spidlen et al., 2010). An alternative method to show FCS keywords and their values in a more readable way is by clicking on the Review Keywords in FCS files link in the Actions box when on the experiment summary page. |
| 13. | Go back to experiment summary and review the sample description for the a2006_O1T2pb05i_A1_A01.fcs FCS file by clicking on the appropriate “show sample description” link. p type = annotation A pop-up window will display the description of the sample, sample source, sample characteristics, and treatment and staining details. |
| 14. | Review the MIFlowCyt score details by clicking on the MIFlowCyt Score bar on the right side of the experiment header. p type = annotation Four collapsible boxes will show MIFlowCyt compliance details of this experiment annotation. There are green, orange, and red check marks indicating provided, partially provided, and missing information. You may expand additional details about any particular item by clicking on the check mark symbol. Alternatively, you may expand or close all details in a particular section by clicking on the + or – symbols near the Compliance caption in the table header. |
| 15. | Review details of how various annotation items contribute to the MIFlowCyt score by moving your mouse over the “i” symbol on the right side of the caption bar of each of the four boxes. p type = annotation An information pop-up box will appear containing information specific for the selected MIFlowCyt section (Fig. 10.18.5). The box may be closed by clicking on the “x” symbol in its caption bar. |
| 16. | Preview a print view of the MIFlowCyt score and compliance report by clicking on the Print View link in the MIFlowCyt box on the left. p type = annotation You may also download this report in a PDF form by clicking on the nearby PDF link. |
Basic Protocol 2: FlowRepository Data Upload and Annotation
- Top of page
- Introduction
- Basic Protocol 1: FlowRepository Public Data Retrieval
- Basic Protocol 2: FlowRepository Data Upload and Annotation
- Commentary
Basic Protocol 2 demonstrates how to upload datasets to FlowRepository and how to annotate these to provide all the information as required by the MIFlowCyt standard.
- Necessary resources are the same as for Basic Protocol 1, with the exception of OpenID, which is required for Basic Protocol 2, whereas it is optional for most of Basic Protocol 1
| 1. | Log in to FlowRepository by navigating your Web browser to https://flowrepository.org and following the Login link. p type = annotation Additional details are discussed in step 9 of Basic Protocol 1. | ||
| 2. | Start a new data submission by following the Create a new experiment link in your inbox view (Fig. 10.18.6). p type = annotation Alternatively, if you are in the Public view (landing page), then you may start a new data submission by following the Submit data link. The system will ask you to log in if you are not currently logged. p type = annotation Information about your available credits is shown in the top left corner of your Inbox view. Credits are used to control the number of unpublished datasets that a user is allowed to upload to FlowRepository.org, as FlowRepository.org is not intended to be a personal archival system. Typically, you will have 50 credits to begin with, and you may also request additional credits if needed. You will need one credit to create a new experiment. This credit will be returned to your account once your experiment becomes public. Note that experiments in FlowRepository can only be kept private for up to 1 year after the first creation of the experiment or until an associated manuscript referencing the experiment data is published.
| ||
| 3. | Fill in the experiment name in the Bank New Experiment form. p type = annotation Try to stay relatively concise while being as descriptive as possible. Choosing a good title will help others locate your experiments in the future. If you intend to publish a manuscript related to this dataset, using an experiment name that is the same or similar to the intended manuscript title is usually a good choice. | ||
| 4. | Keep Project as None. p type = annotation Projects allow you to group experiments; if you expect having many experiments in FlowRepository and you wish to use these additional means of organization, you may create a project by following the Manage My Projects link in your Inbox view. Your experiments can be assigned to your projects once projects are created. | ||
| 5. | Fill out the Primary Researcher and PI/Manager fields. p type = annotation The Primary Researcher is usually the person who performed the experiment and is also typically submitting the data. The PI/Manager may be the same person or it may be a person responsible for a related higher-level project (e.g., a senior scientist, professor, or group leader). Both of them need to have an account with FlowRepository; you may invite new users to FlowRepository at this point. | ||
| 6. | Fill out the date (range) of the experiment by entering the starting and end date fields. p type = annotation Use the date-picker component to provide the dates. The end date of the experiment is optional, to account for cases where an experiment has not been finished yet; however, the MIFlowCyt score will be negatively affected if the end date is not provided. | ||
| 7. | State the purpose, conclusions, and additional comments about the experiment. p type = annotation While only a brief description of the purpose of the experiment is technically sufficient to upload a dataset, it is recommended (and required by MIFlowCyt) that you provide additional details. More information will help you reach a higher MIFlowCyt compliance score. | ||
| 8. | Describe your quality-control measures and/or reference a quality-control experiment. p type = annotation As per MIFlowCyt (section 1.8), a description of the quality-control measures used, such as replicates, calibrations, or control assays, should be provided. If another experiment was performed for the purpose of establishing quality-control standards, then that experiment may be referenced. | ||
| 9. | Provide a few keywords characterizing the experiment. p type = annotation Auto-complete, based on keywords describing existing experiments, is offered. | ||
| 10. | Specify the organization that performed the experiment. You may need to use the “Add new organization” button if the appropriate organization does not exist in the FlowRepository database. p type = annotation If you are entering a new organization, please provide the name and department (if applicable). Continue by entering your postal code (zip). Once you leave this field, the system will try to automatically resolve the city and state/province (if applicable) based on the postal code, assuming that you are specifying an address in the same country from which you are currently connected. If this is not the case, you may specify the country field first, and then the postal code. Postal code lookup is currently supported for approximately 60 countries. Finish by completing and adjusting your address as appropriate. | ||
| 11. | If there are one or more publications associated with this experiment, then specify their PubMed IDs. You may provide a single numeric PubMed ID or a comma-separated list of multiple PubMed IDs. p type = annotation Related publications may also be linked to the experiment later on, which is commonly the case since data are typically shared (at least with the reviewers) prior to the publication of the related manuscript. | ||
| 12. | Finalize the submission of general metadata by pressing the Create Experiment button. This will direct you to a data upload page. | ||
| 13. | Organize a folder containing all the files to be uploaded on your personal computer. p type = annotation Note that the file/folder structure from your local file system will not be replicated on the FlowRepository server, where files are organized based on detected characteristics and additional annotations (e.g., staining panels, experimental variables, etc.). Consequently, you cannot upload multiple files with an identical file name even if these reside in different folders on your local file system. Please make sure that your files have unique names, or rename them in order to avoid an automated renaming mechanism that would be applied on duplicated file names within a single experiment on the FlowRepository server. | ||
| 14. | Follow the instructions on your screen and select data (FCS files) as well as any additional files (figures, MS Word documents, MS Excel spreadsheets, FlowJo workspaces, FCS Express project files, FACS Diva files, etc.) that you wish to upload. Start by pressing the Browse for Folder button to choose the appropriate folder on your local computer. Make sure the “Upload?” check box is selected for all the files you wish to upload, and then click on the Upload Selected Files button. p type = annotation Upload will begin, and you should see the progress bar start to fill toward 100%. You will be directed to an upload status page once the upload is finished. | ||
| 15. | Verify that all of your files were uploaded correctly. FCS files should be automatically categorized into experimental files, compensation controls, and other controls (Fig. 10.18.7). In addition, they should be automatically assigned to staining panels based on markers detected in the FCS header (Fig. 10.18.8). Please verify correct assignment or re-categorize files using the Channel annotation page link if needed. p type = annotation In addition, you should check that all files are correctly readable. The File Inventory box should list all experimental data files with a small scatter-plot thumbnail preview for each of them. The creation of these thumbnails may take some time, especially for multiple or large data files. p type = annotation FlowRepository will refuse the submission of data files that exist in the repository already (e.g., uploaded by any other user). The detection of duplicate files is based on MD5 checksums, and therefore files are compared irrespectively of their names. You may contact the administrators using the Support link in the footer if you feel that the refusal of your data files is not justified. | ||
| 16. | Review channel naming by following the experiment summary page, and subsequently all different staining panels as listed in the FCS files box. p type = annotation Additional details, including guidelines to rename channel descriptions, rename, add or delete panels, change panel assignments, etc., can be found in UNIT 10.17, Basic Protocol 1, steps 15 to 18. |
| 17. | Follow the Annotation Data link in the header of the page. p type = annotation Some annotations may be reusable among multiple experiments: FCS files, sample sources, etc. Therefore, FlowRepository allows you to create a super-set of various annotation concepts that may be reused to describe your experiment. It is therefore recommended that you follow the Annotation Data link prior to annotating your FCS files and samples. Specifically, you should create templates for samples and sample sources, import organisms as necessary, and specify reagents. Providing appropriate details in the Annotation Data section will significantly simplify annotation of your FCS files later. You may also want to review the information in the Getting Started with MIFlowCyt Annotations box. | ||
| 18. | Select the Reagents tab (Fig. 10.18.9). p type = annotation Typically, you do not need to edit anything in the first three tabs (Keywords, Organizations, and Manufactures). p type = annotation The table of reagents contains a list of reagents and their characteristics as required by MIFlowCyt. You can filter the reagents shown by starting to type in the Search field.
| ||
| 19. | Add all reagents used in your experiment (if not listed already) by invoking the “New reagent” form (Fig. 10.18.10) repeatedly. Later on, you will be able to assign reagents to FCS files or to combine them into reusable staining cocktails. p type = annotation For each new reagent, fill out the analyte, analyte detector, analyte reporter, clone, and catalog number as applicable. See MIFlowCyt section 2.4 for details (Lee et al., 2008). Select the reagent manufacturer from the list. In case your reagent manufacturer is not listed, then follow the New button to create and save a new Manufacturer.
| ||
| 20. | Click on the Annotation Data link, Instruments tab, to ensure that the make and model of the flow cytometer(s) used in your experiment is (are) listed among the known instruments. p type = annotation You can filter the instruments shown by starting to type in the Search field. The majority of existing instruments are in the system already. Follow the “New instrument” link and provide the model and manufacturer in case your instrument is not listed. Click the “New manufacturer” button in case the manufacturer of your instrument is not known to FlowRepository. | ||
| 21. | Click on the Annotation Data link, Organisms tab, to ensure that the organism(s) used in your experiment is (are) listed among the known organisms. p type = annotation You can filter the organisms shown by starting to type in the Search field. The NCBI taxonomy contains hundreds of thousands of organisms. In order to simplify the selection, we have imported only a few that are most commonly used in flow cytometry. If your biological sample is derived from an organism that is not listed, follow the “Add organism” link, and you will be able to add it from the NCBI taxonomy (Fig. 10.18.11). Start typing either the Latin or the English name; the auto-complete will show suggestions after the first three characters are typed. Select the appropriate organism and add it by pressing the Add this organism button.
| ||
| 22. | Click on the Annotation Data link, Templates tab, and add templates for your sample sources by following the New annotation template for sample sources link. p type = annotation Annotation templates may be created in order to simplify and speed up MIFlowCyt annotation. Templates contain common annotations that can be applied on specific samples. For biological sample sources, MIFlowCyt requires details such as description, organism, age, gender, phenotype, genotype, and treatment. For example, let us assume that your sample sources are human donors that differ in their gender and age, but everything else is assumed to be the same. You can create an appropriate annotation template, fill out all the common details, and leave the gender and age out of the template. Later on, when annotating the FCS files of your experiment, you will be able to easily create sample sources based on this template, and you will only have to provide the gender and age that differ among the subjects. | ||
| 23. | Click on the “From new” button in the New Annotation Template box with Sample source listed as the template type (Fig. 10.18.12). Select the sample source type and fill out all the fields as required by MIFlowCyt. You may enter ? or one of the common values in the fields that are variable among your sample sources; you will be rewriting this value when applying the template to specify actual sample sources. Click on the Save button to close the Details for sample source template pop-up window. Finally, name the template (you may use the default name as suggested based on your description) and click on the Create button. p type = annotation MIFlowCyt section 2.1 requires sample materials to be described depending on type: biological, environmental, or other. The form will dynamically adjust its fields once you have selected your sample source type. For biological samples, you will need to state the description, organism, age (with units), gender, phenotype, genotype, and treatment. A description and location is required for environmental sample sources, and description only for other sample-source types. Additional information may be provided in the other field (optional). | ||
| 24. | Click on the Annotation Data link, Templates tab, and add templates for your samples by following the New annotation template for sources link. | ||
| 25. | Create your sample templates in a similar fashion to that used to create the sample source template earlier. Click on the “From new” button in the New Annotation Template box (now with Sample listed as the template type). Fill out the description, sample characteristics, and treatment as required by MIFlowCyt sections 2.2 to 2.3. p type = annotation You will need to create new entries by following the New buttons in order to describe sample treatment and characteristics. Describe these accordingly, save them, and then select in the drop-down selection boxes. | ||
| 26. | Select existing staining reagents and/or cocktails or create new entries (Fig. 10.18.13) based on reagents specified in step 19. For each reagent used, follow the New button, fill in the characteristics being measured (see MIFlowCyt section 2.4), select the reagent, and save it with the Save button. If a staining cocktail is used, specify its name, catalog number, and manufacturer (if applicable), and select (create) all fluorescence reagents used in the cocktail. p type = annotation Make sure the appropriate staining reagents and/or cocktails are selected before saving the sample template form. You may select/deselect multiple entries by pressing Ctrl or Shift while you click on an item. p type = annotation Specifying staining details in your sample template is only useful if the same staining is used across multiple samples. Otherwise, you may skip this step and leave the staining unspecified in the template; you will still be able to specify staining details for each FCS file individually (step 30 below). | ||
| 27. | Click on the Save button to close the Details for sample template pop-up window. Finally, name the template (you may use the default name as suggested based on your description) and click on the Create button. |
Steps 34 to 38 are applicable if you opted for extracting some of your sample and/or sample source annotations from a CSV file (spreadsheet) rather than providing these details by filling out on-line forms. Many researchers find this a very useful option, especially if the experiment contains many FCS files. Support for additional file formats may be developed as per community requirements; please see documentation provided on-line at the FlowRepository Web site for updated information.
| 39. | Follow the Review experiment variables link in the green information box or click on your working illustration in the blue Illustrations box. p type = annotation Experiment variables are attributes that differ between samples within an experiment due to pre-existing differences in sample states or due to experimental manipulation of the samples (e.g., smoker versus non-smoker, IL-2 treatment versus no treatment, knockout versus wild-type, or variable number of transplanted stem cells). | ||
| 40. | Click on the appropriate experiment variable type (Fig. 10.18.14, dosages, time points, conditions, individuals, etc.). p type = annotation Experiment variables are commonly used in Figures as dimensions, since researchers are typically interested in visual inspection of the effects of different values of a variable. Therefore, experimental variables are defined within the illustration section of FlowRepository. However, you may still define variables and assign their values to FCS files without using these in any of your illustrations. p type = annotation For the purpose of this example, we will assume that you have selected Conditions as the appropriate variable type for your experiment; a red box titled Conditions will appear.
| ||
| 41. | Click on the Setup link inside the Conditions box. | ||
| 42. | Enter a comma-separated list of conditions to add in the Add conditions box (e.g., PAM stimul., R-FSL stimul., pIC stimul., LPS stimul., no stimul.), and click on the Add Conditions button. p type = annotation This will create additional boxes (containers) for your FCS files, one box for each of the conditions specified. | ||
| 43. | Assign FCS files to the appropriate conditions (Fig. 10.18.15) by dragging them and dropping in the appropriate box. Click on Return to Illustration once all FCS files are correctly assigned (tagged).
| ||
| 44. | Repeat steps 40 to 43 for other types of experimental variables you wish to define. The appropriate boxes, buttons, etc. will be named based on the type of variable you are defining. p type = annotation You may toggle the boxes with experimental variables on and off (i.e., include/exclude from a working illustration) by clicking on the variable type in the row of Available Dimensions. You need to display a variable in order to define the values (assign FCS files), but you can safely hide it afterwards. |
| 45. | Return to your experiment overview by clicking on the Back to Experiment link. |
| 46. | Follow the details link near the first of your FCS files listed in the FCS Files box at the bottom of the page. |
| 47. | Click on the “Describe instrument settings” button inside the FCS File Instrument Settings box |
| 48. | From the drop-down selection box, select the instrument used for acquisition of the particular FCS file. p type = annotation See step 20 above in case your instrument is not included in the selection. p type = annotation The dialog window will expand to include the instrumentation settings description once the instrument has been selected (Fig. 10.18.16). |
| 49. | If you have not altered the instrument by customizing optical filters, light sources, or other hardware components, then select the “Use default instrument settings” check box and skip to step 65 below. p type = annotation As per MIFlowCyt section 3, using default configuration will significantly minimize the effort needed for proper instrumentation annotation. Steps 50 to 64 are included to cover cases when an instrument has been customized. |
| 50. | Select the flow cell type of your instrument from the drop-down selection box. Use the “Add new flow cell type” button and enter the appropriate type in case your flow cell type is not listed in the drop-down selection box. |
| 51. | Provide additional flow fluidics information in the “Other flow fluidics” field (optional). p type = annotation As per MIFlowCyt section 3.3.1.2., this may include the flow cell manufacturer name and model number, flow cell outside shape and dimensions, flow channel shape and dimensions, sheath flow velocity, sheath flow pump type, sample flow velocity, and sample flow pump and other relevant details. |
| 52. | Click on “Add new optical path” in order to describe the optical path for a channel. p type = annotation You will need to describe the optical path for each channel. |
| 53. | Use the Parameter drop-down selection box to select the FCS parameter (channel) for which you are describing the optical path. |
| 54. | Specify the basic components of the optical path by dragging and dropping the framed components (i.e., light source, filter, optical detector, and others) into the sorted list in the yellow box. You may also drag the labels around inside the box to re-order them, or remove them by dragging them over to the trash bin symbol. p type = annotation Initially, the list will contain three items creating a simple optical path to begin with—a light source, a filter, and an optical detector. You can always reset to this stage by clicking on the garbage bin symbol. |
| 55. | Double-click on the Light Source label in the ordered list (typically, item 1) to provide details about the light source. There are two ways to specify the details, either by defining a new light source (click on the Create new light source button) or by selecting a previously described light source. p type = annotation For the first optical path, you will likely have to define a new light source. However, you will be able to reuse previously defined light sources by selecting them from the “Select existing light source” drop-down selection box when defining an additional optical path. |
| 56. | Select the light source type from the drop-down selection box. Specify the excitatory wavelength, power, polarization (optional), beam characteristics (optional), and other relevant information (optional), and save the information by clicking on the “Add component” button. p type = annotation Specified details are as required by MIFlowCyt section 3.3.2. The label in the ordered list will change from light source to light source—edited (Fig. 10.18.17) to indicate that details about this particular component have been provided already. Now, you will need to describe the other components. |
| 57. | Double-click on the Filter label in the ordered list (typically, item 2) to provide details about the optical filter. Again, there are two ways to specify the details—either by defining a new filter (click on the Create new filter button) or by selecting a previously described optical filter. p type = annotation You will have to define a new optical filter the first time you need to use it; however, you will be able to reuse previously defined filters by selecting them from the Select existing filter drop-down selection box if these filters are used in multiple optical paths. |
| 58. | Select the filter type from the drop-down selection box. Specify the transmitted wavelengths, model (optional), manufacturer (optional), and other relevant information (optional). Follow the New link near the manufacturer field if the manufacturer of your optical filter is not included in the list. Provide the name, Web site (optional), phone number (optional), and other important information (optional) about the manufacturer, and save it by clicking the Save button. Save the new optical filter by clicking on the “Add component” button. p type = annotation Specified details are as required by MIFlowCyt section 3.3.4 except for optical filter installation dates (MIFlowCyt section 3.3.4.3), which will be addressed in step 65 below. The label in the ordered list will change from filter to filter—edited to indicate that details about this particular component have been provided already. |
| 59. | Repeat steps 57 to 58 to describe all other optical filters that are on the same optical path. |
| 60. | Double-click on the Optical Detector label in the ordered list (typically the last item) to provide details about the optical detector. As before, there are two ways to specify the details, either by defining a new optical detector (click on the Create new detector button) or by selecting a previously described optical detector. p type = annotation You will have to define a new optical detector the first time you need to use it; however, you will be able to reuse previously defined detectors by selecting them from the “Select existing detector” drop-down selection box if these detectors are used in multiple optical paths (e.g., if multiple signal characteristics, such as the height and area, of a certain signal are captured). |
| 61. | Select the optical detector type from the drop-down selection box. Specify the name (e.g., PMT A; typically, identifiers assigned by instrument manufacturers make up for an appropriate name), amplification type (optional), and other relevant information (optional). Save the new optical detector by clicking on the Add component button. p type = annotation Specified details are as required by MIFlowCyt section 3.3.5, except for optical detector voltages (MIFlowCyt section 3.3.5.3), which are typically included in the optional $PnV keywords in the FCS file (Spidlen et al., 2010). Use the field for “other relevant information” to provide the detector voltage in case it is not included in your FCS file. The label in the ordered list will change from optical detector to optical detector—edited to indicate that details about this particular component have been provided already. |
| 62. | If there are other optical components (beam splitters, spectrometer, etc.) on the optical path, describe these similarly to how you just described the light source, optical filters, and the optical detector. Double click on the Other label in the ordered list, provide the name, type (optional), and description (optional), and save the component by clicking on the Add component button. |
| 63. | Save the optical path by clicking on the Save button on the New optical path details. p type = annotation The newly created optical path will get added among the existing Optical paths on the Describe instrument settings dialog window. |
| 64. | Repeat steps 52 to 63 and add the optical path for each measured parameter where applicable (i.e., excluding time). p type = annotation Make sure all the relevant optical paths are selected in the “Optical paths” selection box; you may add/remove an item from the current selection by holding Ctrl while clicking on the item. |
| 65. | Provide installation dates for filters in optical paths and other relevant details (optional) in the “Describe instrument settings” dialog. p type = annotation You may list specific dates for each filter or include a generic statement, such as “all filters came with the instrument purchased on February 26, 2010.” |
| 66. | Check the “Use these settings” for all FCS files in this experiment check box if you have used the same instrument to acquire all your data files. Close the instrument settings dialog using the Save button. p type = annotation If you used multiple instruments to acquire your data, then you will have to describe these separately by repeating steps 45 to 66 for each of the FCS files. |
| 67. | Return to the experiment illustrations section by following the Back to Experiment Summary link, and then the “My working illustration” link. Gate and analyze your data online (optional) and create custom illustrations (optional) by following the data analysis protocols described in unit 10.17. p type = annotation Alternatively, you may upload third-party analysis files (e.g., FlowJo workspaces, FCS Express project files, FACS Diva files, etc.) and relevant figures, summary statistics, etc., as attachments if you prefer using your own tools for data analysis. Your MIFlowCyt score will not be negatively affected if you decide to provide third-party analysis files rather than analyzing data online. |
| 68. | Review your MIFlowCyt score details by following the MIFlowCyt Score compliance progress bar on the right side of your experiment header. p type = annotation At this point, your MIFlowCyt compliance score should be close to 100% if you followed all previously described steps and provided all the information required by MIFlowCyt. | ||
| 69. | Review the details of your annotation compliance for each MIFlowCyt section and provide additional information as needed to improve your score. p type = annotation There are four tables detailing the compliance of your annotation with the MIFlowCyt standard, one for each section of MIFlowCyt. In each of these tables, the compliance column shows a green (fully compliant), orange (partially compliant), or red (information missing) checkmark. You may expand details by clicking on the checkmark symbol. All details may be expanded or collapsed by clicking on the plus or minus sign in the table heading, respectively. The “improve” column provides links for you to use to improve your annotation and increase your score (Fig. 10.18.18).
|
| 70. | Once you are satisfied with your annotations, return to the experiment summary by following the Back to Experiment Summary link. |
| 71. | Click on the Share with Reviewers button inside the Sharing Permissions box. Confirm the message (press OK) notifying you that sharing this experiment with reviewers will also lock your experiment. p type = annotation As a result, the experiment will be locked and a URL with a secret access code will be generated (e.g., https://flowrepository.org/id/RvFra4aTsCvHN0YxrqfcNrwOX5DvygvxQGCBxly2QqZpKbYXrSrpWNswo7XXVood). |
| 72. | Share the secret URL with your reviewers. p type = annotation For example, you may copy and paste the URL to the cover letter of your manuscript. With this URL, the reviewers will be able to obtain anonymous read-only access to the Public View of your experiment. Once your manuscript is published, the experiment will become publicly available without the need for a secret access code. p type = annotation It is recommended to also include your repository identifier (FR-FCM-xxxx as discussed in Basic Protocol 1, step 5) in the text of the related manuscript. Placing the repository identifier in the manuscript text will help readers locate the related dataset. Depending on the journal, your data may automatically become publicly available once the manuscript is published. Please contact FlowRepository.org administrators if unsure. p type = annotation If reviewers ask for changes to your dataset and/or annotation prior publication of the manuscript, the editor will typically arrange for the experiment to be unlocked for you to edit. Should this not be the case, please contact FlowRepository administrators by following the Support link in the footer of each page. |
Commentary
Background Information
Transparency and public availability of protocols, data, analyses, and results are crucial in order to make sense of the complex biology of human disease, and research efforts should be integrated across teams in an open environment. Private funding agencies, regulatory agencies, publishers, and the scientific community have all recognized the importance of protecting cumulative data outputs to accelerate subsequent exploitation through the community-based development of public data repositories (Field et al., 2009). In a recent re-evaluation of 18 peer-reviewed Nature Genetics microarray articles, the inability of researchers to reproduce analyses was directly linked to data unavailability, incomplete data annotation, or specification of data processing and analysis (Ioannidis et al., 2009). Data sharing allows scientists to expedite the translation of research results into knowledge, products, and procedures to improve human health. Sharing data reinforces open scientific inquiry, encourages diversity of analysis and opinion, promotes new research, makes possible the testing of new or alternative hypotheses and methods of analysis, supports studies on data-collection methods and measurement, facilitates the education of new researchers, enables the exploration of topics not envisioned by the initial investigators, and permits the creation of new datasets when data from multiple sources are combined.
The International Society for Advancement of Cytometry (ISAC), founded in 1979 and the largest international flow cytometry community with approximately 2000 members, recognized the need for a public, community-based data repository. FlowRepository was developed under the auspices of ISAC by extending and adapting Cytobank—an online tool for collaborative analysis of cytometric data to address this need.
To efficiently exchange information, the community must first agree on the kind of information they want to store, though the precise content of documentation will vary by scientific area, study design, type of data collected, and characteristics of the dataset. In flow cytometry, this need was addressed by MIFlowCyt (Lee et al., 2008), which is accepted as a standard by the society. The journal publishers Wiley-Blackwell and Nature Publishing Group reference MIFlowCyt in their instructions to authors. MIFlowCyt is also a component of the Minimum Information for Biological and Biomedical Investigations (MIBBI) set of minimal informational standards (Taylor et al., 2008), and it is endorsed by the Data Interoperability Steering Committee of the Division of Allergy, Immunology and Transplantation within the National Institute of Allergy and Infectious Diseases. Based on the microarray repository experience, the establishment of MIFlowCyt as a minimum information standard was the first crucial step toward developing universal solutions for representing, collecting, annotating, archiving, analyzing, and disseminating flow cytometry data through a public repository. Consequently, support for all MIFlowCyt compatible annotation is a crucial requirement for FlowRepository, and has influenced many of its design aspects and decisions. Although the effort spent providing MIFlowCyt annotations may seem like a burden to data submitters, it will pay off by facilitating third-party understanding of the data and conclusions reached, and by allowing for comparisons to experiments performed by different laboratories. It will foster scientific collaboration and preserve the integrity and quality of cytometry data, which will contribute to the advancement of biomedical sciences by enabling scientists to build upon previous findings.
Critical Parameters
The speed of your Internet connection may become a bottleneck, especially when uploading large datasets consisting of gigabytes of data files. We suggest that you upload your data overnight in this case (you do not need to be present by the computer while the upload is in progress).
In clinical environments, users may need to de-identify FCS files in order to be able to share the dataset while conforming to applicable privacy rule requirements, such as the Health Insurance Portability and Accountability Act (HIPAA, Harrelson et al., 2007). FCS data files contain a segment with keyword/value pairs. Most of these keep basic information essential for the interpretation of the raw data matrix of fluorescence expression levels and other values, such the number of acquired parameters, their names, detector voltage settings, etc. However, some of these keywords may include values that could be used to identify an individual and should therefore be removed. Currently, it may be challenging for clinicians to edit FCS files locally, although there are some tools available that can help with that task (e.g., a free De-Identification Utility offered by Tree Star, Inc., available from http://www.flowjo.com/utilities/). In the future, we intend to simplify this process by integrating the FCS de-identification functionality directly in the data upload mechanism.
Troubleshooting
Cytobank troubleshooting tips, common issues, and questions can be found at http://docs.cytobank.org/wagn/Troubleshooting. FlowRepository-specific inquiries and comments may be submitted via the support link in the footer of each FlowRepository page or directly via an email to flowrepository-admin@isac-net.org.
Time Considerations
The time and effort required to upload and properly annotate a dataset is proportional to the size and complexity of your experiment. It can reach anywhere from ∼30 min for simple cases with a handful of FCS files acquired on a single instrument with default instrumentation settings, to several hours for very large and complicated experiments with hundreds of data files, several experimental variables, and many samples.
Acknowledgements
Development of FlowRepository was supported by the International Society for Advancement of Cytometry, the Terry Fox Research Institute, the Terry Fox Foundation, and the Wallace H. Coulter Foundation. The authors would also like to thank Cytobank, Inc. and its development team (especially Nikesh Kotecha and Chad Rosenberg) for providing the underlying technological platform as free, open-source software, and for their assistance throughout the project, as well as initial hosting of the FlowRepository application. Ryan R. Brinkman was supported by a Michael Smith Foundation for Health Research Scholar Award.