Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@Remi-Gau @effigies
Remi-Gau authored and effigies committed Aug 14, 2024
1 parent 9acd81f commit 50e95a6
Showing 1 changed file with 66 additions and 254 deletions.
320 changes: 66 additions & 254 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,80 +1,72 @@
[![Node Tests](https://github.com/bids-standard/bids-validator/actions/workflows/node_tests.yml/badge.svg)](https://github.com/bids-standard/bids-validator/actions/workflows/node_tests.yml)
[![Python tests](https://github.com/bids-standard/bids-validator/actions/workflows/python_tests.yml/badge.svg)](https://github.com/bids-standard/bids-validator/actions/workflows/python_tests.yml)
[![bids-examples tests](https://github.com/bids-standard/bids-validator/actions/workflows/test-bids-examples.yml/badge.svg)](https://github.com/bids-standard/bids-validator/actions/workflows/test-bids-examples.yml)
[![CircleCI](https://circleci.com/gh/bids-standard/bids-validator.svg?style=shield&circle-token=:circle-token)](https://circleci.com/gh/bids-standard/bids-validator)
[![Codecov](https://codecov.io/gh/bids-standard/bids-validator/branch/master/graph/badge.svg)](https://codecov.io/gh/bids-standard/bids-validator)
[![.github/workflows/build-test-deploy.yml](https://github.com/bids-standard/python-validator/actions/workflows/build-test-deploy.yml/badge.svg)](https://github.com/bids-standard/python-validator/actions/workflows/build-test-deploy.yml)
[![codecov](https://codecov.io/gh/bids-standard/python-validator/graph/badge.svg?token=5iz5rfzv93)](https://codecov.io/gh/bids-standard/python-validator)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3688707.svg)](https://doi.org/10.5281/zenodo.3688707)
[![PyPI version](https://badge.fury.io/py/bids-validator.svg)](https://badge.fury.io/py/bids-validator)
[![Conda version](https://img.shields.io/conda/vn/conda-forge/bids-validator)](https://anaconda.org/conda-forge/bids-validator)

# Python BIDS-Validator

This is a library of helper functions written in Python,
for use with BIDS compliant applications written in this language.

The main function determines if a file extension is compliant with the BIDS specification.

## Installation

To install with pip:

```
pip install -U bids_validator
```

# BIDS-Validator

- [BIDS-Validator](#bids-validator)
- [Quickstart](#quickstart)
- [Support](#support)
- [Maintainers and Contributors](#maintainers-and-contributors)
- [Use](#use)
- [API](#api)
- [.bidsignore](#bidsignore)
- [Configuration](#configuration)
- [In the Browser](#in-the-browser)
- [On the Server](#on-the-server)
- [Through Command Line](#through-command-line)
- [Docker image](#docker-image)
- [Python Library](#python-library)
- [Example](#example)
- [Development](#development)
- [Running Locally in a Browser](#running-locally-in-a-browser)
- [Testing](#testing)
- [Publishing](#publishing)
- [Acknowledgments](#acknowledgments)
To install with conda:

```
conda install bids-validator
```

## Quickstart

1. Web version:
1. Open [Google Chrome](https://www.google.com/chrome/) or
[Mozilla Firefox](https://mozilla.org/firefox) (currently the only
supported browsers)
1. Go to https://bids-standard.github.io/bids-validator/ and select a folder
with your BIDS dataset. If the validator seems to be working longer than
couple of minutes please open [developer tools ](https://developer.chrome.com/devtools)
and report the error at [https://github.com/bids-standard/bids-validator/issues](https://github.com/bids-standard/bids-validator/issues).
1. Command line version:
1. Install [Node.js](https://nodejs.org) (at least version 18.0.0)
1. Update `npm` to be at least version 7 (`npm install --global npm@^7`)
1. From a terminal run `npm install -g bids-validator`
1. Run `bids-validator` to start validating datasets.
1. Docker
1. Install Docker
1. From a terminal run `docker run -ti --rm -v /path/to/data:/data:ro bids/validator /data`
but replace the `/path/to/data` part of the command with your own path on your machine.
1. Python Library:
1. Install [Python](https://www.python.org/)
1. Install [Pip](https://pip.pypa.io/en/stable/installing/) package manager for Python, if
not already installed.
1. From a terminal run `pip install bids_validator` to acquire the
[BIDS Validator PyPI package](https://pypi.org/project/bids-validator/)
or `conda install bids-validator` for the
[Conda package](https://anaconda.org/conda-forge/bids-validator).
1. Open a Python terminal and type: `python`
1. Import the BIDS Validator package `from bids_validator import BIDSValidator`
1. Check if a file is BIDS compatible `BIDSValidator().is_bids('/relative/path/to/a/bids/file')`
1. Note, the file path must be relative to the root of the BIDS dataset, and
a leading forward slash `/` must be added to the file path.

## Support

The BIDS Validator is designed to work in both the browser and in Node.js. We
target support for the latest long term stable (LTS) release of Node.js and the
latest version of Chrome.

There is also a library of helper functions written in Python, for use with BIDS
compliant applications written in this language.

Please report any issues you experience while using these support targets via
the [GitHub issue tracker](https://github.com/bids-standard/bids-validator/issues).
If you experience issues outside of these supported environments and believe we
should extend our targeted support feel free to open a new issue describing the
issue, your support target and why you require extended support and we will
address these issues on a case by case basis.
1. Open a Python terminal and type: `python`
1. Import the BIDS Validator package `from bids_validator import BIDSValidator`
1. Check if a file is BIDS compatible `BIDSValidator().is_bids('/relative/path/to/a/bids/file')`
1. Note, the file path must be relative to the root of the BIDS dataset, and
a leading forward slash `/` must be added to the file path.


### Example

```Python
from bids_validator import BIDSValidator

validator = BIDSValidator()

filepaths = ["/sub-01/anat/sub-01_rec-CSD_T1w.nii.gz", "/sub-01/anat/sub-01_acq-23_rec-CSD_T1w.exe"]
for filepath in filepaths:
print(validator.is_bids(filepath)) # will print True, and then False
```

Note, the file path must be relative to the root of the BIDS dataset, and a
leading forward slash `/` must be added to the file path.

## Acknowledgments

Many contributions to the `bids-validator` were done by members of the
BIDS community. See the
[list of contributors](https://bids-specification.readthedocs.io/en/stable/99-appendices/01-contributors.html).

A large part of the development of `bids-validator` is currently done by
[Squishymedia](https://squishymedia.com/), who are in turn financed through
different grants offered for the general development of BIDS. See the list
below.

Development and contributions were supported through the following federally
funded projects/grants:

- [BIDS Derivatives (NIMH: R24MH114705, PI: Poldrack)](https://grantome.com/grant/NIH/R24-MH114705-01)
- [OpenNeuro (NIMH: R24MH117179, PI: Poldrack)](https://grantome.com/grant/NIH/R24-MH117179-01)
- [Spokes: MEDIUM: WEST (NSF: 1760950, PI: Poldrack & Gorgolewski)](https://grantome.com/grant/NSF/IIS-1760950)
- [ReproNim](http://repronim.org) [(NIH-NIBIB P41 EB019936, PI: Kennedy)](https://projectreporter.nih.gov/project_info_description.cfm?aid=8999833)

## Maintainers and Contributors

Expand Down Expand Up @@ -160,32 +152,7 @@ Please also see [Acknowledgments](#acknowledgments).

<!-- ALL-CONTRIBUTORS-LIST:END -->

## Use

### API

The BIDS Validator has one primary method that takes a directory as either a
path to the directory (node) or the object given by selecting a directory with a
file input (browser), an options object, and a callback.

Available options include:

- ignoreWarnings - (boolean - defaults to false)
- ignoreNiftiHeaders - (boolean - defaults to false)

For example:

`validate.BIDS(directory, {ignoreWarnings: true}, function (issues, summary) {console.log(issues.errors, issues.warnings);});`

If you would like to test individual files you can use the file specific checks
that we expose.

- validate.BIDS()
- validate.JSON()
- validate.TSV()
- validate.NIFTI()

Additionally you can reformat stored errors against a new config using `validate.reformat()`
<!-- ## Use
### .bidsignore
Expand Down Expand Up @@ -329,159 +296,4 @@ bids-validator --config.ignore=99 --config.ignore=44 path/to/bids/dir
This style of use puts limits on what configuration you can require, so for
complex scenarios, we advise users to create a dedicated configuration file with
contents as described above.

### In the Browser

The BIDS Validator currently works in the browser with [browserify](https://browserify.org/)
or [webpack](https://webpack.js.org/). You can add it to a project by cloning
the validator and requiring it with browserify syntax
`const validate = require('bids-validator');` or an ES2015 webpack import
`import validate from 'bids-validator'`.

### On the Server

The BIDS validator works like most npm packages. You can install it by running
`npm install bids-validator`.

### Through Command Line

If you install the bids validator globally by using `npm install -g bids-validator`
you will be able to use it as a command line tool. Once installed you should be
able to run `bids-validator /path/to/your/bids/directory` and see any validation
issues logged to the terminal. Run `bids-validator` without a directory path to
see available options.

## Docker image

[![Docker Image Version (latest by date)](https://img.shields.io/docker/v/bids/validator?label=docker)](https://hub.docker.com/r/bids/validator)

To use bids validator with [docker](https://www.docker.com/), you simply need to
[install docker](https://docs.docker.com/install/) on your system.

And then from a terminal run:

- `docker run -ti --rm bids/validator --version` to print the version of the
docker image
- `docker run -ti --rm bids/validator --help` to print the help
- `docker run -ti --rm -v /path/to/data:/data:ro bids/validator /data`
to validate the dataset `/path/to/data` on your host machine

See here for a brief explanation of the commands:

- `docker run` is the command to tell docker to run a certain docker image,
usually taking the form `docker run <IMAGENAME> <COMMAND>`
- the `-ti` flag means the inputs are accepted and outputs are printed to the
terminal
- the `--rm` flag means that the state of the docker container is not saved
after it has run
- the `-v` flag is adding your local data to the docker container
([bind-mounts](https://docs.docker.com/storage/bind-mounts/)). Importantly,
the input after the `-v` flag consists of three fields separated colons: `:`
- the first field is the path to the directory on the host machine:
`/path/to/data`
- the second field is the path where the directory is mounted in the
container
- the third field is optional. In our case, we use `ro` to specify that the
mounted data is _read only_

## Python Library

[![PyPI version](https://badge.fury.io/py/bids-validator.svg)](https://badge.fury.io/py/bids-validator)
[![Conda version](https://img.shields.io/conda/vn/conda-forge/bids-validator)](https://anaconda.org/conda-forge/bids-validator)

There are is a limited library of helper functions written in Python. The main function
determines if a file extension is compliant with the BIDS specification. You can find
the available functions in the library, as well as their descriptions,
[here](https://github.com/bids-standard/bids-validator/blob/master/bids-validator/bids_validator/bids_validator.py).
To install, run `pip install -U bids_validator` (requires python and pip) or
`conda install bids-validator` (requires a Conda environment).

### Example

```Python
from bids_validator import BIDSValidator
validator = BIDSValidator()
filepaths = ["/sub-01/anat/sub-01_rec-CSD_T1w.nii.gz", "/sub-01/anat/sub-01_acq-23_rec-CSD_T1w.exe"]
for filepath in filepaths:
print(validator.is_bids(filepath)) # will print True, and then False
```

Note, the file path must be relative to the root of the BIDS dataset, and a
leading forward slash `/` must be added to the file path.

## Development

To develop locally, clone the project and run `npm install` from the project
root. This will install external dependencies. If you wish to install
`bids-validator` globally (so that you can run it in other folders), use the
following command to install it globally: `cd bids-validator && npm install -g` (for windows users, if in a different drive add /d, e.g. `cd /d F:\bids-validator && npm install -g`)

Please see the [CONTRIBUTING.md](../CONTRIBUTING.md)
for additional details.

### Bundling

bids-validator is bundled with esbuild. While developing, the script `bids-validator/bin/bids-validator` will automatically bundle the project each time it is run. To test a build without publishing it `npm -w bids-validator run build`. This will generate a bids-validator/dist directory containing the local build and `bids-validator/bin/bids-validator` will use this build. To return to automatic bundling on each run, remove the dist directory.

### Running Locally in a Browser

A note about OS X, the dependencies for the browser require a npm package called
node-gyp which needs xcode to be installed in order to be compiled.

1. The browser version of `bids-validator` lives in the repo subdirectory
`/bids-validator-web`. It is a [React.js](https://reactjs.org/) application
that uses the [next.js](https://nextjs.org/) framework.
2. To develop `bids-validator` and see how it will act in the browser, simply run
`npm run web-dev` in the project root and navigate to `localhost:3000`.
3. In development mode, changes to the codebase will trigger rebuilds of the application
automatically.
4. Changes to the `/bids-validator` in the codebase will also be reflected in the
web application.
5. Tests use the [Jest](https://jestjs.io/index.html) testing library and should be developed in `/bids-validator-web/tests`.
We can always use more tests, so please feel free to contribute a test that reduces the chance
of any bugs you fix!
6. To ensure that the web application compiles successfully in production, run `npm run web-export`

### Testing

If it's your first time running tests, first use the command `git submodule update --init --depth 1` to pull the test example data. This repo contains the [bids-examples github repository](https://github.com/bids-standard/bids-examples) as a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules).

To start the test suite run `npm run test` from the project root. `npm run test -- --watch`
is useful to run tests while making changes. A coverage report is available with
`npm run coverage`.

To run the linter which checks code conventions run `npm run lint`.

### Install globally from a development branch

Global installs are not recommended for development because of the possibility of package conflicts with other Node.js projects. If you do need to test with a global install from a development tree, follow these steps to generate the NPM package without publishing it and install the package locally.

1. `npm -w bids-validator run build`
2. `npm -w bids-validator pack`
3. `npm install -g bids-validator-*.tgz`

### Publishing

Publishing is done with [Lerna](https://github.com/lerna/lerna). Use the command `npx lerna publish` and follow instructions to set a new version.

Using lerna publish will create a git commit with updated version information and create a version number tag for it, push the tag to GitHub, then publish to NPM and PyPI. The GitHub release is manual following that.

## Acknowledgments

Many contributions to the `bids-validator` were done by members of the
BIDS community. See the
[list of contributors](https://bids-specification.readthedocs.io/en/stable/99-appendices/01-contributors.html).

A large part of the development of `bids-validator` is currently done by
[Squishymedia](https://squishymedia.com/), who are in turn financed through
different grants offered for the general development of BIDS. See the list
below.

Development and contributions were supported through the following federally
funded projects/grants:

- [BIDS Derivatives (NIMH: R24MH114705, PI: Poldrack)](https://grantome.com/grant/NIH/R24-MH114705-01)
- [OpenNeuro (NIMH: R24MH117179, PI: Poldrack)](https://grantome.com/grant/NIH/R24-MH117179-01)
- [Spokes: MEDIUM: WEST (NSF: 1760950, PI: Poldrack & Gorgolewski)](https://grantome.com/grant/NSF/IIS-1760950)
- [ReproNim](http://repronim.org) [(NIH-NIBIB P41 EB019936, PI: Kennedy)](https://projectreporter.nih.gov/project_info_description.cfm?aid=8999833)
contents as described above. -->

0 comments on commit 50e95a6

Please sign in to comment.