Metadata-Version: 2.4
Name: fairfetched
Version: 0.1.0a20261015
Summary: data APIs for reproducible data fetching in cheminformatics
Project-URL: Homepage, https://github.com/lucinamay/fairfetched
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: duckdb>=1.5.5
Requires-Dist: polars>=1.35.2
Provides-Extra: track
Requires-Dist: rich>=14.3.3; extra == "track"
Provides-Extra: adrecs
Requires-Dist: fastexcel>=0.12; extra == "adrecs"
Provides-Extra: toxcast
Requires-Dist: fastexcel>=0.12; extra == "toxcast"
Provides-Extra: rdkit
Requires-Dist: rdkit>=2025.9.6; extra == "rdkit"
Provides-Extra: standardise
Requires-Dist: fairfetched[rdkit]; extra == "standardise"
Requires-Dist: chembl-structure-pipeline>=1.2.4; extra == "standardise"
Provides-Extra: split
Requires-Dist: nanoom>=0.1.0a20260815; extra == "split"
Requires-Dist: pulp<4; extra == "split"
Provides-Extra: rough
Requires-Dist: scipy>=1.6; extra == "rough"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: sqlalchemy>=2.0.46; extra == "dev"
Requires-Dist: fairfetched[split]; extra == "dev"
Requires-Dist: fairfetched[rough]; extra == "dev"
Requires-Dist: fairfetched[standardise]; extra == "dev"
Requires-Dist: papyrus-structure-pipeline>=0.0.5; extra == "dev"
Requires-Dist: fairfetched[adrecs]; extra == "dev"
Requires-Dist: fairfetched[toxcast]; extra == "dev"
Requires-Dist: rust-just>=1.46.0; extra == "dev"
Dynamic: license-file

# fairfetched

data APIs for reproducible data fetching in cheminformatics in line with FAIR principles.
the tool is designed such that all raw data is downloaded and kept in one central place (i.e. CHEMBL 37 as the original .db files), and the user has a fast, lightweight, intuitive API to filter / query the data as required for any particular project.

# installation

you can install this package through
`uv add fairfetched` (recommended)

or if you do not use the uv package manager:
`pip install fairfetched`

# examples

you can download Chembl or Papyrus through:

```python
from fairfetched.get import Chembl, Papyrus

# Download the latest ChEMBL release (saves to ~/.data/chembl/<version>)
db = Chembl.from_latest()

# Raw source tables: db.tables.molecule_dictionary or db.lfs["molecule_dictionary"] (both LazyFrames)
# Joined domain views: db.view.bioactivity, db.view.compounds, db.view.proteins, db.view.components
# Parquet file paths: db.parquet_paths
# Raw download paths: db.raw_paths
```

### examples of how to use the LazyFrames:

#### checking columns and datatypes:

```python
from fairfetched.get import Chembl

db = Chembl.demo()
len(db.lfs["activities"].collect_schema())           # 29
db.lfs["activities"].collect_schema().names()[:4]    # ['molregno', 'activity_id', 'assay_id', 'doc_id']
```

#### accessing tables and joined views:

```python
db.tables.molecule_dictionary.filter(molregno=1280).collect()["pref_name"].to_list()  # ['ASPIRIN']
db.view.compounds.collect().shape                                                     # (5, 50)
```

#### selecting and joining tables:

```python
# select specific columns
db.lfs["activities"].filter(molregno=1280).select(
    "activity_id", "assay_id", "standard_value"
).head(3).collect()
# shape: (3, 3)
# ┌─────────────┬──────────┬────────────────┐
# │ activity_id ┆ assay_id ┆ standard_value │
# ├─────────────┼──────────┼────────────────┤
# │ ...         ┆ ...      ┆ ...            │
# └─────────────┴──────────┴────────────────┘

# join with compound structures
result = db.lfs["activities"].join(
    db.lfs["compound_structures"], on="molregno", how="left", validate="m:1"
).head().collect()
# result.shape → (5, 32)
```

#### convert to pandas (if needed):

Ideally at the end of all filtering, call `.collect().to_pandas()` (see polars documentation for more info):

```python
import pandas as pd

df = db.lfs["activities"].head().collect().to_pandas()
isinstance(df, pd.DataFrame)  # True
```

# roadmap

- [ ] papyrus database support
    - [x] papyrus latest version download
    - [x] simple nested filtering
    - [ ] efficient nested filtering
    - [ ] all-version support
    - [ ] built-in pivots
- [ ] chembl database support
    - [x] database to tables (parquet)
    - [ ] intuitive pre-merged flat files
    - [ ] database visualisation
    - [x] remove the need for storing uncompressed .db (`_tables.json` lists the finished tables)
- [ ] reproducion from downloaded raw file
- [ ] reproducible molecular (and protein?) standardisation
- [ ] automated time-url logging and manifest files
- [ ] well-organised logging
- [ ] dependency minimisation
- [ ] other database support
- [ ] preservation of api and parsing logic per major version
