Documentation for `IntensityDataIOFactory` unclear how to get data as numpy array

I would like to read in my data from a file and plot it quickly before starting my analysis (to check I have read in the correct file). I load the data in as follows,

my_data = ba.IntensityDataIOFactory.readIntensityData(filepath)

When I return the python __repr__ for the my_data object I get

<libBornAgainDevice.IHistogram; proxy of <Swig Object of type 'IHistogram *' at 0x112b01870> >

Which is rather opaque. I have consulted the relevant API documentation which is also uninformative.

From running dir(my_data), I have identified array as potentially the object that I desire. I would anticipate this to be a python property of my_data (i.e. I can access it with just my_data.array no brackets). However this in fact a method so I need to use my_data.array() to return a numpy array.

The my_data object appears to be of type libBornAgainDevice.IHistogram the documentation for which I assumed to be in this page. However, this makes no mention of the .array() method.

Personally, I would like to see a much simplified user documentation, that was something like

class ba.IntensityDataIOFactory.readIntensityData(filepath)

Arguments
---------
filepath (str): Data file to be read in 

Methods
-------
array(): Returns numpy array of the data

Though really, I think having a Python __repr__ (https://www.programiz.com/python-programming/methods/built-in/repr) that returns the .array() result would be most understandable.

changed the description

There are several problems here. One of them is already fixed, namely the incomplete documentation of class Histogram1D. This class inherits from the interface (abstract base) class IHistogram. In the past, interface classes were not covered by our user API. Only recently I learned that this has for consequence that methods from such base classes are not described in the Doxygen API doc of inherited classes. Therefore we are now extending Doxygen coverage to interface classes. This has now been done for IHistogram, which results in a much more complete page https://bornagainproject.org/ext/api/git-main/user-API/classHistogram1D.html.

As for the other problems, how would you proceed?

assigned to @andrew.mccluskey

Initially, I would recommend adding a __repr__ for the class that returns the .array() result (https://stackoverflow.com/questions/15013945/how-to-give-a-c-class-a-python-repr-with-swig).

Can you point me at where this documentation is currently generated?

Python help strings are restored in latest main.

$ python3
Python 3.9.10 (main, Jan 16 2022, 17:12:18) 
[GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import bornagain as ba
>>> help(ba.Histogram1D.array)

yields

Help on function array in module libBornAgainDevice:

array(self, *args)
    array(IHistogram self, IHistogram::DataType dataType=DataType::INTEGRAL) -> PyObject
    PyObject * IHistogram::array(DataType dataType=DataType::INTEGRAL) const
    
    Returns numpy array with bin content (accumulated values).

This would still require the user to know about the array method in the first place no?

help(ba.Histogram1D)

Is there any reason not to have a __repr__ that returns the array?

Maybe close this issue, and open a new issue with a specific proposal that describes the functionality that should be added?

Closing this, but I have an idea for making this better after Ammar's big MR.

How is this generated?

Files Wrap/Swig/libBornAgainX.i' (with X=Base,Sample,...`) contain a line

%include "../../auto/Wrap/doxygenX.i"

Files in directory auto/ are automatically generated. Nonetheless, they are under git control, and are part of the source archive. This is for the convenience of users who are not developers, but want to build BornAgain from source: thanks the files in auto/, they can do so without running Swig or Doxygen.

Developers need to regenerate files in auto/ if they changed they API, or any Doxygen comment that goes into a Python help string. To do so, they run cmake with option -DALLCONFIG=ON (this may change), then make.

The files auto/Wrap/doxygenX.i are generated by function GeneratePythonDocs (file PythonDocs.cmake), called by function SwigLib (file Swiglib.cmake), called by function MakeLib (file MakeLib.cmake), called by X/CMakeLists.txt. All this, however, may change soon with Ammar's multi-python MR.

closed