Analysis flow¶

Here, we’ll track typical data transformations like subsetting that occur during analysis.

If exploring more generally, read this first: Project flow.

Setup¶

# a lamindb instance containing Bionty schema
!lamin init --storage ./analysis-usecase --schema bionty

import lamindb as ln
import bionty as bt
from lamin_utils import logger

bt.settings.auto_save_parents = False

💡 connected lamindb: testuser1/analysis-usecase

Register an initial dataset¶

Here we register an initial artifact with a pipeline script register_example_file.py.

!python analysis-flow-scripts/register_example_file.py

Show code cell output Hide code cell output

💡 connected lamindb: testuser1/analysis-usecase

💡 saved: Transform(version='0', uid='K4wsS5DTYdFp6K79', name='register_example_file.py', key='register_example_file.py', type='script', updated_at=2024-05-20 08:35:50 UTC, created_by_id=1)
💡 saved: Run(uid='949bg4NNAUpq6KaVLoZ4', transform_id=1, created_by_id=1)

✅ added 3 records with Feature.name for columns: ['cell_type', 'tissue', 'disease']

❗ 1 non-validated categories are not saved in Feature.name: ['cell_type_id']!
      → to lookup categories, use lookup().columns
      → to save, run add_new_from_columns

✅ added 99 records from public with Gene.ensembl_gene_id for var_index: ['ENSG00000000003', 'ENSG00000000005', 'ENSG00000000419', 'ENSG00000000457', 'ENSG00000000460', 'ENSG00000000938', 'ENSG00000000971', 'ENSG00000001036', 'ENSG00000001084', 'ENSG00000001167', 'ENSG00000001460', 'ENSG00000001461', 'ENSG00000001497', 'ENSG00000001561', 'ENSG00000001617', 'ENSG00000001626', 'ENSG00000001629', 'ENSG00000001630', 'ENSG00000001631', 'ENSG00000002016', 'ENSG00000002079', 'ENSG00000002330', 'ENSG00000002549', 'ENSG00000002586', 'ENSG00000002587', 'ENSG00000002726', 'ENSG00000002745', 'ENSG00000002746', 'ENSG00000002822', 'ENSG00000002834', 'ENSG00000002919', 'ENSG00000002933', 'ENSG00000003056', 'ENSG00000003096', 'ENSG00000003137', 'ENSG00000003147', 'ENSG00000003249', 'ENSG00000003393', 'ENSG00000003400', 'ENSG00000003402', 'ENSG00000003436', 'ENSG00000003509', 'ENSG00000003756', 'ENSG00000003987', 'ENSG00000003989', 'ENSG00000004059', 'ENSG00000004139', 'ENSG00000004142', 'ENSG00000004399', 'ENSG00000004455', 'ENSG00000004468', 'ENSG00000004478', 'ENSG00000004487', 'ENSG00000004534', 'ENSG00000004660', 'ENSG00000004700', 'ENSG00000004766', 'ENSG00000004776', 'ENSG00000004777', 'ENSG00000004779', 'ENSG00000004799', 'ENSG00000004809', 'ENSG00000004838', 'ENSG00000004846', 'ENSG00000004848', 'ENSG00000004864', 'ENSG00000004866', 'ENSG00000004897', 'ENSG00000004939', 'ENSG00000004948', 'ENSG00000004961', 'ENSG00000004975', 'ENSG00000005001', 'ENSG00000005007', 'ENSG00000005020', 'ENSG00000005022', 'ENSG00000005059', 'ENSG00000005073', 'ENSG00000005075', 'ENSG00000005100', 'ENSG00000005102', 'ENSG00000005108', 'ENSG00000005156', 'ENSG00000005175', 'ENSG00000005187', 'ENSG00000005189', 'ENSG00000005194', 'ENSG00000005206', 'ENSG00000005238', 'ENSG00000005243', 'ENSG00000005249', 'ENSG00000005302', 'ENSG00000005339', 'ENSG00000005379', 'ENSG00000005381', 'ENSG00000005421', 'ENSG00000005436', 'ENSG00000005448', 'ENSG00000005469']
💡 saving labels for 'cell_type'

✅ added 3 records from public with CellType.name for cell_type: ['T cell', 'hematopoietic stem cell', 'hepatocyte']
❗ 1 non-validated categories are not saved in CellType.name: ['my new cell type']!
      → to lookup categories, use lookup().cell_type
      → to save, run .add_new_from('cell_type')
💡 saving labels for 'tissue'

✅ added 4 records from public with Tissue.name for tissue: ['kidney', 'liver', 'heart', 'brain']
💡 saving labels for 'disease'

✅ added 4 records from public with Disease.name for disease: ['chronic kidney disease', 'liver lymphoma', 'cardiac ventricle disorder', 'Alzheimer disease']

✅ added 1 record with CellType.name for cell_type: ['my new cell type']

✅ var_index is validated against Gene.ensembl_gene_id
✅ cell_type is validated against CellType.name
✅ tissue is validated against Tissue.name

✅ disease is validated against Disease.name
💡 path content will be copied to default storage upon `save()` with key `None` ('.lamindb/MEh2K3KuL5KMGPgcuEcw.h5ad')
✅ storing artifact 'MEh2K3KuL5KMGPgcuEcw' at '/home/runner/work/lamin-usecases/lamin-usecases/docs/analysis-usecase/.lamindb/MEh2K3KuL5KMGPgcuEcw.h5ad'
💡 parsing feature names of X stored in slot 'var'
✅    99 terms (100.00%) are validated for ensembl_gene_id
✅    linked: FeatureSet(uid='9SWU3JNIUL2rEN88Qmf9', n=99, dtype='float', registry='bionty.Gene', hash='-frOq7J0bik-J7Ad9DX7', created_by_id=1)
💡 parsing feature names of slot 'obs'
✅    3 terms (75.00%) are validated for name
❗    1 term (25.00%) is not validated for name: cell_type_id

✅    linked: FeatureSet(uid='4evfvq9TYg8s69m6a5Bg', n=3, registry='Feature', hash='U8uGHxhO1-LcOxSHR2LC', created_by_id=1)
✅ saved 2 feature sets for slots: 'var','obs'
✅ linked feature 'cell_type' to registry 'bionty.CellType'
✅ linked feature 'tissue' to registry 'bionty.Tissue'

✅ linked feature 'disease' to registry 'bionty.Disease'
✅ saved transform.source_code: Artifact(version='0', updated_at=2024-05-20 08:36:34 UTC, uid='Q5xAOswyhSEmTmOUq887', suffix='.py', description='Source of transform K4wsS5DTYdFp6K79', size=699, hash='p9yfNIWwDKdfz8URlTmM0Q', hash_type='md5', visibility=0, key_is_virtual=True, created_by_id=1, storage_id=1)
✅ saved run.environment: Artifact(updated_at=2024-05-20 08:36:34 UTC, uid='gHtVVaxTRvg54yU15WdB', suffix='.txt', description='requirements.txt', size=3344, hash='DX4AZkvBPK-hfIpUcdAU0Q', hash_type='md5', visibility=0, key_is_virtual=True, created_by_id=1, storage_id=1)

Pull the registered dataset, apply a transformation, and register the result¶

Track the current notebook:

ln.settings.transform.stem_uid = "eNef4Arw8nNM"
ln.settings.transform.version = "0"
ln.track()

💡 notebook imports: bionty==0.43.0 lamin_utils==0.13.2 lamindb==0.72.0

💡 saved: Transform(version='0', uid='eNef4Arw8nNM6K79', name='Analysis flow', key='analysis-flow', type='notebook', updated_at=2024-05-20 08:36:34 UTC, created_by_id=1)

💡 saved: Run(uid='ZDwjMXVcv9f2Q6plqSd6', transform_id=2, created_by_id=1)

artifact = ln.Artifact.filter(description="anndata with obs").one()
artifact.describe()

Artifact(updated_at=2024-05-20 08:36:33 UTC, uid='MEh2K3KuL5KMGPgcuEcw', suffix='.h5ad', accessor='AnnData', description='anndata with obs', size=46992, hash='IJORtcQUSS11QBqD-nTD0A', hash_type='md5', n_observations=40, visibility=1, key_is_virtual=True)

Provenance:
  📎 created_by: User(uid='DzTjkKse', handle='testuser1', name='Test User1')
  📎 storage: uid='jZuGaNrELh7M', root='/home/runner/work/lamin-usecases/lamin-usecases/docs/analysis-usecase', type='local', instance_uid='C46ryhMWM0LV')
  📎 transform: Transform(version='0', uid='K4wsS5DTYdFp6K79', name='register_example_file.py', key='register_example_file.py', type='script')
  📎 run: Run(uid='949bg4NNAUpq6KaVLoZ4', started_at=2024-05-20 08:35:50 UTC, finished_at=2024-05-20 08:36:34 UTC, is_consecutive=True)
Features:
  var: FeatureSet(uid='9SWU3JNIUL2rEN88Qmf9', n=99, dtype='float', registry='bionty.Gene')
    'TSPAN6', 'TNMD', 'DPM1', 'SCYL3', 'C1orf112', 'FGR', 'CFH', 'FUCA2', 'GCLC', 'NFYA', 'STPG1', 'NIPAL3', 'LAS1L', 'ENPP4', 'SEMA3F', 'CFTR', 'ANKIB1', 'CYP51A1', 'KRIT1', 'RAD52'
  obs: FeatureSet(uid='4evfvq9TYg8s69m6a5Bg', n=3, registry='Feature')
    🔗 cell_type (3, cat[bionty.CellType]): 'my new cell type', 'T cell', 'hematopoietic stem cell', 'hepatocyte'
    🔗 tissue (3, cat[bionty.Tissue]): 'kidney', 'liver', 'heart', 'brain'
    🔗 disease (3, cat[bionty.Disease]): 'chronic kidney disease', 'liver lymphoma', 'cardiac ventricle disorder', 'Alzheimer disease'
Labels:
  📎 tissues (4, bionty.Tissue): 'kidney', 'liver', 'heart', 'brain'
  📎 cell_types (4, bionty.CellType): 'my new cell type', 'T cell', 'hematopoietic stem cell', 'hepatocyte'
  📎 diseases (4, bionty.Disease): 'chronic kidney disease', 'liver lymphoma', 'cardiac ventricle disorder', 'Alzheimer disease'

Get a backed AnnData object¶

adata = artifact.backed()
adata

AnnDataAccessor object with n_obs × n_vars = 40 × 100
  constructed for the AnnData object MEh2K3KuL5KMGPgcuEcw.h5ad
    obs: ['_index', 'cell_type', 'cell_type_id', 'disease', 'tissue']
    var: ['_index']

Subset dataset to specific cell types and diseases¶

cell_types = artifact.cell_types.all().lookup(return_field="name")
diseases = artifact.diseases.all().lookup(return_field="name")

Create the subset:

subset_obs = adata.obs.cell_type.isin(
    [cell_types.t_cell, cell_types.hematopoietic_stem_cell]
) & (adata.obs.disease.isin([diseases.liver_lymphoma, diseases.chronic_kidney_disease]))

adata_subset = adata[subset_obs]
adata_subset

AnnDataAccessorSubset object with n_obs × n_vars = 20 × 100
  obs: ['_index', 'cell_type', 'cell_type_id', 'disease', 'tissue']
  var: ['_index']

adata_subset.obs[["cell_type", "disease"]].value_counts()

cell_type                disease               
T cell                   chronic kidney disease    10
hematopoietic stem cell  liver lymphoma            10
dtype: int64

annotate = ln.Annotate.from_anndata(
    adata_subset.to_memory(), 
    var_index=bt.Gene.ensembl_gene_id, 
    categoricals={
        "cell_type": bt.CellType.name, 
        "disease": bt.Disease.name, 
        "tissue": bt.Tissue.name,
    },
    organism="human"
)

annotate.validate()

artifact = annotate.save_artifact(description="anndata with obs subset")

artifact.describe()

Artifact(updated_at=2024-05-20 08:36:35 UTC, uid='NmMa0w5lK7YTORZgYr3c', suffix='.h5ad', accessor='AnnData', description='anndata with obs subset', size=38992, hash='RgGUx7ndRplZZSmalTAWiw', hash_type='md5', n_observations=20, visibility=1, key_is_virtual=True)

Provenance:
  📎 created_by: User(uid='DzTjkKse', handle='testuser1', name='Test User1')
  📎 storage: uid='jZuGaNrELh7M', root='/home/runner/work/lamin-usecases/lamin-usecases/docs/analysis-usecase', type='local', instance_uid='C46ryhMWM0LV')
  📎 transform: Transform(version='0', uid='eNef4Arw8nNM6K79', name='Analysis flow', key='analysis-flow', type='notebook')
  📎 run: Run(uid='ZDwjMXVcv9f2Q6plqSd6', started_at=2024-05-20 08:36:34 UTC, is_consecutive=True)
Features:
  var: FeatureSet(uid='9SWU3JNIUL2rEN88Qmf9', n=99, dtype='float', registry='bionty.Gene')
    'TSPAN6', 'TNMD', 'DPM1', 'SCYL3', 'C1orf112', 'FGR', 'CFH', 'FUCA2', 'GCLC', 'NFYA', 'STPG1', 'NIPAL3', 'LAS1L', 'ENPP4', 'SEMA3F', 'CFTR', 'ANKIB1', 'CYP51A1', 'KRIT1', 'RAD52'
  obs: FeatureSet(uid='4evfvq9TYg8s69m6a5Bg', n=3, registry='Feature')
    🔗 cell_type (3, cat[bionty.CellType]): 'T cell', 'hematopoietic stem cell'
    🔗 tissue (3, cat[bionty.Tissue]): 'kidney', 'liver'
    🔗 disease (3, cat[bionty.Disease]): 'chronic kidney disease', 'liver lymphoma'
Labels:
  📎 tissues (2, bionty.Tissue): 'kidney', 'liver'
  📎 cell_types (2, bionty.CellType): 'T cell', 'hematopoietic stem cell'
  📎 diseases (2, bionty.Disease): 'chronic kidney disease', 'liver lymphoma'

Examine data flow¶

Query a subsetted .h5ad artifact containing “hematopoietic stem cell” and “T cell”:

cell_types = bt.CellType.lookup()

my_subset = ln.Artifact.filter(
    suffix=".h5ad",
    description__endswith="subset",
    cell_types__in=[
        cell_types.hematopoietic_stem_cell,
        cell_types.t_cell,
    ],
).first()

my_subset

Artifact(updated_at=2024-05-20 08:36:35 UTC, uid='NmMa0w5lK7YTORZgYr3c', suffix='.h5ad', accessor='AnnData', description='anndata with obs subset', size=38992, hash='RgGUx7ndRplZZSmalTAWiw', hash_type='md5', n_observations=20, visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=2, run_id=2)

Common questions that might arise are:

What is the history of this artifact?
Which features and labels are associated with it?
Which notebook analyzed and registered this artifact?
By whom?
And which artifact is its parent?

Let’s answer this using LaminDB:

print("--> What is the history of this artifact?\n")
artifact.view_lineage()

print("\n\n--> Which features and labels are associated with it?\n")
logger.print(artifact.features)
logger.print(artifact.labels)

print("\n\n--> Which notebook analyzed and registered this artifact\n")
logger.print(artifact.transform)

print("\n\n--> By whom\n")
logger.print(artifact.created_by)

print("\n\n--> And which artifact is its parent\n")
display(artifact.run.input_artifacts.df())

--> What is the history of this artifact?

_images/635cb7856a3f51ba8ad384eca88a4c44d717d4064aa4d44b2d8a56714cc41205.svg

--> Which features and labels are associated with it?

Features:
  var: FeatureSet(uid='9SWU3JNIUL2rEN88Qmf9', n=99, dtype='float', registry='bionty.Gene')
    'TSPAN6', 'TNMD', 'DPM1', 'SCYL3', 'C1orf112', 'FGR', 'CFH', 'FUCA2', 'GCLC', 'NFYA', 'STPG1', 'NIPAL3', 'LAS1L', 'ENPP4', 'SEMA3F', 'CFTR', 'ANKIB1', 'CYP51A1', 'KRIT1', 'RAD52'
  obs: FeatureSet(uid='4evfvq9TYg8s69m6a5Bg', n=3, registry='Feature')
    🔗 cell_type (3, cat[bionty.CellType]): 'T cell', 'hematopoietic stem cell'
    🔗 tissue (3, cat[bionty.Tissue]): 'kidney', 'liver'
    🔗 disease (3, cat[bionty.Disease]): 'chronic kidney disease', 'liver lymphoma'

Labels:
  📎 tissues (2, bionty.Tissue): 'kidney', 'liver'
  📎 cell_types (2, bionty.CellType): 'T cell', 'hematopoietic stem cell'
  📎 diseases (2, bionty.Disease): 'chronic kidney disease', 'liver lymphoma'

--> Which notebook analyzed and registered this artifact

Transform(version='0', uid='eNef4Arw8nNM6K79', name='Analysis flow', key='analysis-flow', type='notebook', updated_at=2024-05-20 08:36:34 UTC, created_by_id=1)

--> By whom

User(uid='DzTjkKse', handle='testuser1', name='Test User1', updated_at=2024-05-20 08:35:48 UTC)

--> And which artifact is its parent

	version	created_at	created_by_id	updated_at	uid	storage_id	key	suffix	accessor	description	size	hash	hash_type	n_objects	n_observations	transform_id	run_id	visibility	key_is_virtual
id
1	None	2024-05-20 08:36:33.929303+00:00	1	2024-05-20 08:36:33.961557+00:00	MEh2K3KuL5KMGPgcuEcw	1	None	.h5ad	AnnData	anndata with obs	46992	IJORtcQUSS11QBqD-nTD0A	md5	None	40	1	1	1	True

Show code cell content Hide code cell content

!lamin delete --force analysis-usecase
!rm -r ./analysis-usecase

Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.10.14/x64/bin/lamin", line 8, in <module>
    sys.exit(main())
  File "/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/rich_click/rich_command.py", line 367, in __call__
    return super().__call__(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/rich_click/rich_command.py", line 152, in main
    rv = self.invoke(ctx)
  File "/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/lamin_cli/__main__.py", line 103, in delete
    return delete(instance, force=force)
  File "/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/lamindb_setup/_delete.py", line 98, in delete
    n_objects = check_storage_is_empty(
  File "/opt/hostedtoolcache/Python/3.10.14/x64/lib/python3.10/site-packages/lamindb_setup/core/upath.py", line 760, in check_storage_is_empty
    raise InstanceNotEmpty(message)
lamindb_setup.core.upath.InstanceNotEmpty: Storage /home/runner/work/lamin-usecases/lamin-usecases/docs/analysis-usecase/.lamindb contains 4 objects ('_is_initialized' ignored) - delete them prior to deleting the instance
['/home/runner/work/lamin-usecases/lamin-usecases/docs/analysis-usecase/.lamindb/MEh2K3KuL5KMGPgcuEcw.h5ad', '/home/runner/work/lamin-usecases/lamin

-usecases/docs/analysis-usecase/.lamindb/NmMa0w5lK7YTORZgYr3c.h5ad', '/home/runner/work/lamin-usecases/lamin-usecases/docs/analysis-usecase/.lamindb/Q5xAOswyhSEmTmOUq887.py', '/home/runner/work/lamin-usecases/lamin-usecases/docs/analysis-usecase/.lamindb/_is_initialized', '/home/runner/work/lamin-usecases/lamin-usecases/docs/analysis-usecase/.lamindb/gHtVVaxTRvg54yU15WdB.txt']