Skip to content

Daylily-Informatics/bloom

Repository files navigation

Bloom : Templated Abstract Polymorphic (and opinionated) LIMS

a conceptual gambit in collaboration with chatGPT4 /// POC v0.9.6

BLOOM LIMS Build Tests, MacOS, Ubuntu & CentOS BLOOM LIMS Build Tests, MacOS, Ubuntu & CentOS BLOOM CENTOS

Built from first principles and drawing upon 30 years experience scaling laboratory process. Constructed with as few object model shortcuts as I could manage ( I believe these shortcuts are among the main reasons LIMS nearly universally dissapoint ). Supporting both arbitrary and prescribed interacting objects. Intended for use: by small to factory scale laboratories, in regulated environments, for both research & operations usecases. Bloom can handle multiple areas LIS tend to touch: acessioning, lab processes, specimen/sample management, equipment, regulatory and compliance.

Spoilers

bloom early peeks

Oauth2 Authentication w/All Major Social Providers

and flexible whitelisting, etc...

Graph Object View (add, remove, edit, take actions, explore)

Interactive, Dynamic Metrics

bloom-lims-graph

Accessioning Modalities

Nested Assay / Queue / Workset

bloom-lims-trad-view

Intantiate Objects From Available Templates

bloom-lims-instantiated-abstracts

Object Detail

bloom-lims-obj-view

Specialized Object Detail Views

Labware (ie: a 96w plate)

bloom natively will support arbitrarily defined labware, a 96w plate is just one example. Anything that nested arrays of arrays can describe can be configured as a type of labware with next to no effort! bloom-lims-obj-view

Exhaustive & Comprehensive Audit Trails (+soft deletes only)

bloom-lims-audit

Bells And Whistles

Integrated Barcode Label Printing For All Objects

Workflows Available

Accessioning

Pacage receipt -> kits registration (multiple) -> specimen registration (multiple) -> requisition capture & association -> adding specimens to assay queues. Fedex tracking details fetched, barcode printing available.

Plasma Isolation -> DNA Extraction -> DNA Quant

managing all object relationships, tracking all details, printing labels, etc.

Installation

Prerequisites

Hardware Supported

see build test badges above for all supported platforms

  • Mac (14+)
    • brew install coreutils is required for the gtimeout command for some rclone functionality. run alias timeout=gtimeout to use the gtimeout w/zsh.
  • Ubuntu 22+
  • Centos 9

Conda

  • Conda (you may swap in mamba if you prefer). Installing conda:

    • be sure wget is available to you.

    linux a pinned version: https://repo.anaconda.com/miniconda/Miniconda3-py312_24.5.0-0-Linux-x86_64.sh

    x86_64: wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

    arm64: wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh

    macOS

    intel: wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh

    ARM: wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh

    • Then execute the Miniconda.sh script, follow the prompts, when installation completed, follow these last 2 steps:
~/miniconda3/bin/conda init
bash  # newly created shells should not auto load the conda (base) env.

Supabase

Very Quickest Start

assumes you have completed the prerequisites

# Clone the repository
git clone [email protected]:Daylily-Informatics/bloom_lims.git
cd bloom_lims

# This will attempt to build the conda env, install postgres, the database, build the schema and start postgres
source bloom_lims/env/install_postgres.sh 
 
# conda activate BLOOM if is has not happened already.

# Start the Bloom LIMS UI
source run_bloomui.sh

(optional) Install & Run pgadmin4 Database Admin UI

# RUN TESTS
pytest

# START THE UIs (on localhost:8080)
source bloom_lims/env/install_pgadmin.sh 

Integrations

CRMs

If they have APIs, integration to fetch things like physician or patient identifiers/metadata is straight forward.

Zebra Barcode Label Printing

FedEx Tracking API Integration

  • In place, no docs yet, but will work if you create the config yaml file for this library: fedex_tracking_day.

ie: Salesforce

  • with simple_salesforce or salesforce python packages, would be very straight forward.

Design Principles

Enterprise UIDs

Each Object Has A UUID & UUIDs Are Immutable & UUIDs Are Not Reused Or Applied To Other Objects

  • Using a UUID on children objects for convenience will lead to a mess as the need to know details about each object is next to impossible when a UUID is assigned to multiple objects.

The UID Identifies The Object Class And The UUID w/in The Class

Exhaustive Metadata About An Object May Be Queried Using The Enterprise UUID.

Metadata may also be printed on labels along with the UUID.
  • Keeping metadata out of the UUID formula is a fundamental requirement in building flexible and scalable systems. FUNDAMENTAL.

Trust The Database To Manage The UUIDs

  • ...

Clear And Concise Data Model

  • ...

TSV's not CSV's

  • there are few/no compelling reasons to use CSV's over TSV's & so many reasons not to use CSV's.

All LIMS Data Editable w/CRUD UI

  • It is! Fully (though with some safeguards still not in place).
    • soft deletes need to be reviewed more closely

Easily configurable object definitions as well as actions (ie workflows, etc)

  • Requiring as little code changes as possible.

Other

Use Cases

LIMS Actions (must have)

Many To Many Relationships Among All Objects

All other relationships are subsets of this, and designing parts of the LIMS which disallow many to many will result in an inflexible system.

Objects May Be Involved In Multiple Workflows Simultaneously

Support For Predefined and Arbitrary Workflows

Objects may all be: root (singleton, parent & able to become a child at some point), child(singleton, parent and possibly terminal) of one another

Zero Loss Of Data (comprehensive audit trails, soft deletes) && 100% Audit Coverage

Deployment & Maintanence

You may deploy bloom wherever it will run. This does mean you are responsible for all aspects of the deployment, including security, backups (AND recovery), performance optimization, monitoring, etc. This need not be daunting. I am available for consulting on there topics.

Testing

  • with pytest
conda activate BLOOM
pytest

Regulatory & Compliance

CLIA

  • There is no reason bloom can not be used in a CLIA regulated environment.

CAP

  • Bloom can satisfy all relevant CAP checklist items which apply to it. But, as it is s/w you will be running yourself, most checklist items will be concerned with the environment you are using bloom in.

HIPAA

  • If installed in an already HIPAA compliant environment, bloom should not need much or any work to be compliant.

Support

  • no promises, please file issues to log a bug or request a feature.

Authors

License

  • MIT

References // Acknowledgments

Dev Tools

note: all commands below are expected to be run from a shell with conda activated. conda activate BLOOM

Drop The Entire Database(loose all data!) > Rebuild The Database / Re-seed With All Accessible json Templates

The steps are wrapped in a script, please see clear_and_rebuild_postgres.sh.

It is executed as follows:

source clear_and_rebuild_postgres.sh

Stop pgsql

  • source bloom_lims/bin/stop_bloom_db.sh

Remove the db

  • rm -rf bloom_lims/database/*

Rebuild the schema

  • source bloom_lims/env/install_postgres.sh skip the skip will skip building the conda env. This will start pgsql in the env, and build the schema.

Build LIMS Workflows With Autogen Objects

Similar to pytest, but more extensive. Largely useful in development work. The following will auto-gen 'n=2' passes of the lims schema

  • python tx.py 2 .

Run the bloom UI

  • source source run_bloomui.sh

Run the pgadmin UI

  • source bloom_lims/env/install_pgadmin.sh

Start Interactive Shell w/Core Bloom Objects Instantiated

python bloom_shell.py

Random Notes

File System Case Sensitivity

MacOS is Not Case Sensitive

echo "test" >test.log
echo "TEST" >TEST.LOG
more test.log
TEST
more TEST.log
TEST
  • This still shocks me & is worth a reminder.

Ubuntu Is Case Sensitive

echo "test" > test.log
echo "TEST" > TEST.LOG
more test.log
test
TEST.LOG
TEST

Assume Case Insensitivity In All File Names

  • Given we can not be certain where files will be reconstituted, we must assume that files might be created in a cases insensitive file system when allowing download.

Bloom UUIDs and EUIDs Are Safe As File Names

A widely adopted UUID spec (and used by postgres), rfc4122, treates uc and lc as the same character. Bloom EUIDs only contain uc characters in a prefix followed by integers.