API

Functional interface

genemap.map_ids(ids, mapper, drop_duplicates='both', **kwargs)

Maps a list of IDs to new values using the given mapper.

Parameters:

• ids (List[str]) – List of IDs to map.
• mapper (str) – Name of the required mapper (e.g. ‘ensembl’, ‘mgi’, ‘custom’).
• drop_duplicates (str) – How to handle duplicates. If ‘both’, then entries with duplicates in either the source/target columns are dropped from the mapping. If ‘mto’ (many-to-one), then only duplicates in the source column are dropped. If ‘otm’, then only duplicates in the target column are dropped. Finally, if ‘none’, no duplicates are removed from the mapping.
• kwargs (Dict[str, Any]) – Extra keyword arguments for the requested mapper.

Returns:

List of mapped IDs.

Return type:

List[str]

genemap.map_dataframe(df, mapper, drop_duplicates='both', **kwargs)

Maps dataframe index using the given mapper.

Parameters:

• df (pandas.DataFrame) – DataFrame to map.
• mapper (str) – Name of the required mapper (e.g. ‘ensembl’, ‘mgi’, ‘custom’).
• drop_duplicates (str) – How to handle duplicates. If ‘both’, then entries with duplicates in either the source/target columns are dropped from the mapping. If ‘mto’ (many-to-one), then only duplicates in the source column are dropped. If ‘otm’, then only duplicates in the target column are dropped. Finally, if ‘none’, no duplicates are removed from the mapping.
• kwargs (Dict[str, Any]) – Extra keyword arguments for the requested mapper.

Returns:

List of mapped IDs.

Return type:

List[str]

genemap.fetch_mapping(mapper, drop_duplicates='both', **kwargs)

Fetches map used by given mapper.

Returns the mapping that is actually used to map the IDs. This is is mainly useful if you are interested in the mapping itself or want to perform more complicated mappings than are provided by the map_ids and map_dataframe methods.

Parameters:

• mapper (str) – Name of the required mapper (e.g. ‘ensembl’, ‘mgi’, ‘custom’).
• drop_duplicates (str) – How to handle duplicates. If ‘both’, then entries with duplicates in either the source/target columns are dropped from the mapping. If ‘mto’ (many-to-one), then only duplicates in the source column are dropped. If ‘otm’, then only duplicates in the target column are dropped. Finally, if ‘none’, no duplicates are removed from the mapping.
• kwargs (Dict[str, Any]) – Extra keyword arguments for the requested mapper.

Returns:

DataFrame describing the used mapping. The DataFrame contains two columns, the first of which contains the source idenfiers (from which we map), whereas the second contains the target idenfiers (to which we map).

Return type:

pandas.DataFrame

Mapper classes

class genemap.mappers.Mapper(drop_duplicates='both')

Base mapper class.

fetch_mapping()

Fetches mapping used to map ids.

Returns the mapping that is actually used to map the IDs. This is is mainly useful if you are interested in the mapping itself or want to perform more complicated mappings than are provided by the map_ids and map_dataframe methods.

Returns:DataFrame describing the used mapping. The DataFrame contains two columns, the first of which contains the source idenfiers (from which we map), whereas the second contains the target idenfiers (to which we map). Return type:pandas.DataFrame

map_dataframe(df)

Maps index of a dataframe to new values.

Parameters:df (pandas.DataFrame) – DataFrame to map. Returns:Mapped DataFrame in which the index values have been mapped to a new identifier type. Return type:pandas.DataFrame

map_ids(ids)

Maps a list of IDs to new values.

Parameters:ids (List[str]) – List of IDs to map. Returns:List of mapped IDs. Return type:List[str]

class genemap.mappers.EnsemblMapper(from_type, to_type, drop_duplicates='both', from_organism='hsapiens', to_organism=None, host='http://ensembl.org', drop_lrg=True)

Ensembl mapper class.

Maps IDs using Ensembl (via its Biomart interface). As such, this mapper can translate between gene ID types that are available via Ensembls Biomart interface, as well as between the different species available in Ensembl.

Parameters:

• from_type (str) – The source identifier type. Can be the name of any identifier specified in the Ensembl database or one of the available aliases (symbol, entrez or ensembl).
• to_type (str) – The target identifier type (see from_type for more details).
• drop_duplicates (str) – How to handle duplicates. If ‘both’, then entries with duplicates in either the source/target columns are dropped from the mapping. If ‘mto’ (many-to-one), then only duplicates in the source column are dropped. If ‘otm’, then only duplicates in the target column are dropped. Finally, if ‘none’, no duplicates are removed from the mapping.
• from_organism (str) – Name of the source organism.
• to_organism (str) – Name of the target organism. If not given, no mapping between organisms is performed.
• host (str) – The URL to use for accessing Ensembls Biomart. Can be changed to access Ensembls archived datasets.
• drop_lrg (bool) – Whether to drop gene entries starting with ‘LRG’ when mapping to/from Ensembl IDs.

available_aliases()

Return the available aliases for gene ids.

Returns:Dict of aliases. Return type:Dict[str,str]

class genemap.mappers.MgiMapper(from_type, to_type, drop_duplicates='both', from_organism='mouse', to_organism=None, map_url='http://www.informatics.jax.org/downloads/reports/HOM_AllOrganism.rpt')

MGI mapper class.

Maps IDs using the homology table provided by MGI. Supports mapping between gene symbols and Entrez identifers and between several specifies (using orthologous genes).

Parameters:

• from_type (str) – The source identifier type. Can be either ‘symbol’ or ‘entrez’.
• to_type (str) – The target identifier type (see from_type for more details).
• drop_duplicates (str) – How to handle duplicates. If ‘both’, then entries with duplicates in either the source/target columns are dropped from the mapping. If ‘mto’ (many-to-one), then only duplicates in the source column are dropped. If ‘otm’, then only duplicates in the target column are dropped. Finally, if ‘none’, no duplicates are removed from the mapping.
• from_organism (str) – Name of the source organism.
• to_organism (str) – Name of the target organism. If not given, no mapping between organisms is performed.
• map_url (str) – The URL to use to fetch the mapping table from MGI.

class genemap.mappers.CustomMapper(mapping, drop_duplicates='both')

Custom mapper class.

Maps identifiers using a custom mapping provided by the user. The nature of the performed mapping depends on the provided mapping table.

Parameters:

• mapping (pandas.DataFrame) – Dataframe containing the mapping. Is expected to contain exactly two columns, the first of which contains the source ID type, the second of which contains the target ID type.
• drop_duplicates (str) – How to handle duplicates. If ‘both’, then entries with duplicates in either the source/target columns are dropped from the mapping. If ‘mto’ (many-to-one), then only duplicates in the source column are dropped. If ‘otm’, then only duplicates in the target column are dropped. Finally, if ‘none’, no duplicates are removed from the mapping.

class genemap.mappers.ChainedMapper(mappers, drop_duplicates='both')

Chained mapper class.

Maps identifiers using multiple mappers in a chained fashion. In this approach the first mapper maps from type a –> type b, whilst the second maps b –> c, etc. This chained mapper essentially ‘chains’ the mappings of the given mappers to provide a mapping from the to_type of the first mapper to the from_type of the last mapper. (In the two mapper example, this provides a mapping from a –> c).

Parameters:

• mappers (List[Mapper]) – List of Mapper instances to chain.
• drop_duplicates (str) – How to handle duplicates in the mapping.

class genemap.mappers.CombinedMapper(mappers, augment=False, drop_duplicates='both')

Combined mapper class.

Maps identifiers by combining the mappings of multiple mappers. In this setup, mappers are assumed to map the same identifier types (mapper 1 maps from a –> b, as does mapper 2). The mappers may however not be complete, meaning that mapper 2 may contain additional mappings not contained in mapper 1 and vice versa. This combined mapper essentially merges the mappings from both mappers, providing a more comprehensive mapping containing entries from each mapper.

Parameters:

• mappers (List[Mapper]) – List of Mapper instances to combine.
• drop_duplicates (str) – How to handle duplicates in the mapping.