---
title: Overview and Quickstart
slug: ryze/overview-and-quickstart
description: Learn how to use the Dataset Mapper plugin to effortlessly generate mapping files for data transformations. This quickstart guide covers everything from uploading a source dataset to configuring the plugin. Discover examples of using functions in the mapp
createdAt: 2023-09-29T10:58:09.330Z
---

Dataset Mapper is a Formedix ryze plugin which can be used to generate the mapping file used in data transformations. Dataset Mapper extends a define.xml file with mapping commands used to configure an Extract, Transfer, Load (ETL) system.&#x20;

- Dataset Mapper is used to run Dataset Conversions, see also the [Dataset Conversions Guide](https://docs.formedix.com/ryze/dataset-conversion).
- For an example of how you might map proprietary datasets to SDTM, see [Managing Proprietary Datasets](https://docs.formedix.com/ryze/managing-proprietary-datasets).

Dataset Mapper can be used to map one variable to another. You can use it to map from a source dataset to a target dataset, for example, mapping variables from your EDC dataset to a standard SDTM dataset. Dataset Mapper can also be used to perform operations on data, for example, to change strings or to compute other data.

This quickstart guide describes how to upload a source dataset and map variables to the correct standard for submission. 

## Enable the Plugin for your Repository

Dataset Mapper must be enabled by an administrator to be available in your repository. 

To enable the plugin for your repository, go to the Plugins section under **Admin > Repository > Plugins**. 

## Add your Source Dataset

::File{src="https://api.archbee.com/api/presign/aRGXD44FysHcCUICvfsxc/G59gSgzZJuSvJQTc49amF_dm-source.xml" label="DM Source.xml"}

1. From your study, clic&#x6B;**&#x20;Upload Datasets&#x20;**&#x66;rom the toolbar. In this example, we’ll use the sample demographics dataset above (DM Source.xml) as a guide.&#x20;
2. Choose a name for the asset group that is created (whenever you upload a dataset, a new asset group is created)
3. The uploaded dataset should now appear in the study as a new Asset Group.

## Add your Target Dataset

In this example, we’ll map some erroneous variables in the source dataset to the SDTM-IG 3.3 standard. This standard must be available in your library, see [Published Standards](https://docs.formedix.com/ryze/standards#published-standards).

1. Click **Associate Library** and add the SDTM-IG 3.3 standard
2. Create a new Asset Group for the Target Dataset and open the new Asset Group
3. From the new Asset Group, click **Import Assets&#x20;**&#x61;nd import the Demographics Dataset from SDTM-IG 3.3.

![](https://api.archbee.com/api/optimize/aRGXD44FysHcCUICvfsxc/zqSzhtPoDavhlqKTYjGPE_import-sdtm-ig-dm-dataset.gif)

## Add the Plugin to the Target Asset Group

Plugins are added at the Asset group level of a standard or study, see [Using Plugins](https://docs.formedix.com/ryze/plugins#using-plugins) for more information. 

1. From the target Asset Group, click the Asset Group Properties icon
2. Add the Dataset Mapper Plugin to the target Asset Group

## Map the Target Dataset to the Source Dataset

Before we map individual variables, we must first map the dataset. 

1. From the Target dataset, click edit Dataset
2. Open the Plugin Properties tab and go to Dataset Mapper properties
3. Add the Source Dataset by specifying the Source Dataset Identifier.

See also, [Mapping Dataset Properties](https://docs.formedix.com/ryze/dataset-properties).

![](https://api.archbee.com/api/optimize/aRGXD44FysHcCUICvfsxc/5FC3Mnr59DHlP73Dlar9w_add-source-dataset.gif)

## Example Mappings

Some mapping functions must be in the same format, for example, when &#x20;

### Example A: Mapping one variable to another

Once the dataset source is mapped, we can map individual variables from the Target dataset. In this example, we’ll map the target variable “SITEID” to the source variable “SITE”.

1. From the Target Dataset, select the Variable “SITEID”
2. Open the Plugin properties tab and click **Add Mapping Group** from Dataset Mapper properties
3. Enter the select Source Variable from the Source Type
4. From the Source field add “SITE”.

When you run a conversion, the Variable in the Target dataset is populated with data from the source variable.

![](https://api.archbee.com/api/optimize/aRGXD44FysHcCUICvfsxc/gq-6wVfWk4gxlQqYCNpAo_map-siteid-variable.gif)

### Example B: Concatenating PROJECT, SITEID, and SUBJECTI to derive the Unique Subject Identifier USUBJID

In this example we’ll use a function to concatenate these variables. 

:::Iframe{code="<iframe src=&#x22;https://player.vimeo.com/video/704525544?h=54990451c7&#x22; width=&#x22;640&#x22; height=&#x22;564&#x22; frameborder=&#x22;0&#x22; allow=&#x22;autoplay; fullscreen&#x22; allowfullscreen></iframe>"}

:::

1. Select the Variable USUBJID in the Target dataset
2. From Dataset Mapper properties, Click **Add Mapping Group**
3. For this Source Type, select Function
4. Under Function, Click **Add Function Group** and and select the Function Name: **Concatenate**
5. Click **Add Parameter Group&#x20;**&#x61;nd fill in the following:
   1. Source Type: Source Variable
   2. Source: PROJECTI
6. Click **Add Parameter Group** again and add:
   1. Source Type: String
   2. Source: -
7. Click **Add Parameter Group** and add:
   1. Source Type: String
8. Click **Add Parameter Group** and add:
9. Click **Add Parameter Group&#x20;**&#x61;nd add:
   1. Source: -
   2. Source Type: Source Variable
   3. Source: SITEID
   4. Source Type: Source Variable
   5. Source: SUBJETI

When you run a conversion, these three variables are concatenated into one in the Target dataset.


### Example C: Converting a date string into ISO 8601 format

In this example the collected date (BRTHDTC\_) is not in ISO 8601 format, you can use a function to map the string into the correct format.

:::Iframe{code="<iframe src=&#x22;https://player.vimeo.com/video/704525097?h=a28f0cf7c9&#x22; width=&#x22;640&#x22; height=&#x22;564&#x22; frameborder=&#x22;0&#x22; allow=&#x22;autoplay; fullscreen&#x22; allowfullscreen></iframe>"}

:::

1. Select the Variable BRTHDTC in the Target dataset
2. From Dataset Mapper properties, Click **Add Mapping Group**
3. For this Source Type, select Function
4. Under Function, Click **Add Function Group** and and select the Function Name: **Convert date to ISO 8601**
5. Click **Add Parameter Group** and fill in the following:
   1. Source Type: Source Variable
   2. Source: BRTHDTC\_
6. Click **Add Parameter Group** again and fill in the following:
   1. Source Type: String
   2. Source: dd-MMM-yy

The string parameter must match the formatting of the source string.

The BRTHDTC variable is converted to the correct format when you run the conversion process.

### Example D: Compute DY

In this example, the number of days since the study start date is calculated. The number of days is calculated by comparing two date variables in the source dataset, Reference Start Date (RFSTDTC) and Date of Collection (MBDAT). These Dates should be in ISO 8601 format for this example.

1. Add a Variable in the Target dataset called *Study Day Count*
2. From Dataset Mapper properties, Click **Add Mapping Group**
3. For this Source Type, select **Function**
4. Under Function, Select **Compute DY**
5. Click **Add Parameter Group** and fill in the following:
   1. Source Type: Source Variable
   2. Source: RFSTDTC
6. Click **Add Parameter Group** again and fill in the following:
   1. Source Type: Source Variable
   2. Source: MDBAT

**Note:** Both Source Variables must be in the same format, for example, date (2021-10-17) or datetime (2021-10-17T07:44). If they are not in the same format then you must use another function to change the formatting.&#x20;

When the conversion is run, the Study Day Count column displays the number of days between the dates specified in the source.

![](https://api.archbee.com/api/optimize/aRGXD44FysHcCUICvfsxc/8j_nU3wKWYcUxQpUPxBZ4_image2.png)

## Tutorial: Mapping Multiple Source Datasets&#x20;

The following video shows an example of pulling data from two datasets (AE and AEPBASIC) into one dataset (AE\_A01). 

::Image[]{src="https://api.archbee.com/api/optimize/aRGXD44FysHcCUICvfsxc/-6UQRn3Ac1Ri36ko3o8Ui_.blob" size="50" width="381" height="224" position="center" showCaption="false"}

:::Iframe{code="<iframe src=&#x22;https://player.vimeo.com/video/823720880?h=918ff96873&#x22; width=&#x22;640&#x22; height=&#x22;564&#x22; frameborder=&#x22;0&#x22; allow=&#x22;autoplay; fullscreen&#x22; allowfullscreen></iframe>"}

:::

The video shows the typical workflow for working with dataset mapper, including the following:

- Viewing the source data
- Mapping individual variables from multiple sources (AETERM)
- Using Copy Mapping Group to extend the mapping to other datasets
- Converting date types to ISO 8601 format (AESTDTC)
- Running test conversions
- Viewing the converted data

## Common Dataset Mapping Properties

The following properties are commonly used when mapping datasets:

### Include Rows

Include Rows allows you to include rows of data depending on user-set conditions. For example to include rows where a variable has a specific value. Include Rows uses Conditions that affect the input if the Condition evaluates to True. You can specify more than one Condition. Conditions are logic operations and subsequent Conditions apply depending on the previous Condition and any logic operators. 

The following example would include Medical History data where the MHPRESP variable is equal to “Yes” 

![](https://api.archbee.com/api/optimize/aRGXD44FysHcCUICvfsxc/OP_1Dr0Ru9BpRwAKWxmtp_image4.png)

### Sort Output Rows

Sort Output Rows allows you to sort rows in the target dataset or output. For example, by sorting data by Unique Subject Identifier. You can add more than one Sort Key so that subsets of data are sorted.

![](https://api.archbee.com/api/optimize/aRGXD44FysHcCUICvfsxc/pXSLed2YZprvxRH_agOUx_image3.png)

