Metadata-Version: 2.5
Name: baseqdb
Version: 0.10.1
Summary: Your baSeq datasets, analyses and results from Python, with lamindb's names
Project-URL: Homepage, https://baseq.bio
Project-URL: Documentation, https://baseq.bio/docs/python-and-r.html
Author-email: baSeq ApS <info@baseq.dk>
License-Expression: MIT
License-File: LICENSE
Keywords: baseq,bioinformatics,lineage,provenance,rna-seq,single-cell
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Requires-Dist: pandas>=1.5
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == 'pandas'
Description-Content-Type: text/markdown

# baseqdb

Your baSeq datasets, the analyses built on them, what they found and where a result came from, from Python.

```python
import baseqdb as bq
bq.login()                                      # reads BASEQ_API_KEY

bq.Dataset.filter(kind="bulk").to_dataframe()   # yours, newest versions
bq.Dataset.filter(organism="human", condition="dexamethasone")   # by any column of the sample sheets
bq.Dataset.search("dexamethasone")              # as the Data page's search
bq.Analysis.filter(kind="bulk").to_dataframe()  # the analyses you can open, newest first
ds = bq.Dataset.get("kTIqMTTm89P2gbNU0000")     # one version, by its uid
folder = ds.cache()                             # its files, downloaded once
sheet = ds.sample_sheet                         # a DataFrame
bq.Gene.standardize(["ENSG00000109906.15"])     # ['ZBTB16']: genes named as baSeq names them
genes = bq.Gene.df("human")                     # every gene: id, symbol, biotype

analysis = ds.analyses[0]
analysis.steps.to_dataframe()                   # each step, its settings, when it ran
analysis.findings.to_dataframe()                # what each step found
table = analysis.tables["dge_condition_dexamethasone_vs_untreated.csv"].load()

record = bq.Record.get("Z3HMY4V1wC6goA380000")  # a file a step wrote
record.run.inputs                               # the records it read
ds.run.initiated_by                             # the run a version added from code was added in
```

With a key that may add data ("Read and add data"), add a dataset. With the name and kind of one you have, it is its
next version, which starts what that dataset's "When a new version is added" says:

```python
new = bq.Dataset(["counts_filtered.tsv"], name="Airway demo", kind="bulk", sample_sheet="samples.csv").save()
new.version                                     # 2: the next version
new.notes                                       # what else to know, such as what the new version started
```

## Track your code

One line at the top makes a script one run on baSeq, as lamindb's `ln.track()`: its code (kept as a version of the
script), its command line and environment, the files it downloads from baSeq (what it read), the datasets it adds and
the files it saves, and what it found when it says. Reads are counted, not listed one by one; everything a run adds is
kept. Its page on baSeq is under Scripts, Runs outside baSeq; what it found is in your lab's findings too, marked From
code, never taken for a step's checked finding.

```python
bq.track()                                      # this script, as one run
counts = ds.files["counts.tsv"].load()          # noted as what the run read
bq.Record("dge_dex.csv").save()                 # a file of the run
bq.finish(finding="Dexamethasone raised ZBTB16 and FKBP5 the most.",
          genes=["ZBTB16+", "FKBP5+"])          # what it found; or let the script end: an exception ends it as errored
```

## With an AI agent

An agent such as Claude Code can use baseqdb with your key. Ask it to begin each task with `baseqdb track` and end it
with `baseqdb finish`: everything it runs in that folder in between is one run, however many commands it takes.

```sh
baseqdb track "Dexamethasone response in Airway"
python filter_counts.py --min-reads 10          # joins the run
python dge_dex.py --padj 0.01                   # joins the run
baseqdb finish --finding "ZBTB16 and FKBP5 rose the most." --gene ZBTB16+ --gene FKBP5+
```

If you are an agent: begin the task with `baseqdb track "<what the task is>"` in its folder, call `bq.track()` at the
top of each script you write, save results you keep with `bq.Record(path).save()`, and end with `baseqdb finish`,
saying in one short paragraph what the task found (`--finding`, with `--gene` for each gene; `--errored` when the task
failed).

Data you fetch with a key leaves baSeq. Our Data Processing Agreement does not cover what an AI agent or another
service then does with it.

Make an API key on your baSeq Account page, under API keys, then:

```sh
pip install baseqdb
baseqdb login                                   # once: your key, kept on this computer
```

The whole guide, with R: https://baseq.bio/docs/python-and-r.html
