Skip to main content

Distance Sampling automation through python and Distance sofware

Project description

Python module for AUtomated DIstance SAMpling analyses

This module interfaces distance sampling analysis engines from Distance software, and possibly others in the future ; thus, it has been designed in order to make it easier :

  • to run (in parallel) numerous Distance Sampling analyses with many (many) parameter variants on many field observation samples (possibly using some optimisation techniques for automated computation of right and left distance truncations),
  • to select the best analysis variant results through a mostly automated process, based on customisable statistical quality indicators,
  • to produce partly customisable reports in spreadsheet (numerical results only) and HTML formats (more complete, with full-featured plots like in Distance, and more).

As for now, only the Windows MCDS.exe V6 engine and Point Transect analyses are supported, and so, it runs only under Windows.

Requirements

The module itself was actually tested extensively with:

  • python 3.8 only
  • pandas 0.25 to 1.2.5
  • openpyxl 3.0 to 3.1.2
  • matplotlib 3.1 to 3.7
  • jinja2 2.10 to 3.1
  • zoopt 0.4.0
  • xlrd 2.0 (only for .xls format support)

You will get no support outside of this (but porting to python 3.12 is planned for 2024).

As for testing:

  • pytest, pytest-cov
  • plotly (sometimes)
  • xlrd >= 2 (only for old .xls format support)

Installation

You can install pyaudisam from PyPI in your current python environment (conda or venv, whatever):

$ pip install pyaudisam

TODO: Publish also on Conda Forge, probably following this recipe.

Or from a downloaded source package:

$ pip install pyaudisam-1.0.2.tar.gz

Or from a downloaded wheel package:

$ pip install pyaudisam-1.0.2-py3-none-any.whl

Or even directly from GitHub:

  • $ pip install git+https://github.com/pypa/sampleproject.git@1.0.2
  • $ pip install git+https://github.com/pypa/sampleproject.git@main

Usage

As a python package, pyaudisam can be used through its python API.

But there's also a command-line interface: try and run it with the -h/--help option.

python -m pyaudisam --help

Whichever method, the best way to go is to read the concrete quick-start guide : see Documentation below.

Documentation

Note: You can also get a detailled idea of how to use pyaudisam python API by playing with the fully functional jupyter notebook tests/valtests.ipynb (see below Running tests for how to obtain and run it).

TODO:

  • complete the quick start guides above by other small and focused articles to explain some mandatory details:
    • how to build a sample or analysis specification workbook (see a short draft in analyser.py:273),
    • ...
  • write a technical documentation of the whole module,
  • write a guide for building the module API documentation (sphinx should work out of the box as reStructured text has been used in docstrings),

Running tests

You first need to clone the source tree or download and install a source package: once done, look in the tests sub-folder, everything's inside :

  • some tests are fully automated : after installing pytest, simply run it:

    pytest

  • for code corevage during tests, after installing pytest-cov, simply run:

    pytest --cov

  • some other tests not: they are implemented as jupyter notebooks (see tests/unintests.ipynb and tests/valtests.ipynb that you must run step by step, as long as no one has fully automated them :-).

Building

To build pyaudisam PyPI source and binary packages, you first need to clone the source tree or download and extract a source package: once done, it's as simple as:

python -m build

Note: Don't care about warnings about pyaudisam.mcds and pyaudisam.report being recognised as importable, but being absent from setuptools' packages configuration ... these folders simply contain pyaudisam config. and data files, no python code at all.

Contributing

Merge requests are very welcome !

And if you are lacking ideas, here are some good ones below ;-)

To do list

  • finish tests automation (move and completetests/unintests.ipynb and tests/valtests.ipynb notebooks code to pytest scripts, after checking the state of this work in progress in tests/*_test.py scripts),
  • make pyaudisam work under Linux / Mac OS (all python: OK, but calling MCDS.exe):
    • or: through some kind of external client-server interface to MCDS.exe (that runs only under Windows),
    • or: by porting MCDS to Linux (closed Fortran source, but old, so might be obtained through a polite request to this Distance Sampling forum ; BUT, needs an IMSL license, which is horribly expensive).
    • or: by rewriting MCDS from scratch, or by porting the MRDS Distance package to Python,
    • or: by rewriting MCDS using the MRDS Distance package, meaning some kind of interface to R,
  • build a GUI for pyaudisam command-line (with some kind of "project" concept, and parameter set template, and ...),
  • add support for line transects (only point transects for the moment),
  • add support for the co-variates feature of MCDS,
  • ...

Some hints

Some formal things that I don't plan to change (let's concentrate on substantive content) :-)

  • this code is not blacked or isorted or fully conform to pep8 (but it's clean, commented, and it works),
  • the identifier naming scheme used is old-fashioned: camel case everywhere.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyaudisam-1.0.2.tar.gz (3.6 MB view hashes)

Uploaded Source

Built Distribution

pyaudisam-1.0.2-py3-none-any.whl (185.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page