Advise-me: Assessment services for the Advise-Me project

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain]

The Advise-Me project (Automatic Diagnostics with Intermediate Steps in Mathematics Education) is a Strategic Partnership in EU’s Erasmus+ programme. In this project we develop innovative technology for calculating detailed diagnostics in mathematics education, for domains such as ‘Numbers’ and ‘Relationships’. The technology is offered as an open, reusable set of feedback and assessment services. The diagnostic information is calculated automatically based on the analysis of intermediate steps. For more information, see the project website or read the EC-TEL 2018 paper 'Fine-grained Cognitive Assessment based on Free-form Input for Math Story Problems'.


[Skip to ReadMe]

Properties

Versions0.1, 0.1
Change logNone available
DependenciesAdvise-me, base (>=4.8 && <5), bytestring (>=0.10), Cabal (>=1.22), containers (>=0.5), convertible (>=1.1), directory (>=1.2), filepath (>=1.4), HDBC (>=2.4), HDBC-sqlite3 (>=2.3), http-types (>=0.9), ideas (>=1.8), ideas-math-types (>=1.0), lens (>=4.15 && <4.18), mtl (>=2.2), optparse-applicative (==0.14.*), parsec (>=3.1), QuickCheck (>=2.8), random (>=1.1), semigroups (==0.18.5), sqlite-simple (>=0.4), text (>=1.2), time (>=1.5), uniplate (>=1.6), wai (>=3.2.1.1 && <3.2.3), wai-extra (==3.0.22.0), wl-pprint (>=1.2), xlsx (>=0.6.0) [details]
LicenseApache-2.0
Copyright(c) 2019
AuthorJorn van Wijk, Ferdinand van Walree, Niels Steenbergen, Wink van Zon, Bastiaan Heeren
Maintainerbastiaan.heeren@ou.nl
CategoryEducation
Home pagehttp://advise-me.ou.nl/
Source repositoryhead: svn checkout https://ideastest.science.uu.nl/svn/ideas/Tutors/Advise-Me/trunk
Executablesreport.exe, database-builder.exe, advise-me-admin.cgi, advise-me.cgi
UploadedTue Oct 29 10:42:21 UTC 2019 by BastiaanHeeren

Modules

Flags

NameDescriptionDefaultType
xlsxEnabledAutomatic

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainers' corner

For package maintainers and hackage trustees


Readme for Advise-me-0.1

[back to package description]

Readme

This file will attempt to detail the assumptions and workflow of the project. There is a ticket system to keep track of what has been done and what still needs to be done.

Installation

GHC

We develop in a bare Haskell Platform environment. Stack is not used at the moment, due to the complexity of importing local packages that are not yet in Hackage.

At the moment, the code needs to work with our Ubuntu 16.04 LTS (Xenial) server, which uses GHC 7.10.3. On that distribution, it should be enough to do:

sudo apt install haskell-platform{,-doc,-prof}

On other OSes, the easiest way to get this specific version is perhaps to use the generic installer:

wget -O /tmp/hp.tar.gz \
    https://www.haskell.org/platform/download/7.10.3/haskell-platform-7.10.3-unknown-posix-x86_64.tar.gz
tar xf /tmp/hp.tar.gz
sudo ./install-haskell-platform.sh

# We also need to change some flags
sed -i 's/\(.*"C compiler flags",\s*"\)\(.*\)/\1-fno-PIE \2/g
       ;s/\(.*"C compiler link flags",\s*"\)\(.*\)/\1-no-pie \2/g
       ;s/\(.*"ld flags",\s*"\)\(.*\)/\1-no-pie \2/g' \
       /usr/local/haskell/ghc-7.10.3-x86_64/lib/ghc-7.10.3/settings

Database

Since the database is SQLite3, we need the SQLite binary and libraries. On Debian-based distributions, this amounts to:

sudo apt install sqlite3 libsqlite3-dev

On Windows, you can get the required executables and DLLs at sqlite.org.

The initial live database can later be built with the database-builder.exe binary, like so:

./database-builder.exe -o advise-me.db

Web server

To run the binary locally, you can use any web server with CGI support. We can do the following to use Apache to serve CGI scripts from the /usr/lib/cgi-bin directory on Debian-based distributions:

sudo apt install apache2
sudo a2enmod cgid

For other OSes, check this guide.

Haskell environment

The source code of the project is contained in Git and Subversion repositories. To obtain it:

git clone \
    https://github.com/ideas-edu/ideas
cd ideas; make src/Ideas/Main/Revision.hs; cd -

svn checkout \
    https://ideastest.science.uu.nl/svn/ideas/Tutors/math-types

svn checkout \
    https://ideastest.science.uu.nl/svn/ideas/Tutors/Advise-Me/trunk

Install the sandbox:

cd trunk
cabal sandbox init
cabal sandbox add-source ../ideas
cabal sandbox add-source ../math-types
cabal install \
    --only-dependencies \
    --enable-tests \
    --enable-executable-profiling \
    --enable-library-profiling
cabal configure \
    --enable-tests \
    --enable-executable-profiling \
    --enable-coverage

We use make, because there are many different files and interdependencies. Reading the Makefile should give an idea of the workflow. It is also recommended to make a config.mk file, overriding the variables in the Makefile so that they point to the correct directories:

tee config.mk << EOF
IDEAS_DIR = ../ideas/src
MATHTYPES_DIR = ../math-types/src
CGI_BIN = /usr/lib/cgi-bin
EOF

Bayesian networks

To create the Bayesian networks, Genie is used. We used to interface with the SMILE library for using the networks, but that is now done in Haskell itself by transforming the original .xdsl files into a Haskell interface. See network-builder.exe.

Compiling

Now, we can compile the binaries. make processing should take care of everything for us, but of course the binaries can also be created by cabal separately.

Note that there is an xlsx cabal flag that is on by default, because building the xlsx library (used for reading human assessments) is not straightforward on every machine. If you find that the xlsx library is causing issues and you do not need its functionality, do cabal configure -flags="-xlsx" before building.

Project structure

The following directories are important to know.

Apart from the main advise-me.cgi binary, there are a couple of auxiliary binaries to use:

To inspect the resulting databases or to examine statistics, there are multiple options.

Testing

Tests that are implemented now relate exclusively to finding the evidence. Other tests are mostly non-existent, so functionality may break without warning. (For more fine-grained information on how well the evidence matches our expectations, see report.exe.)

Rudimentary regression tests can be performed with a diff, simply to check whether the output has changed since the last update. make regressions does this for you.

cabal test runs the tasty test suite with particular example requests, to check if they still find the evidence we expect. Whenever you fix a specific bug, please add a test along with the relevant request XML.

Coverage

To inspect code coverage, do cabal clean and cabal configure --enable-coverage and rebuild the binaries that you want to test. After running the binaries, .tix files will be created (that you can optionally combine with hpc sum *.tix). From the tix and mix files, you can generate a HTML coverage index or a statistics report. For example:

hpc report
--hpcdir=dist/hpc/vanilla/mix/Advise-me-0.1
--hpcdir=dist/hpc/vanilla/mix/database-builder.exe
database-builder.exe.tix

Profiling

If you have installed the libraries with --enable-library-profiling and configured cabal with --enable-library-profiling --enable-executable-profiling, then you can build a profiling version of the main CGI binary. The Makefile contains a recipe for a PDF report.