First commit of new TF reading class

AlanLoh · Dec 12, 2023 · e1c19ab · e1c19ab
1 parent e1b6bf5
commit e1c19ab
Show file tree

Hide file tree

Showing 56 changed files with 1,502 additions and 1,302 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -4,6 +4,8 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
+  apt_packages:
+    - graphviz
 
 sphinx:
   configuration: docs/conf.py

diff --git a/docs/conf.py b/docs/conf.py
@@ -62,7 +62,8 @@
 autodoc_mock_imports = [
     'pygsm',
     'pyvo',
-    'astroplan'
+    'astroplan',
+    'mocpy'
 ]
 
 default_role = 'obj'

diff --git a/docs/index.rst b/docs/index.rst
@@ -115,7 +115,7 @@ Finally, observations can then be simulated using the simulated beam and a sky m
    io/sst_reading
    io/bst_reading
    io/xst_reading
-   io/undysputed_reading
+   io/tf_reading
 
 .. _data-analysis:
 
@@ -130,10 +130,11 @@ Finally, observations can then be simulated using the simulated beam and a sky m
 .. _tools:
 
 .. toctree::
-   :caption: Tools
+   :caption: Modules
    :maxdepth: 2
 
    nenupy.astro
+   nenupy.io
    nenupy.instru
    nenupy.observation
    nenupy.schedule

diff --git a/docs/io/tf_reading.rst b/docs/io/tf_reading.rst
@@ -0,0 +1,164 @@
+.. _tf_reading_doc:
+
+UnDySPuTeD Time-Frequency Data
+==============================
+
+blabala see tests :class:`~nenupy.io.tf.Spectra` or :meth:`~nenupy.astro.astro_tools.altaz_to_radec`
+
+
+Reading a spectra file
+-----------------------
+
+:class:`~nenupy.io.tf.Spectra`
+
+.. code-block:: python
+
+    >>> from nenupy.io import Spectra
+    >>> sp = Spectra(filename="my_file_0.spectra")
+
+
+:meth:`~nenupy.io.tf.Spectra.info`
+
+.. code-block:: python
+
+    >>> sp.info()
+    filename: my_file_0.spectra
+    time_min: 2023-05-27T08:39:02.0000050
+    time_max: 2023-05-27T08:59:34.2445748
+    dt: 20.97152 ms
+    frequency_min: 19.921875 MHz
+    frequency_max: 57.421875 MHz
+    df: 3.0517578125 kHz
+    Available beam indices: ['0']
+
+
+Pipeline configuration
+----------------------
+
+Predefined pipeline steps
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:attr:`~nenupy.io.tf.Spectra.pipeline` :class:`~nenupy.io.tf.TFPipeline` :class:`~nenupy.io.tf.TFTask`
+
+.. code-block:: python
+
+    >>> sp.pipeline.info()
+    Pipeline configuration:
+        0 - Correct bandpass
+        (1 - Remove subband channels)
+        (2 - Rebin in time)
+        (3 - Rebin in frequency)
+        4 - Compute Stokes parameters
+
+.. code-block:: python
+
+    >>> sp.pipeline_parameters.info()
+    channels: 64
+    dt: 0.02097152 s
+    df: 3051.7578125 Hz
+    tmin: 2023-05-27T08:39:02.0000050
+    tmax: 2023-05-27T08:59:34.2445748
+    fmin: 19.921875 MHz
+    fmax: 57.421875 MHz
+    beam: 0
+    dispersion_measure: None
+    rotation_measure: None
+    rebin_dt: None
+    rebin_df: None
+    remove_channels: None
+    dreambeam_skycoord: None
+    dreambeam_dt: None
+    dreambeam_parallactic: True
+    stokes: I
+    ignore_volume_warning: False
+
+
+Pipeline parameter modification
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    >>> from astropy.time import Time
+    >>> import astropy.units as u
+
+    >>> sp.pipeline.parameters["tmin"] = "2023-05-27T08:40:00"
+    >>> sp.pipeline.parameters["tmax"] = Time("2023-05-27 08:42:00", format="iso")
+    >>> sp.pipeline.parameters["fmin"] = 50
+    >>> sp.pipeline.parameters["fmax"] = 55*u.MHz
+
+Managing pipeline tasks
+^^^^^^^^^^^^^^^^^^^^^^^
+
+:meth:`~nenupy.io.tf.TFPipeline.remove`
+
+.. code-block:: python
+
+    >>> sp.pipeline.remove(2)
+    >>> sp.pipeline.info()
+    Pipeline configuration:
+        0 - Correct bandpass
+        (1 - Remove subband channels)
+        (2 - Rebin in frequency)
+        3 - Compute Stokes parameters
+
+:meth:`~nenupy.io.tf.TFPipeline.insert` :meth:`~nenupy.io.tf.TFPipeline.append`
+
+.. code-block:: python
+
+    >>> from nenupy.io.tf import TFTask
+    >>> sp.pipeline.insert(TFTask.time_rebin(), 1)
+    >>> sp.pipeline.info()
+    Pipeline configuration:
+        0 - Correct bandpass
+        (1 - Rebin in time)
+        (2 - Remove subband channels)
+        (3 - Rebin in frequency)
+        4 - Compute Stokes parameters
+
+Adding custom steps
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    >>> from nenupy.io.tf import TFTask
+    >>> 
+    >>> custom_task = TFTask(
+            name="my task - multiply the data by n_channels",
+            func=lambda data, channels: data*channels,
+            args_to_update=["channels"]
+        )
+    >>> sp.pipeline.insert(custom_task, 3)
+    >>> sp.pipeline.info()
+    Pipeline configuration:
+        0 - Correct bandpass
+        (1 - Rebin in time)
+        (2 - Remove subband channels)
+        3 - my task - multiply the data by n_channels
+        (4 - Rebin in frequency)
+        5 - Compute Stokes parameters
+
+
+Getting the data
+----------------
+
+:meth:`~nenupy.io.tf.Spectra.get`
+
+.. code-block:: python
+
+    >>> data = sp.get(stokes="I")
+
+
+.. code-block:: python
+    
+    >>> data = sp.get(stokes="I", tmin="2023-05-27T08:41:30")
+
+.. note::
+
+    There is a hardcoded size limit to the data output (i.e. after rebinning and all other pipeline operations) fixed at 2 GB, to prevent memory issues.
+    Users willing to bypass this limit may explicitely ask for it using the `ignore_data_size` argument of :meth:`~nenupy.io.tf.Spectra.get`:
+
+    .. code-block:: python
+
+        >>> sp.get(tmin="2023-05-27T08:40:00", tmax="2023-05-27T18:00:00", ignore_data_size=True)
+
+
diff --git a/docs/io/undysputed_reading.rst b/docs/io/undysputed_reading.rst
@@ -1,7 +1,7 @@
 .. _undysputed_reading_doc:
 
-UnDySPuTeD Time-Frequency Data
-==============================
+UnDySPuTeD Time-Frequency Data (deprecated)
+===========================================
 
 :mod:`~nenupy.undysputed.dynspec.Dynspec` is the module designed to
 read and analyze *UnDySPuTeD* DynSpec high-rate data. It

diff --git a/docs/nenupy.astro.astro_tools.rst b/docs/nenupy.astro.astro_tools.rst
@@ -1,5 +1,5 @@
-nenupy.astro.astro\_tools
-=========================
+ nenupy.astro.astro\_tools
+==========================
 
 .. automodule:: nenupy.astro.astro_tools
    :members:

diff --git a/docs/nenupy.astro.beam_correction.rst b/docs/nenupy.astro.beam_correction.rst
@@ -0,0 +1,7 @@
+ nenupy.astro.beam\_correction
+==============================
+
+.. automodule:: nenupy.astro.beam_correction
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/nenupy.astro.jones_mueller.rst b/docs/nenupy.astro.jones_mueller.rst
@@ -0,0 +1,7 @@
+ nenupy.astro.jones\_mueller
+============================
+
+.. automodule:: nenupy.astro.jones_mueller
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/nenupy.astro.pointing.rst b/docs/nenupy.astro.pointing.rst
@@ -1,5 +1,5 @@
-nenupy.astro.pointing
-=====================
+ nenupy.astro.pointing
+======================
 
 .. automodule:: nenupy.astro.pointing
    :members:

diff --git a/docs/nenupy.astro.rst b/docs/nenupy.astro.rst
@@ -6,6 +6,8 @@ nenupy.astro
 .. toctree::
 
    nenupy.astro.astro_tools
+   nenupy.astro.beam_correction
+   nenupy.astro.jones_mueller
    nenupy.astro.pointing
    nenupy.astro.sky
    nenupy.astro.skymodel

diff --git a/docs/nenupy.astro.sky.rst b/docs/nenupy.astro.sky.rst
@@ -1,5 +1,5 @@
-nenupy.astro.sky
-================
+ nenupy.astro.sky
+=================
 
 .. automodule:: nenupy.astro.sky
    :members:

diff --git a/docs/nenupy.astro.skymodel.rst b/docs/nenupy.astro.skymodel.rst
@@ -1,5 +1,5 @@
-nenupy.astro.skymodel
-=====================
+ nenupy.astro.skymodel
+======================
 
 .. automodule:: nenupy.astro.skymodel
    :members:

diff --git a/docs/nenupy.astro.target.rst b/docs/nenupy.astro.target.rst
@@ -1,5 +1,5 @@
-nenupy.astro.target
-===================
+ nenupy.astro.target
+====================
 
 .. automodule:: nenupy.astro.target
    :members:

diff --git a/docs/nenupy.astro.uvw.rst b/docs/nenupy.astro.uvw.rst
@@ -1,5 +1,5 @@
-nenupy.astro.uvw
-================
+ nenupy.astro.uvw
+=================
 
 .. automodule:: nenupy.astro.uvw
    :members:

diff --git a/docs/nenupy.beamlet.beamlet.rst b/docs/nenupy.beamlet.beamlet.rst
@@ -1,5 +1,5 @@
-nenupy.beamlet.beamlet
-======================
+ nenupy.beamlet.beamlet
+=======================
 
 .. automodule:: nenupy.beamlet.beamlet
    :members:

diff --git a/docs/nenupy.beamlet.bstdata.rst b/docs/nenupy.beamlet.bstdata.rst
@@ -1,5 +1,5 @@
-nenupy.beamlet.bstdata
-======================
+ nenupy.beamlet.bstdata
+=======================
 
 .. automodule:: nenupy.beamlet.bstdata
    :members:

diff --git a/docs/nenupy.beamlet.sdata.rst b/docs/nenupy.beamlet.sdata.rst
@@ -1,5 +1,5 @@
-nenupy.beamlet.sdata
-====================
+ nenupy.beamlet.sdata
+=====================
 
 .. automodule:: nenupy.beamlet.sdata
    :members:

diff --git a/docs/nenupy.beamlet.sstdata.rst b/docs/nenupy.beamlet.sstdata.rst
@@ -1,5 +1,5 @@
-nenupy.beamlet.sstdata
-======================
+ nenupy.beamlet.sstdata
+=======================
 
 .. automodule:: nenupy.beamlet.sstdata
    :members:

diff --git a/docs/nenupy.instru.instrument_tools.rst b/docs/nenupy.instru.instrument_tools.rst
@@ -1,5 +1,5 @@
-nenupy.instru.instrument\_tools
-===============================
+ nenupy.instru.instrument\_tools
+================================
 
 .. automodule:: nenupy.instru.instrument_tools
    :members:

diff --git a/docs/nenupy.instru.interferometer.rst b/docs/nenupy.instru.interferometer.rst
@@ -1,5 +1,5 @@
-nenupy.instru.interferometer
-============================
+ nenupy.instru.interferometer
+=============================
 
 .. automodule:: nenupy.instru.interferometer
    :members:

diff --git a/docs/nenupy.instru.nda.rst b/docs/nenupy.instru.nda.rst
@@ -0,0 +1,7 @@
+ nenupy.instru.nda
+==================
+
+.. automodule:: nenupy.instru.nda
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/nenupy.instru.nenufar.rst b/docs/nenupy.instru.nenufar.rst
@@ -1,5 +1,5 @@
-nenupy.instru.nenufar
-=====================
+ nenupy.instru.nenufar
+======================
 
 .. automodule:: nenupy.instru.nenufar
    :members:

diff --git a/docs/nenupy.instru.rst b/docs/nenupy.instru.rst
@@ -7,6 +7,7 @@ nenupy.instru
 
    nenupy.instru.instrument_tools
    nenupy.instru.interferometer
+   nenupy.instru.nda
    nenupy.instru.nenufar
 
 

diff --git a/docs/nenupy.io.bst.rst b/docs/nenupy.io.bst.rst
@@ -1,5 +1,5 @@
-nenupy.io.bst
-=============
+ nenupy.io.bst
+==============
 
 .. automodule:: nenupy.io.bst
    :members:

diff --git a/docs/nenupy.io.io_tools.rst b/docs/nenupy.io.io_tools.rst
@@ -1,5 +1,5 @@
-nenupy.io.io\_tools
-===================
+ nenupy.io.io\_tools
+====================
 
 .. automodule:: nenupy.io.io_tools
    :members:

diff --git a/docs/nenupy.io.rst b/docs/nenupy.io.rst
@@ -8,6 +8,8 @@ nenupy.io
    nenupy.io.bst
    nenupy.io.io_tools
    nenupy.io.sst
+   nenupy.io.tf
+   nenupy.io.tf_utils
    nenupy.io.xst
 
 

diff --git a/docs/nenupy.io.sst.rst b/docs/nenupy.io.sst.rst
@@ -1,5 +1,5 @@
-nenupy.io.sst
-=============
+ nenupy.io.sst
+==============
 
 .. automodule:: nenupy.io.sst
    :members: