BIOSCAN Browser

The BIOSCAN Browser is a web interface to navigate the BIOSCAN-5M dataset dataset. The idea is to lower the threshold for users to explore the dataset by presenting data in interactive and comprehensive ways.

Visit the app on https://browser.bioscan-ml.org/!

Tech stack

• Frontend: React + TypeScript
• Build: Vite
• Styling: Tailwind CSS
• UI primitives: Radix + shadcn/ui
• State management and data fetching: TanStack Query
• Package manager: NPM
• Code quality: ESLint + Prettier
• Deployment: Netlify

Code structure

src/
├── components/       # Reusable components
│   └── ui/           # UI primitives
├── pages/            # Page-level components
│   ├── home/
│   ├── search/
│   ├── record/
│   ├── my-bookmarks/
│   ├── find-similar/
│   ├── taxonomy-tree/
│   ├── report/
│   ├── about/
│   └── style-guide/
├── hooks/            # Hooks for data fetching and state management
├── lib/              # Utility functions and helpers
├── types/            # Shared type definitions
├── App.tsx           # Root component
├── main.tsx          # App entry point
└── index.css         # Global styles

Development

System requirements

• Node
• NPM

The .nvmrc file in the project root specifies the recommended Node version. If you use nvm, run nvm use to switch to the recommended version.

Getting started

# Install dependencies
npm install

# Run app in development mode
npm run dev

The app will now be available in a browser on http://localhost:5173/. Hot reload will be enabled by default.

Report features

We use GitHub for record issue tracking. From the UI, users can see issue reports for records and submit new reports. For the report features we use a GitHub App and two Netlify Functions, for server side communication. npm run dev runs the frontend only, so those two features show their error states locally.

To run the full flow, install the Netlify CLI, copy .env.example to .env.local and fill in the GitHub App key. To test with your own GitHub App and repository, replace the other values as well. Then start the site with netlify dev instead of npm run dev (add --offline if the checkout is not linked to the Netlify site, otherwise the CLI prompts to log in).

The dev server will be available on http://localhost:8888.

Build for production

# Build optimized production bundle
npm run build

# Preview production build locally
npm run preview

Code style

We use Prettier as a code formatter. The project preferences are specified in .prettierrc.

# Auto format all code
npm run format

We use ESLint to detect what we consider as problems in the code. The project preferences are specified in .eslintrc.cjs.

# Run linter for all code
npm run lint

If you are using Visual Studio Code, the following extensions are recommended for code style:

• Prettier - Code formatter
• ESLint

Style guide

The style guide is an optional resource that can be used for BIOSCAN material, not only the BIOSCAN Browser. It includes references to logos, fonts and colors.

UI components

We use shadcn/ui as a component reference. Components are built using Radix UI and Tailwind CSS.

To add a new component to the project, first check out the list of available components. Then use the CLI to add a component to the project. This will create a new component in folder /src/components/ui and install any dependencies it might have. Since components are copied to the project, not installed as dependencies, they can be tweaked as needed.

Deployment

We use Netlify for deployment. Changes pushed to the main branch are automatically deployed. When a pull request is opened, a preview version of the changes will be deployed. The URL to the preview deploy will be visible as a PR comment.

Contributing

See CONTRIBUTING for more information about how to contribute to the code base.

Funders

All project funders are listed on the about page.

Citation

If you use the BIOSCAN Browser in your work, please cite the BIOSCAN-5M paper:

@inproceedings{gharaee2024bioscan5m,
    title={{BIOSCAN-5M}: A Multimodal Dataset for Insect Biodiversity},
    booktitle={Advances in Neural Information Processing Systems},
    author={Zahra Gharaee and Scott C. Lowe and ZeMing Gong and Pablo Millan Arias
        and Nicholas Pellegrino and Austin T. Wang and Joakim Bruslund Haurum
        and Iuliia Zarubiieva and Lila Kari and Dirk Steinke and Graham W. Taylor
        and Paul Fieguth and Angel X. Chang
    },
    editor={A. Globerson and L. Mackey and D. Belgrave and A. Fan and U. Paquet and J. Tomczak and C. Zhang},
    pages={36285--36313},
    publisher={Curran Associates, Inc.},
    year={2024},
    volume={37},
    url={https://proceedings.neurips.cc/paper_files/paper/2024/file/3fdbb472813041c9ecef04c20c2b1e5a-Paper-Datasets_and_Benchmarks_Track.pdf},
}

The Cite this repository button on the GitHub repository page reads CITATION.cff and produces the paper citation above. To credit the browser itself, use:

@misc{viklund2024bioscanbrowser,
    title={{BIOSCAN Browser}: A Web Interface to Navigate the {BIOSCAN-5M} Dataset},
    author={Anna Viklund and Iuliia Zarubiieva and Matthew Sabia and Austin T. Wang
        and Scott C. Lowe and Angel X. Chang and Graham W. Taylor
    },
    year={2024},
    howpublished={\url{https://browser.bioscan-ml.org}},
    note={Source code: \url{https://github.com/bioscan-ml/bioscan-browser}},
}

Copyright and licence

The BIOSCAN Browser code is licensed under MIT. For dataset copyright and licence information, see the BIOSCAN-5M repository.