nuovo commit

docs/source/aspis_py.rst

+ASPIS.py library
+----------------
+
+Intro
+^^^^^
+
+ASPIS.py is a library of code that allows access to the data contained in ASPIS database and other
+various astrophysics community databases, to perform client-side specific analyses of this data and to
+visualize it. The data available are of two types: data in the internal database produced by the CAESAR
+community and information on external data in other databases. Along with access to the data, the
+ASPIS.py library contains code packages that can be imported as library objects, with which to perform
+analysis and/or visualization of the data.
+
+The criterion of ASPIS.py is to act as a collector for the data and analysis software of the astrophysics
+community and to foster cooperation within the community. In fact, one can use the data and analysis
+methods developed by the community and, likewise, share one’s own data and methods. Indeed, we
+have defined a standard template in ASPIS.py for generic data analysis code, and provide a how-to for
+developers in the astrophysics community to convert their own code into the standard template, making it
+easily usable for the entire ASPIS.py community in a standard way. In this way ASPIS.py’s primary goal
+is to promote collaboration and cooperation within the astrophysics community. It facilitates the sharing
+of data and analysis methods among researchers, enabling them to benefit from each other’s work. In
+summary, ASPIS.py is a tool designed to streamline the access, analysis, and sharing of astrophysical
+data and analysis methods within the astrophysics community. It aims to enhance collaboration and
+standardization, making it easier for researchers to work with and build upon each other’s work in the
+field of astrophysics.
+
+Functions
+^^^^^^^^^^^^^^^^^^
+
+The functions of the ASPIS.py module are conceived to implement the following key components of the
+ASPIS service:
+
+1. Access for Advanced Users: ASPIS.py is designed to cater to advanced users in the astrophysics
+community. It offers a set of functions that can be executed programmatically through a Python
+interpreter. This capability allows users to perform more complex computations and analysis tasks,
+surpassing the limitations of a web application.
+
+2. Basic Visualization Tools: While ASPIS.py provides basic visualization tools/functions, it also en-
+courages users to leverage other freely available modules like Sunpy and Astropy for more ad-
+vanced visualization needs. This approach ensures compatibility and flexibility.
+
+3. Ready-to-Use Python Snippets: ASPIS.py intends to provide ready-to-use Python code snippets.
+These snippets are designed to assist entry-level users, making it easier for them to get started
+with the module. Advanced users can further customize these code snippets to suit their specific
+research requirements.
+
+4. Integration with User Programs: The expectation is that advanced users of ASPIS.py will seam-
+lessly integrate the functions provided by the module into their own analysis and visualization pro-
+grams. This promotes flexibility and allows users to tailor their solutions to their research needs.
+
+5. Structured Information in the Database: ASPIS.py relies on structured information within the database.
+This information likely includes details about various astrophysical entities such as phenomena,
+data descriptions, and chains, which are essential for conducting meaningful analyses.
+
+6. Data Outside the Database: ASPIS.py is designed to work with data that exists outside the database
+but corresponds to the descriptions available within the database. This flexibility allows researchers
+to combine data from various sources to enhance their analysis.
+In summary, ASPIS.py is a versatile tool that caters to both entry-level and advanced users in the
+astrophysics community. It provides functions for querying, visualizing, analyzing, and modeling astro-
+physical data. The inclusion of code snippets and use case examples simplifies the usage for a broad
+range of researchers, and advanced users can extend and customize the functionality to meet their spe-
+cific research objectives.
+
+Installation
+^^^^^^^^^^^^
+
+To install ASPIS.py, a user typically needs to follow these general steps. Please note that the specific
+installation process may vary depending on the availability and distribution method of ASPIS.py. The user
+has to ensure that Python is installed on the system before proceeding. The user can install ASPIS.py
+using pip, which is the Python package manager:
+
+``sudo -H pip3 install aspis-0.1.7-py3-none-any.whl``
+
+The command is used to install a Python package from a Wheel file (.whl) using pip3 with adminis-
+trative privileges (via sudo). The specific package being installed is "aspis-0.1.7-py3-none-any.whl".
+
+Here’s a breakdown of the command:
+
+* sudo: It is used to run the pip3 command with superuser privileges, which may be necessary for system-wide installations.
+* -H: This flag is used to set the home directory to the target user’s home directory. It can help avoid potential issues with environment variables when using sudo.
+* pip3: This is the Python package manager for Python 3.
+* install: It’s the pip command to install packages.
+* aspis-0.1.7-py3-none-any.whl: This is Wheel file that you want to install.
+
+If everything is set up correctly, running this command install the ASPIS package version 0.1.7 from
+the provided Wheel file.
+
+Use case example
+^^^^^^^^^^^^^^^^
+
+Here we show an example of the way a user can use a specific product of the ASPIS.py library.
+from aspis import products as aps
+from datetime import datetime
+
+product input:
+
+``V0 = 1846 #* u.km / u.s``
+
+``sigma_V0 = 362 #* u.km / u.s``
+
+``Time_UTC = datetime ( 2017 , 9 , 6 , 14 , 1 , 0)``
+
+call the class:
+
+``obj = aps . pdbm ()``
+
+compute the CME:
+
+``obj . fit (V0 , sigma_V0 , Time_UTC )``
+
+compute the CME on target = Earth:
+
+``obj . predict ()``
+
+plot:
+
+``plt = obj . plot ( savefig = True )``
+
+``plt = obj . plot ( type = ’ Travel time ’, savefig = True )``
+
+``plt = obj . plot ( type = ’ ICME velocity ’, savefig = True )``
+
+This example code performs the following steps:
+
+#.  Import necessary modules and classes from the "aspis" library.
+#.  Define input parameters, namely the initial velocity (V0), its uncertainty (sigma_V0), and a times-tamp (Time_UTC).
+#.  Create an instance of the "pdbm" class from the "aspis.products" module.
+#.  Use this instance to compute the CME (Coronal Mass Ejection) model parameters based on the provided input.
+#.  Predict the behavior of the CME when it reaches its target, which is the Earth in this case.
+#.  Generate and save plots related to the CME modeling and prediction including "Travel time" and "ICME velocity."
+
+Additionally, it’s essential to check the specific classes and methods used in the script to understand
+their usage and any additional requirements for proper execution.
+
+Code snippets and standardization
+.................................
+
+The idea of ASPIS.py is that code developed by different members of the astrophysics community in contiguous 
+fields can be made available to each other and shared in exactly the same way as is usually done
+with data. In the area of data, standardization of formats and thus the use of databases in which to store
+information in a consistent and shared manner has been adopted for years. As for software, the situation
+is more complex because codes have very heterogeneous characteristics among themselves and code
+groupings still have strong limitations. Inspired by some recent experiences aimed at standardizing the
+use of codes and comparing the performance of different methods on the same data, ASPIS.py aims to
+provide a structural scheme with the ability to make the use of code developed by different members of
+the astrophysics community for even different purposes available to the entire community.
+
+In particular, ASPIS provides four main functions:
+
+``class < class_name >:``
+
+``def __init__ ( self ) -> None :``
+
+``# initialize parameters``
+
+``def process ( self ):``
+
+``# process data``
+
+``def run ( self ):``
+
+``# run method``
+
+``def plot ( self ):``
+
+``# plot results``
+
+These functions have been thought with the following purposes:
+
+* the "init" function is used to instantiate the object that will perform the data analysis by initializing the necessary parameters
+
+* the "process" function is for analyzing the data according to a predetermined pattern
+
+* the "run" function is for using the predetermined model
+
+* the "plot" function is for making visible the parameters, data used and outputs of the model
+
+All four functions are parameterizable so as to ensure that complex codes that depend on parameter
+structures can be framed in the ASPIS system and can therefore perform tasks according to different
+patterns.
+The proposed structure is based on the following consideration: advanced methods for data analysis
+in the field of astrophysics (and beyond) fall into two main classes: methods supported by a physical
+model and those that lack it. The former are estimation problems - direct or inverse - for which the
+"process" function should be implemented as the procedure for solving the inverse problem, meaning that
+the optimization method that solves the inverse problem should be implemented in this part. In the "run"
+section, the code that, conversely, solves the forward problem should be inserted. Regarding methods of
+data analysis without a model, namely estimation or statistical learning methods, the "process" and "run"
+functions correspond, respectively, to the training or learning process of the introduced (non-physical)
+model and to the prediction procedure associated with the trained model. This concept resembles the
+“fit” and “predict” methods of the “scikit-learn” library used in the significantly more homogeneous case of
+matrix problem

docs/source/webapp.rst

+ASPIS Web Application
+---------------------
+
+
+Intro
+^^^^^
+
+ASPIS webapp aims to provide an easy, user friendly, access to the data contained in the DATABASE.
+ASPIS webapp will be suited with tools able to easy access and visualize data. Technically, ASPIS
+web-app will access to database using a set of dedicated API (GET) who will act as middleware to the
+Database queries. A key feature will be the function to visualize several data-set in the same page. The
+feature, strongly related to the casual-chain [ref. 1] concept is designed to take into account the standard
+work-flow of the Space Weather community while they are inspecting correlation and liked phenomena
+inside different products. A small and protected amount of server-side and/or client side models should
+be run over visualized data for simple and light computation, notwithstanding the intention of the web-app
+is to facilitate the data exploration and cross-visualization. Users will be encouraged to implement heavy
+computations and advanced data handling using ASPIS.py [ref. 9] libraries.
+
+Functionalities
+^^^^^^^^^^^^^^^
+
+The web-app will be accessible using a common web browser. Basic functionalities are expected to be
+public and will be open to the community:
+
+• Search in the archive based on several keys
+• Time based queries
+• Spatial queries
+• Data visualization
+• Data comparison (Multiple plots)
+• Access to the Causal-chains
+• Causal-chain visualization with multiple plots.
+• Quick citation extraction tools based on visualized data.
+Advanced functionalities will be protected and will be accessible only to user identification:
+• Save search results
+• Save data visualization settings
+• Run internal, server-side, ASPIS models over an identified data-set
+• (optional) Light computation of model and data comparison
+The Access Control List (ACL) will be provided by the ASPIS machines (Fig. 5)
+
+Time-based multi-plot visualization
+...................................
+
+Time is a key link between the most of data-sets provided. So, graphical representation of data shall be
+able to facilitate a time-based comparison between the series visualized by a common timeline. In this
+way, every relationship between time-based plots can be easily found by the user.
+
+Spatial visualization
+.....................
+
+Data-set are generated by instruments spatially referenced by acquisition site (ex. the instrument is
+physically mounted on a Spacecraft or on Earth ), by target position (ex. The instrument target is the
+Sun) and by line of sight (ex. the instrument acquire 20 square deg in a direction of the sky). This info
+can be used to facilitate the user to visualize:
+• Instruments positions in a specified time span
+• Targets positions in a specified time span
+• Targets coverage in instruments line of sights.
+• Visualization of specific phenomena in different reference systems
+
+Event-chain visualization
+.........................
+
+Causal-chains (ref. 1) will get a special section in the webapp. Causal-chains will take advantage from the
+other basic visualization plots and can be associated here as a pre-defined organization of data subsets
+plots. Web-app dedicated section will be able to list and search all causal-chains. Web-app will be able
+to advise the user if, in a nominal visualization plot, the data subset is part of a know causal-chain and
+propose a suitable visualization of such a causal-chain.
+
+Data proximity suggestions
+..........................
+
+User would be prompt by the system in case other data-sets, respect to ones already visualized, will
+have a "proximity" (in terms of observed target, data coherence, data meaning, spatial nearness ) and
+are available in the ASPIS Database system for the observed time-span or in a relevant subsequent time
+(to consider propagation of the phenomena to other instruments).
+