Skip to content

Atlas

Atlas is a user-defined collection of tables that combines the spreadsheets with the relational databases. Each table organizes data around a specific clinical factor or other criteria. With Atlas, users can seamlessly structure and analyze complex datasets.

Parameters:

  • atlas_id (str) –

    Atlas ID

Usage

from polly.auth import Polly from polly.atlas import Atlas, Table, Column

Polly.auth("")

atlas = Atlas(atlas_id="atlas_1")

create_atlas classmethod 

create_atlas(atlas_id, atlas_name)

Creates a new atlas with the specified name and atlas id.

Parameters:

  • atlas_id (str) –

    The id of the new atlas to create.

  • atlas_name (str) –

    Name of atlas to be created.

Returns:

  • –

    The newly created Atlas object.

Examples:

>>> atlas = Atlas.create_atlas(atlas_id='my_atlas', atlas_name='My Atlas')

create_table 

create_table(table_name, columns, rows=None)

Create a new table with the specified name and columns.

Parameters:

  • table_name (str) –

    The name of the new table to create.

  • columns (List[Column]) –

    A list of Column objects representing the columns of the new table.

  • rows (list, default: None ) –

    A list of key-value pairs representing the table data.

Returns:

  • Table –

    The newly created Table object.

Examples:

>>> atlas = Atlas(atlas_id='my_atlas')
>>> columns = [
>>>    Column(column_name='patient_id', data_type='integer', primary_key=True),
>>>    Column(column_name='patient_ name', data_type='text')
>>> ]
>>> patient_table = atlas.create_table(table_name='patient', columns=columns)

delete_atlas classmethod 

delete_atlas(atlas_id)

Delete an atlas based on its atlas id.

Parameters:

  • Atlas_id –

    The id of the atlas to be deleted

Examples:

>>> atlas.delete_atlas(atlas_id="atlas_1")

delete_table 

delete_table(table_name)

Delete the table from the atlas.

Parameters:

  • table_name (str) –

    The name of the table to delete.

Examples:

>>> atlas = Atlas(atlas_id='atlas_1')
>>> atlas.delete_table(table_name='patient')

exists 

exists()

Return True if atlas exists else False

Returns:

  • bool –

    The name of the Atlas as a string

Examples:

>>> atlas = Atlas(atlas_id='atlas_1')
>>> atlas.exists()
True

get_name 

get_name()

Retrieve the name of the Atlas using the Atlas ID

Returns:

  • str –

    The name of the Atlas as a string

Examples:

>>> atlas = Atlas(atlas_id='atlas_1')
>>> atlas.get_name()
'My Atlas'

get_table 

get_table(table_name)

Retrieve a specific table object by name.

Parameters:

  • table_name (str) –

    The name of the table to retrieve.

Returns:

  • Table –

    The Table object representing the specified table.

Notes

It loads the table object and not the table data. Use to_df() function to do so.

Examples:

>>> atlas = Atlas(atlas_id='1234')
>>> table = atlas.get_table(table_name='my_table')

list_atlases classmethod 

list_atlases()

Retrieve the list of atlases associated with an Atlas id.

Returns:

  • –

    A list of Atlas objects representing the atlases associated with an Atlas ID.

Examples:

>>> Atlas.list_atlases()

list_tables 

list_tables()

Retrieve the list of tables associated with an Atlas.

Returns:

  • Table –

    A list of Table objects representing the tables associated with an Atlas.

Examples:

>>> atlas = Atlas(atlas_id='atlas_1')
>>> tables = atlas.list_tables()

query 

query(query)

Execute a query on the Atlas tables.

Parameters:

  • query (str) –

    The SQL query to execute.

Returns:

  • DataFrame –

    The result of the query execution.

Examples:

>>> atlas = Atlas(atlas_id='atlas_1')
>>> result = atlas.query(query='SELECT * FROM patient;')

rename_table 

rename_table(old_table_name, new_table_name)

Rename the name of an existing table in the Atlas.

Parameters:

  • old_table_name (str) –

    The current name of the table to rename.

  • new_table_name (str) –

    The new name to assign to the table.

Returns:

  • Table –

    The renamed Table object.

Examples:

>>> atlas = Atlas(atlas_id='my_atlas')
>>> renamed_table = atlas.rename_table(old_table_name='patient', new_table_name='patient_info')

Examples

Create/Delete Atlas

Polly.auth("<access_key>")

Atlas.create_atlas(atlas_id='my_atlas', atlas_name="My Atlas")

# Atlas(atlas_id=my_atlas)

atlas.delete_atlas(atlas_id='my_atlas')

List Atlas Tables

atlas.list_tables()

#[
# Table(
#  table_name='gene_table', 
#  columns=[
#   Column(column_name='gene', data_type='text', primary_key=True),
#   Column(column_name='basemean', data_type='numeric'),
#   Column(column_name='log2foldchange', data_type='decimal'),
#   Column(column_name='lfcse', data_type='integer'),
#   Column(column_name='stat', data_type='numeric'),
#   Column(column_name='pvalue', data_type='double precision'),
#   Column(column_name='padj', data_type='numeric'), 
#   Column(column_name='negative_log10_padj', data_type='numeric'),
#   Column(column_name='data_type', data_type='text'),
#   Column(column_name='dataset_id', data_type='text')
#  ]
# ),
# Table(
#  table_name='patient',
#  columns=[
#    Column(column_name='curated_patient_id', data_type='text',primary_key=True),
#    Column(column_name='alcohol_history', data_type='boolean'),
#    Column(column_name='alcohol_intensity', data_type='text'),
#    Column(column_name='tobacco_smoking', data_type='integer')
#  ]
# )
#]

Rename a Table in Atlas

table=atlas.rename_table(old_table_name='patient', new_table_name='patients_info')
print(atlas.get_table(atlas_id='atlas_1', table_name='patients_info'))

#Table(
# table_name='patients_info',
# columns=[
#   Column(column_name='curated_patient_id', data_type='text',primary_key=True), 
#   Column(column_name='alcohol_history', data_type='boolean'),
#   Column(column_name='alcohol_intensity', data_type='text'), 
#   Column(column_name='tobacco_smoking', data_type='integer')
# ]
#)

Query any table from the atlas

atlas.query("SELECT * FROM patient LIMIT 10;")
#                              alcohol_history alcohol_intensity  tobacco_smoking
# curated_patient_id                                                             
# patient_1718265078961285000            False              None                4
# patient_1718265078961325000             True          Moderate                2
# patient_1718265078961336000            False          Moderate                2
# patient_1718265078961344000            False               Low                9
# patient_1718265078961350000            False               Low                4
# patient_1718265078961358000            False               Low                7
# patient_1718265078961364000            False              None                0
# patient_1718265078961371000             True               Low                1
# patient_1718265078961377000             True              None                7
# patient_1718265078961385000             True          Moderate                4

Add a new table to an atlas/ deleting existing one

columns = [
    Column(column_name="curated_patient_id", data_type="text"),
    Column(column_name="alcohol_history", data_type="boolean"),
    Column(column_name="alcohol_intensity", data_type="text"),
    Column(column_name="tobacco_smoking", data_type="integer"),
]
new_table = atlas.create_table(table_name="patient_exposure", columns=columns)
print(new_table)

# Table(
#   table_name='patient_exposure', 
#   columns = [
#     Column(column_name="curated_patient_id", data_type="text"),
#     Column(column_name="alcohol_history", data_type="boolean"),
#     Column(column_name="alcohol_intensity", data_type="text"),
#     Column(column_name="tobacco_smoking", data_type="integer"),
#   ]     
# )

atlas.delete_table(table_name="my_table")