Package: pyaudisam
Python module for AUtomated DIstance SAMpling analysesThis module interfacesdistance samplinganalysis engines fromDistance software, and possibly others in the future ; thus, it has been designed in order to make it easier :to run (in parallel) numerousDistance Samplinganalyses 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.RequirementsThe module itself was actually tested extensively with:python 3.8 onlypandas 0.25 to 1.2.5openpyxl 3.0 to 3.1.2matplotlib 3.1 to 3.7jinja2 2.10 to 3.1zoopt 0.4.0xlrd 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-covplotly (sometimes)xlrd >= 2 (only for old .xls format support)InstallationYou can installpyaudisamfromPyPIin your current python environment (conda or venv, whatever):$ pip install pyaudisamTODO: Publish also onConda Forge, probably followingthis recipe.Or from a downloaded source package:$ pip install pyaudisam-1.0.2.tar.gzOr from a downloaded wheel package:$ pip install pyaudisam-1.0.2-py3-none-any.whlOr 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@mainUsageAs apython package, pyaudisam can be used through its python API.But there's also acommand-line interface: try and run it with the -h/--help option.python -m pyaudisam --helpWhichever method, the best way to go is to read the concrete quick-start guide : seeDocumentationbelow.Documentationa short"how it works" guideto understand the basics (also inFrench),a concrete"quick-start" guidewith a real life use case and relevant field data to play with,another similar but shorter concrete"quick-start guide" (in French)(command-line only) with the full field data set of the "ACDC 2019" birding study.Note: You can also get a detailled idea of how to use pyaudisam python API by playing with the fully functionaljupyternotebooktests/valtests.ipynb(see belowRunning testsfor 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 inanalyser.py:273),...write a technical documentation of the whole module,write a guide for building the module API documentation (sphinxshould work out of the box asreStructured texthas been used in docstrings),Running testsYou first need to clone thesource treeor download and install asource package: once done, look in thetestssub-folder, everything's inside :some tests are fully automated : after installing pytest, simply run it:pytestfor code corevage during tests, after installing pytest-cov, simply run:pytest --covsome other tests not: they are implemented asjupyter notebooks(seetests/unintests.ipynbandtests/valtests.ipynbthat you must run step by step, as long as no one has fully automated them :-).BuildingTo build pyaudisamPyPIsource and binary packages, you first need to clone thesource treeor download and extract asource package: once done, it's as simple as:python -m buildNote: 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.ContributingMerge requests are very welcome !And if you are lacking ideas, here are some good ones below ;-)To do listfinish tests automation (move and completetests/unintests.ipynbandtests/valtests.ipynbnotebooks 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 tothis Distance Sampling forum; BUT, needs an IMSL license, which is horribly expensive).or: by rewriting MCDS from scratch, or by porting theMRDS Distance packageto Python,or: by rewriting MCDS using theMRDS 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 hintsSome 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.