Commit 9f8e05f9 authored by Paul McCarthy's avatar Paul McCarthy 🚵
Browse files

DOC: ukbparse->funpack

parent 0bb06e06
``ukbparse`` changelog
======================
``funpack`` changelog
=====================
1.0.0 (Friday 9th May 2019)
---------------------------
Changed
^^^^^^^
* ``ukbparse`` is now called ``FUNPACK`` - the *FMRIB UKBiobank Normalisation,
Processing And Cleaning Kit*.
0.21.1 (Thursday 8th May 2019)
......
The ukbparse library
The funpack library
Copyright 2018 University of Oxford, Oxford, UK.
Copyright 2018-2019 University of Oxford, Oxford, UK.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
......
``ukbparse`` - the FMRIB UK BioBank data parser
===============================================
``funpack`` - the FMRIB UKBioBank Normalisation, Processing And Cleaning Kit
============================================================================
.. image:: https://img.shields.io/pypi/v/ukbparse.svg
:target: https://pypi.python.org/pypi/ukbparse/
.. image:: https://img.shields.io/pypi/v/fmrib_unpack.svg
:target: https://pypi.python.org/pypi/funpack/
.. image:: https://anaconda.org/conda-forge/fmrib_unpack/badges/version.svg
:target: https://anaconda.org/conda-forge/fmrib_unpack
.. image:: https://anaconda.org/conda-forge/ukbparse/badges/version.svg
:target: https://anaconda.org/conda-forge/ukbparse
.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1997626.svg
:target: https://doi.org/10.5281/zenodo.1997626
.. image:: https://git.fmrib.ox.ac.uk/fsl/ukbparse/badges/master/coverage.svg
:target: https://git.fmrib.ox.ac.uk/fsl/ukbparse/commits/master/
.. image:: https://git.fmrib.ox.ac.uk/fsl/funpack/badges/master/coverage.svg
:target: https://git.fmrib.ox.ac.uk/fsl/funpack/commits/master/
``ukbparse`` is a Python library for pre-processing of UK BioBank data.
``funpack`` is a Python library for pre-processing of UK BioBank data.
``ukbparse`` is developed at the Wellcome Centre for Integrative
Neuroimaging (WIN@FMRIB), University of Oxford. ``ukbparse`` is in no way
``funpack`` is developed at the Wellcome Centre for Integrative
Neuroimaging (WIN@FMRIB), University of Oxford. ``funpack`` is in no way
endorsed, sanctioned, or validated by the `UK BioBank
<https://www.ukbiobank.ac.uk/>`_.
``ukbparse`` comes bundled with metadata about the variables present in UK
``funpack`` comes bundled with metadata about the variables present in UK
BioBank data sets. This metadata can be obtained from the `UK BioBank
online data showcase <https://biobank.ctsu.ox.ac.uk/showcase/index.cgi>`_
......@@ -32,30 +33,30 @@ Installation
------------
Install ``ukbparse`` via pip::
Install ``funpack`` via pip::
pip install ukbparse
pip install fmrib_unpack
Or from ``conda-forge``::
conda install -c conda-forge ukbparse
conda install -c conda-forge fmrib_unpack
Introductory notebook
---------------------
The ``ukbparse_demo`` command will start a Jupyter Notebook which introduces
the main features provided by ``ukbparse``. To run it, you need to install a
The ``funpack_demo`` command will start a Jupyter Notebook which introduces
the main features provided by ``funpack``. To run it, you need to install a
few additional dependencies::
pip install ukbparse[demo]
pip install fmrib_unpack[demo]
You can then start the demo by running ``ukbparse_demo``.
You can then start the demo by running ``funpack_demo``.
.. note:: The introductory notebook uses ``bash``, so is unlikely to work on
......@@ -69,17 +70,17 @@ Usage
General usage is as follows::
ukbparse [options] output.tsv input1.tsv input2.tsv
funpack [options] output.tsv input1.tsv input2.tsv
You can get information on all of the options by typing ``ukbparse --help``.
You can get information on all of the options by typing ``funpack --help``.
Options can be specified on the command line, and/or stored in a configuration
file. For example, the options in the following command line::
ukbparse \
funpack \
--overwrite \
--import_all \
--log_file log.txt \
......@@ -103,28 +104,28 @@ Could be stored in a configuration file ``config.txt``::
And then executed as follows::
ukbparse -cfg config.txt output.tsv input1.tsv input2.tsv
funpack -cfg config.txt output.tsv input1.tsv input2.tsv
Customising
-----------
``ukbparse`` contains a large number of built-in rules which have been
``funpack`` contains a large number of built-in rules which have been
specifically written to pre-process UK BioBank data variables. These rules are
stored in the following files:
* ``ukbparse/data/variables_*.tsv``: Cleaning rules for individual variables
* ``ukbparse/data/datacodings_*.tsv``: Cleaning rules for data codings
* ``ukbparse/data/types.tsv``: Cleaning rules for specific types
* ``ukbparse/data/processing.tsv``: Processing steps
* ``funpack/data/variables_*.tsv``: Cleaning rules for individual variables
* ``funpack/data/datacodings_*.tsv``: Cleaning rules for data codings
* ``funpack/data/types.tsv``: Cleaning rules for specific types
* ``funpack/data/processing.tsv``: Processing steps
You can customise or replace these files as you see fit. You can also pass
your own versions of these files to ``ukbparse`` via the ``--variable_file``,
your own versions of these files to ``funpack`` via the ``--variable_file``,
``--datacoding_file``, ``--type_file`` and ``--processing_file`` command-line
options respectively. ``ukbparse`` will load all variable and datacoding files,
options respectively. ``funpack`` will load all variable and datacoding files,
and merge them into a single table which contains the cleaning rules for each
variable.
......@@ -136,7 +137,7 @@ Output
------
The main output of ``ukbparse`` is a plain-text tab-delimited[*]_ file which
The main output of ``funpack`` is a plain-text tab-delimited[*]_ file which
contains the input data, after cleaning and processing, potentially with
some columns removed, and new columns added.
......@@ -148,7 +149,7 @@ file.
You can use any tool of your choice to load this output file, such as Python,
MATLAB, or Excel. It is also possible to pass the output back into
``ukbparse``.
``funpack``.
.. [*] You can change the delimiter via the ``--tsv_sep`` / ``-ts`` option.
......@@ -165,7 +166,7 @@ Loading output into MATLAB
.. _table: https://uk.mathworks.com/help/matlab/ref/table.html
If you are using MATLAB, you have several options for loading the ``ukbparse``
If you are using MATLAB, you have several options for loading the ``funpack``
output. The best option is |readtable|_, which will load column names, and
will handle both non-numeric data and missing values. Use ``readtable`` like
so::
......@@ -212,7 +213,7 @@ Tests
To run the test suite, you need to install some additional dependencies::
pip install ukbparse[test]
pip install fmrib_unpack[test]
Then you can run the test suite using ``pytest``::
......@@ -224,5 +225,5 @@ Citing
------
If you would like to cite ``ukbparse``, please refer to its `Zenodo page
If you would like to cite ``funpack``, please refer to its `Zenodo page
<https://doi.org/10.5281/zenodo.1997626>`_.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment