Module docstrings updated

Author: daquinterop

DSSATTools/__init__.py

@@ -33,12 +33,12 @@
     >>>     insi='UNCU', lat=4.34, long=-74.40, elev=1800, 
     >>>     table=df_with_data
     >>> )
-    >>> soil = SoilProfile.from_file('IBSG910085')
+    >>> soil = SoilProfile.from_file('IBSG910085', 'SOIL.SOL')
     >>> field = Field(
     >>>     id_field='ITHY0001', wsta=weather_station, flob=0, 
     >>>     fldd=0, flds=0, id_soil=soil, fldt='DR000'
     >>> )
-    >>> planting = planting = Planting(
+    >>> planting = Planting(
     >>>     pdate=date(1980, 6, 17), ppop=18, ppoe=18,
     >>>     plme='S', plds='R', plrs=45, plrd=0, pldp=5
     >>> )
@@ -91,11 +91,11 @@
 VERSION = '048'
 
 from DSSATTools import crop
-from DSSATTools.soil import SoilProfile
-from DSSATTools.weather import WeatherStation
+from DSSATTools.soil import SoilProfile, SoilLayer
+from DSSATTools.weather import WeatherStation, WeatherRecord
 from DSSATTools.run import DSSAT
 from DSSATTools import filex
 
 __all__ = [
-    'crop', 'SoilProfile', 'WeatherStation', 'DSSAT', 
+    'crop', 'SoilProfile', 'WeatherStation', 'DSSAT',  'filex'
     ] 

DSSATTools/crop.py

@@ -1,5 +1,20 @@
 '''
-
+This module hosts the classes that represent each crop. Not all crops are 
+implemented. Each crop class is child of a generic Crop class. A crop is 
+instantiated by passing the cultivar code:
+    >>> crop = Sorghum('IB0026')
+This will create a dictionary-like object with keys as the cultivar parameters' 
+names. Then, the cultivar parameters can be modified
+by assigning values:
+    >>> crop['p1'] = 450.
+    >>> crop['g1'] = 0.1
+The ecotype parameter is itself a dictionary-like object with the ecotype 
+parameters' names as keys. Then, the ecotype parameters are modified in the same 
+way as the cultivar parameters:
+    >>> crop['eco#']['topt'] = 35.5
+The cultivar_list class function will return a list of all the cultivars availble
+for a crop:
+    >>> available_cultivars = Sorghum.cultivar_list()
 '''
 import os
 from . import VERSION

DSSATTools/filex.py

@@ -1,10 +1,90 @@
 """
-File X module. 
-
-
-
-    SimulationOptions and Treatment:
-    They are only to represent those sections.
+This module implement the sections of the DSSAT FileX as python objects. All 
+sections are implemented, excepting the enviromental modifications section. 
+Environmental modifications can be easily implemented by modifying the Weather
+component of each experiment. One section object represents a single factor
+level in the experiment.
+
+Each section is defined using the same parameter names (lowercase) of the DSSAT 
+FileX. For example, planting date is defined as follow:  
+    >>> planting = Planting(
+    >>>     pdate=date(1980, 6, 17), ppop=18, ppoe=18,
+    >>>     plme='S', plds='R', plrs=45, plrd=0, pldp=5
+    >>> )
+
+Sections that include a schedule or soil profile (i.e. Initial conditions), are 
+defined as a list of individual events or soil layers. For example, a fertilizer
+section with two fertilizer events is defined as follows:
+    >>> fertilizer = Fertilizer(table=[
+    >>>     FertilizerEvent(
+    >>>         fdate=date(1980, 7, 4), fmcd='FE005', fdep=5,
+    >>>         famn=80, facd='AP002'
+    >>>     ),
+    >>>     FertilizerEvent(
+    >>>         fdate=date(1980, 8, 7), fmcd='FE005', fdep=5,
+    >>>         famn=80, facd='AP002'
+    >>>     )
+    >>> ])
+Other sections based on events are irrigation, residue, chemical, and tillage.
+
+Note that the Fertilizer object is initialized by passing a list of FertilizerEvent
+objects in the 'table' parameter. The table parameter also accepts DataFrames, 
+only if the column names of that DataFrame match the parameters for the individual
+event or layer object. Next is an example of this for the initial conditions section:
+    >>> initial_conditions = InitialConditions(
+    >>>        pcr='SG', icdat=date(1980, 6, 1), icrt=500, icnd=0,
+    >>>        icrn=1, icre=1, icres=1300, icren=.5, icrep=0, icrip=100, icrid=10,
+    >>>        table=pd.DataFrame([
+    >>>            (10, .06, 2.5, 1.8),
+    >>>            (22, .06, 2.5, 1.8),
+    >>>            (52, .195, 3., 4.5),
+    >>>            (82, .21, 3.5, 5.0),
+    >>>            (112, 0.2, 2., 2.0),
+    >>>            (142, 0.2, 1., 0.7),
+    >>>            (172, 0.2, 1., 0.6),
+    >>>        ], columns=['icbl', 'sh2o', 'snh4', 'sno3'])
+    >>>    )
+Note that InitialConditions have more parameters besides the table parameter. The 
+column names of the passed DataFrame are the same as the parameters for the 
+InitialConditionsLayer class. The soil analysis section is the other section based
+on soil layers.
+
+The field and cultivar sections are the only sections that need other DSSATTools 
+objects as input parameters. In this section, the 'wsta' must be a WeatherStation 
+object, and the 'id_soil' must be a SoilProfile object.
+    >>> field = Field(
+    >>>        id_field='ITHY0001', wsta=weather_station, flob=0, fldt='DR000', 
+    >>>        fldd=0, flds=0, id_soil=soil
+    >>>     )
+'wsta' and 'id_soil' also receives weather station and soil profile ids as strings.
+However, this wouldn't make sense in the context of running DSSAT using this package.
+
+The cultivar can be defined either using the Cultivar class, or by directly using the
+one of the classes defined in DSSATTools.crop. 
+    >>> cultivar = Sorghum('IB0026')
+    >>> cultivar = Cultivar(cr='SG', ingeno='IB0026', cname='CSH-1')
+These two definitions will yield the same result. However, when the cultivar is 
+defined using the crop class it is posible to modify the cultivar and ecotype 
+coefficients. More information is found at the DSSATTools.crop module documentation.
+    
+Finally, the simulations controls is created by using the SimulationsControls
+class. Each sub-section of the simulation controls sections is created using its
+own class. Next example shows how to create the simulations controls defining only
+the general options.
+    >>> simulation_controls = SimulationControls(
+    >>>     general=SCGeneral(sdate=date(1980, 6, 1))
+    >>> )
+
+The sections can be created from an existing FileX using the read_filex function.
+That function will return a dictionary, mapping each treatment to its correspondent
+section definitions. The next example reads an existing FileX, and then assigns
+the first treatment to the treatment variable. In this case, treatment is a 
+dictionary mapping each section name to its python object. 
+    >>> treatments = read_filex("Maize/BRPI0202.MZX")
+    >>> treatment = treatments[1]
+
+The create_filex function returns the string of the FileX for for the passed 
+sections defined as their python objects. 
 """
 from datetime import date
 from .base.partypes import (
@@ -1709,14 +1789,14 @@ def read_filex(filexpath):
         )
     return treatments
 
-def write_filex(field:Field, cultivar:Cultivar, planting:Planting, 
+def create_filex(field:Field, cultivar:Cultivar, planting:Planting, 
                 simulation_controls:SimulationControls, harvest:Harvest=None,
                 initial_conditions:InitialConditions=None, 
                 fertilizer:Fertilizer=None, soil_analysis:SoilAnalysis=None, 
                 irrigation:Irrigation=None, residue:Residue=None, 
                 chemical:Chemical=None, tillage:Tillage=None):
     """
-    Returns the FileX string
+    Returns the FileX as a string
     """
     experiment_name = field["id_field"][:4] +\
         simulation_controls["general"]["sdate"].strftime('%y01') + cultivar.code

DSSATTools/run.py

@@ -3,12 +3,24 @@
 so per each DSSAT instance there's a directory where all the necesary files to 
 run the model are allocated. To run the model there are 2 basic steps:
 
-1. Create a new DSSAT instance.
-2. Run the model by calling the run() method.
-You can close the simulation environment by calling the close() method.
-
-The model outputs are storage in the `output` attribute. Up to date the next output
-are available: PlantGro, Weather, SoilWat, SoilOrg.
+1. Create a new DSSAT instance. When DSSAT is instantiated, a simulation environment
+is set. That enviroment is set at the path passed during the call:
+    >>> dssat = DSSAT("/tmp/dssat_test")
+2. Run the model by calling the run_treatment() method. This method receives as 
+parameters the FileX sections' objects:
+    >>> results = dssat.run_treatment(
+    >>>     field=field, cultivar=crop, planting=planting,
+    >>>     initial_conditions=initial_conditions, fertilizer=fertilizer,
+    >>>     simulation_controls=simulation_controls
+    >>> )
+This call returns a dictionary that contains the values of the standard output 
+of the model: FLO, MAT, TOPWT, HARWT, RAIN, etc. After running, the DSSAT instance
+will have all the output files as strings in the output_files attribute, and the 
+output timeseries tables in the output_tables attribute:
+    >>> overview = dssat.output_files['OVERVIEW'] # Gets the overview file as a str
+    >>> plantgro = dssat.output_tables['PlantGro'] # Gets the plant growth table
+3. You can close the simulation environment by calling the close() method.
+    >>> dssat.close
 '''
 
 import subprocess
@@ -32,7 +44,7 @@
 from .filex import(
     Planting, Cultivar, Harvest, InitialConditions, Fertilizer,
     SoilAnalysis, Irrigation, Residue, Chemical, Tillage, Field,
-    SimulationControls, Mow, write_filex
+    SimulationControls, Mow, create_filex
 )
 from .base.utils import detect_encoding
 
@@ -203,7 +215,7 @@ def run_treatment(self, field:Field, cultivar:Cultivar, planting:Planting,
             f'.{cultivar.code}X'
         filex_name = os.path.join(self.run_path, filex_name.upper())
         with open(filex_name, "w") as f:
-            lines = write_filex(
+            lines = create_filex(
                 field, cultivar, planting, simulation_controls, harvest, 
                 initial_conditions, fertilizer, soil_analysis, irrigation,
                 residue, chemical, tillage
@@ -282,13 +294,11 @@ def run_treatment(self, field:Field, cultivar:Cultivar, planting:Planting,
                 continue
             table_start = -1
             init_lines = []
-            for line in file_lines:
+            for line in file_lines.split('\n'):
                 table_start += 1
                 init_lines.append(line)
-
                 if "@" in init_lines[-1][:10]:
                     break
-
             try:
                 df = pd.read_csv(
                     io.StringIO("".join(file_lines)),
@@ -338,7 +348,7 @@ def close(self):
         sys.stdout.write(f'{self.run_path} and its content has been removed.\n')
 
     @property
-    def output(self):
+    def output_tables(self):
         if len(self._output) < 1:
             warnings.warn("No output has been saved")
             return None

DSSATTools/soil.py

@@ -1,8 +1,71 @@
 """
-Contains the SoilProfile and SoilLayer classes. It also has some functions
-to estimate missing soil properties. Specifically, a function to estimate
-soil organic carbon from soil color, and a function to estimate soil hydraulic
-properties using soil texture.
+This module contains the classes and functions that handle the soil definition.
+The soil profile object is created using the SoilProfile class. One way of 
+doing that is just loading soil profile from an existing DSSAT Soil file. For
+that, the from_file soil profile class function is used:
+    >>> soil = SoilProfile.from_file("IBMZ910214", "SOIL.SOL")
+The soil profile can also be created from scratch using the SoilProfile and 
+SoilLayer classes similar to the layer-based sections of the FileX:
+    >>> soil = SoilProfile(
+    >>>     name='IBMZ910214', soil_series_name='Millhopper Fine Sand', 
+    >>>     site='Gainesville', country='USA', lat=29.6, long=-82.37, 
+    >>>     soil_data_source='Gainesville', soil_clasification='S',
+    >>>     scs_family='Loamy,silic,hyperth Arnic Paleudult', scom='', salb=0.18, 
+    >>>     slu1=2.0, sldr=0.65, slro=60.0, slnf=1.0, slpf=0.92, smhb='IB001',
+    >>>     smpx='IB001', smke='IB001',
+    >>>     table = [
+    >>>         SoilLayer(
+    >>>             slb=5.0, slmh='', slll=0.026, sdul=0.096, ssat=0.345, srgf=1.0, 
+    >>>             ssks=7.4, sbdm=1.66, sloc=0.67, slcl=1.7, slsi=0.9, slcf=0.0, 
+    >>>             slhw=7.0, scec=20.0
+    >>>         ),
+    >>>         SoilLayer(
+    >>>             slb=15.0, slmh='', slll=0.025, sdul=0.105, ssat=0.345, srgf=1.0, 
+    >>>             ssks=7.4, sbdm=1.66, sloc=0.67, slcl=1.7, slsi=0.9, slcf=0.0, 
+    >>>             slhw=7.0
+    >>>         ),
+    >>>         SoilLayer(
+    >>>             slb=30.0, slmh='', slll=0.075, sdul=0.12, ssat=0.345, srgf=0.7, 
+    >>>             ssks=14.8, sbdm=1.66, sloc=0.17, slcl=2.4, slsi=2.6, slcf=0.0, 
+    >>>             slhw=7.0
+    >>>         ),
+    >>>         SoilLayer(
+    >>>             slb=45.0, slmh='', slll=0.025, sdul=0.086, ssat=0.345, srgf=0.3, 
+    >>>             ssks=3.7, sbdm=1.66, sloc=0.17, slcl=2.4, slsi=2.6, slcf=0.0, 
+    >>>             slhw=7.0
+    >>>         ),
+    >>>         SoilLayer(
+    >>>             slb=60.0, slmh='', slll=0.025, sdul=0.072, ssat=0.345, srgf=0.3, 
+    >>>             ssks=3.7, sbdm=1.66, sloc=0.17, slcl=2.4, slsi=2.6, slcf=0.0, 
+    >>>             slhw=7.0
+    >>>         ),
+    >>>         SoilLayer(
+    >>>             slb=90.0, slmh='', slll=0.028, sdul=0.072, ssat=0.345, srgf=0.1, 
+    >>>             ssks=3.7, sbdm=1.66, sloc=0.17, slcl=2.4, slsi=2.6, slcf=0.0, 
+    >>>             slhw=7.0
+    >>>         ),
+    >>>         SoilLayer(
+    >>>             slb=120.0, slmh='', slll=0.028, sdul=0.08, ssat=0.345, srgf=0.1, 
+    >>>             ssks=0.1, sbdm=1.66, sloc=0.18, slcl=7.7, slsi=3.1, slcf=0.0, 
+    >>>             slhw=7.0,
+    >>>         ),
+    >>>         SoilLayer(
+    >>>             slb=150.0, slmh='', slll=0.029, sdul=0.09, ssat=0.345, srgf=0.05, 
+    >>>             ssks=0.1, sbdm=1.66, sloc=0.15, slcl=7.7, slsi=3.1, slcf=0.0, 
+    >>>             slhw=7.0
+    >>>         ),
+    >>>         SoilLayer(
+    >>>             slb=180.0, slmh='', slll=0.029, sdul=0.09, ssat=0.345, srgf=0.05, 
+    >>>             ssks=0.1, sbdm=1.66, sloc=0.1, slcl=7.7, slsi=3.1, slcf=0.0, 
+    >>>             slhw=7.0
+    >>>         )
+    >>>     ]
+    >>> )
+
+This module also contains some functions to estimate missing soil properties. The 
+estimate_from_texture function estimates the soil hydro-dynamic properties based
+on soil texture. The sloc_from_color estimates the soil organic carbon based on
+the soil color.
 """
 
 from .base.partypes import (

DSSATTools/weather.py

@@ -1,6 +1,19 @@
 '''
-
-
+This module contains the classes that handle the weather definition. The 
+WeatherStation class represents the DSSAT weather station. The weather station
+object can be created by reading the data from existing DSSAT wheater files:
+    >>> weather = WeatherStation.from_files(["UAFD9001.WTH", "UAFD9101.WTH",])
+Note that the input parameter is a list of files, as DSSAT can have multiple files
+for the same station. The list of files must correspond to the same station. The
+weather station can also be created using the data from a DataFrame:
+    >>> weather_station = WeatherStation(
+    >>>     insi='UNCU', lat=4.34, long=-74.40, elev=1800, 
+    >>>     table=df_with_data
+    >>> )
+where the df_with_data contains the weather data and its column names match the 
+DSSAT weather parameters' names. As with the event-based sections of the FileX,
+the table is a list of events (daily weather records). In this case the 
+WeatherRecord class is the class representing each daily weather record.
 '''
 import os
 import pandas as pd

README.md

@@ -32,7 +32,7 @@ DSSATTools library allows the user to create low-code scripts to run simulations
 
 DSSATTools implements an object-based approach to define DSSAT simulation input. This aims to mimic the process of creating the DSSAT input files (SOL, WTH, FileX) using the DSSAT GUI Tools. Then, the same way that XBuild has one menu for each FileX section (e.g. Cultivar, Soil Analysis, Planting Date, etc.), there is one DSSATTools class for each section of the FileX. Also, there is one class for the WTH file, and one class for the SOL file. 
 
-The filex module contains all the classes that represent each of the FileX sections. The crop module contains the Crop classes, one per crop. Such classes represent the crop and their cultivar and ecotype parameters. The soil module contains the SoilProfile class, which represents a single soil profile. The weather module hosts the WeatherStation class, which represents the Weather Station file (WTH).
+The filex module contains all the classes that represent each of the FileX sections. All the FileX sections are implemented excepting enviromental modifications. The crop module contains the Crop classes, one per crop. Such classes represent the crop and their cultivar and ecotype parameters. The soil module contains the SoilProfile class, which represents a single soil profile. The weather module hosts the WeatherStation class, which represents the Weather Station file (WTH).
 
 Here is one example on how the package is used to run a simple simulation:
 
@@ -48,12 +48,12 @@ Here is one example on how the package is used to run a simple simulation:
 >>>     insi='UNCU', lat=4.34, long=-74.40, elev=1800, 
 >>>     table=df_with_data
 >>> )
->>> soil = SoilProfile.from_file('IBSG910085')
+>>> soil = SoilProfile.from_file('IBSG910085', 'SOIL.SOL')
 >>> field = Field(
 >>>     id_field='ITHY0001', wsta=weather_station, flob=0, 
 >>>     fldd=0, flds=0, id_soil=soil, fldt='DR000'
 >>> )
->>> planting = planting = Planting(
+>>> planting = Planting(
 >>>     pdate=date(1980, 6, 17), ppop=18, ppoe=18,
 >>>     plme='S', plds='R', plrs=45, plrd=0, pldp=5
 >>> )

debug_filex.py

@@ -13,9 +13,9 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'DSSATTools'
-copyright = '2023, Diego Quintero'
+copyright = '2025, Diego Quintero'
 author = 'Diego Quintero'
-exclude_patterns = ['base', 'models']
+exclude_patterns = ['base']
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration