Skip to main content

Python FPbase API

License PyPI Python Version CI codecov

Python wrapper for FPBase.org GraphQL API.

See https://www.fpbase.org/graphql for an interactive playground and full documentation on the graphql schema (click the little book icon on the top left corner).

Installation

pip install fpbase

API

See all response model types in fpbase.models.

Functions that return a single object

  • fpbase.get_fluorophore (can return either protein or dye)
  • fpbase.get_protein (will only return proteins)
  • fpbase.get_microscope
  • fpbase.get_filter
  • fpbase.get_light_source
  • fpbase.get_camera

Functions that return a list of available object keys

  • fpbase.list_fluorophores (includes both proteins and dyes)
  • fpbase.list_proteins
  • fpbase.list_dyes
  • fpbase.list_microscopes
  • fpbase.list_filters
  • fpbase.list_light_sources
  • fpbase.list_cameras

Other

  • fpbase.graphql_query : Send generic GraphQL query to FPbase (see https://www.fpbase.org/graphql for full documentation on the graphql schema and an interactive playground)

Caching and rate limits

Lookup tables (e.g. the names of all proteins, dyes and filters) are cached on disk for 24 hours, and microscopes for 1 hour, so that new Python processes don't need to download them again. Set the FPBASE_CACHE_DIR environment variable to change the cache location.

The FPbase API is rate limited. Throttled requests are automatically retried after the delay requested by the server.

Example Usage

import fpbase

fpbase.get_fluorophore("mCherry")
# NOTE: you can also use `get_protein()` if you want to ensure that the
# fluorophore is a protein and the response is an `fpbase.models.Protein`
output
Protein(
    name='mCherry',
    id='ZERB6',
    default_state=State(
        id=336,
        name='mCherry',
        exMax=587.0,
        emMax=610.0,
        emhex='#f70000',
        exhex='#ff4600',
        ext_coeff=72000.0,
        qy=0.22,
        spectra=[
            Spectrum(id=79, subtype='EX', owner_filter=None, owner_camera=None, owner_light=None),
            Spectrum(id=80, subtype='EM', owner_filter=None, owner_camera=None, owner_light=None),
            Spectrum(id=158, subtype='A_2P', owner_filter=None, owner_camera=None, owner_light=None)
        ],
        lifetime=1.4
    ),
    seq='MVSKGEEDNMAIIKEFMRFKVHMEGSVNGHEFEIEGEGEGRPYEGTQTAKLKVTKGGPLPFAWDILSPQFMYGSKAYVKHPADIPDYLKLSFPEGFKWERVMNFEDGGVVTVTQDSSLQDGEFIYKVKLRGTNFPSDGPVMQKKTMGWEASSERMYPEDGALKGEIKQRLKLKDGGHYDAEVKTTYKAKKPVQLPGAYNVNIKLDITSHNEDYTIVEQYERAEGRHSTGGMDELYK',
    pdb=['2H5Q'],
    genbank='AAV52164',
    uniprot='X5DSL3',
    agg=<Olig.MONOMER: 'M'>,
    switch_type=<SwitchType.BASIC: 'B'>,
    primary_reference=Reference(doi='10.1038/nbt1037', url='https://doi.org/10.1038/nbt1037'),
    references=[
        Reference(doi='10.1038/nbt1037', url='https://doi.org/10.1038/nbt1037'),
        Reference(doi='10.1021/bi060773l', url='https://doi.org/10.1021/bi060773l'),
        Reference(doi='10.1038/nmeth1062', url='https://doi.org/10.1038/nmeth1062'),
        Reference(doi='10.1038/nmeth.1596', url='https://doi.org/10.1038/nmeth.1596'),
        Reference(doi='10.1038/nmeth.1955', url='https://doi.org/10.1038/nmeth.1955'),
        Reference(doi='10.1091/mbc.e16-01-0063', url='https://doi.org/10.1091/mbc.e16-01-0063'),
        Reference(doi='10.1038/s41598-017-12212-x', url='https://doi.org/10.1038/s41598-017-12212-x'),
        Reference(doi='10.1038/s41598-018-28858-0', url='https://doi.org/10.1038/s41598-018-28858-0'),
        Reference(doi='10.1002/pld3.112', url='https://doi.org/10.1002/pld3.112'),
        Reference(doi='10.1371/journal.pone.0219886', url='https://doi.org/10.1371/journal.pone.0219886'),
        Reference(doi='10.1073/pnas.2017379117', url='https://doi.org/10.1073/pnas.2017379117'),
        Reference(doi='10.1038/s41467-023-40647-6', url='https://doi.org/10.1038/s41467-023-40647-6')
    ]
)
fpbase.get_fluorophore("DAPI")
output
Fluorophore(
    name='DAPI',
    id='15',
    default_state=State(
        id=15,
        name='DAPI',
        exMax=359.0,
        emMax=461.0,
        emhex='',
        exhex='',
        ext_coeff=None,
        qy=None,
        spectra=[
            Spectrum(id=7754, subtype='AB', owner_filter=None, owner_camera=None, owner_light=None),
            Spectrum(id=222, subtype='EX', owner_filter=None, owner_camera=None, owner_light=None),
            Spectrum(id=223, subtype='EM', owner_filter=None, owner_camera=None, owner_light=None)
        ],
        lifetime=None
    )
)
# fetch info for <https://www.fpbase.org/microscope/i6WL2W/>
fpbase.get_microscope("i6WL2W")
output
Microscope(
    id='i6WL2WdgcDMgJYtPrpZcaJ',
    name='Example Widefield (Sedat)',
    opticalConfigs=[
        OpticalConfig(
            name='Widefield Blue',
            filters=[
                FilterPlacement(
                    path='EX',
                    filter=Filter(
                        id=52,
                        name='Chroma ET395/25x',
                        spectrum=Spectrum(id=375, subtype='BX', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='BS',
                    filter=Filter(
                        id=10,
                        name='Chroma T425lpxr',
                        spectrum=Spectrum(id=333, subtype='LP', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='EM',
                    filter=Filter(
                        id=47,
                        name='Chroma ET460/50m',
                        spectrum=Spectrum(id=370, subtype='BM', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                )
            ],
            camera=Camera(
                id=4,
                name='Andor Zyla 4.2 PLUS',
                spectrum=Spectrum(id=1328, subtype='QE', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            light=LightSource(
                id=9,
                name='SOLA 395',
                spectrum=Spectrum(id=394, subtype='PD', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            laser=None
        ),
        OpticalConfig(
            name='Widefield Dual FRET',
            filters=[
                FilterPlacement(
                    path='EX',
                    filter=Filter(
                        id=63,
                        name='Lumencor 470/24x',
                        spectrum=Spectrum(id=399, subtype='BX', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='BS',
                    filter=Filter(
                        id=62,
                        name='Chroma 59022bs',
                        spectrum=Spectrum(id=385, subtype='BS', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='EM',
                    filter=Filter(
                        id=689,
                        name='Semrock FF02-641/75',
                        spectrum=Spectrum(id=1025, subtype='BP', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                )
            ],
            camera=Camera(
                id=4,
                name='Andor Zyla 4.2 PLUS',
                spectrum=Spectrum(id=1328, subtype='QE', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            light=LightSource(
                id=9,
                name='SOLA 395',
                spectrum=Spectrum(id=394, subtype='PD', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            laser=None
        ),
        OpticalConfig(
            name='Widefield Dual Green',
            filters=[
                FilterPlacement(
                    path='EX',
                    filter=Filter(
                        id=63,
                        name='Lumencor 470/24x',
                        spectrum=Spectrum(id=399, subtype='BX', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='BS',
                    filter=Filter(
                        id=62,
                        name='Chroma 59022bs',
                        spectrum=Spectrum(id=385, subtype='BS', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='EM',
                    filter=Filter(
                        id=569,
                        name='Semrock FF03-525/50',
                        spectrum=Spectrum(id=905, subtype='BP', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                )
            ],
            camera=Camera(
                id=4,
                name='Andor Zyla 4.2 PLUS',
                spectrum=Spectrum(id=1328, subtype='QE', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            light=LightSource(
                id=9,
                name='SOLA 395',
                spectrum=Spectrum(id=394, subtype='PD', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            laser=None
        ),
        OpticalConfig(
            name='Widefield Dual Red',
            filters=[
                FilterPlacement(
                    path='EX',
                    filter=Filter(
                        id=67,
                        name='Lumencor 575/25x',
                        spectrum=Spectrum(id=403, subtype='BX', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='BS',
                    filter=Filter(
                        id=62,
                        name='Chroma 59022bs',
                        spectrum=Spectrum(id=385, subtype='BS', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='EM',
                    filter=Filter(
                        id=689,
                        name='Semrock FF02-641/75',
                        spectrum=Spectrum(id=1025, subtype='BP', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                )
            ],
            camera=Camera(
                id=4,
                name='Andor Zyla 4.2 PLUS',
                spectrum=Spectrum(id=1328, subtype='QE', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            light=LightSource(
                id=9,
                name='SOLA 395',
                spectrum=Spectrum(id=394, subtype='PD', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            laser=None
        ),
        OpticalConfig(
            name='Widefield Far-Red',
            filters=[
                FilterPlacement(
                    path='EX',
                    filter=Filter(
                        id=445,
                        name='Chroma ET640/30x',
                        spectrum=Spectrum(id=781, subtype='BX', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='BS',
                    filter=Filter(
                        id=6,
                        name='Chroma T660lpxr',
                        spectrum=Spectrum(id=329, subtype='LP', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='EM',
                    filter=Filter(
                        id=719,
                        name='Semrock FF01-698/70',
                        spectrum=Spectrum(id=1055, subtype='BP', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                )
            ],
            camera=Camera(
                id=4,
                name='Andor Zyla 4.2 PLUS',
                spectrum=Spectrum(id=1328, subtype='QE', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            light=LightSource(
                id=9,
                name='SOLA 395',
                spectrum=Spectrum(id=394, subtype='PD', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            laser=None
        ),
        OpticalConfig(
            name='Widefield Triple Cyan',
            filters=[
                FilterPlacement(
                    path='EX',
                    filter=Filter(
                        id=79,
                        name='Lumencor 440/20x',
                        spectrum=Spectrum(id=415, subtype='BX', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='BS',
                    filter=Filter(
                        id=60,
                        name='Chroma 69008bs',
                        spectrum=Spectrum(id=383, subtype='BS', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='EM',
                    filter=Filter(
                        id=46,
                        name='Chroma ET470/24m',
                        spectrum=Spectrum(id=369, subtype='BM', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                )
            ],
            camera=Camera(
                id=4,
                name='Andor Zyla 4.2 PLUS',
                spectrum=Spectrum(id=1328, subtype='QE', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            light=LightSource(
                id=9,
                name='SOLA 395',
                spectrum=Spectrum(id=394, subtype='PD', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            laser=None
        ),
        OpticalConfig(
            name='Widefield Triple FRET',
            filters=[
                FilterPlacement(
                    path='EX',
                    filter=Filter(
                        id=79,
                        name='Lumencor 440/20x',
                        spectrum=Spectrum(id=415, subtype='BX', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='BS',
                    filter=Filter(
                        id=60,
                        name='Chroma 69008bs',
                        spectrum=Spectrum(id=383, subtype='BS', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='EM',
                    filter=Filter(
                        id=36,
                        name='Chroma ET535/30m',
                        spectrum=Spectrum(id=359, subtype='BM', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                )
            ],
            camera=Camera(
                id=4,
                name='Andor Zyla 4.2 PLUS',
                spectrum=Spectrum(id=1328, subtype='QE', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            light=LightSource(
                id=9,
                name='SOLA 395',
                spectrum=Spectrum(id=394, subtype='PD', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            laser=None
        ),
        OpticalConfig(
            name='Widefield Triple Red',
            filters=[
                FilterPlacement(
                    path='EX',
                    filter=Filter(
                        id=67,
                        name='Lumencor 575/25x',
                        spectrum=Spectrum(id=403, subtype='BX', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='BS',
                    filter=Filter(
                        id=60,
                        name='Chroma 69008bs',
                        spectrum=Spectrum(id=383, subtype='BS', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='EM',
                    filter=Filter(
                        id=689,
                        name='Semrock FF02-641/75',
                        spectrum=Spectrum(id=1025, subtype='BP', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                )
            ],
            camera=Camera(
                id=4,
                name='Andor Zyla 4.2 PLUS',
                spectrum=Spectrum(id=1328, subtype='QE', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            light=LightSource(
                id=9,
                name='SOLA 395',
                spectrum=Spectrum(id=394, subtype='PD', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            laser=None
        ),
        OpticalConfig(
            name='Widefield Triple Yellow',
            filters=[
                FilterPlacement(
                    path='EX',
                    filter=Filter(
                        id=41,
                        name='Chroma ET500/20x',
                        spectrum=Spectrum(id=364, subtype='BX', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='BS',
                    filter=Filter(
                        id=60,
                        name='Chroma 69008bs',
                        spectrum=Spectrum(id=383, subtype='BS', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                ),
                FilterPlacement(
                    path='EM',
                    filter=Filter(
                        id=36,
                        name='Chroma ET535/30m',
                        spectrum=Spectrum(id=359, subtype='BM', owner_filter=None, owner_camera=None, owner_light=None),
                        manufacturer='',
                        bandcenter=None,
                        bandwidth=None,
                        edge=None
                    ),
                    reflects=False
                )
            ],
            camera=Camera(
                id=4,
                name='Andor Zyla 4.2 PLUS',
                spectrum=Spectrum(id=1328, subtype='QE', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            light=LightSource(
                id=9,
                name='SOLA 395',
                spectrum=Spectrum(id=394, subtype='PD', owner_filter=None, owner_camera=None, owner_light=None),
                manufacturer=''
            ),
            laser=None
        )
    ]
)

Metadata

Release files for fpbase 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fpbase 0.2.0
File Size Uploaded
fpbase-0.2.0.tar.gz 19.4 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for fpbase 0.2.0
File Interpreter ABI Platform
fpbase-0.2.0-py3-none-any.whl Python 3 none any Details

Total release size: 33.9 kB

Release files / fpbase-0.2.0.tar.gz

Download URL fpbase-0.2.0.tar.gz
Size 19.4 kB
Tags Source
SHA-256 checksum
How to use checksums
64de785d86d35d70228fa52389abe0b38e2eabdc8378609efdf4ab1f72828de6
BLAKE2b-256 checksum
How to use checksums
28d20fd173a6849dbd1389a429a0b7fb3fec6ec959cc8f097f20fac3c849a157
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / fpbase-0.2.0-py3-none-any.whl

Download URL fpbase-0.2.0-py3-none-any.whl
Size 14.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
726630ca6485dbb550cdbaaaaa538a79b7ecc646c65a6c0c02ee058c2e63bd7a
BLAKE2b-256 checksum
How to use checksums
823aeb2b3c6870201bd9d32a9474e0dca72ad152620d65bafa5595a3b5829846
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release history Release notifications | RSS feed

0.2.1

2 release files

This release

0.2.0 This release

2 release files

0.1.3

2 release files

0.1.2

2 release files

0.1.1

2 release files

0.1.0

2 release files

0.0.1

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page