# Help/Tutorial
<table width="1024">
<tbody>
<tr>
<td>
Table of Contents: <br>
<ul>
<li>I. How to use the database</li>
<ul>
<li>• Browsing and searching</li>
<li>• Comparing groups from different experiments with Cart and Sandbox</li>
</ul>
<li>II. How to compare your data with the data already present in the AMDB</li>
<ul>
<li>• Creating a User Account</li>
<li>• Quick comparison of your data without publishing to AMDB</li>
<li>• Uploading and Publishing your data to AMDB</li>
</ul>
</ul>
</td>
<td align="right">
<a href="/">
<img src="/media/content_files/1/AMDB_logo.png" alt="AMDB logo" width="200px">
</a>
</td>
</tr>
</tbody>
</table>
---
## I. How to use the database
### Browsing and searching
##### [Species](/amdb/taxonomy/tree/) and [comparison](/amdb/taxonomy/compare/) of species
Browse or search for taxa or species of interest on the [Species](/amdb/taxonomy/tree/) page. Searching can be accomplished by entering part of a species name into the search bar and then either pressing 'Enter' or clicking the *'Search'* button. Clicking on a taxon name, including a species name, will open the taxon Card, which provides information on its description, taxon dependencies, and a list of Experiments, Groups, and Samples related to this taxon. In addition to the species description, each species Card generates statistical charts derived from all Groups and Samples in AMDB that include this species. Links to experiments involving this species are also available on the Card. On the [Species comparison](/amdb/taxonomy/tree/) page, you can consolidate all the information for a specific tissue of your chosen species. Furthermore, you can compile metabolite content data for multiple species within a single tissue and directly compare them in AMDB, using the information available in the database.
##### [Experiments](/amdb/experiments/list/), [Groups](/amdb/groups/list/), and [Samples](/amdb/samples/list/)
[Browse](/amdb/experiments/list/) or [search](/amdb/experiments/search/) through completed experiments within the database on the Experiments page. Completed experiments typically involve the comparison of two or more sample groups to identify differences in metabolomes attributed to various factors, such as species, diseases, ecological conditions, and more. Each experiment Card includes a description, specifying the groups being compared and the factors under investigation. Below the description, you will find a set of statistical charts. These charts encompass:
1. ***Principal Component Analysis (PCA) 2D score***: This provides a standard overview of the data in metabolomics. You can adjust scaling, grouping, or exclude samples via the *'Options'* button.
2. ***PCA (3D)*** score: Similar to the 2D score, this adds a third dimension (3rd Principal Component) to the analysis. The same options for scaling, grouping, and sample exclusion are available.
3. ***PCA (loadings)***: Plots loadings of the first two Principal Components. You can adjust scaling or exclude samples using the *'Options'* button.
4. ***PIE*** chart: This reflects the averaged values of the most abundant metabolites across all samples. You can exclude specific samples using the *'Options'* button.
5. ***Box plot***: This presents a box-and-whiskers plot for a specific metabolite. You can select the metabolite for the box plot and adjust grouping or sample exclusion via the *'Options'* button.
6. ***Volcano plot***: This allows you to identify differences between two groups by considering both Fold Change and the statistical significance of this change. In *'Options'* you can customize grouping, select a statistical test (parametric Student's t-test or nonparametric Mann-Whitney U-test), apply the false discovery rate (FDR) correction, and adjust cut-off values. Sample exclusion options are also available.
7. ***Metadata analysis***: If samples contain continuous attributes or factors, like animal weight or age, you can generate charts based on these values for metabolites. You can select the attribute and metabolite for the chart using the *'Options'* button, and also adjust grouping and sample exclusion.
Below the statistical charts, there are four tables (initially collapsed):
1. ***Concentration Table***: Clicking on this table will expand it, providing average concentrations of metabolites within groups. The values represent averages ± standard deviations, measured in nanomoles per gram of wet tissue weight (nmol/g).
2. ***Full Concentration Table*** (Sample View): This table reflects the concentration of metabolites in each individual sample, also in nanomoles per gram of wet tissue (nmol/g). You can sort both of these tables in ascending or descending order based on the values in their columns, which include metabolite name, average concentration within a group, and concentration within a specific sample.
3. ***Metadata*** Table: This table provides descriptions of properties for each sample, including group, species, tissue, gender, origin, sample weight, sampling location, attributes/factors, and more. Clicking on any property that is clickable will reveal additional information about that specific property.
4. ***Raw Files*** Table: This table offers the option to select and download raw data either for specific individual samples or for all samples at once. When you opt to download raw data, you will receive a compressed file that additionally contains full experiment details, including both data and metadata.
Alternatively, you can download only the experiment details, both data and metadata, without raw files using the **'Download .csv file'** button.
[Browsing](/amdb/groups/list/) or [searching](/amdb/groups/search/) ofor **groups** can be done on the Groups page. A **group** consists of samples that share uniform characteristics, such as originating from a single species, tissue, and disease/factor. Each Group card includes a standard description, similar to an Experiment card, featuring statistical charts, data tables, metadata tables, and raw data. The list of individual **samples** is available on the [Sample](/amdb/samples/list/) page, and specific sample searches can be performed on the [Search samples](/amdb/samples/search/) page.
##### [Metabolites](/amdb/metabolites/list/)
[Browse](/amdb/metabolites/list/) or [search](/amdb/metabolites/search/) through metabolites that have been identified and quantified in AMDB. The table can be sorted by name, AMDB ID, and external database IDs. Each metabolite card offers a concise description, metabolite parameters, links to external resources, and the ability to search for Samples, Groups, and Experiments containing that specific metabolite.
Alternatively, you can search for a particular metabolite or a combination of several metabolites within samples, sample groups, or experiments on a [dedicated page](/amdb/metabolites/searchby/). For Nuclear Magnetic Resonance (NMR) parameters of metabolites, such as functional group, multiplicity, chemical shift, and number of protons, you can refer to the [NMR metabolite table](/amdb/metabolites/nmr/). This table can be sorted by name and NMR chemical shift.
### Comparing groups from different experiments with **Cart** and [Sandbox](/amdb/experiments/sandbox/)
To facilitate the comparison of groups from different experiments, AMDB provides a convenient feature known as the **Cart**. You can effectively utilize this feature by following the procedure below:
1. Search for a group of interest and access its Card.
2. Scroll to the bottom of the Card, where you will find the *'Add group to comparison'* button. Click it to add the Group to the **Cart**. The icon in the top-right corner will now indicate *'(1)'* Group in **Cart**.
3. Repeat the process of searching for and selecting Groups to be compared.
4. The **Cart** will display the number and list of selected Groups, allowing you to review and make further modifications in the selection if needed.
5. To proceed with the comparison, click the *'Compare'* button. This action will transfer the selected groups into the [Sandbox](/amdb/experiments/sandbox/).
Alternatively, you can add groups for comparison directly in the [Sandbox](/amdb/experiments/sandbox/). Search for groups using their names or IDs on the right side of the Sandbox, then grab and move groups of interest to the left side, which displays the list of selected for comparison groups. Click the *‘Generate’* button, and based on the selection, the system will consolidate related information from the groups, combining it into a 'new' Experiment with a standard Card, that includes statistical charts, data tables, metadata tables, and raw data. You can download the generated experiment and its corresponding raw data.
All groups constituting completed experiments can be added to the Cart simply by clicking the *'Add experiment to comparison'* button at the bottom of the experiment Card. By utilizing the **Cart** and [Sandbox](/amdb/experiments/sandbox/) features, researchers can easily compare multiple groups of interest, enabling comprehensive analysis across different groups or experiments within AMDB.
Similarly, the [Species comparison](/amdb/taxonomy/compare/) page in AMDB consolidates all the information related to a specific tissue in one or multiple species of interest. This page generates a comprehensive summary, similar to an experiment card.
---
## II. How to compare your data with the data already present in the AMDB
#### Creating a User Account
AMDB allows registered users to upload their own quantitative metabolomic data and compare it with the data already present in AMDB. To get started, follow these steps:
1. **Create a User Account**: Click the [Sign up](/accounts/signup/) button on the AMDB top menu. Enter your email address, choose a desired username, create a password, and repeat the password. Click *'Sign up'* to complete the registration process.
2. **Log In**: Once registered, log in using your username and password. If you forget your password, you can use the "Forgot password?" link on the Login page. You can also tick the checkbox "Remember me" if you want to log in automatically.
[Data manager](/amdb/profile/manager/) page
For registered users, the Data Manager page will appear. Here, you can [create yor own](/amdb/profile/manager/#ownExperiments) experiment by either uploading a *.csv or *.xlsx file (using a template) or creating an empty experiment to enter values manually.
#### Quick comparison of your data without publishing to AMDB
To quickly compare your data with existing data in AMDB, follow this simplified procedure:
1. **Download the Template**: Download the [simplified template](/amdb/experiments/template/) (template.xlsx) for the experiment from the Data Manager page. This Excel template contains only the required fields that need to be filled in (Groups, Samples, Metabolites). Follow the instructions in the second 'instructions' Excel sheet of the template.
2. **Fill in the Template**: Cells with the red upper-right corner contain tooltips that pop up when the cursor hovers over them. Fill in the experiment name in the first row (in cell B1). The experiment name should not match existing experiment names in AMDB. Fill the experiment description in the second row (in cell B2). Populate the Groups row (4th row); the number of cells should match the number of samples. Make sure that the name within one group of samples and in the description column match exactly. Fill in the text description of groups in 5th and 6th rows if the experiment contains two groups. Append 7th, 8th, etc. rows (after '2nd group' and before the 'Sample names' row), if the experiment contains more than two groups. Fill in the sample names in the corresponding row. Fill in rows with metabolite names and their corresponding concentrations in samples (in nmol/g) under the 'Metabolites' row. Empty and N/A values indicate difficulties in quantitation (e.g., overlapping peaks), while zero values indicate that the value is below the LOQ (or LOD) of the instrument. The metabolite names can be taken from the [Metabolites](https://amdb.online/amdb/metabolites/list/) section. If the metabolite is absent in the AMDB, use the PubChem name, the system will fetch the metabolite description and automatically add it to the AMDB. If the metabolite is missing in PubChem, [contact us](https://amdb.online/contact/). Save the table as *.csv or *.xlsx.
3. **Create the Experiment in AMDB**: Navigate to Data Manager → Experiments → Create experiment → [Import from template](/amdb/experiments/import/). Select the filled template file and click the *'Proceed'* button. The next step involves template validation, including validation of metabolite names. Check that the names of the metabolites match correctly with those existing in AMDB. Correct them if necessary and press *'Confirm'*. Several warnings will be displayed 'species is not specified' and 'tissue is not specified' because the template used is the simplified one. Below these warning messages, the standard experiment Card (with description, statistics, tables) will be displayed.
4. **Review and Manage**: The created experiment and corresponding groups and samples are private, visible only to you, and can be found on the [Data Manager](/amdb/profile/manager/#ownExperiments) page. You can view, edit or delete the created experiment if necessary. Missing fields in data and metadata for the uploaded experiment, and corresponding groups and samples can be populated directly in the website by *'Edit experiment'*, *'Edit sample group'* or *'Edit sample'* buttons. Filled fields can also be edited.
5. **Compare Groups**: Now the Groups created by the User is available for comparison with the existing in the AMDB Groups. Follow the paragraph *'Comparing groups from different experiments with **Cart** and [Sandbox](/amdb/experiments/sandbox/)'*
#### Uploading and Publishing your data to AMDB
To ensure a structured and comprehensive submission of your data, we offer an **extended template**. This template includes additional fields for metadata, such as species, tissue, diseases, gender, origin, and additional factors/attributes, in addition to the required ones (Groups, Samples, Metabolites). Here's how to proceed:
1. **Download the Extended Template**: Obtain the [extended template](/amdb/experiments/template/?extended) (extended_template.xlsx) for your experiment from the [Data Manager](/amdb/profile/manager/#ownExperiments) page. Before you start filling in the extended template, review the metadata fields in the second *'db_entries'* Excel sheet of the extended template. If you find that a metadata entry (e.g., Species or metabolite) is missing in AMDB, please [contact us](/contact/) first. Our team will add the necessary information to the database.
2. **Fill in the Template**: Follow the instructions provided in the third Excel sheet of the template. This process aligns with the simplified procedure described in the previous paragraph, *'Quick comparison of your data without publishing to AMDB'*. In addition to the simplified procedure, complete the metadata fields for your samples, including species, tissue, diseases, gender, origin, and any additional factors/attributes. Most metadata fields can be selected from drop-down lists (e.g., species, tissue) indicated with a red upper-right corner in the cell. To populate values in neighbouring cells within a row, you can do so in the typical Excel fashion by pointing to a cell and dragging the fill handle. Leave cells empty if no information is available or if it's not applicable. Save the table as *.csv or *.xlsx.
3. **Create the Experiment in AMDB**: Once you've filled in the extended template, navigate to Data Manager → Experiments → Create experiment → [Import from template](/amdb/experiments/import/). Select the filled extended template file and click the "Proceed" button.
4. **Review and Manage**: The created experiment and corresponding groups and samples are private, visible only to you, and can be found on the [Data Manager](/amdb/profile/manager/#ownExperiments) page. Now the Groups created by the User is available for comparison with the existing in the AMDB Groups. You can view, edit or delete the created experiment if necessary. Missing fields in data and metadata for the uploaded experiment, and corresponding groups and samples can be populated directly in the website by *'Edit experiment'*, *'Edit sample group'* or *'Edit sample'* buttons. Filled fields can also be edited.
5. **Publish the Experiment in AMDB**: To publish your experiment in AMDB submit it for validation on the Data Manager page. This action will also create a discussion where you can provide additional information about the experiment and discuss it with AMDB staff. Note that the chat is visible only to AMDB staff. Once the submitted experiment has been validated, it will become publicly available in the database.
By following these steps, you can ensure a well-structured and informative submission of your data in AMDB, enabling meaningful comparisons and analyses.
---